CLAUDE.md：让AI编程助手记住项目规范

一、问题：为什么每次都要重复交代

智能编程助手已经深度介入日常开发流程，但一个普遍存在的摩擦点是：上下文的丢失。每开启一个新会话，助手对项目一无所知——它不知道这个仓库用哪个包管理器，不知道依赖清单是否允许随意变动，不知道哪些目录属于“只读”区域，更不会主动在改完之后跑一遍测试。

于是开发者被迫在每次对话开头粘贴一段几乎相同的说明：

• 本项目使用 pnpm，请不要改用 npm；
• 不要随意新增依赖，确有需要先说明理由；
• 不要修改与本任务无关的文件；
• 完成后请运行测试并汇报结果。

这些内容有一个共同特征：它们不是针对某一次任务的指令，而是长期有效的项目级约定。把它们反复写进一次性提示词，本质上是用一种易失的介质承载稳定的知识，代价有三：

1. 重复劳动：每次会话都要重新组织语言，长文本还会挤占上下文窗口；
2. 一致性差：不同成员写的版本措辞不一，助手理解到的约束强度也不同；
3. 容易遗漏：忙起来只交代一半，剩下的约定等于不存在。

正确的做法是把这类稳定知识从“对话”迁移到“文件”，让工具在进入项目时自动加载。这正是项目级规范文件（下文以 CLAUDE.md 指代此类文件）的价值所在。

二、定位：它不是项目说明书

在动手写之前，必须先厘清这份文件的定位，否则很容易写成一份臃肿的 README 副本。

项目说明书回答“这个项目是什么”：架构概览、模块划分、部署拓扑、业务背景、历史沿革。它的读者是人，尤其是新加入的成员，阅读场景是通读与检索。

项目规范文件回答“在这个项目里应该怎么做”：约束、偏好、禁区、验收标准。它的读者主要是智能助手（人类成员同样受益），阅读场景是每次会话开始时被自动加载，因此它必须短、硬、可执行。

由此可以推导出几条编写原则：

• 只写约束，不写背景。助手不需要知道业务故事，只需要知道“不能用 npm”。
• 可判定优先于可理解。“优先使用函数式写法”难以判定；“新增导出必须附带单元测试”可以判定。
• 命令要具体。写“运行测试”不如写“运行 pnpm test，失败时贴出完整错误输出”。
• 控制体量。文件越长，关键约束被稀释的概率越高；建议控制在几十行到一百余行。

一个实用的判断标准是：如果某条内容删掉之后，助手的行为不会发生变化，那它就不该出现在这里。

三、内容组织：把约定分成四类

将长期约定按性质归类，有助于写出结构清晰、不易遗漏的文件。常见可分为四类。

1. 工具链与命令约定

明确项目使用的包管理器、运行时版本、构建与测试命令。这类约定的反例代价很高——用错包管理器会产生额外的锁文件，污染仓库并引发合并冲突。

## 工具链
- 包管理器固定为 pnpm，禁止生成 package-lock.json 或 yarn.lock
- 安装依赖：pnpm install
- 运行测试：pnpm test
- 类型检查：pnpm typecheck

2. 依赖管理约束

新增依赖是智能助手最容易“自作主张”的环节之一。约束应当同时说明禁止什么和允许的例外路径，只写禁止会让助手在确实需要时选择沉默绕过。

## 依赖
- 未经确认不得新增、升级或移除任何依赖
- 若判断确有必要，先说明用途、体积影响与替代方案，等待确认后再执行
- 优先使用运行时与标准库已提供的能力

3. 改动边界

明确哪些区域可以改、哪些区域禁止触碰。这条约束直接对应“不要修改无关文件”的诉求，但表述得更可操作。

## 改动范围
- 仅修改与当前任务直接相关的文件
- 以下目录只读：迁移脚本、生成的类型定义、第三方补丁
- 不做与任务无关的格式化、重命名或注释整理

4. 完成标准

把“做完”定义清楚，包括验证方式与汇报格式。这是最容易被忽略、但对协作效率影响最大的一类。

## 完成标准
- 改动后必须运行 pnpm test 与 pnpm typecheck
- 汇报内容包含：改动文件清单、测试结果、遗留风险
- 测试失败时不得声称任务完成，需贴出失败用例与初步分析

四、生效机制与写法要点

此类文件之所以有效，依赖一个简单机制：工具在会话初始化阶段自动读取项目根目录下的约定文件，将其作为系统级上下文注入。这意味着其中的内容优先级高于用户在对话中的临时指令，也更稳定。理解这一点后，写法上有几个要点。

第一，用肯定句描述期望行为。 否定句在长上下文中容易被弱化。“使用 pnpm”比“不要用 npm”更直接；两者可以并用，但肯定的表述应当在前。

第二，为规则附上理由（简短）。 助手在遇到规则未覆盖的边缘情况时，理由能帮助它做出合理推断。例如注明“锁定单一包管理器是为了避免多份锁文件冲突”，比孤立的禁令更有指导性。

第三，把高频错误写成显式条目。 观察若干次会话中助手犯过的错，逐条转为规则。这份文件应当是在实践中长出来的，而不是一次性设计完成的。

第四，分层组织，支持局部覆盖。 若仓库包含多个子项目，可在子目录放置独立的规范文件，形成“根级通用约定 + 子项目特有约定”的结构，避免把所有细节堆在根文件里。

五、维护：让它保持有效

规范文件的最大风险不是写得不全，而是写完之后无人维护，逐渐与实际情况脱节。一条过时的规则比没有规则更糟——它会稳定地误导助手。

建议建立三个轻量机制：

1. 随流程变更同步更新。更换包管理器、调整测试命令、新增只读目录时，把更新规范文件纳入变更清单，与代码改动同批评审。
2. 定期清理。每隔一段时间回顾一次，删除已由工具链自动保证的规则（例如已被 CI 强制执行的检查），保留真正需要助手注意的部分。
3. 纳入版本控制并接受评审。规范文件的修改应当走与其他配置文件相同的评审流程，让团队对“助手应该如何行为”保持显式共识，而不是让它悄悄漂移。

六、收益：从重复提示到一次沉淀

将长期约定沉淀为项目级规范文件，带来的改变是具体可感的：

• 会话启动成本下降：不再需要每次粘贴大段说明，开箱即用；
• 行为一致性提升：所有成员共享同一份约束，助手在不同人手里的表现更可预期；
• 误改风险降低：依赖变动、无关文件改动等高频问题被前置拦截；
• 验收标准统一：测试与汇报要求写死在文件里，减少“做完了但没验证”的情况；
• 知识显性化：那些原本只存在于老成员脑子里的默契，变成了仓库中可读、可评审、可继承的文本。

需要强调的是，这类文件并不能替代 CI、代码评审与测试覆盖。它是协作层面的补充：把适合由助手在编码过程中遵守的约定，放在助手能够读到的地方。工程约束的最终保障仍然来自自动化流水线，而规范文件的作用是让助手在第一现场就少犯错，从而让流水线少拦截几次。

七、小结

把“每次都要提醒”变成“进入项目自动读取”，本质上是一次知识载体的迁移：从易失的对话上下文，迁移到持久的、受版本控制的仓库文件。落地的关键在于三点——定位上只写约束不写背景，内容上按工具链、依赖、边界、验收四类组织，维护上随流程变更同步更新。做好这三点，一份几十行的文件就能显著降低日常协作中的重复沟通与误改成本。