CLAUDE.md 与 AGENTS.md：是什么、该写什么，以及为什么智能体会无视规则

CLAUDE.md 与 AGENTS.md 是什么

它们是放在仓库根目录的普通 Markdown 文件，智能体会在会话开始时自动把它们加载到上下文中。通过这些文件，你可以告诉智能体那些它无法从代码中自行推断的信息：如何启动环境、用哪些命令验证工作、哪些项目规则不容讨论，以及详细文档放在哪里。

CLAUDE.md 是 Claude Code 读取的文件。AGENTS.md 是理念相同的开放格式，许多编程智能体都支持它。如果团队同时使用多个智能体，最好把主要内容放在 AGENTS.md 中，再让 CLAUDE.md 引用它。Claude Code 支持用 @ 导入另一个文件：

# CLAUDE.md
@AGENTS.md

这样规则只存在一处，两个文件不会互相矛盾。

智能体如何读取这些文件

指令文件的内容会与系统提示词一起进入模型的上下文窗口，并在整个会话中保留。由此产生三个重要结论。

• 每一行都占用上下文空间。文件每次启动都会被完整读取，即使当前任务只需要其中十分之一。
• 它是文本，而不是可执行的规则。模型会像对待其他上下文一样考虑它，没有任何机制保证百分之百遵守。严格的禁令需要用机制来保障：检查、钩子、访问权限。
• 文件可以分层放置。Claude Code 会加载项目根目录的 CLAUDE.md 以及用户目录 ~/.claude/ 中的文件；位于子目录的文件，则在智能体处理该目录中的文件时加载。这样就可以把模块的规则放在模块旁边。

在 CLAUDE.md 和 AGENTS.md 中该写什么

好的指令文件是地图，而不是教科书。它要回答的，是你在项目第一天会向一位资深同事询问的问题。

1. 如何构建和验证项目

这是最有价值的部分：智能体在声称“完成”之前必须执行的具体命令，比如测试、代码检查、类型检查、启动环境。没有这些命令，智能体只能“凭感觉”检查自己的工作。

2. 硬性约束

一份简短的清单，列出任何情况下都不能违反的规则：安全和数据的不变量。要写成不变量，而不是实现步骤：“所有 SQL 查询都必须参数化”，而不是“请在某某文件中使用某某函数”。

3. 项目地图

各部分位于何处：目录结构的几行说明，以及从哪里找到详细内容。对于每个大主题，给出指向独立文档的链接，智能体只有在处理该主题时才会打开它。

4. 工作状态存放在哪里

为了接续上一次会话的工作，应该看哪些文件：计划文件、进度日志、待办清单。这能治好智能体在会话之间的“失忆”。

不应该写什么

• 智能体能从代码中读到的内容。依赖列表在 package.json 或 pyproject.toml 里，类的结构在代码本身中。
• 泛泛的建议。“写整洁的代码”“要仔细”不会改变任何行为，只会占用空间。
• 项目历史和一次性笔记。“三月份我们从 MySQL 5.7 迁移了”对当前任务毫无帮助。
• 冷门任务的详细说明。部署或数据迁移的步骤一周才用一次，应该放进独立文档或 skill。
• 密钥。文件保存在仓库中，并会完整送入模型。令牌和密码只能放在环境变量里。

为什么智能体会忽略文件中写着的规则

典型的情况是：智能体犯了错，于是有人在文件里加一条规则；又犯了一次错，再加一条。几个月后文件已有数百行，而一条关键的安全规则，智能体却像它不存在一样违反。通常有四个原因，并且同时起作用。

文件臃肿

一个 600 行的文件大约相当于 1 万到 2 万个 token。上下文窗口看起来很大，但代码、命令输出和对话历史也要占用它。指令占的空间越多，每条规则得到的关注就越少，留给任务本身的空间也越少。

规则埋在中间

与开头和结尾相比，语言模型更难有效利用长文本中间的信息。六百行中的第三百行，正处在最薄弱的位置。

没有优先级

一条不容讨论的禁令和一条随手记下的风格偏好，格式完全一样，都是列表中的一行。智能体无从判断哪个更重要。如果文件里有三条相互矛盾的风格规则，智能体每次运行的行为都会变得随机。

逐渐腐化

添加规则不花钱，删除规则却令人担心：“万一有什么依赖它呢？”于是文件单调增长，有用行的比例不断下降。可以用信噪比来衡量：典型任务真正需要多少行，而实际上有多少行是多余的。

如何修复：用路由文件代替长篇大论

只精简文件而不调整结构是没有用的：规则仍然混杂在一起。有效的做法是一组措施。

1. 把入口文件变成路由。50 到 150 行：验证命令、硬性约束、项目地图，以及指向各专题文档的链接。
2. 把专题拆分成独立文件。例如 docs/agents/deploy.md、docs/agents/database.md。智能体需要时再打开。在 Claude Code 中，对于重复出现的流程，skills 很合适：只有在需要时才会加载。
3. 把关键内容放到最前面。硬性约束放在文件开头，用简短的独立段落并明确标注 MUST。
4. 消除矛盾。每个主题只保留一条规则。如果存在例外，就把例外写在规则旁边。
5. 用机制来巩固规则。如果违反是不可接受的，光靠文字是不够的：需要能发现违规的检查，比如代码检查器、测试、pre-commit 钩子、智能体钩子，或者访问权限层面的限制。
6. 定期审查。为文件设定行数上限，每次添加内容时都问一问：什么可以删除或移出去。

规则还是检查？

精简 AGENTS.md 示例

# AGENTS.md——支付后端（FastAPI、PostgreSQL）

## MUST——不得违反
- 金额为 int（以分为单位），绝不使用 float
- 只使用参数化 SQL，不用 f-string
- 不修改已应用的迁移，只能新增迁移
- 密钥只能来自环境变量

## 声称“完成”之前的验证
docker compose up -d     # 环境
make lint                # ruff + mypy
make test                # pytest
make e2e                 # 下单场景
单元测试通过但没有 e2e，不算“完成”。

## 地图
- app/payments/   — 金额计算、折扣、服务商 webhook
- app/api/        — HTTP 接口
- tests/e2e/      — 用户场景
详细内容：docs/agents/architecture.md、docs/agents/database.md

## 工作状态
- PLAN.md      — 当前目标、完成标准、下一步
- PROGRESS.md  — 已完成的工作及验证方式，死胡同
- BACKLOG.md   — 顺带发现的问题：记录在这里，现在不修

会话结束时，更新 PROGRESS.md 以及 PLAN.md 中的下一步。

注意这里没有什么：没有依赖库清单，没有风格建议，没有项目历史。这些要么能从代码中看出，要么由检查来保障，要么放在专题文档中。

失忆问题：指令文件加计划文件

指令文件描述的是如何在项目中工作，但不说明现在正在发生什么。为此需要一个单独的状态文件：智能体在会话开始时读取它，在结束时更新它。其中包括：目标、已完成的工作及验证方式、带理由的决定、被否决的方案，以及唯一的下一步。检验质量很简单：打开一个新会话，只输入“继续”，看智能体能否不提问就开始有用的工作。

不要把两个文件混为一谈。指令很少变化，适用于所有任务。计划每次会话都在变化，只针对当前任务。如果混在一起，指令文件很快就会被过时的笔记撑大。

如何检验文件是否有效

指令文件同样需要检验。选几个典型任务，比如修 bug、小功能、重构，观察智能体在没有提示的情况下做了什么：是否运行了正确的命令，是否打开了正确的专题文档，是否遵守了硬性约束。如果某条规则被违反，先问自己：它是否看得见，是否与其他规则冲突，能否用自动检查代替。最后才考虑追加一行文字。

总结

CLAUDE.md 和 AGENTS.md 是智能体进入项目的入口。只有当它们保持为简短的地图——验证命令、顶部的硬性约束，以及指向细节和计划文件的链接——才能发挥作用。如果规则被忽略，问题几乎总是出在臃肿、缺乏结构的文件上；而真正关键的规则，还必须用检查和钩子来加固。指令与状态的搭建方法，在 Harness 工程课程中结合实践做了详细讲解。