跳到主内容
AIHO 2026 全新改版上线
A
claude-codeclaude-md配置最佳实践工作流

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

发布 2026-08-02更新 2026-08-02核实 2026-08-02

一句话结论

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 超标。

AIHO 观点：优先级 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 自动生成5 秒出初稿，覆盖结构冗余多、有错、抓不住项目精髓新项目快速起步
纯手写精准、无噪音费时、易遗漏核心长期项目
混合（推荐）快 + 准需 5-10 分钟 review大多数团队

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

AIHO 观点：/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 协议）。

相关阅读

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

相关工具

Claude Code