一、三份指令的写法

模糊版：「代码要整洁、注意命名、别写重复代码、提交信息写清楚」。四条全落不成检查。 流水账版：列了十二条，其中三条带数字。能落成检查的只有那三条。 精准版：五条，每条都有阈值，比如「行宽不超 88」「函数不超 50 行」。五条全能验。

差别不在长短。流水账版比精准版长一倍多，能用的反而更少。 判据就一句：这句话能不能写成一个函数，输入是代码，输出是「过」或「不过」。

二、真跑：五条约束查六个文件

把精准版那五条写成五个检查器：行宽、函数长度、名字长度、有没有 TODO、有没有模块说明。 拿六个小程序文件去查，一共报出三处：一个单字母函数名、一处 TODO、一个没有模块说明的文件。 三处都不致命，但都是「人眼容易放过、机器一查就中」的那类。

更关键的是：模糊版那四条，一处都报不出来——不是因为没有违规，是因为没法判断。 所以「写了等于没写」不是修辞。落到检查上，它就是零条。

三、精准表达的三条公式

第一条：把形容词换成数字。「行宽不要太长」改成「行宽不超 88」。 第二条：把范围说清。「改相关文件」改成「只改 src 下的 py 文件」。 第三条：把否定换成动作。「别乱改」改成「改之前先跑一遍测试，失败就停」。

三条做的是同一件事：把「我想要的」翻译成「你能验的」。 第三条尤其重要：否定式指令只说了不许什么，没说该做什么，模型只能自己补——补出来的往往不是你想要的。

四、分步确认：早一步发现，少四步返工

演示里一个八步的任务，第四步开始走偏。三种做法，返工量差很多。 一次说完：第八步交活才发现，白干五步。 分三段（3 / 6 / 8）：第六步末发现，白干三步。

每步确认：第四步末就发现，白干一步。 但每步确认的代价是交互次数翻八倍。 所以实操上按风险分段：不可逆的步骤（删数据、发布、改配置）前面必停，可逆的步骤连着做。

五、指令该写在哪一层

项目级的规矩写根目录指令文件：所有人所有任务都适用，比如「用哪个测试命令」。 模块级的约定写子目录指令文件：只在改这个模块时读进来，比如「这层的数据库访问必须走仓储」。 这一次的要求直接对话里说：不进文件，不污染长期指令。

最常见的错是把「这一次的要求」写进长期指令，写多了之后每条都被稀释——指令一长， 重要的和不重要的就分不出来了。 一个自查：把文件里每一行都问一遍「三个月后还成立吗」。不成立的挪出去。

六、动手 Demo：三份 CLAUDE.md，只有一份能被机器检查

把「指令写得好不好」变成可数的东西：这条约束能不能落成一个检查器。 五个检查器真的去查六个文件，看能报出几处。

def width(src):
    return [i + 1 for i, ln in enumerate(src.split(u"\n")) if len(ln) > 88]

def todo(src):
    return [i + 1 for i, ln in enumerate(src.split(u"\n"))
            if u"TODO" in ln or u"FIXME" in ln]

实跑输出：

--------------------------------------------------------------------
三份 CLAUDE.md，只有一份能被机器检查
--------------------------------------------------------------------

  指令写得好不好，有个硬判据：能不能落成一条检查。
  落不成检查的，等于「希望你这么做」，而不是「要求你这么做」。

  ① 三份指令的写法
  --------------------------------------------------------------------
| 版本 | 长什么样 | 能不能查 |
|---|---|---|
| 模糊版 | 代码要整洁、注意命名、别写重复代码、提交信息写清楚 | 4 条全落不成检查 |
| 流水账版 | 列了十二条，其中三条带数字 | 3 条能落成检查 |
| 精准版 | 五条，每条都有阈值 | 5 条全能落成检查 |


  ② 真跑：五条约束查六个文件
  --------------------------------------------------------------------
| 约束 | 报出几处 | 前两处 |
|---|:---:|---|
| 行宽不超 88 | 0 处 | — |
| 函数不超 50 行 | 0 处 | — |
| 名字不短于两字 | 1 处 | a.py:3 |
| 没有 TODO | 1 处 | b.py:4 |
| 模块有 docstring | 1 处 | d.py:1 |

  五条约束在六个文件里一共报出 3 处。而模糊版那四条，一处都报不出。
  有意思的是 a.py 和 d.py：a.py 函数名就一个字母，d.py 连 docstring 都没有。
  这两处靠人眼看很容易放过，靠检查就是两条红色。

  ③ 精准表达的三条公式
  --------------------------------------------------------------------
  - 把形容词换成数字：「行宽不要太长」改成「行宽不超 88」。
  - 把范围说清：「改相关文件」改成「只改 src 下的 py 文件」。
  - 把否定换成动作：「别乱改」改成「改之前先跑一遍测试，失败就停」。
  三条都是同一个动作：把「我想要的」翻译成「你能验的」。

  ④ 分步确认：早一步发现，少四步返工
  --------------------------------------------------------------------
| 做法 | 什么时候发现走偏 | 返工多少 |
|---|---|---|
| 一次说完 | 第 8 步后交活 | 白干 5 步 |
| 分三段（3 / 6 / 8） | 第 6 步末发现 | 白干 3 步 |
| 每步都确认 | 第 4 步末发现 | 白干 1 步 |

  演示里第八步交活，第四步开始走偏。一次说完要白干 5 步；分三段只赔 3 步。
  但「每步都确认」的代价是交互次数翻八倍。所以实操上按风险分段：
  不可逆的步骤（删数据、发布、改配置）前面必停，可逆的步骤连着做。

  ⑤ 指令该写在哪一层
  --------------------------------------------------------------------
| 内容 | 写哪儿 | 为什么 |
|---|---|---|
| 项目级的规矩 | 根目录 CLAUDE.md | 所有人所有任务都适用 |
| 模块级的约定 | 子目录 CLAUDE.md | 只在改这个模块时读进来 |
| 这一次的要求 | 对话里直接说 | 不进文件，不污染长期指令 |

  最常见的错是把「这一次的要求」写进 CLAUDE.md，写多了之后每条都被稀释。
  ! 五个检查器是演示用的简化实现，规则本身可换成团队自己的；分步的步数是设定的。

①三份写法：模糊版四条全落不成检查、流水账版十二条里三条能验、精准版五条全能验。差别不在长短。 ②五个检查器查六个文件，报出三处：单字母函数名、一处 TODO、一个没有模块说明的文件。 都是人眼容易放过、机器一查就中的那类。 ③模糊版那四条一处都报不出——不是没违规，是没法判断。所以「写了等于没写」不是修辞。 ④分步确认：一次说完白干五步、分三段白干三步、每步确认白干一步。按风险分段，不可逆的步骤前面必停。

30 秒实验

1. 再加一条检查「每个函数都有类型标注」，重跑一遍。六个文件里报出几处？这条约束该算精准还是模糊？
2. 把行宽阈值从 88 改成 72，重跑一遍。报出的处数变了，这说明什么？阈值定得太严会有什么后果？
3. 给「分三段」改成「分两段（4 / 8）」，重跑一遍。它和每步确认差几步？什么情况下两段就够？

常见误区

1. 写一堆形容词。落不成检查，等于没写。
2. 以为写得越长越细。指令一长，重要的和不重要的就分不出来。
3. 只写否定式。「别乱改」没说该做什么，模型只能自己补。
4. 把这一次的要求写进长期指令。写多了会把真正的规矩稀释掉。
5. 八步任务一次说完。走偏了要到最后交活才发现，返工最贵。

一个人会写了，下一节讲怎么让一个团队都这么写：四级配置怎么合。

• ☐ （本篇完，下一篇 10.6 团队落地：从个人到组织的跃迁）

相关笔记

• CLAUDE.md 写作范式：指令文件的加载层级
• 团队落地：从个人到组织的跃迁：四级配置怎么合
• Claude Code 橙皮书 · 索引
• 🐎 Claude Code 实战 · 索引