CLAUDE.md 设置指南：为 Claude Code 编写项目说明与示例
Neaptide · 2026年9月20日 · 8 分钟阅读 · 更新于: 2026年10月3日
用可调整模板编写 CLAUDE.md，记录项目命令与验证规则，检查文件加载，并排查 Claude Code 忽略说明的原因。
本文目录
Claude Code 能读懂项目代码，但有些工作规则在代码里看不出来：为什么测试环境不能给真实客户发邮件，哪些目录是自动生成的，团队靠哪项检查确认修复有效。如果每开一个新任务都要重讲一遍，就该把它们写进 CLAUDE.md。
CLAUDE.md 是一个 Markdown 文件，用来给 Claude Code 提供长期有效的指令。项目命令、重要限制和验证标准都可以记在里面。起步时在仓库根目录建一个文件就够了。文件可以放在哪里、如何加载，Anthropic 文档里有说明。
下面用一个小型网站项目做示例。目录和命令请换成你自己的：这是一份练习用的模板，没有人在你的应用上验证过。
哪些规则值得写下来
假设要给咨询表单加一个“公司”字段。只知道项目用 TypeScript 远远不够，智能体还得找到表单，弄清数据发往哪里，并且在不惊动真实销售团队的前提下测试提交。
好的规则能帮人做出具体决定：
| 过于笼统 | 可用于工作 |
|---|---|
| 写高质量代码 | 修改表单后检查空值、无效邮箱和成功提交 |
| 遵循设计 | 使用现有 TextField 组件及其错误状态 |
| 不要破坏项目 | 修改处理函数后运行对应测试与类型检查 |
| 注意多语言 | 标签和错误消息写入字典，不直接写在组件里 |
| 检查结果 | 分别报告已执行检查与无法执行的检查 |
右边一列并不适用于所有仓库，它有用，是因为贴合这个项目。如果你的项目里没有 TextField，就得改写规则，否则这条说明本身就会制造错误。
回想一下你最近给智能体提过的意见，哪些下次还用得上？只针对某个按钮的要求，留在当前任务里；适用于所有表单的约定，才写进项目规则。
CLAUDE.md 放在哪里
团队共用的规则放在项目根目录的 `CLAUDE.md`。跨项目通用的个人偏好可以放在 `~/.claude/CLAUDE.md`。子目录里的 CLAUDE.md，会在 Claude 读取该目录下的文件时加载。
初始结构可以很简单：
project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/如果文件已经存在，先读一遍。两套相近的规则很难同步维护：测试命令换了，往往只改了其中一份。
文件名也要核对。编辑器隐藏扩展名时，一不留神就会建成 `CLAUDE.md.txt`。
怎样生成初稿
在已打开的 Claude Code 会话里执行 `/init`，它会根据项目生成一份初始 CLAUDE.md。生成的内容要逐项核对：命令是否存在，路径是否还有效，限制是否符合你的工作方式。Anthropic 的建议也是先生成、再修订。
如果想先看方案、暂时不动文件，可以这样说：
阅读 README、package.json 中的脚本与目录结构，提出 CLAUDE.md 草稿。包含启动和检查命令、重要修改边界，以及不能从代码中确定的事项。把未知内容列为问题，暂时不要创建或修改文件。
这样拿到的是一份可以和仓库逐项对照的文本。不要因为它看起来工整就照单全收。项目里没有对应脚本的话，`npm test` 毫无用处。
网站项目的 CLAUDE.md 示例
这份模板是我们为本文写的，假设有一个服务类网站，使用 npm、TypeScript、翻译字典，以及单独配置的表单测试。命令和目录名只是为了展示结构，使用前请换成真实名称。
# 项目
带咨询表单的服务网站，界面为俄语和英语。
主要用户流程：选择服务并提交咨询。
## 代码位置
- src/components/forms/ — 字段与表单。
- src/server/leads/ — 咨询处理。
- src/i18n/ — 界面语言字典。
- tests/leads/ — 咨询处理测试。
## 命令
- npm run dev — 本地启动。
- npm run typecheck — 类型检查。
- npm run test:leads — 咨询处理测试。
- npm run build — 构建应用。
## 修改规则
- 复用现有表单组件与错误处理函数。
- 界面文案写入两个语言版本的字典。
- 项目现有工具足够时，不添加依赖。
- 保留其他人尚未完成的改动。
## 验证
- 修改咨询流程时，检查必填项、无效邮箱，以及向测试接收端成功提交。
- TypeScript 修改后运行 npm run typecheck。
- 修改咨询处理后运行 npm run test:leads。
- 界面修改后，在浏览器检查受影响页面。
- 无法执行某项检查时，说明原因及剩余不确定性。
## 环境
- 仅向测试接收端执行提交检查。
- 所需环境变量名称见 .env.example。
- 不要把密钥值写入代码、报告或文档。
## 报告
简述修改、已执行检查及剩余问题。
区分测试结果和对应用行为的推测。先检查命令，再确认验证规则确实做得到。没有测试接收端，写一条指令也变不出来；要么先准备好测试环境，要么写明眼下可行的验证办法。
不必保留所有章节。库项目更看重公共 API 和兼容性；文章类网站更看重内容结构、元数据和内部链接。
怎样判断说明是否有帮助
这里有两个问题要分开看：文件有没有加载，智能体的行为有没有改变。
运行 `/context`，在 Memory files 列表里找到你的文件，然后交给智能体一个结果明确的小任务。Anthropic 明确建议用这个命令确认文件已加载。
以示例网站为例：
给咨询表单添加可选“公司”字段。修改前找到现有字段组件与提交处理函数。修改后检查填写和不填写公司时都能提交。只列出实际执行过的检查。
然后看三点：
- 是否用了指定组件与翻译字典？
- 不填可选字段时是否仍能提交？
- 报告中的检查结果是否能与工具输出核对？
如果有一项不符合，先找原因。可能是规则含糊，可能是代码里还有一个相似的处理函数，也可能是测试没有覆盖这个场景。弄清楚问题出在哪里，再考虑要不要加一条禁令。
可以做一份简单的记录：任务、预期操作、实际结果、改了哪条规则。这是我们建议的验证方法，本文并没有做过这样的实验。成功一次，不代表这条规则以后都会被遵守。
Claude 忽略 CLAUDE.md 时怎么办
先确认该加载的文件确实加载了，再看看项目里其他文件有没有同一主题的说明。按照文档，Claude 找到的所有 CLAUDE.md 会合并进入上下文，所以嵌套文件不会自动取消上层的规则。
接着看措辞。“认真测试”留给智能体的选择太多；“修改咨询处理函数后运行某某命令”指定的是一个看得到结果的动作。
还有一种可能：说明已经过时。测试搬了位置、目录结构变了，相关规则就要跟着改。一份描述旧项目的文档，智能体照着做也做不对。
最后，删掉重复的内容和泛泛的愿望。Anthropic 建议说明要简短、贴合项目，并在工作中不断修订。没有哪个篇幅能保证指令一定被遵守。
什么时候使用 rules 和 Skills
项目变大以后，按用途拆分说明。`.claude/rules/` 用来存放按主题划分的规则，其中也包括只对特定路径生效的规则。Skills 适合那些只在特定情况下才用到的可重复流程。
| 内容 | 适合的位置 |
|---|---|
| 主要命令和通用检查顺序 | CLAUDE.md |
| 所有表单的校验约定 | 主题规则 |
| 发布准备流程 | Skill |
| 今天添加“公司”字段 | 当前任务 |
这样维护起来更省事：发布流程变了，不必去改每一个场景说明。不过，拆成多个文件并不会让规则更准确，内容上的矛盾还是得逐条解决。
CLAUDE.md 为什么不能替代访问限制
“不要给真实客户发邮件”是一条有用的工作约定，技术上的访问限制则要另行配置。Claude Code 提供 `/permissions` 以及 allow、ask、deny 规则，CLAUDE.md 里写什么都不会改变这些权限。
在表单这个例子里，应当把测试环境配置成：提交的请求确实发往测试接收端。这样一来，收件方是否正确，就不再取决于智能体怎么理解某段文字。