技能目录

规范本身的写法

给 coding agent 的执行参考。每节结构：为什么 → 做法 → 判据 → 反例。

这一篇讲写给 agent 的规范文本该怎么写才被照做。判别标准只有一个：改完之后 agent 的行为有没有变。

0. 目录

原则 / 推导依据 / 判据
判据：唯一不可省的一段
祈使句与主语
给默认不给菜单
解释 why，不用全大写
不解释模型已经知道的东西
不写泛泛的最佳实践
多步流程清单化与验证闸门
覆盖力测试
错误信息即自我纠正工具
自造术语的处理
反模式
反例速查表

1. 原则 / 推导依据 / 判据

每条原则三段：

**原则**：默认值与阈值是设计问题，不是实现问题。

**推导**：反馈说「不好用」时，默认动作是调参数；但两次改判都只动了取值层，
说明机制层本来就对。此时重写机制是在修一个不存在的问题。

**判据**：收到「手感不对」类反馈时，先问「机制层还是取值层」，并写下答案。

为什么三段缺一不可：缺原则（你写的是资料）；缺推导（agent 在遇到反例时会绕过它）；缺判据（你写的是愿望）。

三条纪律：

原则句里不含项目名词——判别见 abstracting.md 第 1 节的代换测试。
推导必须能回答「不这样会怎样」，且那个后果是具体的。「会导致质量问题」不合格；「前几轮会反复修在错误的层次上」合格。
判据可执行——见下一节。

判据：正文每条原则三段齐全，且推导段能指出一个具体的失败后果。

2. 判据：唯一不可省的一段

判据是「原则」和「愿望」的分界线。

写法	类型	为什么
「旁白只说画面给不出的话」	愿望	没人会照做——它没说怎么算「给不出」
「删掉这句，玩家损失的是一个信息还是一次判断？」	判据	两三分钟能答，是/否明确

判据的两种形式，优先第一种：

机械可查：grep 退出码、枚举计数、字段存在、禁用集为空、max() 结果不含某字段。→ 能进评测集的 good 级断言。
人工过一遍：两三个能在几分钟内给出是/否的问题。→ 标 weak_manual。

写法要求：判据要写成一个问题或一个动作，不是一句陈述。「一致性良好」是陈述，「同一条事实是否只有一个数据源」是问题。

判据：正文每条判据都能被写成脚本检查，或被人在一两分钟内回答。答案有歧义的判据要加量化限定（「至少两类」比「分类清楚」可用）。

3. 祈使句与主语

动词开头，无主语。「按 X 分类」，不是「你应该按 X 分类」。

去掉的词：请、应该、尽量、最好、推荐。其中「应该」和「尽量」尤其有害——它们把一条规则降级成一条偏好，遵守率显著下降。

去掉假设性副词：显然、众所周知、简单。它隐含「你可能不知道」，对已经知道的内容是纯噪声。

判据：正文里 grep 不到「应该」「尽量」「最好」「显然」。

4. 给默认不给菜单

写清推荐路径与例外条件。

菜单式：「可以用 A 抽取，也可以用 B 抽取，也可以手工整理。」默认式：「用 A 抽取。B 在素材来源异构时更好（C 的前提是素材少于千行且 A 的开销不划算）。」

为什么：列一串选项等于把选择权交给 agent 的先验，而它的先验是最常见的那种做法——在你的项目里通常是错的。规则的价值在于它否定了默认。

例外条件必须写清触发条件，不写「特殊情况下另议」——那是把决策推回给 agent，而且它会随便决定什么算特殊。

判据：正文里没有不带例外条件的并列选项列表；每条例外都带触发条件。

5. 解释 why，不用全大写

写 ALWAYS / NEVER 是黄旗：它把一条有理由的规则降级成一条需要外部权威的规则。带推理的指令（做 X，因为 Y 会导致 Z）遵守率显著高于生硬的祈使句。

强制式：「MUST 给每条原则写判据。」带理由式：「给每条原则写判据，因为没有判据的原则是没人会照做的愿望——这类条目在实际交付里占大多数。」

需要绝对措辞时（安全、数据不可逆），绝对措辞 + 理由并列，不二选一。

过度使用绝对词的代价：文档里 MUST/NEVER 超过三处，读者会把它整体降级为语气词。

判据：正文里 MUST/NEVER/CRITICAL 的出现次数可数且 ≤3；每处都有紧邻的理由。

6. 不解释模型已经知道的东西

为什么：模型已经掌握的知识，重复一遍是纯预算消耗，且会稀释真正的约束——读者（和模型）对文档的信任是总量分配的。

具体例子：不要解释什么是 git commit、不要解释什么是幂等、不要解释 JSON 语法。

反向的例子（要解释）：这个项目特有的坑、这个领域里违反直觉的事实、模型大概率会猜错的地方。官方认为最高价值的段落是 Gotchas——与环境相关、defy 合理假设的事实。

判据：删掉某段解释后，agent 的行为会变吗？不变就删。

7. 不写泛泛的最佳实践

「妥善处理错误」「保持代码整洁」「注意用户体验」「做好充分测试」——这类是官方点名的失败模式。它们没有可执行内容，写进去的唯一效果是让文档显得完整。

替代写法：把每一条泛泛的最佳实践追问到底——**具体指什么？由谁在什么时刻执行？失败的形态是什么？**答不出来就删，答得出来就写成判据。

泛泛：「做好测试。」展开：「每个 case 的断言要标 strength；UNMEASURED 的项不编分数。编一个分数比留空更糟——它会让报告看起来完整而其实不可信。」

判据：正文里每条陈述都能被追问成「谁在什么时刻做什么」。追不出来的删掉。

8. 多步流程清单化与验证闸门

多步写成可勾选清单，每步以可验证动作结尾。

**最小可勾选清单**

- [ ] 20 条触发查询写完（10 正 10 近似负，正例含至少 3 条关联不明显的）
- [ ] 8–10 个输出 case 写完，每条断言标了 strength
- [ ] 每条至少跑 3 次

验证闸门是流程里的硬停止点。 最好的闸门是顺序要求：先建评测再写文档，靠顺序强制；靠「请先建评测」不是——agent 会先写文档，然后补评测。

每步要有失败出口：「这一步没做出来怎么办」比「这一步要做什么」更能防错。好的失败出口是一句可判断的错误信息（见第 10 节）。

判据：正文里每个清单项都有可机械检查的完成条件；流程里存在至少一个顺序闸门；每个清单有明确的失败出口。

9. 覆盖力测试

问：如果 agent 只做步骤里明确写明的事，结果是否可接受？

可接受 → 步骤有漏洞。它能跳过，且跳过之后还能交差，那这条步骤没有强制力。补上遗漏的那一步。

不可接受 → 覆盖力足够。

反面测试：删掉整个流程里最显然的一步，输出质量会不会掉？不会，说明这步是装饰。

判据：清单里没有任何一步是「不做也能交差」的。

10. 错误信息即自我纠正工具

好的错误信息让 agent 下一轮自己纠正；差的让它再问一次。

差的	好的
「格式错误」	「每行必须是 `原话 \| 原则 \| 判据` 三段；第 7 行只有两段」
「测试失败了」	「case o03 的断言 2 两种配置下都 fail，说明 skill 里缺了这条内容」
「触发率太低」	「负例里 n04 n07 被触发——它们共享『写入正式文档』这个概念，收窄 description 的边界」

三条写法要求：

指出具体位置——行号、字段名、case id、文件名。
指出下一步动作——「改 X」而不是「注意 X」。
说明后果——「这会让合并阶段丢信息」比「这是不允许的」有用。

「这是不允许的」是零信息的：它没有告诉 agent 正确形态是什么，所以它下一轮只能再问一次。

判据：文档里出现的每条错误提示都带具体位置和下一步动作。

11. 自造术语的处理

优先用领域内已存在的词。 必须造词时：

在术语表里定义一次。
标注为自建框架——不加标注，读者会以为它是公认概念，然后按公认概念的强度使用它。
通则正文里不出现只在本次工作里存在的名词。

自建框架在正文也要标注，不只是术语表里。正文里的标注比术语表里的更重要——因为正文是读者实际会读的地方。

判据：术语表里每项都能回答「这个词在本次工作之前就存在吗」。答不出且未标「自建」的，违规。

12. 反模式

症状	后果	治疗
全大写 MUST/NEVER 成串	读者整体降级为语气词	换解释 why
愿望式原则	没人照做	补判据
并列选项清单	agent 选先验，而先验通常是错的	给默认 + 例外条件
「应该」「尽量」	规则降级成偏好	删
泛泛最佳实践	无可执行内容	追问到底或删
解释已知常识	稀释真约束	删
无位置的错误提示	agent 再问一次	加位置 + 下一步
流程里没有闸门	顺序被跳过	用顺序强制，不用叮嘱
抽象掉 why	原则立不起来	加推导

13. 反例速查表

反例	为什么错	正确做法
「MUST 给每条原则写判据」	无理由的强制降低遵守率	解释 why：没判据的原则是愿望
「你应该尽量写得清楚一点」	偏好而非规则	「每条原则写三段：原则 / 推导 / 判据」
「旁白只说画面给不出的话」	愿望：没定义怎么算给不出	「删掉这句，玩家损失的是信息还是判断？」
「妥善处理错误」	泛泛最佳实践	追问到具体步骤，或删
「注意一致性」	同上，且不可追问了	删
「可以用 A 也可以用 B」	agent 会选先验	「用 A。B 在 X 情况下更好」
「显然应该先建评测」	假设性副词 + 叮嘱不构成闸门	用清单顺序强制
「格式错误」	无位置、无下一步	「第 7 行只有两段，需三段」
解释什么是幂等	浪费预算，稀释约束	删
自造词不加标注	伪装成共识	术语表 + 正文都标「自建框架」
「详见参考」	不是错误信息，是缺失	「如果 X 则读 y.md」