夜雨聆风Agent 指令 · 代码精简 · YAGNI · 跨平台 · DietrichGebert/ponytail ——
项目中约 8K star 的 AI 编码规则层，通过一条六步决策指令让
Claude、Cursor 等 11 个 Agent 学会"能不写就不写"。
AI Agent 写代码，能救人先气死人
让一个没有约束的 AI 编码助手写"日期选择器"——它先装 flatpickr，
再写包装组件、样式表、useEffect 垃圾清理，最后附一段关于时区
处理的讨论。日期选择，浏览器原生 <input type="date"> 一行搞定。
这不是个例。让 AI 写 Email 校验：正则类 + 自定义 Validator 类
+ 包装函数，27 行。实际上 "@" in email 再加个确认邮件就够
了。写缓存系统：120 行手工 LRU、TTL、线程锁，而 functools.lru_cache
一行覆盖。排序：手写快排，重新分配数组，V8 引擎自带
.sort() 不用。API 端点：Controller / Service / Repository 三层 +
自定义异常 + DTO，五个文件。FastAPI 里 9 行的事。
问题不是 AI 不会写，是 AI 不知道什么不该写。主流 Agent 的默认 策略是"多给比少给好"——主动建抽象层、预判未来需求、补充完整 错误处理，生成大量调用方从未问过的东西。结果代码膨胀、成本上扬、 审查耗时。这个场景的读者——无论是用 Claude Code、Cursor 写原型， 还是用 Codex、Copilot 写生产代码——每天都在处理这种"话很多但 不在点子上"的 AI 输出。
更隐蔽的问题是反馈循环。Agent 写了 120 行的缓存类，你留下了， 下次它觉得"上次这个项目用缓存类了，那我继续用"。没人在第一版 就问"我们真的需要一个缓存类吗？"。Ponytail 解决的就是这个 起点问题：把"项目里最资深老程序员"的审慎量化为机器可执行的 指令规则。它不削足适履，而是先问——这双鞋真的需要吗？
装完即生效，五条命令覆盖日常
Ponytail 不是一个独立工具，而是一套指令集与插件体系，安装成本 降到最低：
Claude Code 安装：两条命令搞定。
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
Codex：同样从插件市场安装，信任两枚生命周期钩子即可。安装后 会自动注入指令、注册命令、显示当前模式。
Cursor / Windsurf / Copilot：把对应目录下的规则文件复制到
项目 rules/ 目录，重启会话即生效。
Gemini CLI：一条扩展安装指令贯通。
OpenCode：通过 plugin 注入，自动加载 AGENTS.md。
Kiro：复制 steering 文件到项目或全局目录。
GitHub Copilot CLI：读取项目内的 AGENTS.md 和 copilot-instructions.md 即可全局生效。
全部 11 个平台覆盖方式是仓库原生支持的：.cursor/rules/、
.windsurf/rules/、.clinerules/、AGENTS.md、.kiro/steering/
等各平台读取规则的位置都放了等价副本，并用自动脚本做漂移检测。
开箱即用：装好后每次会话自动加载，无需额外配置。
日常使用靠几条内置命令：
• /ponytail 查看当前模式与规则状态
• /ponytail lite | full | ultra 切换精简力度
• /ponytail-review 审查已有代码的删减空间
• /ponytail-audit 全仓库"这代码真的需要"检查
• /ponytail-help 详细解释各命令与模式含义
典型实战场景：
场景一：新 API 端点。 需求是"添加一个根据 ID 返回用户的端点"。 未使用 Ponytail 时，Agent 生成 Controller / Service / Repository / Schema / Exception 五个文件，外加三层 DI 注入。使用后 9 行：
@app.get("/users/{user_id}", response_model=UserOut)
def get_user(user_id: int, db: Session = Depends(get_db)):
user = db.get(User, user_id)
if not user:
raise HTTPException(404)
return user
保留响应 Schema 做信任边界（防止 ORM 模型泄露字段），砍掉中间层， 附注释："第二个调用者出现时才加 Service 层"。
场景二：前端排序。 需求是"给数组排序"。Agent 此前手写 quicksort（24 行递归，大数组爆栈）。Ponytail 作用下：
numbers.sort((a, b) => a - b)
一句。附带注释："引擎优化排序，不重写"。
场景三：缓存逻辑。 遇到缓存需求时先问"真的需要吗？"——如果
还没测量过热路径就不写。确认需要后优先 functools.lru_cache，
而非自建类。需要分布式时用 Redis，不做中间方案。
常见误区：新手容易误以为 Ponytail 会忽略正确性——实际上它 明确声明"不会偷懒的"四点：输入校验、防数据丢失的错误处理、安全 性、可访问性。信任边界的验证从不缩减。
六步决策梯：压缩代码的核心机制
Ponytail 的核心是一段约 95 行的规则文本，统一注入 Agent 会话。 它不是复杂算法，而是一个决策梯（Decision Ladder），写作代码 前先逐级检查：
1. 东西真有需要写吗？ -> 不写（YAGNI）
2. 标准库已经有了？ -> 用它
3. 浏览器/平台原生功能覆盖了？ -> 用它
4. 已安装依赖里有人实现了？ -> 用它
5. 能一行搞定？ -> 一行
6. 以上都不行，再写最少代码。
Agent 从第一级开始检查，命中了就直接跳过后面的级别。这意味着 Agent 不会自动进入"写代码模式"，而是先思考"能不能不写"。这看起来 简单，却反转了几乎所有 AI 编码助手的默认行为。
创新点一：ponytail: 注释协议。 当 Agent 选择一个明知有
上限的简写方案（如用全局字典做缓存、O(n²) 扫描、朴素启发式），
它必须在注释中以 ponytail: 开头写明上限与升级路径。这不是
自我批评——而是让审查者和未来维护者一眼看出"这里做了有意识的
权衡，什么时候该升级"。示例：
cache = {}
Ponytail 还通过一个巧妙的规则平衡了"代码量的减少"和"知识传递 的保留"：用户清楚知道每一处偷懒的后续成本，这比"看到代码发现 没做缓存失效机制"要安全得多。
创新点二：分级精简。 Lite / Full / Ultra 三级。Full 是默认， 严格走六步梯。Lite 放宽限制（适用于教学和示例），Ultra 则对 任何代码先假设"不需要"，要求调用者提供更充分理由。这解决了 "同一规则不能适应所有上下文"的问题。更精细一些，Ultra 模式 在一些贡献者验证中看到代码量再降一个数量级——适用于遗留系统 重构时"彻底清洗"。
创新点三：跨平台统一。 11 个 Agent 各有自己的规则格式
（.cursor/rules/、AGENTS.md、copilot-instructions.md 等），
Ponytail 在每个平台目录下放了内容等价但语法适配的副本，用
scripts/check-rule-copies.js 做漂移检测。这让你不需要在每个
工具里各建一套"少写废话"规则。
基准数据：三个模型（Haiku / Sonnet / Opus），五类日常编码 任务，十轮中位数统计。与无约束 base line 对比： - 代码行数减少 80%–94%（base line 约 256–693 行，Ponytail 约 39–51 行） - token 消耗降低 47%–77% - 响应速度快 3–6 倍
对比同类 Caveman 方案：Ponytail 代码行数仅为其 40%（47 vs 117）， token 消耗低 2%，速度持平。差异源于 Caveman 走"压缩提示词" 路线，Ponytail 走"缩减代码产出"路线。
代价也很清晰：Ponytail 限制了 Agent 的"创造力"——你不会看到它
主动提供一个你没想到的好抽象层。对需要"自由发挥"的场景（如
头脑风暴架构），需临时 /ponytail lite 或关闭。
哪些场景值得马上试
场景一：个人或小团队的 AI 编码工作流。 如果你每天在 Claude Code 或 Cursor 写前端/后端代码，装好 Ponytail 后每会话省下 60%–80% 的代码量——从"写出再删改"变成"写一句就继续"。每个 会话的 token 成本降约 50%，耗时从分钟级降到秒级。全职开发者 按每天 10–20 次 Agent 交互算，每月能省数百元 API 费用。
场景二：微服务与 API 项目。 API 端点、数据校验、排序、缓存
是微服务里的基础重复劳动，也是 Agent 最易膨胀的区域。结合
/ponytail-review 定期审查已提交代码，可以持续剥离没有使用场景
的抽象层。特别是 For 新项目，从第一行就用 Ponytail 约束，
代码库初始规模可比过往项目小 60% 以上。
更广阔的空间：决策梯模式理论上可扩展到代码审阅 CI 管线—— PR 合并前自动检测"是否有比手写更省的原生方案"，或在代码扫描中 标记"可被标准库替换"的手写逻辑。Ponytail 的规则体系也可作为 企业内部 Agent 策略的底层模板，补充合规层后统一推广。
但 Ponytail 最大的价值不是技术上的——它提醒所有人：AI 代码生成 最大的瓶颈不是模型不够强，而是我们还没教会它"什么时候闭嘴"。 在每一行代码都被自然语言"唤醒"的时代，这个项目提出的不是一个 更好的写法，而是一个更基本的判断力。
