让 AI 读懂你的项目：上下文和规则文件

第 05 模块第 5 课讲过：模型本身不记得任何东西，每次对话都从零开始。AI 编程工具也一样。你昨天花了半小时跟它解释"我们的测试要用 make test 跑，不能直接 pytest"，今天打开一个新对话，它又直接跑了 pytest。

解决办法是把这些"每次都要重新解释的事情"写进一个文件，让工具每次启动时自动读进上下文。这一课讲这个文件怎么写。

这些文件叫什么

不同的工具，读的文件不一样。截至 2026 年 9 月，各家官方文档的说法是：

AGENTS.md 是一个开放的格式，现在由 Linux 基金会下的 Agentic AI Foundation 维护，它的官网（agents.md）列出了二十多个支持它的工具。它的定位很简单：README 是写给人看的，AGENTS.md 是写给 AI 编程工具看的。

Claude Code 的文档明确写着它读 CLAUDE.md 而不读 AGENTS.md。如果你的项目已经有了 AGENTS.md，官方推荐的做法是建一个 CLAUDE.md，里面写一行 @AGENTS.md 把它引进来，这样两类工具读到的是同一份内容，不用维护两份：

@AGENTS.md

## 只对 Claude Code 生效的补充
改动 src/billing/ 下的代码之前，先进入计划模式。

文件名和规则会随版本变化，用之前看一眼你所用工具的最新文档。下面讲的写法，对所有这类文件都适用。

放在哪里，谁先谁后

这类文件通常可以放在好几个层级：

• 个人全局：比如 ~/.codex/AGENTS.md、~/.claude/CLAUDE.md，写你个人在所有项目里的偏好。
• 项目根目录：提交到 git，整个团队共享。
• 子目录：在大型仓库里，某个子项目可以有自己的一份，只在处理那个目录的文件时生效。

多个文件同时存在时，一般的规则是：离当前工作的文件越近，越优先。AGENTS.md 官网的原话是 "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything"，也就是离被编辑文件最近的那份生效，而你在对话里直接说的话优先级最高。Codex 和 Claude Code 的做法是把从根目录到当前目录的各层文件依次拼接起来，越靠近当前目录的越靠后，后面的内容自然覆盖前面的。

写什么

用一个问题来判断：这件事，是不是每次都要跟 AI 重新解释一遍？

值得写进去的，通常是这些：

怎么构建、怎么测试、怎么检查。这是最重要的一项。AI 改完代码，要能自己验证。写清楚具体的命令：

## 命令
- 安装依赖：`uv sync`
- 运行全部测试：`uv run pytest -q`
- 只跑一个文件：`uv run pytest tests/test_retrieval.py -q`
- 代码检查：`uv run ruff check .`

项目的结构。哪些代码在哪个目录，入口在哪里。只写 AI 从文件名看不出来的部分。

这个项目特有的规矩。和通用做法不一样的地方，最值得写：

## 约定
- 所有调用大模型的代码都通过 `llm.py` 里的函数，不要直接 new 一个 OpenAI 客户端。
- 价格表在 `llm.PRICES`，改价格只改这一处。
- 用户能看到的文字一律用中文。

踩过的坑。AI 犯过一次的错，写下来，防止它再犯：

## 注意
- 检索器里调用本地模型必须持有 `_MODEL_LOCK`，多线程同时调用会互相争抢到几乎卡死。
- `data/httpx-docs/` 是第三方文档的副本，不要修改里面的文件。

不写什么

• AI 自己看代码就能知道的东西。目录里有哪些文件、用了哪些依赖，它自己会看。写进去只是浪费上下文。
• 泛泛的原则。"写出高质量的代码"、"注意安全"，没有任何可以检查的内容，写了等于没写。
• 很长的操作步骤。只在某类任务里才需要的长流程，不适合放在每次都要读的文件里。有些工具有专门的机制按需加载（比如 Claude Code 的 skills、Cursor 的按条件生效的规则）。
• 秘密。密钥、密码、内部地址，一律不要写。这个文件会被提交到 git，也会进入模型的上下文。

Claude Code 的文档建议一份 CLAUDE.md 控制在 200 行以内。原因很直接：这个文件每次都会整个读进上下文，越长越占地方，而且规则越多，模型越难全部遵守。

写得具体，才能被遵守

对比两种写法：

具体的写法有一个共同点：可以检查。AI 做没做到，你一看就知道。含糊的写法，AI 会觉得自己已经做到了。

规则之间不能矛盾。根目录的文件说"用 2 个空格缩进"，子目录的文件说"用 4 个空格"，模型可能随便挑一个。定期把这些文件读一遍，删掉过时的、互相冲突的内容。

规则文件是上下文，不是强制

这一点非常重要，也最容易被误解。

Claude Code 的官方文档说得很明白：CLAUDE.md 是作为上下文交给模型的，模型会尽量遵守，但不保证严格遵守。它不是一道强制执行的规则。你在文件里写了"不要修改 .env 文件"，模型大多数时候会照做，但总有例外。

第 05 模块第 8 课的实验给过一个很好的对照：提示词里写得清清楚楚的安全规则，更强的那个模型仍然 5 次里有 4 次违反了。规则文件和提示词本质上是同一种东西。

所以真正不能碰的东西，要用工具提供的强制机制来限制，而不是写在规则文件里指望模型自觉：

• 权限设置：大多数工具都能配置哪些命令、哪些文件需要你确认，哪些直接禁止。比如 Claude Code 可以在设置里写禁止规则，Codex 可以选择只读或者只能在工作区内写入的沙箱。
• 钩子：一些工具支持在特定时机自动运行你的脚本，比如每次改完文件自动跑格式化、每次执行命令前检查它是不是危险命令。钩子是程序在执行，不依赖模型的判断。
• git 和代码审查：AI 的所有改动都通过 git 提交，你在合并之前看一遍。这是最后、也最可靠的一道关。

一句话：规则文件用来告诉 AI"怎么做更好"，强制机制用来保证"什么绝对不能做"。

从一个空文件开始

不要一上来就写一份大而全的规则文件。更好的办法是：

1. 用工具自带的初始化命令生成一个初稿。Claude Code 和 Codex 都有 /init 命令，会分析你的项目，写出构建命令、目录结构这些基本信息。
2. 删掉 AI 自己看代码就能知道的内容，补上它不知道的：团队约定、踩过的坑。
3. 以后每当 AI 犯了第二次同样的错误，或者你发现自己又在对话里重复解释同一件事，就往文件里加一条。

规则文件和评估集一样，是在使用中一点点长出来的。

练习

1. 给你自己的一个项目写一份 AGENTS.md（或者 CLAUDE.md），控制在 50 行以内。写完之后，对照本课"不写什么"一节删一遍。
2. 找一条你想让 AI 严格遵守的规则（比如"不许修改 migrations 目录"），查一查你用的 AI 编程工具有没有办法把它变成强制的限制，而不只是写在规则文件里。
3. 为本课程的 RepoBot v4 写一份 AGENTS.md。想一想：一个第一次打开这个项目的 AI 编程工具，最需要知道哪几件事？

自测

1. 项目里已经有 AGENTS.md，想让 Claude Code 也读到同样的内容，怎么做？

Claude Code 读 CLAUDE.md，不读 AGENTS.md。按官方文档，可以建一个 CLAUDE.md，在里面写一行 @AGENTS.md 把它引入，下面还可以追加只针对 Claude Code 的内容；如果不需要额外内容，也可以建一个指向 AGENTS.md 的符号链接。

2. 在规则文件里写了"不要修改 .env 文件"，能保证 AI 不会改吗？

不能。规则文件是作为上下文交给模型的，模型会尽量遵守，但不保证。真正不能碰的东西，要用工具的权限设置、钩子这类强制机制来限制，并且通过 git 审查每一次改动。

3. 规则文件里最值得写的是什么？最不应该写的是什么？

最值得写的是 AI 自己看不出来、又每次都需要的信息：怎么构建和测试（具体命令）、项目特有的约定、踩过的坑。最不应该写的是 AI 看代码就能知道的东西、没法检查的泛泛原则，以及任何密钥和密码。