CLAUDE.md 设置指南：为 Claude Code 编写项目说明与示例
Neaptide · 2026年9月20日 · 8 分钟阅读
用可调整模板编写 CLAUDE.md，记录项目命令与验证规则，检查文件加载，并排查 Claude Code 忽略说明的原因。
本文目录
Claude Code 可以阅读项目代码，但有些工作规则无法从代码中看出来：为什么测试环境不能给真实客户发邮件、哪些目录自动生成，以及团队用什么检查确认修复有效。如果每个新任务都要重复解释，就适合写入 CLAUDE.md。
CLAUDE.md 是为 Claude Code 提供持续性指令的 Markdown 文件。 可以记录项目命令、重要边界和验证标准。最初只需在仓库根目录创建一个文件。Anthropic 文档说明了存放位置和加载方式。
下面是小型网站的教学示例。请按实际目录和命令修改；它不是在你的应用上验证过的配置。
哪些规则值得写下来
假设要为咨询表单添加“公司”字段。仅知道项目使用 TypeScript 不够，智能体还需要知道表单在哪、数据发往哪里，以及如何测试而不联系真实销售团队。
好规则能帮助作出具体决定：
| 过于笼统 | 可用于工作 |
|---|---|
| 写高质量代码 | 修改表单后检查空值、无效邮箱和成功提交 |
| 遵循设计 | 使用现有 TextField 组件及其错误状态 |
| 不要破坏项目 | 修改处理函数后运行对应测试与类型检查 |
| 注意多语言 | 标签和错误消息写入字典，不直接写在组件里 |
| 检查结果 | 分别报告已执行检查与无法执行的检查 |
右列不是通用答案，它的价值在于贴合项目。如果没有 TextField，就必须改写规则，否则说明本身会制造错误。
回顾最近对智能体的反馈：哪些下次还会用到？只针对一个按钮的要求留在当前任务；适用于所有表单的约定可以进入项目规则。
CLAUDE.md 放在哪里
团队共享规则放在根目录的 `CLAUDE.md`。个人通用偏好可放在 `~/.claude/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.md 设置。
示例任务：
给咨询表单添加可选“公司”字段。修改前找到现有字段组件与提交处理函数。修改后检查填写和不填写公司时都能提交。只列出实际执行过的检查。
审阅三个问题：
- 是否用了指定组件与翻译字典？
- 不填可选字段时是否仍能提交？
- 报告中的检查结果是否能与工具输出核对？
某项不符合时先找原因：规则可能含糊，代码可能有第二个相似处理函数，也可能测试没有覆盖场景。理解原因后再考虑增加禁令。
可记录任务、预期操作、实际结果及规则修改。这是建议的验证方法，不是已完成实验的报告。一次成功不代表以后一定遵守。
Claude 忽略 CLAUDE.md 时怎么办
先确认文件已加载，再查找其他文件中同主题的说明。文档指出，发现的 CLAUDE.md 会合并进入上下文；不能认为嵌套文件自动取消此前所有规则。加载顺序。
再看措辞。“认真测试”留下很多选择；“修改咨询处理函数后运行某命令”则指定了可观察操作。
也可能说明已经过时。测试迁移或目录变化后，要更新相关规则。描述旧项目的文档很难被正确执行。
最后删去重复内容和泛泛愿望。Anthropic 建议说明简短、贴合项目，并按实际工作持续修订。没有一个固定长度能保证遵守。内容建议。
什么时候使用 rules 和 Skills
项目变大后，按用途拆分。`.claude/rules/` 可保存主题规则，包括按路径适用的规则。Skills 适合特定情况下需要重复执行的流程。项目规则、Claude Code Skills。
| 内容 | 适合的位置 |
|---|---|
| 主要命令和通用检查顺序 | CLAUDE.md |
| 所有表单的校验约定 | 主题规则 |
| 发布准备流程 | Skill |
| 今天添加“公司”字段 | 当前任务 |
这样更便于维护：发布流程改变时，不需要修改每个场景说明。但拆文件本身不会让规则更准确，内容矛盾仍须解决。
CLAUDE.md 为什么不能替代访问限制
“不要给真实客户发邮件”是有用的工作约定，技术访问限制则需单独配置。Claude Code 提供 `/permissions` 和 allow、ask、deny 规则，CLAUDE.md 不会改变这些权限。权限文档。
表单示例中，应让测试环境实际把请求发往测试接收端，而不只依赖智能体对某段文字的理解。