【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.mdREADME一次性 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 能力让开发者能够把更多时间投入到设计、决策和代码评审把那些稳定、重复且可规范化的知识交给文档和工具共同维护。