Ponytail 规则集深入解析：.clinerules/ponytail.md 如何让 AI Agent 像最懒的资深工程师一样写代码

本文以 .clinerules/ponytail.md 这份 30 行的紧凑规则文件为主体，完整拆解 Ponytail 项目的核心方法论：七级"懒惰阶梯"、根因修复原则、硬性规则清单与"不可懒惰"的安全例外条款，并结合仓库中的校验脚本、基准测试产物与真实模型输出示例，说明这套规则为什么能系统性减少 AI 生成代码中的过度工程，以及如何在 Cline 等纯指令型 Agent 中使用它。读完本文，你能完整理解这份规则文件的每一条款设计意图、它在多 Agent 适配体系中的定位，以及如何验证规则副本的一致性。

一、.clinerules/ponytail.md 是什么：Cline 的 always-on 规则文件

.clinerules/ponytail.md 是 Ponytail 项目为 Cline 提供的指令型适配器：Cline 会自动加载 .clinerules/ 目录下的规则文件作为每轮对话的常驻上下文，因此把 Ponytail 的行为规则放在这里，Agent 在写任何代码前都会被"约束"为懒资深工程师（lazy senior developer）模式——"Lazy means efficient, not careless. The best code is the code never written."（懒惰意味着高效，而非粗心；最好的代码是从未写下的代码）。

在 docs/agent-portability.md 的适配器列表中，Cline 一行明确写着：文件为 .clinerules/ponytail.md，备注为 "Project rule"（项目级规则）。这代表 Ponytail 的分发策略分两层：

1. 插件层（Claude Code、Codex、OpenCode、Hermes 等）：完整技能 + 生命周期钩子，支持 /ponytail lite|full|ultra 强度切换与命令；
2. 指令层（Cursor、Windsurf、Cline、Copilot、Kiro、Antigravity 等）：不支持技能或钩子的宿主，只需把对应规则的紧凑副本放进项目，即可获得 always-on 规则集——.clinerules/ponytail.md 正是这一层中 Cline 对应的那份。

README 的 Install 章节也印证了这一点：对于 Cline，"copy the matching rules file from this repo（.clinerules/）" 即可完成接入，卸载时"Delete the copied rule file"即可。也就是说这份文件的设计前提是零安装、单文件、复制到项目即生效。

二、规则文件的完整继承：七级"懒惰阶梯"

这份文件的核心是一段编号 1–7 的判定阶梯。原文逐字继承如下（引自 .clinerules/ponytail.md）：

Before writing any code, stop at the first rung that holds:

1. Does this need to be built at all? (YAGNI)
2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
3. Does the standard library already do this? Use it.
4. Does a native platform feature cover it? Use it.
5. Does an already-installed dependency solve it? Use it.
6. Can this be one line? Make it one line.
7. Only then: write the minimum code that works.

关键设计是 "stop at the first rung that holds"——爬到第一级站得住的台阶就停，不是把七级全走完再取最优。这保证规则执行是一次廉价的顺序检查，而不是一个研究项目。长版本 skills/ponytail/SKILL.md 对此的表述是："The ladder is a reflex, not a research project"，并补充了两级台阶同时成立时的取舍："Two rungs work → take the higher one and move on"（取更高一级，直接往下走）。

阶梯的运行前提：先理解，再爬梯

文件第 15 行有一条容易被忽略的前提约束：

The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.

即阶梯在理解问题之后运行，而不是替代理解：先通读任务与它触及的代码，端到端追踪真实流程，然后才开始爬梯。这一条在后文"不可懒惰"条款中被再次强调（"a small diff you don't understand is just laziness dressed up as efficiency"，一个你都不理解的小 diff 只是伪装成效率的懒惰）。从源码结构看，这条约束被 scripts/check-rule-copies.js 的不变量机制间接触及：该脚本虽未直接钉住这句话，但它钉住了阶梯第 2 级（in this codebase）等关键措辞，防止任何一份副本在同步时悄悄丢失规则要点。

规则级第 2 级：复用优先于重写

阶梯第 2 级是 Ponytail 相比"单纯少写代码"提示词最独特的一级——先查本代码库是否已有可复用的 helper、util 或模式。SKILL.md 长版本对此的解释更直白："A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop."（先找后写；重写几米之外已有东西是最常见的糟粕）。

这一级在 scripts/check-rule-copies.js 中被显式钉为规则不变量：

const INVARIANTS = [
  'in this codebase',                      // ladder rung: reuse what already exists (#217)
  ...
];

注释标明其来源是 issue #217——即历史上曾出现 Agent 无视库内已有工具而重复造轮子的真实漂移，团队通过把关键短语升级为必须逐字存在的不变量来防止回归。

根因修复原则

文件第 17 行给出 Bug 修复的判定法则：

Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.

报告里写的是症状。动手前先 grep 目标函数的所有调用方，在共享函数处一次性修复：在共享函数里加一个守卫，diff 比在每个调用方各加一个更小；而只补工单点名的那条路径，会让兄弟调用方继续带着同一个 bug。从源码结构看，这条原则同时是"懒惰"（更小的 diff）与"根因"（覆盖所有调用路径）的交汇点——它把"懒惰"从减少代码量升格为减少 bug 总量。

三、硬性规则清单：八条 Rules 逐条解读

文件 "Rules:" 段落列出了八条负向/正向约束，逐条对应其设计意图：

规则（原文要点）	设计意图
No abstractions that weren't explicitly requested	禁止未请求的抽象：没有单实现的 interface、没有单产品的 factory
No new dependency if it can be avoided	能避免就不加新依赖；SKILL.md 补充"Never add a new one for what a few lines can do"
No boilerplate nobody asked for	没人要的脚手架不写，"later can scaffold for itself"
Deletion over addition. Boring over clever. Fewest files possible	删除优先于添加；无聊优先于聪明（"clever is what someone decodes at 3am"）；文件数最少化
Shortest working diff wins, but only once you understand the problem	最短可运行 diff 获胜——但前提是你理解了问题；"The smallest change in the wrong place isn't lazy, it's a second bug"（在错误位置的最小改动不是懒惰，是第二个 bug）
Question complex requests: "Do you actually need X, or does Y cover it?"	对复杂需求要反问：你真的需要 X，还是 Y 就覆盖了？
Pick the edge-case-correct option when two stdlib approaches are the same size	两个等长的标准库方案中，选边界情况正确的那个——"lazy means less code, not the flimsier algorithm"（懒惰是少写代码，不是挑脆弱的算法）
Mark deliberate simplifications ... with a ponytail: comment naming the ceiling and upgrade path	凡是在已知天花板下有意切角的简化（全局锁、O(n²) 扫描、朴素启发式），必须用 ponytail: 注释标明天花板与升级路径

最后一条 ponytail: 注释约定值得单独展开。SKILL.md 给出了示例写法：

# ponytail: global lock, per-account locks if throughput matters

即注释必须命名天花板 + 给出升级路径。这条注释不是普通注释，它是被 skills/ponytail-debt/SKILL.md 消费的机器可读标记：/ponytail-debt 命令会"Harvest the ponytail: shortcuts you've deferred into a ledger, so 'later' doesn't become 'never'"（把你延期的 ponytail: 捷径收割进一本账本，让"以后再说"不会变成"永不再说"）。换句话说，紧凑规则文件里这 8 个字（ponytail: comment）背后连着一个技术债追踪技能，形成"简化 → 标记 → 回收"的闭环。

scripts/check-rule-copies.js 中 'naive heuristic'（天花板注释规则）和 'flimsier algorithm'（健壮变体规则）分别被钉为不变量，说明团队把这两条视为最容易在措辞改写中丢失的规则。

四、"Not lazy about"：安全例外清单

文件最后一行（第 30 行）是整个规则集的安全阀，原文继承如下：

Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested.

不可懒惰的清单包含六类：

1. 理解问题——读完、追踪真实流程后再选阶梯；
2. 信任边界的输入校验；
3. 防止数据丢失的错误处理；
4. 安全；
5. 可访问性（accessibility）；
6. 真实硬件需要的校准——"平台永远不是规格书上的理想态，时钟会漂移，传感器会偏差"，所以最小化模型不能吞掉校准旋钮。

这一行的工程化保障同样体现在 check-rule-copies.js 中，四个安全例外被逐一钉为不变量，注释说明了原因：

// pin each so a reword in either file can't silently drop one. Only validation
// was pinned before.
'input validation at trust boundaries',
'prevents data loss',
'security',
'accessibility',

即：以前只钉了输入校验一条，后来把"防数据丢失、安全、可访问性"全部钉住，防止某次措辞改写在某一份文件里悄悄丢掉其中一条安全例外。

"一个可运行检查"原则

同一行末尾还包含规则集中最容易被误解的一条：

Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

没有检查的懒惰代码等于没写完：非平凡逻辑（分支、循环、解析器、涉及钱或安全的路径）必须留下一个可运行的检查——逻辑坏了它会失败的最小单元，可以是 assert 式的 demo/__main__ 自检或一个小测试文件，不引框架、不用 fixture；而平凡的一行代码不需要测试，"YAGNI applies to tests too"（YAGNI 同样适用于测试）。这解释了 Ponytail 为什么在基准测试中能"100% safe"（见 README.md 的 agentic 基准：baseline、caveman、ponytail 三组安全分均为 100%，而裸的 "YAGNI + one-liners" 提示词只有 95%）——因为它保留了恰好一个安全检查，而不是零个。'ONE runnable check' 与 'Lazy code without its check is unfinished' 在 check-rule-copies.js 中同样被列为不变量。

五、实测效果：规则文件在真实基准中的表现

规则文件的价值不是宣言，而是可复现的输出对比。examples/ 目录提供了同一模型（Claude Haiku 4.5，temperature 1）、同一 prompt、无技能组与 Ponytail 组的逐字输出，examples/README.md 汇总了行数对比。以 examples/csv-sum.md 为例，任务为"读 sales.csv 并对 amount 列求和"：

无 Ponytail（20 行）：

import pandas as pd

df = pd.read_csv('sales.csv')
total_amount = df['amount'].sum()
print(f"Total amount: ${total_amount:,.2f}")

外加"Alternative methods"段落（csv 标准库版、带异常处理的 pandas 版）和一段推荐论述——这正是规则文件第 26 条（Question complex requests）和 SKILL.md 输出条款（"No essays, no feature tours"）针对的行为。

With Ponytail（3 行）：

import csv

total = sum(float(row['amount']) for row in csv.DictReader(open('sales.csv')))
print(total)

并附带一句符合约定格式的说明："Skipped: pandas, error handling, file closing, add when the CSV is large, malformed, or you need more analysis."——即 ponytail: 注释约定在"跳过说明"上的同款克制：跳过什么、什么时候再补回来。这 3 行方案同时命中了阶梯第 3 级（stdlib：csv 模块，而非 pandas 依赖）和第 6 级（一行完成核心逻辑），且末尾的"add when..."保留了升级路径，与第四节的"一个检查/明确例外"原则完全同构。

README 的 agentic 基准（真实 Claude Code 会话编辑真实 FastAPI + React 仓库，12 个功能工单，n=4）给出总体数据：ponytail 组相对无技能基线 LOC -54%、tokens -22%、cost -20%、time -27%，安全分 100%；其中过度工程陷阱（如日期选择器）收益最大——"date picker 404 to 23 lines"，对应的正是阶梯第 4 级（原生平台特性）：

<!-- ponytail: browser has one -->
<input type="date">

复现方式见 benchmarks/README.md：npx promptfoo eval -c benchmarks/promptfooconfig.yaml，完整方法学见 benchmarks/results/2026-06-18-agentic.md。

六、多 Agent 分发体系中这份文件的位置与一致性保障

Ponytail 的规则文本存在三个层级，.clinerules/ponytail.md 属于第二层：

层级	文件	角色
运行期真源	skills/ponytail/SKILL.md	插件宿主运行时加载的长版本：额外含 Persistence、Output 格式（[code] → skipped: [X], add when [Y].）、Intensity 三档（lite/full/ultra）对照表与逐档示例
紧凑真源	AGENTS.md	与 .clinerules/ponytail.md 同体的紧凑规则（AGENTS.md 末尾多一句自指备注），供 Zed、Amp、Jules、Antigravity 等读 AGENTS.md 的宿主使用
宿主副本	.cursor/rules/ponytail.mdc、.windsurf/rules/ponytail.md、.clinerules/ponytail.md、.qoder/rules/ponytail.md、.github/copilot-instructions.md 等 7 份	各宿主的项目级规则副本，正文必须与 AGENTS.md 逐字一致

一致性由 scripts/check-rule-copies.js 在测试期强制保障。其工作方式分两步：

1. 字节级对比：读取 AGENTS.md 作为 canonical 文本，剥掉末尾的自指段落后，与 7 份副本（含 .clinerules/ponytail.md）逐一对比；.cursor 与 .kiro 两份副本会先经 stripFrontmatter 去除宿主专属 frontmatter，Cline 这份则直接 trim 后全文比对——任何一个字不同都会报 drifted from AGENTS.md 并以退出码 1 失败：

const copies = [
  ['.cursor/rules/ponytail.mdc', stripFrontmatter],
  ['.windsurf/rules/ponytail.md', text => text.trim()],
  ['.clinerules/ponytail.md', text => text.trim()],
  ['.agents/rules/ponytail.md', text => text.trim()],
  ['.qoder/rules/ponytail.md', text => text.trim()],
  ['.github/copilot-instructions.md', text => text.trim()],
  ['.kiro/steering/ponytail.md', stripFrontmatter],
];

2. 不变量检查：SKILL.md 长版本无法与紧凑版字节比对，改为断言 9 条"承重"规则短语（in this codebase、naive heuristic、ONE runnable check、flimsier algorithm、四个安全例外、Lazy code without its check is unfinished）必须同时逐字出现在 SKILL.md 与 AGENTS.md 中——任何一份改写措辞都会触发失败，提示开发者把修改同步到所有副本。

脚本注释里也写明了升级路径："Upgrade path: generate the copies from SKILL.md if this ever misses a real drift."（如果这种金丝雀检查漏掉真实漂移，就从 SKILL.md 生成各副本）。开发流程上，README 的 Development 章节要求修改紧凑规则文本后运行 node scripts/check-rule-copies.js 与 npm test。

与插件宿主注入路径的差异

对于支持钩子的宿主（Claude Code、Codex、pi 等），规则不是静态文件而是运行时注入：hooks/ponytail-instructions.js 的 getPonytailInstructions(mode) 会读取 SKILL.md，经 filterSkillBodyForMode 按当前强度档（lite/full/ultra）过滤——只保留该档的强度表行和对应示例，规则条目则逐字保留；SKILL.md 缺失时回退到内置的 getFallbackInstructions 紧凑文本。从源码结构看，这份回退文本正是 .clinerules/ponytail.md 同一套内容的运行时变体。而 Cline 这类指令型宿主不走注入：它没有 /ponytail 命令、没有模式切换、没有钩子，整个规则文件就是全部行为——这也是为什么 .clinerules/ponytail.md 必须自洽：第 5 节引用的"100% safe"、"一个可运行检查"等承诺，在 Cline 场景下完全由这 30 行文本承担。

七、在 Cline 中使用与验证

使用方式与 README.md Install 章节、docs/agent-portability.md 的说明一致：

1. 接入：把本仓库的 .clinerules/ponytail.md 复制到目标项目的 .clinerules/ 目录，Cline 即自动将其作为项目规则加载，无需任何配置、钩子或 Node 环境（Node 依赖仅存在于 Claude Code/Codex 插件的生命周期钩子路径，与本文件无关）；
2. 行为：Agent 在每次响应中按七级阶梯自检，产出最短可运行 diff，并遵守"一个可运行检查"与 ponytail: 天花板注释约定。注意此层不提供 /ponytail 命令、lite/full/ultra 档位切换——这些属于技能宿主能力，指令型宿主"load the always-on ruleset without the commands"；
3. 退出：删除项目中的该规则文件即完全卸载（README Uninstall 表中 Cline 一行的操作正是 "Delete the copied rule file"）；
4. 校验：修改规则文本后，在仓库内运行 node scripts/check-rule-copies.js 确认 7 份副本未漂移、9 条不变量仍在 SKILL.md 与 AGENTS.md 中同时存在，再跑 npm test。

与 SKILL.md 长版本的差异速查

如果需要对比这份紧凑文件与 skills/ponytail/SKILL.md 的完整差异，可关注以下几点（紧凑版被压缩掉、但语义由插件宿主版本保留的内容）：

• 输出契约：SKILL.md 规定 "Code first. Then at most three short lines" 与模式化格式 [code] → skipped: [X], add when [Y].，以及"解释比代码长就删掉解释"；紧凑版把输出约定并入规则第 6 条（Question complex requests）的语义中；
• 强度档位：lite/full/ultra 三档表与逐档缓存示例（lru_cache vs 手写 TTL 缓存）只存在于 SKILL.md；
• 持久性条款（"ACTIVE EVERY RESPONSE. No drift..."）与边界条款（"stop ponytail / normal mode" 退出语、与 Caveman 的分工）同样只在 SKILL.md 中展开。

从源码结构看，check-rule-copies.js 的设计（紧凑版字节一致 + 长版不变量金丝雀）正是为了在"单文件即可用"的 Cline 场景与"完整技能体验"的插件场景之间维持语义等价：Cline 用户拿到的是规则的最小完整闭包——阶梯、规则、安全例外、检查义务，一条不缺。

八、小结

.clinerules/ponytail.md 用一个 30 行文件承载了 Ponytail 方法论的全部可执行内核：以"七级阶梯"压缩代码产出，以"根因修复"压缩 bug 总量，以八条硬规则封住抽象/依赖/样板三个膨胀入口，以六项"不可懒惰"清单和一个可运行检查守住安全底线，再以 ponytail: 天花板注释把有意简化变成可追踪的技术债。它不是孤立文案，而是受 scripts/check-rule-copies.js 字节级与不变量双重校验的多副本规则体系中 Cline 的那一份，其效果可由 examples/csv-sum.md 等基准产物（20 → 3 行）与 benchmarks/ 目录的可复现测试直接验证。对使用 Cline 或任何读取 .clinerules/ 的 Agent 的开发者而言，复制这一个文件，即可让"最好的代码是从未写下的代码"成为默认行为。