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

规则文件的第一价值不是省字，是让每一次开工都从同一个起点开始——它把你反复交代的东西变成只交代一次。

📝 本节和前面几节的关系

上一章讲的是单次任务里怎么配合，这一节讲一件跨任务、跨会话都长期生效的东西：给它的地图。

一、先算那笔账

假设你每次开工都要交代同样五条要求：只改某个目录、不要重命名、不要升级依赖、交付前跑测试、提交信息写中文。 口头交代，第十次仍然要交代一遍；写进文件，第一次之后就省掉了。 省下的字不算什么。要紧的是另一件事：

二、它真正解决的是【每次都从同一个起点开始】

口头交代的版本会漂：这次多说一句、下次忘了说，同一个项目在不同会话里规矩不一样。 规则文件把这条钉在文件里，不靠记性。 所以它的价值不在省事，在一致性——同一个项目，今天和下个月用同一套规矩。

三、为什么说它是最重要的文件

项目里有两类文件：一类是给程序看的（源码、配置），一类是给它看的（规则文件）。 第一类写错了程序会报错；第二类写错了它只是【默默地做错事】。 因为不出错，所以更重要——你不会被提醒。

四、一个直白的说法

你花多少时间在写代码上，就该花差不多多少时间在告诉它怎么干这份活上。 这不是额外开销，这是这份工作本来就有的成本——你只是第一次把它写下来了。

五、动手 Demo：同一句话，交代十次的代价

下面把五条要求的两种交代方式并排算账。

rules = [u"只改 src 目录", u"不要重命名文件", u"不要升级依赖",
         u"跑完测试再交付", u"提交信息写中文"]
per = sum(len(r) for r in rules)
T([u"每次口头交代", u"%d 字" % per, u"%d 字" % (per * 10)], [16, 16, 16])
T([u"写进规则文件", u"%d 字" % per, u"0 字"], [16, 16, 16])

实跑输出：

--------------------------------------------------------------------
同一句话，交代十次的代价
--------------------------------------------------------------------

先算一笔账。假设你每次开工都要交代同样五条要求：

    规则内容：只改 src 目录；不要重命名文件；不要升级依赖；跑完测试再交付；提交信息写中文

五条加起来 36 个字。分两种做法：

  做法             第 1 次     第 10 次     累计多写的字
  -------------------------------------------------------
  每次口头交代     36 字       36 字        360 字
  写进规则文件     36 字       0 字         36 字

差 324 个字不算什么，要紧的是**它每次都要先读一遍你的项目才知道你是谁**。
规则文件的第一价值不是省字，是**让每一次开工都从同一个起点开始**。

字数的差距只是表象，真正的差别在下一句：它每次都要先读一遍你的项目才知道你是谁。 所以规则文件的第一价值不是省字，是每次开工从同一个起点开始。

30 秒实验

  1. 数一数：你现在口头交代过几次同样的要求？超过三次就写进文件。
  2. 想一想你的项目里有哪些【它做错了也不会提醒你】的地方——那些正是规则文件该管住的。

常见误区

  1. 把规则文件当成给新人的文档。它的读者是它，不是人；写人话、写指令、写红线。
  2. 只在出问题时才想起来写它。规则是日常文件，不是事故报告。
自测三问（点开对答案） 1. 规则文件的第一价值是什么？ —— 让每一次开工都从同一个起点开始——一致性，不是省字。 2. 为什么它比源码更重要？ —— 源码写错会报错，规则写错它只是默默地做错事——你不会被提醒。 3. 口头交代的根本缺陷是什么？ —— 版本会漂：这次多说一句、下次忘了，同一个项目规矩不一样。

相关笔记