【claude code实践】CLAUDE.md 入门：给 AI 写一份项目说明书

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 规范；
• 测试方式；
• 禁止修改目录。

第三步：分析代码

定位：

• PaymentService；
• OrderService。

建立任务上下文。

第四步：完成修改

新增：

• 超时处理；
• 回滚逻辑；
• 单元测试。

第五步：执行验证

运行测试。

确认没有破坏已有功能。

第六步：开发者 Review

检查：

• 是否符合架构规范；
• 是否满足业务要求；
• 是否遗漏异常情况。

最终完成提交。

相比每次重新解释项目规则，整个协作过程更加稳定，也更容易保持一致性。

六、它和传统方式的区别

可以发现，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 能够理解这些规则时，它才能更稳定地参与代码阅读、功能开发、测试生成和重构等工作，而开发者则可以把更多精力放在架构设计、业务决策和代码质量把控上。