ponytail-audit：面向整个仓库的过度工程审计 Skill 设计与输出规范

2026-09-04 20:22:45作者：柯茵沙

本文以 ponytail 仓库中的 skills/ponytail-audit/SKILL.md 为主体，系统讲解 ponytail-audit 这一"全仓库过度工程审计"Skill 的设计动机、五种发现标签（tag）分类体系、扫描目标清单、逐行排名式的报告格式，以及它与 ponytail-review 的分工边界；并结合 commands/ponytail-audit.toml、pi-extension/index.js、tests/commands.test.js 等源码，说明该 Skill 在各 Agent 宿主中的注册与一致性保障机制。读完本文，你可以准确复述 ponytail-audit 的完整行为契约（触发方式、输出格式、退出语、边界条款），并理解一个"纯提示词 Skill"如何在多宿主插件体系中保持一致。

1. ponytail-audit 是什么：全仓库版的过度工程审计

ponytail 项目的设计理念是"让 AI Agent 像房间里最懒的资深工程师一样思考——最好的代码是你从未写过的代码"。在这一理念下，仓库提供了六个 Skill（定义于 skills/ 目录），其中 ponytail-audit 的职责在 skills/ponytail-audit/SKILL.md 的 frontmatter 中被明确描述为：

Whole-repo audit for over-engineering. Like ponytail-review, but scans the entire codebase instead of a diff: a ranked list of what to delete, simplify, or replace with stdlib/native equivalents.

即：对过度工程（over-engineering）进行全仓库审计。它与 skills/ponytail-review/SKILL.md 的核心区别只有一处——扫描对象：

维度	ponytail-review	ponytail-audit
扫描范围	当前 diff（本次改动）	整个代码树（the whole tree）
定位	审查"新写的东西是否过度"	盘点"仓库里还能删掉什么"
排序	按 diff 内位置列出	按可削减量从大到小排名（ranked biggest cut first）
结算语	`net: -<N> lines possible.`	`net: -<N> lines, -<M> deps possible.`（多一个依赖削减项）
是否修改代码	否，只列出发现	否，只列出发现（One-shot report, does not apply fixes）

文档正文开宗明义地用一句话总结了这一关系："ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank findings biggest cut first."（即 ponytail-review 的全仓库版，按最大削减量优先排序。）

触发方式同样写在 frontmatter 中，当用户说出以下任意表述时应启用该 Skill："audit this codebase"、"audit for over-engineering"、"what can I delete from this repo"、"find bloat"、"ponytail-audit"，或直接调用命令 /ponytail-audit。注意它是一次性报告（one-shot）：产出审计清单后即结束，不持续驻留某个模式，也不会动手修改任何文件。

1.1 命令注册与多宿主分发

该 Skill 并非孤立文件，而是通过"同一份提示词、多种宿主适配"的方式分发。仓库中可确认的分发证据包括：

Claude Code / Gemini CLI 的文件型命令：commands/ponytail-audit.toml，其中 prompt 字段是 SKILL.md 行为契约的压缩版：扫描全树而非 diff、一行一个发现、按最大削减优先排名、五个标签、以净行数与依赖数收尾，无可删则输出 "Lean already. Ship."。
pi 扩展：pi-extension/index.js 中 pi.registerCommand("ponytail-audit", ...)，handler 直接转发为 /skill:ponytail-audit，即把 pi 的斜杠命令映射回同一份 SKILL.md。
Hermes Agent 插件：plugin.yaml 与 __init__.py 将其注册为 /ponytail-audit；tests/hermes-plugin.test.js 中测试了 /ponytail_audit repo 形式的输入能被正确改写并回显 ponytail-audit 与参数 repo。
Qoder 插件：tests/qoder-plugin.test.js 断言 ponytail-audit 在插件命令集中。
文档侧：docs/agent-portability.md 将 skills/ponytail-audit/SKILL.md 列为"whole-repo over-engineering audit"的可移植行为之一，skills/ponytail-help/SKILL.md 的速查卡将其描述为 "Whole-repo over-engineering audit: ranked list of what to delete"。

一致性由测试守护：tests/commands.test.js 的机制是——解析 pi 扩展源码中所有 registerCommand(...) 注册项，逐一断言 commands/<name>.toml 与 .opencode/command/<name>.md 都必须存在。这意味着"pi 注册了 ponytail-audit 命令"必然有对应的 Claude 命令文件与 OpenCode 命令文件，防止命令在不同宿主间出现漂移（drift）。

2. 发现标签体系：五种 tag 及其替换语义

SKILL.md 的 "Tags" 一节声明标签体系与 ponytail-review 完全一致（"Same as ponytail-review"），这是刻意的设计：review 与 audit 共享同一套"发现语言"，区别仅在扫描范围与排序。五个标签及其判定标准如下：

标签	判定标准	替换物（Replacement）要求
`delete:`	死代码、未被使用的灵活性（unused flexibility）、投机性功能（speculative feature）	无（nothing）——直接删，不写替代
`stdlib:`	手写的、标准库本就内置的功能	必须点名具体的标准库函数
`native:`	依赖或代码在做平台/宿主已经提供的事	必须点名具体的平台特性
`yagni:`	只有一个实现的抽象、没人设置的配置、只有一个调用方的层	内联/删除该层
`shrink:`	逻辑相同、行数更少的写法	必须展示更短的形式

其中 stdlib:、native:、shrink: 三个标签有一个共同的强制约束：发现必须携带可执行的替换说明——stdlib: 要指名函数、native: 要指名特性、shrink: 要给出更短代码。这使得每条发现不是"这里可能能简化"式的模糊建议，而是可以直接落地的操作项。ponytail-review 中给出的示例正好演示了这一语言的形态（引自 skills/ponytail-review/SKILL.md）：

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.
L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.
L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.

反面教材同样值得注意——ponytail-review 明确否决了"这个 EmailValidator 类也许可以更简单，你觉得这些校验规则现阶段都必要吗？"这类模糊措辞，正确写法是 L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail. 这种一行定位 + 标签 + 削减物 + 替换物的断言式输出。ponytail-audit 沿用同一语言，只是把 L<line> 定位换成仓库级路径。

3. 扫描目标清单（Hunt）：过度工程的六种高发形态

SKILL.md 的 "Hunt" 一节列出了审计时应当主动搜寻的具体模式，这是整个 Skill 中"方法论含量"最高的段落：

标准库/平台已内置的依赖（Deps the stdlib or platform already ships）——为几个函数引入整个 npm 包或 pip 包；
单一实现的接口（single-implementation interfaces）——只有一个 concrete 的抽象层；
只生产一种产品的工厂（factories with one product）；
只做转发的包装器（wrappers that only delegate）——调用另一层、不增加任何行为；
只导出一个东西的文件（files exporting one thing）——为"组织良好"而存在的空壳模块；
死开关与死配置（dead flags and config）以及手写的标准库（hand-rolled stdlib）。

这六类形态与主 Skill skills/ponytail/SKILL.md 中的"梯子"（the ladder）哲学一一对应：梯子第 1 级问"这东西需要存在吗"（对应 yagni/delete），第 3 级"标准库能做吗"（对应 stdlib），第 4 级"平台原生特性覆盖吗"（对应 native），而"不要未要求的抽象、一个实现的接口、一种产品的工厂、从不改变的值的配置"正是 skills/ponytail/SKILL.md Rules 一节的原文条款。也就是说，ponytail-audit 实际上是把 ponytail 模式在写入代码时执行的自我约束，反向用作对存量代码的检查清单——同一套价值观，两种时态。

从源码结构看，仓库自身也践行了这条清单：例如 benchmarks/arms/ 中 baseline 与 ponytail 两个 arm 的脚本各自保持最小化，且 ponytail: 注释约定（"标记有意的简化并写明升级路径"）为 skills/ponytail-debt/SKILL.md 的债务台账提供了输入，形成 audit（找可删项）→ debt（跟踪已做的简化）的闭环。

4. 输出规范：一行一条、按削减量排名、固定结算语

"Output" 一节规定了审计报告的机器可解析形态，共三条硬约束：

一行一个发现，按可削减量降序排名，固定格式：
```
<tag> <what to cut>. <replacement>. [path]
```
例如：stdlib: 60-line debounce util. setTimeout + useRef, 5 lines. [src/hooks/useDebounce.ts]。注意路径置于末尾并带方括号，与 ponytail-review 的 L<line> 行号前缀不同——因为全仓库审计的粒度是文件/模块而非 diff 行。
结算行（End with）：
```
net: -<N> lines, -<M> deps possible.
```
这里比 ponytail-review 的 net: -<N> lines possible. 多出一个 -<M> deps 项，呼应全仓库审计特有的能力：识别可整体移除的依赖。这也是 commands/ponytail-audit.toml 中 "End with the net lines and dependencies removable" 的提示词来源。
零发现时的固定退出语：Lean already. Ship.（已经够精简，直接发布。）这一约定与 ponytail-review 的 "Scoring" 一节一致，避免审计在"没发现问题"时输出含糊的免责声明。

这套格式的工程价值在于：输出是可排序、可聚合、可 diff 的。结算行给了一个单一量化指标（可删行数 + 可删依赖数），排名保证了先做回报最大的削减——把"仓库瘦身"变成一个有优先级队列的任务列表，而不是一篇印象式评论。

5. 边界条款：只谈复杂度，正确性显式出局

"Boundaries" 一节定义了 ponytail-audit 的行为边界，这是使用该 Skill 时最容易被忽略、也最影响结果可信度的部分：

范围限定：只审计过度工程与复杂度。正确性 bug、安全漏洞、性能问题显式不在范围内（"Correctness bugs, security holes, and performance are explicitly out of scope"），遇到应转交常规 review 流程（"Route them to a normal review pass"）。这一切割有实际意义：一个只报 bug 不报臃肿的审计与一个只报臃肿的审计互不干扰，后者不会在"删掉这段代码"时漏掉其正确性影响，使用者需要自行安排两道工序。
只列不改：Lists findings, applies nothing. 与 skills/ponytail-review/SKILL.md 的 "Does not apply the fixes, only lists them" 同一契约——审计产出是清单，执行删除是独立的人工决策。
一次性（One-shot）：报告生成后任务即完成，不驻留、不轮询。
退出方式：说 "stop ponytail-audit" 或 "normal mode" 即恢复常规模式。

对比 ponytail-review 的边界条款还有一条额外保护值得注意：单个冒烟测试或基于 assert 的自检是"ponytail 的最低要求，不是臃肿，永不标记删除"。ponytail-audit 虽未逐字重复该句，但从源码结构看两者共享同一标签体系与同一套 ponytail 价值观（主 Skill 明确"非平凡逻辑应留下一个可运行的检查"），因此对存量测试的同类豁免在实践中应当同样适用；若你的仓库恰好只有一层最小自检，预期审计结果就是结算行而非删除建议。

6. 实操路径：如何触发一次 ponytail-audit

基于仓库内可确认的分发文件，以下触发方式均可用（适用前提：已在对应宿主中安装 ponytail 插件/Skill）：

宿主	触发方式	依据
支持 Skill 的 Agent（通用）	说出 "audit this codebase"、"find bloat"、"what can I delete from this repo" 等触发语，或直接 `/ponytail-audit`	frontmatter `description`
Claude Code	`/ponytail-audit [target]`（after-install.md 标注支持带目标参数），安装后 Skill 名为 `ponytail:ponytail-audit`	after-install.md、tests/copilot-plugin.test.js
OpenCode	全部六个命令均以斜杠命令形式提供，含 `/ponytail-audit`	skills/ponytail-help/SKILL.md
Hermes Agent	斜杠命令 `/ponytail-audit`（亦兼容 `/ponytail_audit` 下划线写法），共享网关中建议将访问权限限定给可信用户	README.md、tests/hermes-plugin.test.js
pi	`/ponytail-audit`，内部转发为 `/skill:ponytail-audit`	pi-extension/index.js
OpenClaw	`clawhub install ponytail-audit`（与 review/debt/gain/help 同样方式安装）	README.md
Qoder	Skill 系统调用 `/ponytail-audit`，插件清单指向 `skills/` 目录	README.md、tests/qoder-plugin.test.js

典型工作流为三步：(1) 在目标仓库内触发 /ponytail-audit；(2) 得到按削减量排名的一行式发现列表与 net: 结算行；(3) 人工按排名顺序执行删除/替换（该 Skill 本身不执行）。若结果中出现超出复杂度范畴的问题线索，按边界条款转交常规 review；若你已经在 ponytail 模式下开发，配套的 skills/ponytail-debt/SKILL.md 可把 ponytail: 注释收割为债务台账，skills/ponytail-gain/SKILL.md 则提供基准测试口径的"收益记分板"，三者共同构成 ponytail 的"写时约束 → 存量审计 → 简化台账"完整闭环。

7. 小结

ponytail-audit 是一个以纯 Markdown Skill 文件（skills/ponytail-audit/SKILL.md）定义完整行为契约的"全仓库过度工程审计器"：

输入：整个代码树（而非 diff）；
方法：六种高发过度工程形态的定向搜寻（死代码、单实现抽象、单产品工厂、纯转发包装器、单导出文件、死配置与手写标准库）；
输出：<tag> <what to cut>. <replacement>. [path] 一行式、按削减量降序的发现列表，以 net: -<N> lines, -<M> deps possible. 结算，零发现时输出 Lean already. Ship.；
边界：只谈过度工程与复杂度，正确性/安全/性能显式出局，只列不改，一次性执行；
分发：同一份 SKILL.md 经 commands/*.toml、pi 扩展、OpenCode 命令、Hermes/Qoder 插件等薄适配器分发到各宿主，并由 tests/commands.test.js 这类测试防止命令在宿主间漂移。