Claude Code 已经能改代码，但每次换个会话，你还得提醒它用哪个包管理器、测试怎么跑、哪些文件不能直接改。遇到这种情况，可以先把这些反复解释的规则整理成一份 CLAUDE.md。
这份文件给 Claude 提供持续的项目说明。写得有效，关键在于让它知道具体该做什么、为什么这样做，以及怎样判断工作完成。只写“保证代码质量”，它仍然不知道你这个项目的质量标准是什么。
下面以本地 Claude Code 为例，说明文件放在哪里、怎么写和怎么验证。功能说明依据 2026 年 10 月 10 日的官方文档；示例项目和命令用于演示，需要按你的仓库调整，没有进行 Claude Code 端到端实测。官方项目记忆文档
先分清：项目规则和接入配置放在哪里
CLAUDE.md 适合放项目长期需要的说明，例如测试入口、与默认习惯不同的约定，以及容易反复踩的坑。API 地址、密钥和权限配置则属于设置层，不应把真实密钥塞进团队共享的说明文件。
如果你还没把 Claude Code 接通，先完成站内的第三方 API 配置教程。模型能正常响应后，再用本文整理项目规则。修改 CLAUDE.md 不会替你切换 API 地址或计费渠道。
还有一个边界：Claude 把这些说明当作上下文，不能保证逐条严格执行。必须禁止某类操作时，需要用客户端权限配置或适合的 Hook 执行约束，不能只写一句“绝对不要做”。官方说明
文件放在哪里，决定它影响哪些项目
先从项目根目录的一份文件开始，够用后再拆分。
| 位置 | 适合放什么 |
|---|---|
| ~/.claude/CLAUDE.md | 你跨项目使用的个人习惯 |
| 项目根目录的 CLAUDE.md，或 .claude/CLAUDE.md | 团队共享的项目规则 |
| 项目中的 CLAUDE.local.md | 只适用于你本机的项目说明，应加入 .gitignore |
| 子目录里的 CLAUDE.md | 只与该部分代码有关的说明 |
启动时，Claude Code 会加载工作目录及其上级目录中的说明文件。工作目录下面的子目录文件按需加载：当 Claude 读取或修改该目录里的文件时，相关说明才进入上下文。多个说明会一起进入上下文，不要把它理解成“子目录规则自动覆盖上层规则”。文件加载机制
比如你在前端目录工作，却把整个团队的规则写进个人的 ~/.claude/CLAUDE.md，其他成员就不会通过仓库得到这些规则。反过来，把你本机的测试地址写进共享文件，也可能误导同事的环境。
先生成骨架，再把空话改成具体操作
在已安装并登录的 Claude Code 中，从项目根目录启动会话，输入：
/init
官方说明，这个命令会分析代码库，生成起始的 CLAUDE.md；已有文件时会建议改进，而不是直接覆盖。初始化说明
生成之后，重点检查里面的路径、命令和约定。工具能读到 package.json，不代表它知道团队实际上认可哪一种测试方式。你可以把之前反复纠正它的事情补进去，把它本来就能从代码中看出的冗余说明删掉。
下面几种改法更容易验证：
| 原来的说明 | 改写后的说明 |
|---|---|
| 保持代码质量 | 修改业务逻辑后，运行相关测试和类型检查；失败时报告具体错误，不把未通过写成成功 |
| 遵循项目架构 | 新的计费逻辑放在 src/billing/，接口层调用已有服务，不在路由处理器中重复计算金额 |
| 不要乱改文件 | src/generated/ 是生成产物，修改对应源文件并运行生成命令 |
| 充分测试 | 修复 bug 时增加能复现该问题的用例；先跑相关测试，涉及共享逻辑时再跑完整测试 |
表中的路径是假设示例，不能原样当作你仓库的真实结构。有效的规则要能回答三个问题：什么情况下执行，具体做什么，以及怎样检查结果。
一份可以按仓库调整的 CLAUDE.md
假设项目使用 pnpm、TypeScript 和 Vitest，下面这份说明可以作为起点。先核对 package.json：如果没有 typecheck、test 或 generate 脚本，就改成真实命令，或删掉不适用的规则。
# 项目工作约定
## 工具和验证
- 使用 pnpm。修改依赖时同步 pnpm-lock.yaml。
- pnpm typecheck：类型检查。
- pnpm test --run：完整测试。
- pnpm test --run 路径/用例.test.ts：运行相关测试。
- 修改业务逻辑后先跑相关测试及类型检查。
涉及共享基础逻辑时，再跑完整测试。
- 命令失败时报告错误和影响，不将“未运行”或“失败”写成通过。
## 代码边界
- src/generated/ 是生成代码，不直接编辑。
修改源定义后运行 pnpm generate。
- 新功能优先复用现有服务；增加依赖前说明现有实现为何不够。
- 不在接口层重复计费计算；复用 src/billing/ 的公共逻辑。
## 修复和交付
- 修复 bug 时，先用一个测试或可复现步骤说明原问题。
- 保持修改范围与任务一致。发现其他问题，单独列出。
- 完成后说明行为变化、验证结果，以及尚未解决的问题。
这份示例刻意没有罗列完整目录树，也没有把“可读性、可维护性、可扩展性”反复写一遍。具体项目可以有不同标准，但每一条最好能改变 Claude 的实际决策。
如果一条说明只对某个子模块有用，把它移到对应目录的说明或路径规则里。多步骤、偶尔才运行的工作流，则更适合做成 Skill，避免每次会话都加载一整套流程。官方写作实践
规则变多后，再按路径拆分
大型仓库可以用 .claude/rules/ 按主题组织规则。例如，只有修改后端 TypeScript 时，才需要加载 API 约定：
文件位置：.claude/rules/api.md
---
paths:
- "src/api/**/*.ts"
---
# API 约定
- 使用项目现有的错误处理方式，不新增另一套响应格式。
- 新增输入字段时，同时检查校验和对应测试。
带 paths 的规则在 Claude 工作涉及匹配文件时加载；没有路径限制的规则会在每个会话中加载。具体匹配语法以官方路径规则文档为准。
另一种组织方法是用 @docs/project-rules.md 导入说明。它方便维护，但导入文件也会展开进上下文，不能靠拆成多个导入文件来降低加载成本。若目标是减少无关规则，路径作用域或按需使用的 Skill 更合适。文件导入说明
怎么确认 Claude 真的加载并使用了规则
保存文件后，在项目根目录重新启动一个会话，输入：
/context
检查 Memory files 中是否有预期的根目录说明。这能确认文件被加载，还不能证明 Claude 的后续操作一定符合规则。子目录说明按需加载，不一定出现在启动时的列表中。
再拿一个小任务观察行为，例如：
先不要修改代码。检查这个仓库的项目说明和 package.json，
列出当前包管理器、类型检查命令和测试命令，说明各自来自哪里。
若项目说明中的命令不存在，明确指出，不要假设它可运行。
核对它给出的命令是否真实存在、是否与你的约定一致。接着选择一个可以撤销的小改动，看它是否按规则选了测试，并给出实际结果。只回复“我会遵守”，不算行为验证。
/memory 可以查看和编辑说明文件。规则不生效时，先查加载位置，再查表述和冲突，不要直接往文件里追加十次“必须严格遵守”。官方验证与排错方法
已经写了规则，为什么还是容易跑偏
常见问题是文件确实加载了，但里面的规则过宽、互相矛盾，或者早已不适用于当前仓库。
如果个人说明要求 npm，项目说明要求 pnpm，先统一这些约定。如果写的是“任何修改都运行全部测试”，但一个完整测试需要很长时间，可以明确哪些改动只跑相关用例，哪些情况需要全量验证。不要同时要求“每次全跑”和“尽量不跑全量”，让 Claude 猜你的优先级。
官方建议每份 CLAUDE.md 尽量控制在 200 行以内。这个数字是维护建议，不是第 201 行就不加载的硬限制。删减时优先去掉普通编程常识、重复规则和失效路径，保留真正影响工作方式的约定。有效指令写法
仓库已经有 AGENTS.md 时，也不要维护两份内容相同但逐渐分叉的文件。当前官方文档说明，部分新版本能直接读取 AGENTS.md，但它与 CLAUDE.md 共存时存在加载选择和版本限制。需要兼顾不同工具时，可以在 CLAUDE.md 中使用下面这一行导入，之后再验证加载情况：
@AGENTS.md
这里的 @AGENTS.md 要写在实际文件正文中，而不是放进代码围栏。官方说明，代码围栏中的导入语法不会展开。AGENTS.md 支持与兼容方式
先写下你已经反复解释过的几条规则，拿一个小任务验证。发现问题后，修改具体那一条，再看行为有没有变化。等这份说明能稳定帮你少纠正几件事，再考虑扩展到更多目录。
