Ponytail 使用指南
1. Ponytail 是什么
Ponytail 是一个面向 AI 编程助手的“最简实现”插件。
它不会替代编程能力，而是约束 AI 的实现方式：先充分理解需求和现有代码，再选择代码量更少、依赖更少、维护成本更低的方案。
核心原则：
- 判断需求是否真的需要实现
- 优先复用项目已有代码
- 优先使用标准库
- 优先使用平台原生能力
- 优先使用已经安装的依赖
- 能用一行解决就不写几十行
- 最后才编写最少的新代码
“最简”不代表忽略输入校验、数据安全、错误处理、无障碍支持或明确要求。
2. 快速开始
Ponytail 安装并启用后，直接描述开发需求即可：
帮我修复订单重复提交的问题。
给这个页面增加日期选择功能，使用最简单的实现。
也可以显式调用：
@ponytail 帮我实现这个功能Ponytail 会优先寻找现有实现、标准库或原生能力，并尽量减少修改范围。
3. 三种模式
Lite
/ponytail lite正常完成需求，同时用一句话指出更简单的替代方案，由用户决定是否采用。
适合：
- 需求已经确定
- 希望 AI 少质疑需求
- 仍想知道有没有更省事的方案
Full
/ponytail默认模式。严格执行“复用、标准库、原生能力、最少代码”的选择顺序。
适合：
- 日常功能开发
- Bug 修复
- 小型重构
- 控制新增依赖和代码复杂度
Ultra
/ponytail ultra最激进的精简模式。优先删除而不是新增，并主动判断需求是否可以不做。
适合：
- 清理历史包袱
- 快速原型
- 明显过度设计的项目
- 强力控制代码膨胀
简单理解：
| 模式 | 行为 |
|---|---|
| Lite | 按要求做，同时提醒 |
| Full | 选择最简单的正确方案 |
| Ultra | 优先考虑不做或删除 |
模式通常持续到切换、关闭或会话结束。
4. 专项命令
@ponytail
开启 Ponytail 编程模式，使用最简单且可靠的方案完成任务。
示例：
@ponytail 给用户列表增加 CSV 导出功能@ponytail-review
只检查当前 Git 修改内容是否存在过度设计。
主要寻找：
delete：无用代码或预留功能stdlib：重复实现了标准库能力native：代码或依赖可以由平台原生能力替代yagni：暂时没有实际用途的抽象shrink：相同逻辑可以明显缩短
示例：
@ponytail-review 检查当前修改注意：
- 默认检查当前修改，不检查整个项目
- 只生成审查结果，不自动修改代码
- 不负责检查正确性、安全漏洞和性能问题
/ponytail-audit
扫描整个代码库，查找可删除、简化或替换的设计。
示例：
/ponytail-audit它与 ponytail-review 的区别：
| 命令 | 检查范围 |
|---|---|
ponytail-review | 当前 Git 修改 |
ponytail-audit | 整个代码库 |
该命令只报告问题，不自动修改。
/ponytail-debt
收集代码中的 ponytail: 注释，形成简化事项清单。
示例注释：
# ponytail: 当前使用全局锁，并发量明显增长时改为按账号加锁命令输出会说明：
- 哪些地方采用了临时简化
- 当前方案的能力上限
- 什么情况下需要升级
- 哪些注释缺少明确的升级条件
默认只读取和报告，不写入文件。
/ponytail-gain
显示 Ponytail 官方基准测试中的代码量、成本和速度数据。
这些数字来自公开基准测试，不代表当前项目实际节省的数据。
@ponytail-help
显示模式、命令和配置的快捷帮助。
5. 推荐使用流程
开发新功能
@ponytail 实现这个需求，优先复用项目已有能力，不增加非必要依赖。Ponytail 会先阅读相关代码，再决定是否需要新增实现。
修复 Bug
@ponytail 查明根因并修复，不要只处理表面报错。Ponytail 通常会检查相关函数的调用方，并尽量在共享入口修复一次。
检查本次修改
@ponytail-review 检查当前修改是否过度设计。根据报告决定是否需要进一步执行修改。
检查整个项目
/ponytail-audit适合定期清理依赖、包装层、单实现接口和废弃配置。
查看遗留的简化方案
/ponytail-debt适合在版本发布或架构调整前检查此前主动留下的技术限制。
6. 它不会自动做什么
专项检查命令默认不会修改代码：
| 操作 | 是否修改代码 |
|---|---|
@ponytail 执行开发需求 | 会 |
@ponytail-review | 不会 |
/ponytail-audit | 不会 |
/ponytail-debt | 不会 |
/ponytail-gain | 不会 |
@ponytail-help | 不会 |
如果希望应用检查结果，需要明确提出：
根据刚才的 ponytail-review 结果，修复前两项。7. 关闭与恢复
关闭：
stop ponytail或者：
normal mode恢复默认模式：
/ponytail8. 默认模式配置
默认模式是 full。
可以通过环境变量设置：
export PONYTAIL_DEFAULT_MODE=ultra或者使用配置文件：
{
"defaultMode": "lite"
}配置文件位置：
- macOS/Linux：
~/.config/ponytail/config.json - Windows：
%APPDATA%\ponytail\config.json
支持的值：
lite
full
ultra
off优先级为：
环境变量 > 配置文件 > 默认 full9. 使用建议
日常开发使用 Full 即可。
只有在以下情况下才建议切换：
- AI 经常质疑已经确定的需求：使用
Lite - 项目明显臃肿，需要强力精简：使用
Ultra - 只想检查本次改动：使用
ponytail-review - 想检查整个项目：使用
ponytail-audit
Ponytail 专注于减少不必要的复杂度。代码正确性、安全性和性能仍应通过正常代码审查和测试单独确认。