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.md 的问题是写了一堆偏好，但没有一条能被检查。下面这套写法把约定从「描述」升级成「判据」，AI 与人都知道什么算做到了。

三类内容，分开写

关键是不要把偏好写成硬约束。 一条「所有函数都要写 JSDoc」的硬约束会让 agent 在明显不需要注释的地方硬塞注释；写成偏好它才知道可以让步。

把反例写进去，比写正例更有效

规则里最有信息量的往往是否定句。相比「用 TypeScript 严格模式」，更有用的是「不要出现 any，确实无法避免时在行内写 // eslint-disable-next-line 并说明理由」。 agent 对「不要做什么」的响应明显好于「要做什么」。

让规则可验证

# 在总结里给出这一步的输出，才算完成任务
pnpm typecheck && pnpm test:unit

凡是你能写出一条命令去检查的规则，都应该把那条命令写进 CLAUDE.md。 这样 agent 有自检手段，你验收时也不用读它的自述。

为什么这件事在 2026 年下半年变重要了

Anthropic 于 2026-10-16 发布的内部就业研究报告里有一个容易被忽略的数字：给 agent 的书面长期指令，从 2025 年 7 月的几百条增长到一年后的 8,500 条；同时**「元工作」（给 agent 写指令、让一个 agent 审另一个、搭监控面板）占员工交互式 Claude 会话的比例从 10% 涨到 22%**（详见 Anthropic 就业报告资讯）。

这两个数字说明：CLAUDE.md 这类指令文件已经从「技巧」变成「基础设施」。 当 agent 的运行时长达到人类的数倍量级，项目指令文件的质量就直接等于产能的乘数——一份含糊的 CLAUDE.md 会被放大成大量返工，一份清晰的则会被复用成千上万次。

本报告由 Anthropic 雇员研究其本人所在公司，属自评而非独立审计，引用时应连同该前提一并说明。

更新说明

相关阅读

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

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