CLAUDE.md 最佳实践：让 Claude Code 一次写对的关键

一句话结论

CLAUDE.md 是 Claude Code 的「项目记忆」——每次启动自动读取，决定它懂不懂你的项目。写好了，成功率从约 60% 拉到 85%+；但写得太多（>2000 字）会污染上下文，反而抓不住重点。一份好的 CLAUDE.md 聚焦「项目结构 + 常用命令 + 编码约定 + 禁忌清单」四块，用 /init 生成初稿再手工精修最稳。

CLAUDE.md 在启动时如何被读取

Claude Code 进入项目时，会按以下优先级加载记忆：

1. ~/.claude/CLAUDE.md — 用户级全局记忆（所有项目生效）
2. 项目根/CLAUDE.md — 项目级（最常用）
3. 子目录/CLAUDE.md — 局部覆盖（进入该目录时叠加）
4. CLAUDE.local.md — 本地不提交版本（放敏感/个人偏好，gitignore）

所有层的内容会拼进系统提示，所以每一层都别太长，否则总 token 超标。

2026-09-20 更新：v2.1.277（2026-09-18）起，第 2 层有了回退——当项目根没有 CLAUDE.md 时，Claude Code 会改读根目录的 AGENTS.md 作为项目指令（可在 /config → Project instructions 关闭）。注意这是回退而非合并：只要存在 CLAUDE.md，AGENTS.md 就不会被读。

2026-09-28 更正（据官方 CHANGELOG 原文）：初上线（v2.1.277）时该回退仅限直连 Anthropic API，本站曾写「Bedrock / Vertex / Foundry 暂不支持」。v2.1.281 已解除该限制——现已在 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM 网关，以及关闭遥测的会话上生效。已在用 AGENTS.md 的团队可据此少维护一份文件，但删除 CLAUDE.md 前请实测。来源：Claude Code Changelog。社区反馈称「空 CLAUDE.md 也会挡住回退」，该说法未见于官方表述。

AI 之家 观点：优先级 4 的 CLAUDE.local.md 是团队协作的隐藏利器——把「你的个人偏好 / 本地路径 / 私有密钥相关说明」放进去且不提交，既不污染仓库又能让本机 Claude Code 更懂你。

一份好的 CLAUDE.md 模板

# 项目概述
这是一个 Nuxt 3 全栈博客系统，前端 Vue + Tailwind，后端 Nitro server routes。

# 项目结构
- pages/        页面路由（文件即路由）
- components/   Vue 组件，用 <script setup>
- server/       API 路由（event handlers）
- composables/  复用逻辑（自动导入）
- content/      Markdown 内容源

# 常用命令
- pnpm dev        启动开发服务器
- pnpm test       跑 Vitest
- pnpm lint       跑 ESLint
- pnpm build      生产构建

# 编码约定
- TypeScript strict，禁止 any
- 组件用 <script setup> + Composition API
- API 调用走 server/ 层，禁止前端暴露密钥
- 提交前必须 pnpm lint && pnpm test 通过

# 禁忌
- 不要禁用 SSR
- 不要在客户端读取 runtimeConfig.secret
- 不要引入未列入 package.json 的依赖
- 不要改写 migrations/ 下的历史迁移文件

长度 vs 效果：太长会污染上下文

我们在 Claude Code 深度评测 里做过 A/B：CLAUDE.md 超过 ~2000 字，成功率从 87% 掉到 68%。原因不是「信息多」，而是模型在长文本里抓不住优先级——它会把「项目结构」和「一条无关紧要的注释习惯」同等对待。

甜区建议：

• 核心项目：200-500 行，结构化、列表化
• 局部子目录：50-100 行足够
• 全局 ~/.claude/CLAUDE.md：只放跨项目通用习惯（<100 行）

/init 自动生成 vs 手写 vs 混合

混合流程：/init 生成 → 删冗余 → 补「禁忌清单」和「常用命令」→ 用 /memory 固化长期记忆。

AI 之家 观点：/init 生成后一定要 review。自动生成常把 node_modules 里的东西写进结构、把不重要文件当核心。花 5 分钟精修，比让它乱猜 10 次强。

子目录 CLAUDE.md 的妙用

大 monorepo 里，根目录 CLAUDE.md 管全局，子目录再覆盖：

packages/core/CLAUDE.md      # 「这是核心库，改这里要跑全量测试」
packages/cli/CLAUDE.md       # 「CLI 用 commander，命令注册看这里」
apps/web/CLAUDE.md           # 「前端用 Nuxt，禁止直连后端」

Claude Code 进入对应目录会自动叠加，避免全局文件无限膨胀。

与 .cursor/rules 的同步策略

同时用 Cursor 和 Claude Code 的团队，最怕「两套约定各写各的，最后 AI 听谁的」。

推荐做法：

1. 单一事实源：把约定写在 CLAUDE.md（Claude Code 原生支持）。
2. Cursor 侧引用：在 .cursor/rules/base.mdc 里写一行「项目约定见根目录 CLAUDE.md，遵循其规范」，让 Cursor 也读同一份。
3. 或用 AGENTS.md 桥接：写一份 AGENTS.md，Cursor / Claude Code / Cline / Codex 都读它（详见 AGENTS.md 协议）。
4. 进 git：CLAUDE.md 和 .cursor/rules 都提交，新人 clone 即一致。

常见问题

Q：CLAUDE.md 改了要重启吗？ A：不用。Claude Code 每次启动重新读取；正在运行的会话用 /memory 编辑后下次对话生效。

Q：敏感信息能写进 CLAUDE.md 吗？ A：绝对不要写密钥本身。写「密钥走环境变量 XXX，不要硬编码」这种说明。真正敏感内容放 CLAUDE.local.md（不提交）。

Q：和 AGENTS.md 冲突怎么办？ A：让 AGENTS.md 作单一事实源，CLAUDE.md 引用它或保持同步（见 AGENTS.md 协议）。

相关阅读

• 工具卡：Claude Code
• 评测：Claude Code 深度评测
• 方案：Cursor Rules 最佳实践 ｜ AGENTS.md 协议
• 对比：Claude Code vs Codex CLI

来源说明：本文基于 code.claude.com 官方 Memory 文档、第三方 cheat sheet 及 AI 之家 编辑部实践归纳。命令与功能以最新官方文档为准。