你是否厌倦了每次与 Claude 对话时，都要重复解释项目的背景、代码规范和那些特有的“坑”？CLAUDE.md 正是为解决这一问题而生。它是一个 Markdown 配置文件，Claude 会在每个会话开始时自动读取，从而在项目层面记住你的偏好和工作流，显著减少重复沟通，提升协作效率。这篇文章将带你从零开始，掌握创建、组织与长期维护 CLAUDE.md 的完整方法。本文内容由 Vishwas Gopinath 分享，并发布在云栈社区与开发者们共同探讨。
为什么你需要一个 CLAUDE.md 文件
每次开启新对话，Claude 都像一张白纸。它不知道你偏爱具名导出还是默认导出，不清楚该用 npm run test 还是 yarn test 来执行测试，更不了解你项目中那个认证模块有着特殊的重试逻辑。
结果就是，你要么在每次提示中反复说明这些细节，要么一不小心漏掉某个关键信息，最终不得不花时间去修复 AI 生成的、不符合项目约定的代码。CLAUDE.md 就是为了打破这个循环。Claude 会自动读取它，让你的项目级偏好在不同会话间持续生效。
如何创建你的 CLAUDE.md 文件
最快捷的方式是使用 /init 命令。在你的项目根目录下执行这个命令，Claude 会根据项目结构和检测到的技术栈，生成一个初始版本的 CLAUDE.md。
当然，你也可以从零开始手写。但个人更推荐将 /init 的生成结果作为起点，然后删除不需要的部分。毕竟，删除总是比凭空创造要容易。生成的内容中通常会包含一些显而易见的说明或无用的填充信息，精简它们非常重要。
你可能会问，既然工具生成了，为什么不全部保留？核心原因在于：上下文（Token）是宝贵的资源。CLAUDE.md 中的每一行文字，都会与你真正想让 Claude 执行的任务指令竞争有限的注意力。
关于文件位置，你有三个主要选择：
- 项目根目录：最常见的位置。将其提交到版本控制中，确保团队所有成员共享同一套上下文。
- .claude/CLAUDE.md：如果你倾向于将配置文件集中管理，可以放在
.claude 子目录下。
- ~/.claude/CLAUDE.md：用户级别的默认配置，对你机器上的所有项目生效。
对于不希望提交到仓库的个人偏好（例如你喜欢的编辑器模拟键位、输出详略程度等），可以创建一个 CLAUDE.local.md 文件，并记得将其加入 .gitignore。
请注意：文件名是区分大小写的。必须严格命名为 CLAUDE.md（全部大写）.md（小写）。这是 Claude Code 识别并加载记忆文件的唯一方式。
如何组织你的 CLAUDE.md 文件
这是最核心的部分：究竟应该往这个文件里放什么？
必备内容
-
项目背景 (Project Context)
用一两句话让 Claude 快速进入状态。例如：“这是一个基于 Stripe 支付集成的 Next.js 电商应用。” 简短的一句话蕴含了大量技术栈和业务信息。
-
代码风格 (Code Style)
明确你的格式和编码模式偏好。是使用 ES Modules 还是 CommonJS？是否强制使用 TypeScript 并禁用 any 类型？一定要具体。“保持代码风格一致”这种模糊表述是无效的。
-
命令 (Commands)
写下如何运行测试、构建、代码检查（Lint）和部署。当你让 Claude “运行测试”时，它会直接使用这里定义的命令。
-
坑点 / 注意事项 (Gotchas)
记录项目中那些特有的警告和陷阱。比如：
- 那个带有奇怪重试逻辑的认证模块。
- 调用某个内部 API 时必须携带的特定 Header。
- 绝对不允许直接修改的配置文件。
一个完整示例
下面是一个适用于 Next.js 项目的 CLAUDE.md 示例，结构清晰，指令明确：
# Project: ShopFront
Next.js 14 e-commerce application with App Router, Stripe payments, and Prisma ORM.
## Code Style
- TypeScript strict mode, no `any` types
- Use named exports, not default exports
- CSS: Tailwind utility classes, no custom CSS files
## Commands
- `npm run dev`: Start development server (port 3000)
- `npm run test`: Run Jest tests
- `npm run test:e2e`: Run Playwright end-to-end tests
- `npm run lint`: ESLint check
- `npm run db:migrate`: Run Prisma migrations
## Architecture
- `/app`: Next.js App Router pages and layouts
- `/components/ui`: Reusable UI components
- `/lib`: Utilities and shared logic
- `/prisma`: Database schema and migrations
- `/app/api`: API routes
## Important Notes
- NEVER commit .env files
- The Stripe webhook handler in /app/api/webhooks/stripe must validate signatures
- Product images are stored in Cloudinary, not locally
- See @docs/authentication.md for auth flow details
应该写多长？
通常建议控制在 300 行以内。越精炼越好，因为上下文 Token 非常宝贵。
不过，规则并非绝对。如果你的代码库约定异常复杂，或者存在不常见的模式，那么更详细的说明反而能避免 Claude 做出错误假设，从而减少后期的返工成本。
我的原则是：只放入 Claude 在开始工作前必须知道的内容。如果某些信息只在特定场景下有用，我会将其移到单独的文件中，再通过引用引入。
@imports 引用机制
CLAUDE.md 支持使用 @path/to/file 的语法导入其他文件内容，例如：
See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts
这对于保持主文件精简非常有用。你可以将详细的设计文档、API 规范等放在独立的 Markdown 文件中，只在需要时引用。Claude 会在相关场景下自动加载这些被引用的内容。
引用支持多种路径：
- 相对路径：
@docs/style-guide.md
- 绝对路径
- 甚至用户级文件：
@~/.claude/my-preferences.md
引用可以嵌套（被引用的文件可以再引用其他文件），但请谨慎使用，避免形成难以维护的引用迷宫。
使用 .claude/rules/ 实现模块化规则
对于更大型的项目，可以考虑使用 .claude/rules/ 目录。将规则按主题拆分到多个聚焦的文件中，而不是全部堆叠在一个 CLAUDE.md 里。
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目说明
│ └── rules/
│ ├── code-style.md # 代码风格规范
│ ├── testing.md # 测试约定
│ └── security.md # 安全要求
.claude/rules/ 目录下的所有 .md 文件都会与主 CLAUDE.md 一同被自动加载，无需手动 @import。
当团队职责清晰划分时，这种方式尤其高效：
- 前端团队维护
code-style.md，
- 测试团队维护
testing.md，
- 安全团队维护
security.md。
这样避免了所有人在一个巨大的文件中解决合并冲突。
子目录中的 CLAUDE.md
还有最后一层结构：项目子目录中的 CLAUDE.md。
当 Claude 在某个子目录中工作时，它会自动读取该目录及其所有父级目录中的 CLAUDE.md。这些文件不会在会话启动时一次性全部加载，而是根据 Claude 当前“所在”的代码区域动态生效。
这对于 Monorepo 或模块界限清晰的项目非常有用：
/api 目录可以有自己的 CLAUDE.md，专门定义 REST 或 GraphQL API 的规范。/packages/ui 目录可以包含组件开发的独立规则（如使用 Storybook、特定的 Props 命名约定等）。
如何维护你的 CLAUDE.md 文件
CLAUDE.md 不是一份一劳永逸的文档。项目在演进，你的认知和偏好也在变化，这个文件理应随之更新。
在工作中不断补充规则
当 Claude 做出一个不符合你预期的假设或行为时，不要仅仅在当次对话中纠正它。更好的做法是：直接让 Claude 将这条新规则写入 CLAUDE.md。
例如，如果 Claude 使用了 console.log 进行调试，而你希望统一使用项目内的 logger 工具。你可以说：“请将这条规则加入我的 CLAUDE.md：始终使用 logger 进行日志记录，禁止使用 console.log。”
这样一来，这条偏好就在未来的所有会话中都生效了。CLAUDE.md 就这样在实际使用中自然生长。你无需一开始就预见到所有情况，而是在实战中不断积累和记录经验。
注意：早期版本的 Claude Code 曾有一个 # 快捷键用于快速添加指令，但在 2.0.70 版本后被移除。现在的标准做法就是直接让 Claude 编辑你的 CLAUDE.md 文件。
定期回顾和整理
每隔几周，可以请 Claude 帮忙审查并优化一次 CLAUDE.md。随着时间的推移，规则会累积，有些可能变得冗余，有些可能与新加入的规则冲突。
一句简单的“请审查这个 CLAUDE.md 文件，并提出改进建议”，就能帮你发现这些问题。及时删除过时的内容，合并重复的规则，澄清模糊的表述。
这听起来像是额外的工作，但比起你在每个新对话中反复解释，或者事后修复大量不符合约定的代码，这点维护成本要划算得多。
对关键规则进行强调
对于绝对不能违反的“铁律”，可以使用强调性词汇来提升 Claude 的注意度，例如：
- “IMPORTANT：绝不要直接修改
migrations/ 文件夹中的历史迁移文件。”
- “YOU MUST：在提交代码前，必须运行完整的测试套件
npm run test:e2e。”
当然，这并非 100% 可靠。随着对话延长、上下文拥挤，Claude 仍有可能疏忽。但根据经验，明确的强调确实能显著提高规则被遵守的概率。
关键是要克制。如果每条规则都标上 IMPORTANT，那就等于没有重点。
如何随着时间不断改进你的 CLAUDE.md
最有价值的更新往往来自代码评审（Code Review）。
当一次 Pull Request 暴露出某个之前未曾文档化的团队约定，或者评审者指出了一段违反既有模式的代码时，这就是一个明确的信号：应该把这条规则加入 CLAUDE.md。这样可以防止未来再犯同样的错误。
如果你在使用 Claude Code 的 GitHub Action（可通过 /install-github-action 安装），你甚至可以在 PR 的评论中直接 @claude 来更新文件。
例如：
“@claude add to CLAUDE.md: never use enums, always prefer string literal unions for type definitions.”
Claude 会更新 CLAUDE.md 文件，并将更改作为 PR 的一部分提交。这个由 Boris Cherny 分享的工作流，非常高效地形成了一个反馈闭环：真实问题 → 转化为明确指令 → 预防未来错误。
你的 CLAUDE.md 会逐渐演变成一个“活的”项目知识库，沉淀着团队在开发过程中积累下来的宝贵经验和共识。
CLAUDE.md 最佳实践
- 开头一句话：用简洁的一句话说明项目是什么。
- 风格要具体：代码风格偏好必须具体、可执行，避免模糊。
- 包含关键命令：测试、构建、代码检查、部署等命令不可或缺。
- 描述具体的坑：对陷阱的描述要足够细致，能真正起到预防作用。
- 控制篇幅：目标在 300 行以内，或确保每一行都有其不可替代的价值。
- 善用引用：将详细说明移至通过
@import 引用的独立文件中。
- 及时清理：定期删除过时的、或与新规则冲突的内容。
- 强调关键点：对真正核心的规则使用强调词，但务必克制。
- 持续更新：在工作过程中随时添加指令，而非仅初始创建时编写。
- 结合 Code Review：当 PR 评审暴露出未文档化的约定时，立即更新。
- 定期审查：像重构代码一样，定期审视和优化你的 CLAUDE.md。
对于大型项目：
- 约定差异明显的子目录，应考虑配备各自的
CLAUDE.md。
- 将规则拆分到
.claude/rules/ 下的独立文件，有助于明确不同团队的责任边界。
从今天开始
如果你还没有 CLAUDE.md，现在就在你的项目根目录运行 /init。仔细检查生成的内容，删掉无用的部分，加入你自己的代码风格偏好和关键命令。
如果你已经有一个 CLAUDE.md，那么下次当 Claude 的产出不符合你预期时，别只是纠正它——直接命令它更新配置文件。亲眼看着这个文件在真实的使用场景中一点点成长和完善。
一个文件，几分钟的初始配置，长期下来，为你节省的将是大量的重复沟通和返工时间。
关于本文
译者：飘飘
作者：Vishwas Gopinath
原文：https://www.builder.io/blog/claude-md-guide
发表于 昨天 09:03
|
查看: 7|
回复: 0
