Ponytail：让 AI Agent 以「最懒资深工程师」方式写最少代码的技术指南

Ponytail 是一个面向 AI 编程代理（Claude Code、Codex、Copilot CLI 等 15 个 agent）的技能插件，核心思想是「最好的代码是你根本没写的代码」——在动手写代码之前，先沿着一架七级阶梯找到能解决问题的最懒方案。阅读本文可以掌握 Ponytail 的工作原理、可复现的基准测试数据、覆盖多种 agent 的完整安装配置方法，以及配套的 /ponytail 命令体系，从而把「减少过度构建」这一工程纪律真正落到自己的 AI 工作流中。

它解决什么问题：先看一个典型场景

Ponytail 的人设是一位「最懒的资深工程师」：长发辫、椭圆眼镜、在公司待得比版本控制系统还久。你把五十行代码甩给他，他看一眼，什么也不说，然后换成一行。Ponytail 就是把这种行为装进你的 AI agent 里。

README 给出的标志性例子是日期选择器。普通的 agent 接到「加一个日期选择器」会：安装 flatpickr、写一个 wrapper 组件、附加一个 stylesheet，然后开始跟你讨论时区问题。而在 Ponytail 模式下，产出是这样：

<!-- ponytail: 浏览器已经有了 -->
<input type="date">

这个例子直接对应 skill 定义中阶梯的第四级——「原生平台特性能不能覆盖它？」。更多「幸存」的示例收录在 examples/ 目录中，包括防抖、深拷贝、邮箱校验、分组、限流、无限滚动、React 倒计时等常见任务，每个文件都展示了「过度构建 vs 最懒可行解」的对比。

基准测试数据：agentic 测量方法与结果

Ponytail 的官方数字来自真实的 agentic 会话，而不是隔离的单次补全。测量方式为：无头（headless）Claude Code 会话，在一个真实的开源仓库（tiangolo 的 full-stack-fastapi-template，FastAPI + React）上编辑代码，以会话留下的 git diff 为评估对象。12 个 feature ticket，同一 agent 带 skill 与不带 skill 各跑一轮，n=4，模型为 Haiku 4.5。

相对无 skill 基线的结果如下：

vs 无 skill 基线	LOC	tokens	成本	时间	安全
ponytail	-54%	-22%	-20%	-27%	100%
caveman（简洁散文对照组）	-20%	+7%	+3%	+2%	100%
提示词「YAGNI + 单行优先」	-33%	-14%	-21%	-30%	95%

关键结论是：ponytail 是唯一在所有四项指标上同时下降、且保持 100% 安全的变体。削减幅度与「过度构建陷阱」直接相关——日期选择器从 404 行降到 23 行（-94%），颜色选择器从 287 行降到 23 行（-92%），因为改用原生 <input>；而对本身已经最小的代码（后端 CRUD），各变体几乎完全收敛，说明它只在有肉的地方下刀。

早期的单发（single-shot）基准曾报告 80–94% 的削减，但社区指出裸模型基线会用大量散文和选项撑大答案，部分差异是对话基线造成的假象。重建后的 agentic 基准正是对这一批评的回应：基线换成了「不带 skill 的同一个 Claude Code agent」，并新增了安全轴（把生成的代码拿去执行对抗性输入，如路径穿越、SQL 注入、伪造 token）。完整方法、逐任务表格与局限性说明见 benchmarks/results/2026-06-18-agentic.md，复现入口在 benchmarks/ 目录。

需要强调 README 中的一条原则：规则从来不是「更少的 token」，而是「只写任务真正需要的，并且绝不削减验证、错误处理、安全与可访问性」。代码变小是因为它确实必要，而不是代码高尔夫。在会「思考」的模型上，成本与延迟的下降只是副产品。

工作原理：七级「最懒阶梯」

Ponytail 的核心机制是一架决策阶梯。在写任何代码之前，agent 停在第一个「站得住」的台阶上：

1. 这个东西需要存在吗？      → 不需要：直接省略（YAGNI）
2. 这个代码库里已经有了？     → 复用它，别重写
3. 标准库能搞定？            → 用标准库
4. 原生平台特性能覆盖？       → 用原生特性
5. 已安装的依赖能解决？       → 用它
6. 一行代码能写完？          → 就一行
7. 最后才是：能工作的最小代码

这架阶梯的完整定义位于 AGENTS.md，它是所有「仅指令」型 agent 的常驻规则文件，核心原文规则包括：

• 没有被明确要求的抽象一律不写（不写只有一个实现的接口、只生产一种产品的工厂、给恒定值做的配置）；
• 能不引新依赖就不引；没有人不需要的样板代码；
• 删除优先于添加，无聊优先于炫技，文件数尽可能少；
• 最短可工作的 diff 获胜——但前提是已经理解了问题，「在错误位置的最小改动不是懒，是第二个 bug」；
• 修复 bug 修根因而非症状：先 grep 目标函数的所有调用方，在共享函数里加一处守卫，比在每个调用方各加一处 diff 更小，也更不易漏掉兄弟调用路径；
• 对刻意保留的「有已知上限的简化」（全局锁、O(n²) 扫描、朴素启发式），用 ponytail: 注释标出上限和升级路径，例如 # ponytail: 全局锁，吞吐量有要求时改按账户加锁。

阶梯的使用时机也有严格约束：先理解问题，再爬阶梯——先读任务与被改动触及的代码，端到端走通真实流程，然后才选台阶。用 skill 文件的话说：「懒在解法上，绝不在阅读上。」

skill 中的完整行为约束

从 skills/ponytail/SKILL.md 可以看到这套规则的 skill 化实现，其中几个值得注意的细节：

绝不懒的边界（Never simplify away）：信任边界的输入校验、防数据丢失的错误处理、安全措施、可访问性基础、以及任何用户明确要求的部分。如果用户坚持要完整版本，就老老实实构建，不再争辩。

测试纪律：「没有检查的懒代码是没写完的」。非平凡逻辑（分支、循环、解析器、金额/安全路径）必须留下一个可运行的检查——最小的、逻辑一坏就会失败的东西（基于 assert 的 demo()/__main__ 自检或一个小测试文件，不引框架、不造 fixture）；一行代码级别的实现则无需测试，YAGNI 同样适用于测试。

输出格式约束：先代码，之后最多三行短说明——跳过了什么、何时该补回来。如果解释比代码长，删掉解释：「每段为简化辩护的散文都是伪装成文字的复杂度回流。」

三个强度等级

skill 定义了三个强度级别，与安装后的 /ponytail 开关对应：

等级	行为
lite	照要求构建，但用一行指出更懒的替代方案，由用户决定
full	强制执行阶梯。标准库与原生特性优先，最短 diff、最短解释。默认等级
ultra	YAGNI 极端派。删除先于添加，交付单行解并在同一句里挑战其余需求

以「给这些 API 响应加缓存」为例，三个等级的回答分别是：lite 会正常加缓存并附一句「functools.lru_cache 一行就能覆盖」；full 直接给出 @lru_cache(maxsize=1000) 并注明跳过了自定义缓存类；ultra 则回答「在 profiler 说话之前不需要缓存」，并断言手写 TTL 缓存类是「带命中率的 bug 农场」。

安装：覆盖 15+ agent 的分层适配

README 的幽默备注是：「这是 Ponytail 会向你索要的最大努力。」

前置条件

Claude Code 与 Codex 的插件会执行两个小型 Node.js lifecycle hooks，因此 node 必须在 PATH 中（Nix/nvm 用户注意：必须是非交互 shell 的 PATH）。若不在，skills 本身照常工作，只是自动激活会静默失效而不是在每个 prompt 上抛错。

Claude Code

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

桌面应用没有 /plugin 命令，需从界面安装：Customize → 个人插件旁的 + → Create plugin and add marketplace → Add from repository，然后填入仓库地址。

Codex

codex plugin marketplace add DietrichGebert/ponytail
codex

在 Codex 中打开 /plugins，选择 Ponytail marketplace 并安装 Ponytail；然后打开 /hooks，审查并授权它的两个 lifecycle hooks，最后开一个新会话。同一套安装也覆盖 Codex 桌面应用：装完重启即可自动发现插件。

GitHub Copilot CLI

copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

交互式会话中使用等价的 slash 命令：/plugin marketplace add DietrichGebert/ponytail 与 /plugin install ponytail@ponytail。Copilot CLI 会把插件命令归在插件名下，例如：

/ponytail:ponytail ultra
/ponytail:ponytail-review

Pi agent harness

pi install git:github.com/DietrichGebert/ponytail

OpenCode

在 opencode.json 中加入：

{ "plugin": ["@dietrichgebert/ponytail"] }

或者从 checkout 直接运行（插件复用仓库里的 hooks/ 与 skills/）：

{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

插件会在每个回合按当前激活的等级注入规则集，并注册 /ponytail 命令（见下文命令一节）。OpenCode 还会自动加载本仓库的 AGENTS.md，因此即使不装插件，规则也生效；插件额外提供 lite/full/ultra/off 等级开关。./ 路径相对你项目里的 opencode.json 解析；若要在多个项目间共享同一个 checkout，改用 .mjs 的绝对路径（它能相对自身位置找到 hooks/ 和 skills/）。

Gemini CLI 与 Antigravity CLI

gemini extensions install https://github.com/DietrichGebert/ponytail

扩展把规则集作为每场会话的永久上下文加载，并注册 /ponytail 命令；skills/ 同样被包含，任务需要时自动激活。

Google 正在把 Gemini CLI 更名为 Antigravity CLI（二进制名 agy），同一扩展可安装到那边：

agy plugin install https://github.com/DietrichGebert/ponytail

Antigravity 复用本仓库的 gemini-extension.json。区别在于 Antigravity 会把 /ponytail 命令转成 skills，所以以消息形式写进聊天（例如直接发送 /ponytail-review）而不是从 slash 菜单里选。在迁移完成前（README 标注约为 2026 年 6 月 18 日），gemini extensions install 也仍然有效。若要作为永久规则，把规则集放到 .agents/rules/。

CodeWhale、Devin CLI 与 OpenClaw

• CodeWhale：从项目根读取 AGENTS.md，无需任何配置。把 AGENTS.md 拷到你的项目里，或直接从本仓库 checkout 中运行 codewhale，即可。

• Devin CLI：

  devin plugins install DietrichGebert/ponytail
  

  skills 以 /ponytail:ponytail、/ponytail:ponytail-review 等形式可用。

• OpenClaw：

  clawhub install ponytail
  

  review/audit/debt/help 等 skill 同样安装（clawhub install ponytail-review 等）。OpenClaw 在编码任务上应用它，同时暴露为 /ponytail 命令。没有 ClawHub 时，把 .openclaw/skills/ponytail 拷贝到 ~/.openclaw/skills/。

默认等级与全局配置

安装后规则每场会话激活，并伴随一组命令。默认等级为 full，可通过环境变量 PONYTAIL_DEFAULT_MODE（取值 lite/full/ultra/off）或 ~/.config/ponytail/config.json（Windows 为 %APPDATA%\ponytail\config.json）中的 defaultMode 字段为每场新会话设定。会话开场与切换模式时的提示文本会显示当前激活等级。/ponytail ultra 专为你把代码库搞毛的时刻准备。

仅指令类适配器的规则文件

对不支持 skill/插件的 agent，做法是把对应的规则文件拷进项目。各 agent 对应的文件位置如下：

Agent	规则文件/目录
Cursor	.cursor/rules/
Windsurf	.windsurf/rules/
Cline	.clinerules/
GitHub Copilot（编辑器）	.github/copilot-instructions.md
Aider	AGENTS.md
Kiro	.kiro/steering/

Kiro 的具体做法：把 .kiro/steering/ponytail.md 拷到 ~/.kiro/steering/（全局）或项目内的 .kiro/steering/。

Copilot CLI 还有一个纯指令回退方案：项目内读取 AGENTS.md 与 .github/copilot-instructions.md，或把规则拷到 ~/.copilot/copilot-instructions.md 让所有项目启用。此路径保持常驻指引，但不提供等级开关和 hooks。VS Code 搭配 Codex 扩展时直接读取 AGENTS.md，因此从本仓库根运行即零配置可用（~/.codex/AGENTS.md 可让 Codex 全局生效）。

更完整的「哪个文件对应哪个 agent」的映射表，包括 Hermes、Swival、Qoder、Zed、Junie、Amp、Jules 等，见 docs/agent-portability.md。该文档还定义了适配原则：保持适配器薄——支持 skill/hook 的宿主直接指向共享的 skills/ 与 hooks/；只支持项目指令的宿主，则让拷贝的规则文本与 AGENTS.md 保持一致。

命令体系

命令	作用
/ponytail [lite | full | ultra | off]	切换强度或关闭；不带参数时报告当前等级
/ponytail-review	审查当前 diff 中的过度设计，返回「该删什么」清单
/ponytail-audit	对整个仓库（而非仅 diff）做过度设计审计
/ponytail-debt	把代码里标记为 ponytail: 的欠账收集进台账，让「以后再说」不至于变成「永不说」
/ponytail-help	上述命令的快速参考

命令需要支持 skills 的宿主（Claude Code、Codex、Devin CLI、OpenCode、Gemini、pi、Swival）。在 Codex 中它们以 skill 形式存在，用 @ 调用（@ponytail-review）。仅指令类适配器（Cursor、Windsurf、Cline、Copilot、Kiro、Antigravity）只加载常驻规则集，不含这些命令。命令定义文件位于 commands/ 目录（如 ponytail.toml、ponytail-review.toml），skill 实现位于 skills/ 目录，每个 skill 一个 SKILL.md。

注意 /ponytail-debt 与规则中 ponytail: 注释约定的闭环关系：规则要求 agent 在留下「有已知上限的简化」时打标记，而 debt 命令负责把这些分散的标记汇总成可追踪的清单，避免技术债无声蒸发。

开发与维护

本仓库的 npm 包名为 @dietrichgebert/ponytail（见 package.json），npm test 会依次执行根目录 tests/、pi-extension 与 ponytail-mcp 三套测试。修改规则文本时有两条维护纪律：

1. 规则副本必须对齐。同一套紧凑规则被拷贝到各个适配器的文件中，改完后运行：

   node scripts/check-rule-copies.js
   npm test
   

   前者专门校验各适配器的规则文本与源文本一致，防止某个 agent 拿着过期规则运行。

2. OpenClaw 的 skill 包是生成物。.openclaw/skills/ 从 skills/ 生成，改动 skill 后需重新构建，否则测试套件会因产物过期而失败。

基准测试方面，correctness 基准会调用 Python 执行邮箱与 CSV 校验（优先探测 python3，其次是 python），CSV 校验要求本地安装 pandas。

FAQ

能否与 caveman 一起使用？ 可以，而且应该。caveman 缩小 agent 说的话，ponytail 缩小 agent 写的东西：两者各管一半，互不重叠——caveman 不动代码一个字节，ponytail 不碰散文。简洁的对话配最小的代码。这也是基准中 caveman 被用作对照组的原因：它证明了 ponytail 的效果来自「懒代码纪律」而非单纯的「话少」。

需要配置文件吗？ 不需要。可选的 ~/.config/ponytail/config.json 或 PONYTAIL_DEFAULT_MODE 环境变量只能固定默认等级，其余一切免配置。

如果我确实需要一个 120 行的缓存类呢？ 你不需要。但坚持的话，他会给你建。慢慢地。正确地。看着你。

可扩展性如何？ 你没写的代码无限可扩展：零 bug、零 CVE、上线至今 100% 可用率。

为什么叫「ponytail」？ 你早就知道为什么了。

许可证

Ponytail 采用 MIT 许可证——「能用的最短许可证」。

适用前提小结：文中安装命令与 hook 行为以当前仓库为准；agentic 基准数字基于 Haiku 4.5、n=4 的 12 个 feature 任务，单模型、有限样本，复现方式见 benchmarks/agentic/README.md。