【claude code实践】CLAUDE.md 应该写什么：命令、规范、架构与禁区
CLAUDE.md 应该写什么：命令、规范、架构与禁区
引言：为什么现在需要理解它
很多开发者开始使用 Claude Code 后，都会遇到一个问题：
同样是一个项目，有时候 Claude Code 表现得像一位熟悉代码库的同事，有时候却会犯一些团队内部几乎不会出现的错误。
例如：
- 使用了团队已经废弃的框架；
- 修改了自动生成的代码；
- 绕过了统一的数据访问层；
- 忘记执行测试；
- 修改了本不应该修改的配置文件。
这些问题并不是因为模型不会写代码，而是因为它不知道团队的规则。
代码能告诉 AI「系统是怎么实现的」，却很难告诉它「团队为什么这样实现」。
而CLAUDE.md存在的意义，就是把这些隐藏在团队经验中的知识显式写下来。
不过，新的问题又来了：
很多团队知道应该创建CLAUDE.md，却不知道里面应该写什么。
有人把 README 全部复制进去。
有人只写一句：
这是一个 Java 项目。还有人把几十页设计文档全部放进去。
这些做法都不能充分发挥CLAUDE.md的价值。
真正重要的不是写得越多越好，而是写Claude Code 在开发过程中真正需要知道的信息。
本文将围绕CLAUDE.md的内容组织展开，重点讨论四类最值得维护的信息：命令（Commands）、规范（Conventions）、架构（Architecture）和禁区（Guardrails）。
一、CLAUDE.md 是什么
一句话来说：
CLAUDE.md 是一份长期维护的 AI 协作说明书，用来告诉 Claude Code 如何参与当前项目的开发，而不仅仅是如何理解代码。
它最大的特点不是介绍项目，而是描述开发规则。
如果 README 回答的是：
这个项目是什么？
那么CLAUDE.md回答的是：
在这个项目里，应该怎样开发。
因此，它不应该成为代码文档，也不应该成为设计文档，而应该成为一份面向 AI 的开发指南。
很多开发者容易误解的一点是：
CLAUDE.md并不是 Prompt。
Prompt 更偏向一次任务，例如：
帮我修复登录 Bug。
而CLAUDE.md更像项目中的长期约束：
- 使用什么架构；
- 如何运行测试；
- 哪些目录不能修改；
- 哪些规范必须遵守。
这些信息不会随着一次任务结束而失效，因此更适合沉淀到项目中。
二、从「写给 AI 的项目说明书」开始理解它
可以把CLAUDE.md想象成团队迎接新成员的一份《开发须知》。
当一位新同事加入项目时，团队通常不会要求他立刻阅读几十万行代码，而是会先告诉他几件事：
- 项目采用什么架构；
- 核心目录在哪里；
- 开发流程是什么；
- 哪些模块不要轻易修改；
- 提交代码之前要完成哪些检查。
这些内容并不会随着某一个需求改变，而是团队长期积累下来的经验。
Claude Code 的情况也类似。
虽然它能够阅读代码，但很多开发规则无法直接从代码中推导出来。例如：
- 为什么所有数据库访问必须经过 Repository？
- 为什么
generated/目录不能修改？ - 为什么提交前必须运行集成测试？
如果这些信息没有明确记录，Claude Code 只能依赖推断，而推断未必符合团队约定。
因此，CLAUDE.md的目标不是增加更多上下文，而是减少 AI 的猜测。
三、它解决了什么问题
1. 避免重复输入项目规则
开发者经常需要告诉 Claude Code：
不要修改自动生成代码。
新接口必须补测试。
使用 pnpm，不要使用 npm。
这些规则其实属于项目级知识。
CLAUDE.md可以把它们沉淀下来。
改变的是：
AI 每次进入项目都能够遵循同一套规则。
限制在于：
规则更新后，需要同步维护文档。
2. 降低错误修改的概率
很多错误不是代码能力不足，而是违反团队规范。
例如：
直接修改数据库脚本；
绕过统一日志组件；
新增接口没有权限校验。
这些问题都可以通过明确约束减少。
改变的是：
Claude Code 更容易按照团队已有方式工作，而不是自行选择实现路径。
限制在于：
规则越模糊，AI 越容易产生不同理解。
3. 提高长期协作效率
随着 AI 成为开发流程的一部分，团队知识开始从「口头传递」转向「文档传递」。
CLAUDE.md正是这种知识沉淀的载体。
改变的是：
开发者可以把更多精力放在需求和设计上，而不是反复解释开发约定。
限制在于：
它只能描述长期规则，无法替代当前任务背景。
四、它的基本工作方式
Claude Code 在执行任务时，会不断构建上下文，而CLAUDE.md提供的是其中最稳定的一层。
一个典型流程如下：
开发任务 │ ▼ 读取 CLAUDE.md │ ▼ 建立项目规则 │ ▼ 搜索相关代码 │ ▼ 分析与修改 │ ▼ 执行测试 │ ▼ 输出结果其中，CLAUDE.md不负责解释代码实现，而负责影响后续决策。
例如：
开发者提出：
增加订单接口。如果CLAUDE.md写着：
所有接口必须： - 使用统一响应对象 - 添加权限注解 - 补充单元测试Claude Code 就会把这些规则纳入自己的执行计划，而不是仅仅完成接口代码。
这也是为什么，一份好的CLAUDE.md能够提升 AI 输出的一致性，而不仅仅是准确性。
五、一个典型使用流程
假设团队维护一个微服务项目，并准备让 Claude Code 参与开发。
首先，他们创建了如下CLAUDE.md：
# Commands 测试： ./gradlew test 格式化： ./gradlew spotlessApply # Conventions 所有数据库访问必须经过 Repository。 所有接口统一返回 ApiResponse。 新增接口必须添加测试。 # Architecture 认证： auth-service 订单： order-service 支付： payment-service # Guardrails 禁止修改 generated/ 禁止修改 migration 禁止提交 .env接下来，开发者提出任务：
给订单接口增加导出功能。
Claude Code 的执行过程通常如下：
- 读取
CLAUDE.md； - 知道订单模块位置；
- 按照统一响应格式生成接口；
- 不直接访问数据库；
- 修改后执行测试；
- 保持生成代码不变；
- 等待开发者 Review。
整个流程中，CLAUDE.md并没有告诉 AI 如何写代码，而是告诉它应该遵守哪些规则。
六、它和传统方式的区别
| 对比维度 | CLAUDE.md | README | 一次性 Prompt | 团队 Wiki |
|---|---|---|---|---|
| 面向对象 | AI 协作者 | 人类开发者 | 当前任务 | 团队成员 |
| 生命周期 | 长期 | 长期 | 单次 | 长期 |
| 内容重点 | 开发规则 | 项目介绍 | 当前需求 | 全量知识 |
| 是否影响 AI 行为 | 是 | 部分 | 是 | 通常需要人工查阅 |
| 是否适合团队协作 | 是 | 是 | 否 | 是 |
真正的区别在于：
CLAUDE.md描述的是开发过程，而不是项目本身。
七、CLAUDE.md 应该写什么，不应该写什么
围绕标题中的四个关键词，可以建立一份稳定的内容框架。
1. Commands（开发命令）
这是 Claude Code 最容易直接利用的信息。
建议包括：
- 项目启动命令；
- 测试命令；
- 构建命令；
- 格式化命令；
- Lint 命令。
例如：
## Commands Run tests: ./gradlew test Lint: ./gradlew check Format: ./gradlew spotlessApply这些命令能够帮助 Claude Code 在完成修改后主动验证结果。
2. Conventions（开发规范）
这里记录团队长期遵循的约定，例如：
- 命名规范；
- 返回值格式；
- 日志规范；
- 异常处理方式；
- 数据访问原则；
- 测试要求。
例如：
所有数据库操作必须经过 Repository。 Controller 不允许直接访问数据库。 新增接口必须补充测试。这些规则比单纯的代码风格更重要，因为它们决定了项目的一致性。
3. Architecture（架构说明）
这里不需要详细设计图，而是帮助 Claude Code 快速建立整体认知。
例如：
auth/ 负责认证 order/ 订单 payment/ 支付 common/ 公共组件还可以说明：
- 服务之间的关系；
- 核心模块职责；
- 关键数据流。
目标是帮助 AI 快速找到正确的分析入口。
4. Guardrails（开发禁区）
这是最容易被忽略，也是最重要的一部分。
建议明确写出：
- 禁止修改自动生成代码；
- 禁止修改数据库迁移；
- 禁止提交敏感配置；
- 不允许绕过权限校验；
- 不允许修改第三方 SDK。
例如：
不要修改： generated/ migration/ vendor/ 第三方 SDK这些规则能够有效降低误修改风险。
八、开发者应该如何使用它
实践中，可以遵循几个原则。
第一，优先写长期规则，而不是临时需求。
如果某项信息只对当前任务有效，更适合作为 Prompt，而不是写进CLAUDE.md。
第二，保持内容简洁。
每一条规则都应该能够指导开发，而不是解释实现细节。
第三，持续维护。
团队规范发生变化时，应同步更新文档。
第四，与 README 分工明确。
README 描述项目。
CLAUDE.md描述开发。
第五，把重点放在容易出错的地方。
相比介绍技术栈，更值得写的是：
- 哪些目录不能改；
- 哪些规则不能违反；
- 哪些检查必须执行。
这些信息对 AI 的帮助更直接。
九、它的局限和风险
幻觉仍然存在
即使拥有完整的规则，Claude Code 仍可能误解复杂业务逻辑。
缓解建议：保留人工 Review，并通过测试验证关键修改。
文档容易过期
项目规范改变后，CLAUDE.md如果没有同步更新，会持续误导 AI。
缓解建议：将其纳入代码评审和版本管理流程。
内容过于冗长
把 Wiki 全部复制进去，会增加上下文负担。
缓解建议：保持概览，详细内容链接到其他文档。
无法覆盖所有特殊情况
团队经验中总会存在例外。
缓解建议：对特殊业务规则，在任务中补充说明，而不是全部放入长期文档。
仍然依赖开发者判断
CLAUDE.md能帮助 AI 遵守规则，但无法代替开发者做架构取舍和业务决策。
缓解建议：将 AI 定位为执行者，把关键决策保留给开发者。
对大型项目需要分层维护
一个文件无法完整描述复杂系统。
缓解建议：将全局原则放在CLAUDE.md，模块细节拆分到独立文档，通过引用形成分层知识结构。
十、总结：它真正改变的是什么
CLAUDE.md的核心价值，并不是告诉 Claude Code 如何生成代码，而是告诉它如何像团队成员一样参与开发。
它沉淀的是代码之外的长期知识：开发命令、团队规范、系统架构和开发禁区。这些内容过去依赖口头沟通，如今可以成为项目的一部分，与代码一起维护、一起演进。
对于团队而言，真正值得投入精力的，不是把所有知识都写进CLAUDE.md，而是优先记录那些AI 最容易猜错、却最影响开发质量的信息。以“命令、规范、架构、禁区”为核心组织内容，既能帮助 Claude Code 更快进入工作状态，也能降低重复沟通和误修改的成本。
从这个角度来看，CLAUDE.md更像是一份 AI 协作者手册，而不是配置文件。它连接了团队经验与 AI 能力，让开发者能够把更多时间投入到设计、决策和代码评审，把那些稳定、重复且可规范化的知识，交给文档和工具共同维护。