大家好，我是专注于编程领域的鱼皮。

　　最近，我注意到一个趋势，越来越多的开发者开始使用Claude Code、Cursor等AI编程辅助工具。然而，不少人在使用一段时间后开始抱怨：AI似乎并不总是那么听话，有时修改一个Bug反而引入了三个新问题，或者添加一个功能却意外改变了整个技术栈。

　　这些问题的根源，很多时候并非AI本身不够智能，而是因为我们没有为它提供足够的上下文信息。

　　每次AI开启一个新的会话，它都如同一张白纸，对我们的项目技术栈、团队代码规范、以及之前的决策一无所知。

　　如果我们不主动告知，AI就只能猜测，猜对了是运气，猜错了则意味着我们需要返工，浪费时间和tokens。

　　那么，有没有一种方法能让AI在每次开始工作前就自动了解我们的项目呢？

　　当然有！这就是我们今天要深入探讨的CLAUDE.md。

　　⭐️本文内容将纳入我免费开源的教程中

　　一、CLAUDE.md究竟是什么？

　　CLAUDE.md是Claude Code中的一个Markdown文件，通常放置在项目的根目录下。

　　每当Claude Code启动一个会话时，它会自动读取这个文件，并将其中的内容视为项目的背景知识。

　　你可以将其视为为AI量身定制的“入职手册”。就像新员工入职时，我们会提供一份文档，介绍公司的技术栈、代码规范、测试流程以及需要注意的陷阱等。CLAUDE.md的作用正是如此。

　　例如，一个简单的CLAUDE.md可能如下所示：

　　# 我的博客系统

Next.js 16 + TypeScript + Tailwind CSS + Supabase
## 常用命令
-npm run dev # 启动开发服务器
-npm run test # 运行测试
-npm run build # 构建生产版本

## 代码规范
-使用函数式组件，避免使用class组件
-样式仅使用Tailwind CSS，不编写自定义CSS
-所有组件必须包含TypeScript类型定义


　　AI在每次开始工作前都会先阅读这份文档，随后生成的代码将自动遵循这些规范，无需我们每次重复交代。

　　但有一点需要注意，CLAUDE.md对AI而言是建议性的，而非强制性的配置。其效果取决于我们撰写的具体程度和简洁性。越精确的指令，AI的遵循度越高；反之，模糊的要求可能被AI忽略。

　　二、更通用的AGENTS.md

　　你可能会问，这是否仅适用于Claude Code？如果我使用Cursor等其他工具怎么办？

　　实际上，几乎所有主流的AI编程工具都提供了类似的机制。例如，Cursor支持.cursor/rules/和AGENTS.md来实现相同的功能。

　　AGENTS.md是一个跨工具的开放标准，由OpenAI、Google、Cursor等多家公司联合推出。目前，已有数万个开源项目采用，支持30多种AI编程工具。

　　虽然Claude Code默认仅读取CLAUDE.md，但我们可以在CLAUDE.md中通过一行@AGENTS.md将其导入，实现两者之间的互通。

　　这些Markdown文件的本质相同，都是为AI提供项目说明书。掌握撰写这份说明书的技巧，无论更换何种AI编程工具，都能游刃有余。

　　此外，AGENTS.md不仅可用于项目开发指导，还可作为指导AI工作的流程文档。例如，我利用AGENTS.md定义各种工作流程，如图文创作、产品客服、数据分析等场景，通过一份Markdown文件固定AI的工作方式，每次启动时自动加载，避免重复交代。

　　后续内容我将统一使用CLAUDE.md进行讲解，但其中的技巧同样适用于所有工具。

　　三、为何必须重视CLAUDE.md的撰写？

　　你可能会认为，这不过是一个配置文件，随意撰写即可。

　　然而，这种想法大错特错！CLAUDE.md的质量直接决定了AI协助我们工作的效率和准确性。

　　根据我长期使用AI编程的经验，一个优秀的CLAUDE.md至少能解决以下三个问题：

　　第一，减少重复沟通。

　　在没有CLAUDE.md的情况下，每次新会话我都需要重复交代技术栈、代码规范、项目结构等信息。有了它，这些信息AI自动掌握。

　　第二，提升代码一致性。

　　之前，AI有时使用React函数组件，有时又生成class组件；样式时而采用CSS Modules，时而编写内联样式。将规范写入CLAUDE.md后，此类问题基本消失。

　　第三，降低出错率。

　　例如，我的项目中有一个特殊的API响应格式{ success, data, error }，若不写入规则，AI每次都会按自己的习惯生成。写入后，Claude会自动遵循，无需我每次纠正。

　　我在之前的文章中提到过，当规则文件长度在50行左右时，AI的遵循率可达94%；但若堆砌至400行，遵循率将下降至71%。

　　因此，CLAUDE.md并非越长越好，而是需要精准。

　　这引出了本文的核心问题，也是重点内容：如何撰写一份优秀的CLAUDE.md文档？

　　四、如何撰写高质量的CLAUDE.md？

　　以下技巧经过社区大量实践和我个人验证，建议仔细阅读并深入理解。

　　1、控制在200行以内

　　这是Claude Code官方文档的建议。

　　CLAUDE.md的内容会在每次会话开始时加载到AI的上下文窗口中。这个窗口容量有限，规则文件越长，留给实际工作内容的空间就越少。

　　此外，AI对指令的遵循能力与指令数量呈负相关。有研究表明，AI大约能合理遵循150至200条指令，超过此数量，遵循质量将均匀下降，不仅忽略新增指令，整体表现也会变差。

　　因此，撰写CLAUDE.md应如同撰写简历，力求精炼。

　　对于每一行内容，都应自问：删除它是否会导致AI出错？

　　若答案为否，则果断删除。

　　2、仅记录AI无法猜测的信息

　　官方文档专门列出了CLAUDE.md中应包含和不应包含的内容清单，极具参考价值。

　　应包含的内容：

　　 AI无法猜测的构建命令和测试命令

　　 与默认不同的代码风格规则

　　 团队的Git规范（分支命名、PR格式）

　　 项目特有的架构决策

　　 开发环境的特殊要求（如必需的环境变量）

　　 容易踩坑的地方

　　不应包含的内容：

　　 AI通过阅读代码即可了解的信息

　　 通用的语言规范（AI本就掌握）

　　 详细的API文档（应放在其他位置，CLAUDE.md中仅提供链接）

　　 诸如“编写干净代码”、“注意性能”等泛泛之谈

　　以我的编程导航项目为例，我将一些即使阅读代码也容易忽略的约定写入CLAUDE.md，如API响应统一使用BaseResponse包装类、异常统一用BusinessException抛出。虽然AI深入分析代码也能发现这些模式，但写入规则后能省去它每次重新推断的过程，效率大幅提升。

　　3、使用正面指令而非否定指令

　　这一技巧颇具反直觉性。

　　有研究发现，87.5%的AI规则违反源于同一原因：否定句反而激活了被禁止的概念。例如，你写“不要使用分号”，AI看到“分号”二字后，反而更容易在后续生成中包含分号。

　　这与心理学中的白熊效应如出一辙：告诉自己不要想白熊，脑海中却立刻浮现白熊的形象。

　　因此，正确的做法是使用正面表述替代否定表述：

　　 ❌ 不要使用class组件 → ✅ 使用函数式组件和Hooks

　　 ❌ 不要使用any类型 → ✅ 所有变量必须有明确的TypeScript类型定义

　　 ❌ 不要在主分支直接提交 → ✅ 所有变更应通过feature分支提交PR

　　
4、指令需具体且可验证

　　模糊的指令等同于无指令。AI擅长处理具体规则，但对抽象要求则会自行发挥。

　　举例如下：

　　 ❌ 正确格式化代码 → ✅ 使用2空格缩进

　　 ❌ 测试你的更改 → ✅ 提交前运行npm test

　　 ❌ 保持文件有序 → ✅ API handlers应放在src/api/handlers/

　　指令越具体，AI越容易判断自己是否遵循，违反时也越容易被发现。

　　5、利用Hooks实现强制执行

　　CLAUDE.md本质上仅为建议，并非100%生效的禁令。

　　对于代码格式化、提交前运行测试、拦截危险命令等任务，应使用确定性的自动化脚本执行。

　　Claude Code提供了Hooks机制，可在AI操作的关键节点自动执行预设脚本。

　　例如，若希望每次文件编辑后自动运行ESLint，编写一个Hooks配置即可实现，AI不介入，100%执行。

　　简而言之，CLAUDE.md负责建议，Hooks负责强制操作。

　　
6、大项目采用路径规则按需加载

　　若项目规模较大，200行根本无法容纳所有规范。此时，切勿强行塞入CLAUDE.md，而应使用.claude/rules/目录进行拆分。

　　每个规则文件可使用YAML frontmatter指定仅对特定路径的文件生效：

　　---
paths:
-"src/api/**/*.ts"
---

# API开发规范
-所有API端点必须包含输入验证
-使用标准的错误响应格式
-添加OpenAPI文档注释


　　这样，只有当Claude操作src/api/下的TypeScript文件时，这些规则才会加载到上下文中，既节省上下文空间，又避免用不相关规则干扰AI。

　　7、利用@import实现渐进式披露

　　社区中最受推崇的高级技巧是渐进式披露，其核心思想是避免将所有信息塞入CLAUDE.md，而是告知AI去哪里查找所需信息。

　　做法简单：在项目中创建docs/目录，存放各类专题文档，然后在CLAUDE.md中使用简短描述加触发条件进行引用：

　　## 参考文档

### API架构 — @docs/api-architecture.md
何时阅读：添加或修改API端点时

### 数据库设计 — @docs/database-design.md
何时阅读：创建或修改数据模型时


　　这样，Claude仅在真正需要时才会读取对应文档，平时不占用上下文空间。

　　CLAUDE.md的@path导入语法支持相对路径和绝对路径，最多可嵌套4层。

　　这一思路与我之前讲解的上下文工程和Agent Skills相似。AI编程工具的上下文窗口有限，不能一股脑将所有信息塞入。Anthropic官方将此策略称为just-in-time，即让AI按需获取信息，而非全量加载。

　　8、让AI协助维护

　　CLAUDE.md并非撰写后便一成不变，而应是一份随项目成长不断完善的“活”文档。

　　Claude Code创始人推荐的习惯是：每次Claude犯错时，不仅修正错误，还要让它将纠正写入CLAUDE.md。

　　我同样采用此做法，例如，Claude使用了错误的导入路径，纠正后我会告诉它：“将这条规则更新到CLAUDE.md中，下次别再犯。”

　　Claude擅长为自己编写规则，时间久了，你的CLAUDE.md将变成一份完整的项目知识库，出错率将显著下降。

　　此外，Claude Code现提供Auto Memory自动记忆功能，Claude会自动记录其在工作中发现的模式和偏好，存入~/.claude/projects/<项目>/memory/目录下。这些笔记每次会话都会自动加载，相当于AI为自己做的备忘录。

　　你随时可使用/memory命令查看和编辑这些记忆。

　　
五、如何快速创建CLAUDE.md？

　　看到这里，你可能会想，这些技巧我都记住了，但从零开始撰写一份完整的CLAUDE.md仍感头疼。

　　别担心，有几个快速起步的方法。

　　使用/init命令自动生成

　　在Claude Code中输入/init，Claude会自动分析你的代码库，生成一份包含构建命令、测试指令和项目规范的CLAUDE.md。若文件已存在，它会建议改进而非覆盖。

　　但需注意，自动生成的内容可能不够精确，毕竟AI只能看到你的代码成果，不理解背后的过程。

　　社区中有观点认为，CLAUDE.md影响工作流的每个阶段和产出的每个文件，一条不良指令的破坏力远超一行坏代码。因此，自动生成后，务必自行审查，该删的删、该补的补。

　　让AI从对话中提炼

　　我常用的一种方法是，先不急于撰写CLAUDE.md，正常与AI协作完成一两个任务。完成后，让AI回顾整个对话过程，帮我总结出需要记住的项目规范和注意事项，直接写成CLAUDE.md。

　　这样得到的规则文件是从实战中提炼出来的，比凭空想象要精准得多。

　　以我带团队做项目为例，每次Code Review中发现AI犯的错误，我都会让Claude将修正追加到CLAUDE.md中。一个月后，这份文件已沉淀了几十条极具针对性的规则，新同事使用Claude Code时上手也快了很多。

　　
参考优秀开源项目

　　GitHub上有个awesome-claude-md仓库，收录了100多个真实项目的CLAUDE.md示例，覆盖各种技术栈和项目类型，包括Anthropic官方、Cloudflare的monorepo项目等。

　　此外，还有个awesome-claude-code仓库，整理了Skills、Hooks、斜杠命令等Claude Code生态工具，同样值得收藏。

　　有时间的话，可以让AI帮你分析这些案例，找个与你项目技术栈接近的参考撰写，比从零开始快得多。

　　记住，CLAUDE.md的内容宁缺毋滥。

　　先从最关键的20行开始，在实际使用中再慢慢补充。

　　六、多层级配置与团队协作

　　若你在团队中使用Claude Code，或同时进行多个项目，有一些进阶玩法值得了解。

　　四层作用域

　　CLAUDE.md不仅可放在项目根目录，还支持四个层级，按加载顺序从先到后排列：

　　1）组织级，由公司IT统一部署的规范，对所有人强制生效

　　2）用户级~/.claude/CLAUDE.md，对你本机的所有项目生效

　　3）项目级./CLAUDE.md，仅对当前项目生效，可提交到Git

　　4）本地级./CLAUDE.local.md，仅对当前项目生效，不提交到Git

　　加载越靠后的内容，AI越倾向于优先遵循，因此优先级为本地级 > 项目级 > 用户级。但组织级较为特殊，虽加载最早，却不可被个人或项目设置排除，属于公司强制执行的底线规范。

　　建议团队共享的规范写在项目级，个人偏好写在本地级，两者互不干扰。

　　团队共建CLAUDE.md

　　Claude Code创始人推荐将CLAUDE.md用Git管理，让团队成员共同维护。

　　每当有人在Code Review中发现AI犯的错误，就将修正追加到CLAUDE.md中。时间久了，这个文件将沉淀团队的开发经验和规范，成为整个团队的AI使用手册。

　　我们团队同样如此。例如，面试鸭后端项目的AGENTS.md中，沉淀了技术栈选型、Spring Boot分层规范、统一响应格式、异常处理方式、数据库命名规则等约定。新同事入职直接查看这份文件即可上手，Claude也能自动遵循这些规范生成代码，节省了大量沟通成本。

　　
重要规则务必存入文件

　　当你在对话中使用/compact压缩上下文时，项目根目录的CLAUDE.md会被重新读取和注入。但你在对话中口头说的指令，如后续代码都用async/await，压缩后便会消失。

　　因此，凡是重要的规则，务必写入CLAUDE.md，不要仅在对话中提及。这一点与我之前讲解的上下文工程相通，持久化信息要落到文件里，别光靠AI的短期记忆。

　　七、排查CLAUDE.md不生效的问题

　　若发现AI似乎未遵守CLAUDE.md中的规则，可按以下顺序排查：

　　1）运行/memory命令，检查你的CLAUDE.md是否被正确加载

　　2）检查指令是否过于模糊。如“格式化好代码”这种AI无法执行的指令，应改为“使用2空格缩进、单行不超过80字符”

　　3）检查不同文件之间是否存在矛盾指令。如CLAUDE.md中说用MyBatis Plus，某个rules文件中又说用MyBatis Flex，AI可能随机选择一个

　　4）若某个操作必须在特定时机执行，如每次提交前运行lint，则不要依赖CLAUDE.md，改用Hooks

　　
结语

　　没想到吧，就这么一个Markdown文件，竟是AI编程时代最重要的基础设施之一。

　　以前，我们撰写README.md是给人看的；现在，撰写CLAUDE.md是给AI看的。但本质相同，都是将项目的重要信息组织好、传达清楚。区别在于，给AI写的说明书需更精炼、更具体、更可执行。

　　若你尚未为自己的项目撰写CLAUDE.md，不妨立即尝试。从最简单的20行开始，将技术栈、构建命令以及AI常犯的几个规则写入其中，你将立刻感受到它的强大。

　　我是鱼皮，持续分享AI编程干货。