把「每次都要交代一遍」的话写进仓库：一份项目说明该写什么

用了两周之后，大部分人都会遇到同一件事：每开一个新会话，都要把「测试怎么跑」「这个目录别动」「日志写在哪」再说一遍。说到第三十遍的时候你会意识到，这些话不该活在对话里，该活在仓库里。

这就是项目说明文件干的事。名字不重要——Claude Code 2.1.277（2026 年 9 月 18 日）之后，项目里没有 CLAUDE.md 时它会去读 AGENTS.md，所以已经在用别家工具的人可以只维护一份。重要的是里面写什么。

先搞清楚它是什么：不是文档，是「入职须知」

很多人第一次写这个文件，写成了项目文档：架构图、模块说明、技术选型理由。写完两百行，然后发现没什么效果。

原因是搞错了读者。这份文件的读者不是「想了解这个项目的人」，是一个每次来都失忆、但手很快的新同事。他不需要知道你们为什么选了 Postgres，他需要知道：跑起来用哪条命令、哪个目录碰了会出事、提交信息按什么格式写。

一个简单的判断标准：这句话你在对话里说过两次以上吗？ 说过，就该进这个文件。没说过，就先别写——你猜的「他可能需要知道」，九成是多余的。

五块内容，缺一块就会在某个地方付代价

第一块：怎么跑起来

最基础，也最容易写得不够具体。

括号里那句「不要用 npm」才是重点。命令本身它能猜到，猜不到的是你们踩过的坑。

第二块：哪些地方不许动

这一块的收益最直接。写法要具体到路径：

为什么值得单独一块：事后发现它动了不该动的东西，成本远高于事先写两行字。 尤其是迁移文件和生产配置这两类，一旦被改，回滚的代价不是回滚代码那么简单。

第三块：本项目的约定

命名、目录分工、提交信息格式、注释语言、日志该往哪写。这些东西它从代码里能推断出一部分，但推断会在边界上出错——比如你们有两种命名风格并存（老代码一种、新代码一种），它多半会学到错的那种。

写清楚「新代码一律按 X」，比让它自己猜准得多。

第四块：踩过的坑

这一块的价值最高，因为模型的通用知识里没有你们项目的特例。

形式就是一条一条的事实：

每一条都是曾经让人浪费过半小时的东西。写进去之后，同样的半小时不会再浪费第二次。

第五块：验收标准

告诉它「什么算做完了」。这一块很多人没写，结果就是它总在「我已经完成了」和你「这还没完」之间来回。

第三条尤其值得写。「顺手把旁边那段也优化了」是这类工具最常见的越界行为，而它每次都觉得自己在帮忙。

一份可以直接抄的骨架

第一版写 30 到 60 行就够了。 不要一次写成规章制度——你自己都记不住的规则，执行起来也会打折。

三个常见写法，都是负收益

第一，把整个架构文档搬进来。 两百行的背景知识会挤占上下文，而且其中九成跟当前任务无关。它读完之后手上的「有效信息密度」反而下降了。架构文档留在 docs/ 里，需要时让它去读。

第二，写成愿望清单。 「代码要优雅」「注意性能」「保持可读性」这类话没有任何操作性，等于没写。换成可验证的表述：「单个函数不超过 50 行」「新增接口必须有入参校验」。

第三，写完就不管了。 这份文件会过期。判断它该更新的信号只有一个：你又在对话里解释了一遍同一件事。 每次出现这个信号，就去加一条。

一个真实的例子：同一段任务，有说明和没说明的差别

拿一件很普通的活做对照——「给这个接口补上入参校验」。

没有项目说明时，一轮下来通常是这样：它先花几轮读文件猜项目结构，然后按它见过最多的那种写法补校验（很可能不是你们用的那个库），顺手把旁边两个函数也「优化」了，最后给你一个 11 个文件的改动。你 review 完，发现有用的只有 2 个文件，剩下 9 个要回滚。

有项目说明时，它第一轮就知道三件事：校验用哪个库、新代码放哪个目录、不许动旁边的东西。改动落在 2 个文件上，你三分钟看完。

差别不在模型聪不聪明，在你有没有把「这个项目的特例」交给它。模型的通用知识里有一百种写校验的方法，你们项目里只接受一种——这一条信息不写下来，它每次都得猜，而且每次猜的可能不一样。

顺带说一个副作用：改动范围变小之后，你的 review 质量会明显上升。11 个文件你会开始跳着看，2 个文件你会逐行看。改动规模直接决定了你的把关质量，这件事比「它写得对不对」更影响最终结果。

什么时候该拆成多份

一份文件写到一百多行，会开始出现两个信号：你自己找东西要翻半天，以及里面有些规则只对某一个模块成立。

这时候拆：根目录那份只留全局的东西，模块级的规则放到各自的目录里。 大多数工具会在进入某个目录干活时读那个目录下的说明，全局那份保持精简。

拆的判断标准很简单：这条规则是不是对整个仓库都成立？ 是就留在根目录，不是就下沉。一条只对前端目录成立的命名规则留在根目录，它会在你改后端的时候白白占上下文，还可能被误用。

多人仓库怎么办

两个实际问题。

要不要提交到 git？ 要。这份文件的价值就在于团队共享——你踩过的坑，别人不用再踩一遍。真有个人偏好（比如你习惯的快捷命令），放到本地不提交的那份里，不要混进团队共用的。

并行开发怎么避免互相踩？ 如果多个人（或多个会话）同时在一个仓库里干活，在「不许动」那一块里加上「别人正在改的模块」。更彻底的做法是各自开独立的工作树，各干各的，互不影响——这个习惯在两个人以上的项目里省下的时间，比任何提示词技巧都多。

验收：怎么知道它真的读了

写完之后做一次验证，别假设它生效了。

新开一个会话，问一句：

如果它复述的是你写的内容、并且点名了文件，说明生效了。如果它回答的是通用的最佳实践，那么大概率是文件没被读到——检查文件名和位置是不是对的，以及是不是被 .gitignore 挡住了。

最后

这份文件的投入产出比，大概是所有工程习惯里最高的一个：写一次，半小时；之后每个会话都省五分钟。

而且它有复利：每加一条坑，就少一次返工；返工少了，你会更敢把它放到重要的链路上；放得越多，你越能发现新的坑该写进去。三个月之后回头看，这份文件会是整个仓库里最值钱的一个文件。