波仔
🧡 第五章 CLAUDE.md：给AI一张地图
📄 一句话概括

规则文件有两种失败方式：写太少它不听话，写太多它抓不住重点；二百行的项目百科里，真正影响行为的可能只有三行。

📝 本节和前面几节的关系

上一节说了这份文件为什么重要，这一节讲最容易犯的那个错误：写太多。

一、两种失败方式

写太少：它不知道你的规矩，于是按自己的默认来，按默认来往往就是按最差的方式。 写太多：一份二百行的百科塞进上下文，真正影响行为的那三行被稀释了。 第二种失败更隐蔽——因为你确实写得很认真。

二、什么叫【护栏】

护栏只写会改变它行为的条目：范围、风格、验证方式、不能碰的东西。 护栏型规则的特征：每一条都能被一次具体任务验证——要么它遵守了，要么它没遵守。 本节的演示测的就是这一点：三条护栏，三次验证，全都用得上。

三、什么叫【百科全书】

项目历史、团队八卦、完整接口文档、通用教程——这些它靠读你的项目就能得到，写了只是占用注意力。 判据在第 5.3 节：这条信息它能不能自己读出来？能，就别写。 还有一个现实理由：没人维护得动。一份要每周同步的规则文件，三个月后就过期了。

四、正确的顺序

先写五条护栏，跑一周，再加。每次它犯了错，补一条。 这样长出来的规则文件，每一行都有来历，也每一行都还在被用。 从零开始写一份完美规则文件是不现实的——你并不知道自己会犯什么错。

五、动手 Demo：从【护栏】开始，别写【百科全书】

下面用三条护栏去验一条真实指令，看命中率。

thin = [u"改代码前先说范围", u"不改测试目录", u"交付前跑测试"]
cases = [(u"改代码前先说范围", True, u"命中：先列范围"),
          (u"不改测试目录", True, u"命中：用户明说了别动"),
          (u"交付前跑测试", False, u"没命中：用户没提测试")]

实跑输出：

--------------------------------------------------------------------
从【护栏】开始，别写【百科全书】
--------------------------------------------------------------------

写规则文件有两种失败方式：写太少它不听话，写太多它抓不住重点。先看差距：

一份【护栏】型规则，只 3 行：
    - 改代码前先说范围
    - 不改测试目录
    - 交付前跑测试

来测一条指令：把项目里所有日期格式统一，注意别动测试文件。

    [命中] 改代码前先说范围       命中：先列范围
    [命中] 不改测试目录         命中：用户明说了别动
    [没中] 交付前跑测试         没命中：用户没提测试

三条里命中 3 条。就算这份护栏再精简，它**每一条都在被用上**。

反过来，一份二百行的项目百科里，真正影响行为的可能只有三行，
**剩下的一百九十七行是在稀释那三行的注意力**。所以从护栏开始。

护栏型规则的判据就是这一列：每一条都能被一次具体任务验证。 而二百行的项目百科里，真正影响行为的可能只有三行，剩下的一百九十七行在稀释那三行。

30 秒实验

  1. 把你现在想写的规则全列出来，然后逐条问：它能改变它的行为吗？不能就划掉。
  2. 给这份文件定一个上限：超过多少行就停下来重新审一遍。

常见误区

  1. 追求【一次写全】。你并不知道自己会犯什么错，规则是长出来的，不是设计出来的。
  2. 把项目介绍、团队背景写进去。那不是护栏，是给人看的文档。
自测三问（点开对答案） 1. 规则文件的两种失败方式是什么？ —— 写太少它按默认来；写太多把真正有效的条目稀释掉。 2. 护栏型规则的判据是什么？ —— 每一条都能被一次具体任务验证——要么遵守了，要么没遵守。 3. 为什么不该一次写全？ —— 你并不知道自己会犯什么错；规则是长出来的。

相关笔记