Ponytail /ponytail-review 深度解析：只找过度设计的 Diff 审查技能与「删除清单」输出规范

本篇以 Ponytail 仓库中 OpenClaw 技能包内的 ponytail-review 技能定义 为核心，完整拆解这套「只审过度设计、每行发现只输出一句话」的 Diff 审查规则集：五种标签、行内定位格式、净删行计分与边界声明，并结合仓库源码说明该技能如何由 canonical 技能 生成、如何被测试套件锁定不漂移、以及它与 /ponytail-audit 等兄弟技能在 Ponytail 体系中的分工。读完你可以掌握：如何在支持技能（skill）的 Agent 中触发该审查、如何读懂并套用其输出格式，以及从源码层面理解 Ponytail 多端规则文件保持一致性的工程手段。

技能定位：Ponytail 六技能中唯一面向 Diff 的「减法审查器」

Ponytail 是一个把「最懒资深工程师」注入 AI 编码 Agent 的规则集项目，其核心理念是 AGENTS.md 与 主技能 中反复出现的「最好的代码是你没写的代码」。项目围绕这一理念拆分为六个技能：主技能 /ponytail 管编码行为，其余五个是专项工具。ponytail-review 的 frontmatter 描述把它的职责钉死在一个切口上：

name: ponytail-review
description: >
  Code review focused exclusively on over-engineering. Finds what to delete:
  reinvented standard library, unneeded dependencies, speculative abstractions,
  dead flexibility. One line per finding: location, what to cut, what replaces
  it. Use when the user says "review for over-engineering", "what can we
  delete", "is this over-engineered", "simplify review", or invokes
  /ponytail-review. Complements correctness-focused review, this one only
  hunts complexity.

两个关键定位：

1. 只管复杂度，不管正确性。描述末尾的 "Complements correctness-focused review, this one only hunts complexity" 与 OpenClaw 副本 正文的 Boundaries 一节相互印证：正确性 bug、安全漏洞、性能问题被显式排除在范围之外，应交给常规审查流程。
2. 面向当前 Diff，而非整个仓库。这与 /ponytail-audit（审计整个仓库）形成互补，前者处理「这次改动里有什么可以删」，后者处理「整个仓库积累了什么」。

从 canonical 版本的 description 还可以提取出技能的触发方式：用户在会话中说 "review for over-engineering"、"what can we delete"、"is this over-engineered"、"simplify review" 等自然语言，或直接调用 /ponytail-review 命令，技能都会被激活。

运行载体：OpenClaw 技能包与 frontmatter 规范

本次解析的主体文件位于 .openclaw/skills/ponytail-review/SKILL.md，它是 Ponytail 为 OpenClaw/ClawHub 平台生成的技能包。其 frontmatter 结构为：

---
name: ponytail-review
description: "Review a diff for over-engineering. Finds what to delete: reinvented stdlib, needless deps, speculative abstractions. One line per finding."
homepage: https://github.com/DietrichGebert/ponytail
license: MIT
---

与 canonical 技能 相比有两点差异，均由生成脚本 scripts/build-openclaw-skills.js 刻意制造：

• description 被压缩成一行且不超过 160 字符。脚本头部注释说明了原因：OpenClaw 要求 description 是单行短文本，而 canonical 版本的长描述是为 Claude 的技能选择器调优的。render() 函数会对超长或含引号的 description 直接抛错，从源头杜绝不合规输出。
• 正文逐字（verbatim）复制自 skills/<name>/SKILL.md，只重写 frontmatter。脚本注释明确写着 "the ruleset never drifts; only the frontmatter is rewritten"，即六端规则内容永远与源头一致。

安装方式在 README 的 OpenClaw 小节有说明：clawhub install ponytail 安装主技能，review 技能同理（clawhub install ponytail-review，五个技能各自独立安装）。没有 ClawHub 时的降级方案是把 .openclaw/skills/ponytail 目录拷贝到用户目录 ~/.openclaw/skills/ 下。

输出契约：一行一发现，定位到行号

技能正文第一句就定义了整套输出的契约：

Review diffs for unnecessary complexity. One line per finding: location, what to cut, what replaces it. The diff's best outcome is getting shorter.

Format 一节给出精确的语法模板：

L<line>: <tag> <what>. <replacement>.

多文件 Diff 时，行号前加文件名前缀：

<file>:L<line>: ...

行范围用连字符表示（如 L12-38、L52-71），覆盖一段连续代码。这条契约的意义在于让审查结果可机读、可逐条执行：每条发现自带位置、动作和替代物，开发者不需要二次理解就能判断是否采纳，Agent 也可以按行号直接定位回 Diff。

五种标签：一个过度设计的分类学

文档定义了五个标签，每个标签对应一类不同的「过度设计」病灶，并规定了替代物该怎么写：

标签	命中对象	替代物要求
delete:	死代码、用不上的灵活性、投机性功能	无（replacement 为 nothing）
stdlib:	手搓的标准库已提供之物	必须点名具体的标准库函数
native:	依赖或代码在做平台已内建的事	必须点名具体的平台特性
yagni:	只有一个实现的抽象层、没人设置的配置、只有一个调用者的层	内联（inline），直到第二个实现出现
shrink:	逻辑相同但行数更多的写法	必须展示更短的写法

这五个标签并非随意划分，它们与 Ponytail 主技能中「七级阶梯」（skills/ponytail/SKILL.md）的审查视角精确对应：阶梯第 1 级「这东西需要存在吗」对应 delete: 和 yagni:，第 3 级「标准库能做吗」对应 stdlib:，第 4 级「平台原生特性覆盖吗」对应 native:，第 6 级「能一行吗」对应 shrink:。可以说 ponytail-review 是编码阶梯在事后审查方向的镜像：写代码时向上爬阶梯，审 Diff 时用标签向下核对。

正反例：措辞本身就是训练信号

文档的 Examples 一节先给出一个反例，再给五个正例，完整继承如下：

反例（典型的「啰嗦审查员」输出）：

❌ "This EmailValidator class might be more complex than necessary, have you considered whether all these validation rules are needed at this stage?"

正例（符合 Format 契约的输出）：

✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`

✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`

✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`

✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`

✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`

这组对照示范了 Ponytail 一以贯之的输出纪律：

• 不用疑问句，用陈述句。反例用 "have you considered..." 把决策推回给用户；正例直接断言「27 行验证类 → 1 行 "@" in email」，并顺带给出理由（真正的验证在确认邮件环节）。
• 每条都自带量化对比（27 行 vs 1 行、0 deps），让 net: -<N> 的计分有据可依。
• yagni: 标签的替代物是「等条件满足再说」（"until a second one exists"），而不是「现在就重构成工厂」。这与 主技能规则 中 "no interface with one implementation, no factory for one product, no config for a value that never changes" 完全同频。
• delete: 标签明确写 "Nothing replaces it"，呼应标签表里 "Replacement: nothing" 的规定，避免读者期待一个并不存在的替代方案。

其中 repo.py:L88 这条演示了多文件 Diff 时 <file>:L<line>: 的带文件名前缀写法，与 Format 一节首尾呼应。

计分机制：唯一重要的指标是「净删行数」

Scoring 一节只有一句话，但定了整个技能的验收标准：

End with the only metric that matters: net: -<N> lines possible. If there is nothing to cut, say Lean already. Ship. and stop.

两个要点：

1. 审查以一行总结收尾，格式为 net: -<N> lines possible.——前面所有发现的替代物加总后，理论上能让 Diff 缩短的行数。这让「审查通过」有了可度量定义：不是「没有大问题」，而是「没有可删的行」。
2. 存在显式的「无需修改」出口。如果 Diff 本身已经精简，输出固定短语 Lean already. Ship. 然后停止，不再补充赞美或建议。这个短路出口很关键：它防止审查技能在无事可报时退化成泛泛而谈的「整体印象」段落。

这套计分与 commands/ponytail-review.toml 中为斜杠命令注入的精简提示词一致——命令版把同样的规则压缩进一段 prompt：

description = "Review changes for over-engineering, what can be deleted"
prompt = "Review the current code changes for over-engineering only, not correctness. One line per finding: L<line>: <tag> <what to cut>. <replacement>. Tags: delete (dead code/speculative feature), stdlib (reinvented standard library), native (dependency doing what the platform does), yagni (abstraction with one implementation), shrink (same logic, fewer lines). End with the net lines removable. If nothing to cut: 'Lean already. Ship.'"

也就是说，无论用户走技能触发（OpenClaw、Claude Code、Codex 的 @ponytail-review）还是走斜杠命令（如 Copilot CLI 的 /ponytail:ponytail-review，见 README Commands 一节），拿到的都是同一套标签、同一行格式、同一收尾句。README 的命令表中对该命令的描述是 "Review the current diff for over-engineering, hands back a delete-list."——「删除清单」正是这套机制的产品化说法。

边界声明：不修、不碰正确性、测试是下限不是赘肉

Boundaries 一节是这份 50 多行文档中工程判断最重的部分，原文完整继承并逐条展开：

1. 范围隔离：过度设计与复杂度，仅此而已。

Scope: over-engineering and complexity only. Correctness bugs, security holes, and performance are explicitly out of scope. Route them to a normal review pass, not this one.

把正确性、安全、性能明确划出范围，是一种防御「技能膨胀」的设计：如果 ponytail-review 什么都审，它就和普通 code review 没有区别了。技能把跨领域发现「路由」给常规审查通道，自己只打复杂度这一个靶子。

2. 冒烟测试是 ponytail 的下限，永远不标删。

A single smoke test or assert-based self-check is the ponytail minimum, not bloat, never flag it for deletion.

这条规则解释了 Ponytail 体系内一个看似矛盾的点：主技能明明要求「删一切不必要的东西」，却豁免最小测试。答案在 主技能 的 "Lazy code without its check is unfinished" 规则：非平凡逻辑（分支、循环、解析器、资金/安全路径）必须留下一个可运行的检查（assert 自检查或一个小型 test_*.py），"No frameworks, no fixtures, no per-function suites unless asked"。ponytail-review 把这条写作规则翻译成审查规则——一个冒烟测试恰恰是 ponytail 的「地板」而非「天花板」，标删它就是审查技能犯错。

3. 只列不改。

Does not apply the fixes, only lists them.

技能是纯「诊断」工具：输出删除清单，不动手改代码。修改权留在开发者（或后续一次显式的编码任务）手里。这保持了审查与执行两个回合的职责分离，也符合 Ponytail 主技能 "Shortest working diff wins" 的哲学——审查本身不应产生任何 Diff。

4. 退出机制：回到冗长模式。

"stop ponytail-review" or "normal mode": revert to verbose review style.

用户随时可以用这两句口令让 Agent 回到常规冗长审查风格。这与 主技能的 Boundaries（"stop ponytail" / "normal mode": revert）用的是同一套退出协议，六个技能共享一致的开关语义。

工程佐证：规则副本如何保证六端不漂移

文档本身是一份「提示词工程」产物，而 Ponytail 仓库把它当成代码来管理。以下源码证据说明这份 SKILL.md 在仓库管线中的位置，帮助理解「为什么你在 OpenClaw 里看到的规则与 GitHub 上 canonical 版本一字不差」。

1. 生成管线。 scripts/build-openclaw-skills.js 是 .openclaw/skills/ 目录的唯一写入者：它读取 skills/ 下六个 canonical 技能，剥掉原 frontmatter，换上含单行短 description、homepage 与 license: MIT 的新 frontmatter，正文原样保留，写出到 .openclaw/skills/<name>/SKILL.md。ponytail-review 的短描述即该脚本 DESCRIPTIONS 表中的 'ponytail-review' 项，恰好也就是你在 OpenClaw 技能文件 frontmatter 里看到的那句话。

2. 漂移即失败。 tests/openclaw-skills.test.js 对每个技能跑三项断言：已提交的 .openclaw 副本必须与生成器输出逐字节相等（过期则提示 stale — run: node scripts/build-openclaw-skills.js）；正文必须以 canonical 正文结尾（verbatim 校验）；description 必须单行且 ≤160 字符。这意味着任何人直接手改 .openclaw/skills/ponytail-review/SKILL.md 的正文都会在测试中失败——规则只能从源头修改。

3. 关键规则字面锁定。 与上述「副本字节相等」不同，主技能 skills/ponytail/SKILL.md 比 compact 副本长，无法逐字节比较，scripts/check-rule-copies.js 采用「canary」策略：列出 10 条承重的规则短语（如 input validation at trust boundaries、prevents data loss、security、accessibility 四条安全豁免项），断言它们在 SKILL.md 与 AGENTS.md 中同时存在，措辞一改就报警。ponytail-review 的 Boundaries 中「正确性/安全/性能不在范围」与主技能的四条安全豁免，共同构成 Ponytail 的「懒而不失责」底线，且这条底线在两个入口文件中都有字面级保护。

4. 发布侧同版本管理。 ClawHub 不自动同步 GitHub，scripts/publish-openclaw-skills.js 用 package.json 的版本号逐个发布六个技能，README 的开发章节要求改技能后先重跑构建脚本、再走发布脚本（支持 --dry-run 预览），防止技能包与仓库版本漂移。

实操路径：在支持技能的 Agent 中触发 ponytail-review

基于 README 的安装与命令章节，典型的落地流程如下：

1. 安装（任选其一，均为只读/本地安装操作，不涉及改动 Ponytail 仓库本身）：
   • OpenClaw：clawhub install ponytail-review（或 clawhub install ponytail 全家桶）；无 ClawHub 时把 .openclaw/skills/ponytail 拷贝到 ~/.openclaw/skills/；
   • Claude Code：/plugin marketplace add DietrichGebert/ponytail + /plugin install ponytail@ponytail（两条分开发送）；
   • Codex：codex plugin marketplace add DietrichGebert/ponytail 后 codex plugin add ponytail@ponytail，技能以 @ponytail-review 调用；
   • Copilot CLI：插件命令后以 /ponytail:ponytail-review 调用；
   • 仅指令型适配（Cursor、Windsurf、Cline、Kiro 等）加载的是 always-on 规则集，不注册斜杠命令，此时靠自然语言触发（"review for over-engineering" 等）或直接参考本文的标签格式手动套用。
2. 在有未提交改动时触发：让 Agent 基于当前 git diff 执行审查。输出的每条发现形如 L<line>: <tag> ...，多文件改动时带 repo.py:L88: 式前缀，末行必为 net: -<N> lines possible. 或 Lean already. Ship.。
3. 处置清单：技能只列不改，开发者逐条决定取舍；决定不采纳的 yagni:/shrink: 条目，可结合 ponytail-debt 技能 的 ponytail: 注释机制登记为技术债（该机制在 主技能 中定义：主动裁剪并标注已知上限的简化，用 ponytail: 注释写明上限与升级路径）。
4. 需要全仓视角时切换工具：ponytail-review 只看 Diff；想审整个仓库积累，用 /ponytail-audit（对应 skills/ponytail-audit/SKILL.md）；想看规则集本身的完整能力清单，用 /ponytail-help。

小结

ponytail-review 用不到 50 行文本定义了一个约束极强、边界清晰的 Diff 审查协议：五种标签覆盖过度设计的五种典型病灶，L<line>: <tag> <what>. <replacement>. 一行一发现的格式保证结果可定位、可执行，net: -<N> lines 把审查成败压缩成一个净删行指标，而 Boundaries 一节划出正确性、安全、性能三条禁区并豁免最小冒烟测试。仓库源码进一步展示了这份「提示词」如何被当代码治理：生成脚本 保证六端正文 verbatim 一致，测试 让任何漂移直接失败，canary 校验 锁定承重规则的字面措辞。对使用者而言，价值在于把「这段代码是不是过度设计了」这个模糊问题，变成一份带行号、带替代方案、带净删行数、并且绝不越权动正确性的删除清单。