面试官问CLAUDE.md写法，Claude Code两年经验却答不上

最近观察到一种有趣的现象：许多开发者开始尝试使用 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 执行工作流的标准文档。例如，在图文创作、产品客服、数据分析等场景中，都可以通过一份 Markdown 文件将 AI 的工作方式固定下来，每次启动时自动加载，省去重复交代的麻烦。

后续我们将统一使用 CLAUDE.md 来讲解，但其中的技巧对所有工具都适用。

三、为什么一定要写好这个文件？

你可能觉得，这不过是个配置文件，随便写写就行了吧？

这种想法大错特错。CLAUDE.md 的质量直接决定了 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 还是有点头疼。别担心，这里有几个快速入门的方法。

用 /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 的创始人推荐使用 Git 来管理 CLAUDE.md，让团队成员共同维护。每当有人在 Code Review 中发现 AI 犯了错误，就将修正内容追加到 CLAUDE.md 里。时间久了，这份文件就沉淀了团队的开发经验和规范，成为整个团队的 AI 使用手册。

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

重要规则一定要存文件

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

因此，凡是重要的规则，一定要写入 CLAUDE.md，不要只在对话里提及。这一点与上下文工程也是相通的——持久化的信息要落到文件里，不能仅依赖 AI 的短期记忆。

七、排查不生效的问题

如果你发现 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 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：面试官问CLAUDE.md写法，Claude Code两年经验却答不上要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题