CLAUDE.md 入门给 AI 写一份项目说明书引言为什么现在需要理解它如果你带过新人大概都会经历这样的过程。第一天新同事打开项目你不会直接让他修改代码而是会告诉他这个项目是做什么的哪几个模块最重要代码应该从哪里开始看哪些目录不能随便改提交代码之前要运行哪些测试团队有哪些开发规范。这些信息大部分并不在代码里而是来自团队长期积累的经验。对于 Claude Code 来说也是如此。虽然它能够主动搜索代码、阅读文件、执行命令但它并不知道哪些模块是核心、哪些规则属于团队约定、哪些目录只是历史遗留。如果缺少这些背景它只能依赖代码本身推断而推断并不总是准确。因此Claude Code 提供了一种简单却非常重要的机制——CLAUDE.md。它的作用不是描述代码实现而是把开发者希望 AI 始终了解的项目知识整理成一份长期维护的项目说明书。本文将围绕CLAUDE.md展开解释它是什么、为什么存在、应该写什么以及如何让它真正成为 Claude Code 理解项目的重要入口。一、CLAUDE.md 是什么一句话来说CLAUDE.md 是一份专门面向 Claude Code 的项目说明文档用来描述项目背景、开发规范、工作约定和 AI 在项目中的协作规则。第一次看到这个文件时很多开发者都会误解。有人认为它只是另一个 README。有人觉得它就是 Prompt。还有人把它当成配置文件。实际上这三种理解都不完全正确。README 面向的是所有开发者重点介绍项目是什么、如何启动、如何使用。Prompt 通常只服务于一次对话每次开始新的会话都需要重新输入。而CLAUDE.md更像是一份长期存在于项目中的协作说明。它记录的是那些不会频繁变化、但对 AI 持续完成开发任务非常重要的信息。例如项目采用什么架构哪些目录禁止修改编码规范是什么测试如何执行提交代码前需要检查什么团队有哪些开发约定。这些内容不是一次任务的背景而是整个项目的长期知识。二、从「给 AI 写项目说明书」开始理解它可以把 Claude Code 想象成一位刚加入团队的新同事。每次开始开发之前他都会问很多问题Controller 放在哪里数据库访问统一走哪个模块是否允许直接修改 SQL日志应该使用哪个组件如果每次都靠开发者口头说明不仅效率低而且容易遗漏。于是团队决定整理一份《开发说明》。里面写着项目采用领域驱动设计。 所有数据库访问必须经过 Repository。 禁止直接修改 migration。 所有新增接口必须补充单元测试。 提交前执行 ./gradlew test以后每一位新人都会先阅读这份文档。CLAUDE.md的定位与此非常接近。它不是让 AI 理解业务代码而是帮助 AI 快速理解团队如何开发这个项目。这一点非常重要。代码决定了系统如何运行而CLAUDE.md决定了AI 应该如何参与开发。三、它解决了什么问题1. 避免重复解释开发规则很多开发者每天都会重复告诉 AI不要修改generated/。测试必须运行。使用 Jest。不允许直接访问数据库。这些说明其实属于项目知识而不是任务知识。CLAUDE.md可以把它们长期保存下来。改变的是开发者不用每次重新输入相同的规则。限制在于如果规则发生变化文档也需要同步更新。2. 减少错误推断Claude Code 很擅长分析代码但无法知道为什么团队坚持某种写法为什么某个目录不能修改为什么必须走某个接口如果没有说明它只能根据代码猜测。而CLAUDE.md可以直接告诉它所有权限统一由 AuthService 管理。 禁止绕过权限中间件。 所有缓存统一使用 RedisClient。改变的是AI 不需要依赖推断而是可以遵循明确约定。限制在于文档无法覆盖所有特殊情况。3. 提高长期协作效率随着项目越来越大开发者与 AI 的协作会越来越频繁。如果每次都重新介绍项目背景不仅浪费上下文也影响开发效率。CLAUDE.md相当于把长期信息沉淀下来。改变的是每次新任务都可以建立在相同的基础之上。限制在于它不能替代当前任务的具体描述。四、它的基本工作方式理解CLAUDE.md可以从 Claude Code 的上下文构建过程来看。第一步读取项目说明Claude Code 进入项目后会优先获取项目中的长期说明信息。例如项目采用 Spring Boot。 所有接口返回统一格式。 禁止修改 generated/。 测试命令 ./gradlew test这些内容成为项目级上下文的一部分。第二步结合开发任务开发者输入给订单接口增加优惠券校验。Claude Code 不只是分析任务还会结合项目说明是否符合架构应该修改哪些模块是否需要补充测试是否违反已有约定第三步读取相关代码随后继续搜索代码阅读模块分析依赖建立任务上下文。这里CLAUDE.md提供的是方向而源码提供的是细节。第四步执行修改完成修改代码更新测试调整文档。整个过程中项目说明持续影响 Claude Code 的决策。第五步验证结果根据项目说明执行./gradlewtest或者npmtest验证是否符合团队要求。因此CLAUDE.md并不是一次性的 Prompt而是整个开发流程中的长期约束。五、一个典型使用流程假设一个团队维护着电商系统。他们编写了如下CLAUDE.md# 开发规范 订单逻辑 backend/order 支付 backend/payment 数据库 统一 Repository。 测试 npm test 不要修改 generated/。开发者提出需求增加支付超时自动取消订单。整个过程如下。第一步提出任务Claude Code 接收需求。第二步读取项目说明知道支付模块位置Repository 规范测试方式禁止修改目录。第三步分析代码定位PaymentServiceOrderService。建立任务上下文。第四步完成修改新增超时处理回滚逻辑单元测试。第五步执行验证运行测试。确认没有破坏已有功能。第六步开发者 Review检查是否符合架构规范是否满足业务要求是否遗漏异常情况。最终完成提交。相比每次重新解释项目规则整个协作过程更加稳定也更容易保持一致性。六、它和传统方式的区别对比维度CLAUDE.mdREADME普通 Prompt团队 Wiki面向对象Claude Code所有开发者当前对话团队成员生命周期长期维护长期维护单次会话长期维护是否参与 AI 上下文是可以作为参考是通常不会自动使用描述内容开发约定、规则、协作方式项目介绍、启动方法当前任务全量知识是否适合持续开发是部分适合不适合较适合但成本高可以发现CLAUDE.md与 README 并不是替代关系而是互补关系。README 解释项目是什么CLAUDE.md解释AI 应该如何参与这个项目。七、适合什么场景不适合什么场景适合的场景CLAUDE.md特别适合沉淀那些长期有效的项目知识例如项目架构说明目录职责划分编码规范提交前检查项测试命令开发流程约定禁止修改的目录常见开发注意事项。这些信息能够持续提升 Claude Code 的理解效率。不适合的场景以下内容则不建议放入CLAUDE.md临时开发任务一次性的 Prompt详细业务需求大量接口文档长篇设计方案经常变化的数据。这些内容更适合作为任务上下文或独立文档维护。八、开发者应该如何使用它写长期有效的信息优先记录那些半年甚至一年都不会变化的内容。例如架构原则技术选型编码规范测试流程。避免把临时需求写进去。保持内容简洁不要把CLAUDE.md写成几十页的开发手册。更好的方式是给出原则提供入口链接详细文档。让 Claude Code 能够快速理解而不是花费大量上下文阅读说明。与 README 分工明确建议遵循这样的原则README 回答项目是什么CLAUDE.md回答AI 如何参与这个项目这样两份文档各司其职。随项目一起维护项目规范发生变化时应同步更新CLAUDE.md。否则AI 将依据过时的信息继续工作。配合任务 Prompt 使用即使拥有完善的CLAUDE.md开发者仍然需要描述当前任务。例如仅修改订单模块。 不要调整数据库结构。 补充对应测试。长期规则和当前任务结合才能形成完整上下文。九、它的局限和风险文档可能过期项目持续演进但CLAUDE.md没有同步维护。缓解建议将其纳入项目文档体系与代码评审同步更新。内容过多把团队 Wiki 全部复制进去。缓解建议保持精炼只保留长期有效的信息并链接详细文档。内容过少只有一句这是一个 Java 项目。这样的说明几乎没有帮助。缓解建议增加架构、规范、目录职责和测试流程等关键信息。无法替代源码CLAUDE.md可以说明原则但无法解释具体实现。缓解建议将其作为导航而不是代码说明书。无法替代开发者判断AI 能够遵守规则但无法理解所有业务背景和设计取舍。缓解建议对重要设计决策、安全相关修改和复杂业务逻辑保留人工评审。对超大型项目覆盖有限一个文件无法描述整个企业级系统。缓解建议保持CLAUDE.md聚焦全局原则模块细节放入独立文档并通过链接组织知识体系。十、总结它真正改变的是什么CLAUDE.md的价值并不在于让 Claude Code 变得更聪明而在于让它更快进入团队的开发语境。它沉淀的是那些隐藏在代码之外的知识架构原则、开发规范、协作方式和长期约定。这些信息过去主要依赖团队成员口口相传如今可以通过一份项目说明书稳定地提供给 AI。从开发工作流来看CLAUDE.md并不是 README 的替代品也不是一次性的 Prompt而是连接团队经验与 AI 协作的一层长期上下文。它让每一次开发任务都能建立在统一的规则之上而不是从零开始理解项目。对于开发者来说真正值得投入的不是把所有知识都塞进CLAUDE.md而是持续维护一份简洁、准确、长期有效的 AI 项目说明书。当 Claude Code 能够理解这些规则时它才能更稳定地参与代码阅读、功能开发、测试生成和重构等工作而开发者则可以把更多精力放在架构设计、业务决策和代码质量把控上。