CLAUDE.md 最佳实践：让 Claude Code 正确记住项目规则

CLAUDE.md 保存人类明确写下、希望每次相关会话都遵循的规则；自动记忆由 Claude Code 根据工作过程积累，并可由用户审查。两者都不是代码和正式文档的替代品。

适合写入的是工具无法可靠推断的测试命令、仓库礼仪、架构约束和环境陷阱。标准语言常识、完整 API 文档和逐文件说明只会占用上下文。

在项目根目录启动 Claude Code 后运行 /init，工具会根据构建系统、测试框架和项目结构生成初稿。生成内容必须经过项目维护者审查。

初稿只是一份候选规则。删除 Claude 能从 package.json、Makefile 或代码直接得出的内容，保留真正影响执行正确性的约束。

每条规则应回答“何时做什么”和“如何验证”。“写高质量代码”没有操作价值；“修改 TypeScript 后运行 pnpm typecheck”可以直接执行。

如果删除某一行不会导致 Claude 犯错，就应删掉。规则过长会稀释用户当前提示和真正重要的约束。

~/.claude/CLAUDE.md 适合个人跨项目偏好，项目根目录 CLAUDE.md 适合团队规则，CLAUDE.local.md 适合不共享的项目备注。子目录规则在 Claude 访问相应目录时按需加载。

Monorepo 中不要把所有包的命令堆进根文件。根层只放全仓规则，每个包在自己的目录维护具体测试、构建和架构约束。

CLAUDE.md 可以用 @path 引入额外文件。.claude/rules/ 中只有带 paths frontmatter 的规则才按匹配文件按需加载；没有 paths 的规则会在启动时无条件进入上下文。

导入应指向稳定、短小的文档。不要递归导入大型 README 树，也不要导入可能包含密钥的个人文件。

用 /context 查看哪些 CLAUDE.md 和规则已进入当前上下文。规则未生效时，先检查启动目录、文件位置、语句是否冲突，以及文件是否过长。

把 CLAUDE.md 当作代码审查：行为出现偏差时补最小规则，默认行为已经正确时删除冗余规则。确定性强制动作应迁移到 Hooks，而不是继续加重语气。