AI 反过度工程顾问 — Lazy-Coder Guardrail (Ponytail)

你现在运行 agent-lazy-coder 技能。目标：给你的 coding agent 装上一副懒程 序员守门员——它在每次改动前先问三个问题：能不能不写？能不能删？能不能复 用已经有的？——然后把答案落成三种可追溯的产物：diff 级 delete-list、全库 audit、ponytail: 短笔记攒出的技术债台账。

底层是 @dietrichgebert/ponytail （MIT、跨 host guardrail plugin，通过 agentskills.io 官方 marketplace 分发）。它是 一个 agent-side skill，不是独立 CLI：装进你的 host coding agent 之后，直接 用 /ponytail-review / /ponytail-audit / /ponytail-debt 三条 slash command 触发，全部推理复用 host 已经登录的模型订阅。

课程只做约定式约束——把三条命令、四个落盘路径、四条相邻课边界钉死，不新 增任何 wrapper、不新增 Clawvard 一方 SDK service、不新增 Clawvard 后端调用点。

这门课做什么（边界写在第一屏）

• ✅ 做：/ponytail-review 在你 push 前审当前 diff，给一张 delete-list； /ponytail-audit 把整个仓库按 impact ÷ effort 排序出历史过度工程 finding； /ponytail-debt 把散落在源码里的 // ponytail: <一句话原因> 短笔记收成一 张 markdown 台账。三条命令的产物都以真实 file:line 锚点为准。
• ✅ agent-in-the-loop：所有推理跑在你 host coding agent 已经登录的模型账户 上——Claude Code 走你的 Claude 订阅、Codex CLI 走 ChatGPT 订阅、Gemini CLI 走 Gemini 订阅。课程不要求你额外提供 Anthropic / OpenAI / Google 独立 API key。
• ✅ 产物真实可追溯：./out/ponytail-review.md 每条 finding 带 file:line + 一句 rationale + 明确的动作建议；./out/ponytail-audit.md 表格里的每一行都 能定位到具体源代码位置；./out/debt-ledger.md 严格只收 ponytail: 前缀短 笔记，TODO / FIXME 一律不收。
• ❌ 不做：替代 PR 行级 code review + severity 前缀（那是 open-code-review， 用阿里 ocr CLI + 你自己的 Anthropic key）；替代顾问式仓库改进计划（那是 agent-plan-then-execute， 写 plans/*.md 后派便宜 executor 实施）；替代 agent 上下文文件压缩（那是 shrink-agent-context，处理 CLAUDE.md 之类，不是用户代码本身）。

一句话定位：open-code-review = 给 PR 里的每一行写 review comment； agent-plan-then-execute = 帮你写「怎么加」； agent-lazy-coder = 帮你决定「能不能不加、能不能删、能不能复用」——方向相反。

前置条件

• 本机 Node ≥ 18 + npm，用来装 host coding agent 和 marketplace 拉取 ponytail plugin 用（每种 host 的安装命令见下节）。
• 一款支持插件市场的 coding agent，任选其一：
  • Claude Code（推荐首选，SOP 主路径）
  • Codex CLI / GitHub Copilot CLI / Cursor / Windsurf / Cline / Kiro / Gemini CLI / Antigravity / Pi agent / OpenCode / Hermes / Devin CLI / OpenClaw / CodeWhale / Swival —— ponytail 官方 README 列出的 marketplace 入口全部适配。
• 该 host 已登录你自己的模型订阅（Claude Pro / Team、ChatGPT Plus / Team、 GitHub Copilot、Google AI Pro，任选其一）。课程不需要你另外提供 Anthropic / OpenAI / Google 独立 API key。
• 要审的仓库：一个你能 cd 进去的本地 Git 仓库；可以是你的私有项目、也可 以是任何公开 OSS repo。ponytail 全程只读源码，不写 working tree。

安装

跨 host 通用主路径（agentskills.io 官方 CLI，一句话装完）：

# 1) 装 ponytail（通用路径，Claude Code / Codex CLI / Cursor / Windsurf / Cline / Gemini CLI 等 15+ host 都认）
npx skills add DietrichGebert/ponytail

装完后在你 host 的 REPL 里自检：

/ponytail-help
# → /ponytail-review    /ponytail-audit    /ponytail-debt
# → /ponytail [lite|full|ultra|off]

/ponytail full        # 强度定档（会话级；默认 full）

其它受支持 host 的备用安装入口（当 npx skills add 不可用时，走该 host 自身官方入口）：

为什么不做一层 wrapper？ ponytail 三条 slash command 直接产出课程 deliverable； 上游没有硬编码输出文件路径，课程只在下面 SOP 里把三条落盘路径钉死为 ./out/ponytail-review.md / ./out/ponytail-audit.md / ./out/debt-ledger.md。 这属于约定式约束，不是代码适配层——课程侧不新增任何 npm 包、任何 Clawvard 一方 SDK service、任何 Clawvard 后端调用点。

三条主指令

1) /ponytail-review — pre-push guardrail on the current diff

/ponytail-review [--base <ref>] [--tee ./out/ponytail-review.md]

• 默认审 git diff origin/main...HEAD；你可以传 --base <sha> 指定另一个 base。
• 输出一张 delete-list：每条 finding 带 file:start-end 锚点 + 一句 rationale
  • 明确动作建议（删除 / 合并到已有 / 换成标准库或已装依赖 / 保留但精简）。
• 必须 tee 一份到 ./out/ponytail-review.md（贴 PR 描述用），并在对话里 给你 Top 3 最狠的 finding 一句话结论。

如果你想暂时不处理某条 finding：在对应源文件插一行 // ponytail: <一句话原因>（或 markdown / HTML / YAML 里用对应注释语法）， 下一次 /ponytail-debt 会自动归档进台账。

2) /ponytail-audit — whole-repo sweep

/ponytail-audit [--tee ./out/ponytail-audit.md]

• 全库扫源码 + 配置 + 脚本，按四条主线打分：
  1. 能不能删 —— 直接死代码、无人引用的 helper、无用抽象。
  2. 是不是重复实现 —— 标准库 / 已装依赖 / 已有内部函数已经能做的事。
  3. 抽象层数够不够薄 —— 单调用点的工厂 / 单实例的接口 / 单实现的策略。
  4. 依赖是不是白装 —— package.json 里没人 import、或者能被 Node stdlib 替掉的第三方包。
• 输出按 impact ÷ effort 排序的 finding 表；每条带 file:line + 建议动作 + 影响范围（"drop-in" / "small refactor" / "needs characterization test"）。
• 必须 tee 一份到 ./out/ponytail-audit.md。

3) /ponytail-debt — collect ponytail: short-notes

/ponytail-debt [--tee ./out/debt-ledger.md]

• 搜整个仓库里所有 ponytail: 前缀短笔记（源码注释 // /* */ #； markdown / HTML 里的 <!-- ponytail: ... -->；YAML 里的 # ponytail: ... 都算）。
• 落成一张 markdown 表：file:line / 短笔记原文 / 分类（delete / dedupe / stdlib / defer） / 是否已解决（初次收集全部为未解决）。
• 必须 tee 一份到 ./out/debt-ledger.md。
• 严格只收 ponytail: 前缀；TODO: / FIXME: 不收（那些是你 issue tracker 的活）。

强度档位

/ponytail [lite|full|ultra|off] 是会话级设置，改变 review / audit 的严厉程度：

想临时关掉一条特定 finding 类别：/ponytail off --category=abstraction。

输出文件约定（下游可复现）

课程约定所有落盘产物都放在 ./out/ 下：

./out/ 建议加进 .gitignore；这些是你 review 用的中间产物，不需要进 commit。 真实样例见 public/skills/agent-lazy-coder/samples/。

与相邻课的边界

• 本课 = /ponytail-review 审 diff / /ponytail-audit 审全库 / /ponytail-debt 收技术债；产物是 delete-list + audit 表 + ledger。 方向是删/复用/不写。
• open-code-review = 阿里 ocr CLI，通用 PR 行级 review + severity 前缀
  • Anthropic key 直连 + JSON+MD 报告；输出的是 line-anchored comment， 不是 delete-list，且需要你自己的 Anthropic key。
• agent-plan-then-execute = shadcn/improve skill，senior advisor 模式： audit 后写 plans/*.md spec，派便宜 executor 在隔离 worktree 实施。 方向是写。
• simplify（Claude Code 内置技能） = 一次性对 staged diff 做小幅清理； 本课是常驻 guardrail plugin，三条指令覆盖 pre-push review、全库 audit、 debt 收账三个不同时间点，还支持强度档位。
• shrink-agent-context = 压缩 agent 上下文文件（CLAUDE.md / AGENTS.md 之类）；本课处理用户代码本身，不是 agent 上下文。

红线与不要做的事

• 不要指望 ponytail 帮你添加功能——它的整套 prompt 是"能不能不加"。 想让 agent 帮你实现新东西，用 agent-plan-then-execute。
• 不要把 review 找出的三十条 finding 合成一个大 PR ——每一条都是独立可 reverse 的最小改动，独立提交更容易 review。
• 不要用 ponytail 审你不打算 land 的实验分支——lite 档也会给你压力。 这时用 /ponytail off 就好。
• 不要绕过 ponytail: 前缀去藏笔记——/ponytail-debt 只认这一个前缀； 换成 TODO: / FIXME: 会被漏掉。

降级路径（用户 host 无订阅时）

若你的主力 host 没有可用订阅额度，官方 marketplace 提供的免费入口：

• Codex CLI 免费额度 —— 装完直接可用。
• Gemini CLI 免费额度 —— 装完直接可用。
• OpenCode —— 本地 / 开源接线，可挂本机 Ollama 之类作为推理端。

三条免费入口任一款都能覆盖本课全部三条指令；无需人工发放 API key，无需 Clawvard 侧兜底。

学习完成后

告诉用户：

我已经学会了 agent-lazy-coder。给我一个本地 Git 仓库和一段 diff，我会：

1. 装 @dietrichgebert/ponytail（marketplace 一句话装完），把 /ponytail 档位定到 full。
2. 跑 /ponytail-review 审当前 diff → 一张 delete-list 落到 ./out/ponytail-review.md，每条 finding 带 file:line + 建议动作。
3. 跑 /ponytail-audit 全库审历史过度工程 → 按 impact ÷ effort 排序的 finding 表落到 ./out/ponytail-audit.md。
4. 跑 /ponytail-debt 把散落的 ponytail: 短笔记收成一张 markdown 台账 到 ./out/debt-ledger.md，让"回头再收拾"可追溯。
5. 整个过程只读源码，不动你的 working tree、不 commit、不 push。 我用你 host coding agent 已经登录的模型订阅推理，不要你另外的 Anthropic / OpenAI / Google key。课程主页 https://clawvard.school/courses/agent-lazy-coder。