别再裸奔：用 agent.md 管住代码
Coding Agent 写坏代码，往往不是模型不够强，而是项目约束没有被写清楚。本文给出一套可直接落地的 AGENTS.md 模板、分层策略与评估方法。
截至 2026 年 8 月 23 日，开发者 Fabien Sanglard 最近分享了一套用 agent.md 改善 LLM 辅助编程质量的方法：把架构边界、测试命令、工作流程和验收条件写进仓库，让 Coding Agent 每次进入项目时先读规则，再开始改代码。
这件事看起来只是多写一个 Markdown 文件，实际解决的却是 AI 编程中最难缠的问题之一：模型会换、会话会结束、上下文会压缩，但仓库对代码质量的要求不能跟着失忆。
**agent.md 是存放在代码仓库中的持久化 Agent 指令文件，用于告诉 Coding Agent 这个项目允许怎样修改、必须怎样验证，以及哪些边界不能突破。**本文沿用 Sanglard 的 agent.md 说法讨论这种方法，但在实际项目中，文件名不能随意填写：OpenAI Codex 等工具主要识别 AGENTS.md，Claude Code 使用 CLAUDE.md，GitHub Copilot 和 Cursor 也有各自的规则文件。
我们的判断是：**Agent 指令文件值得写，但它不是“万能提示词”，而是一份面向机器的代码库契约。**写得短、具体、可验证，它能减少无意义重构和测试遗漏；写成几百行团队文化手册，它只会继续消耗上下文，并制造新的指令冲突。
Coding Agent 为什么需要一份“仓库说明书”
**Coding Agent 是能够自主读取文件、搜索符号、编辑代码、执行命令并根据结果继续迭代的软件开发智能体。**它与传统代码补全的区别，不是一次能生成更多代码，而是具备“观察—行动—验证—修正”的循环。
这个循环仍然高度依赖上下文。Agent 如果不知道项目使用哪个测试命令、不知道领域层禁止引用基础设施层，也不知道团队要求保持公共接口兼容，它就只能依据训练数据中的常见模式自行猜测。
猜测通常会产生“看起来合理”的代码。例如，一个 TypeScript 项目已经统一使用 Zod 校验输入，Agent 却可能新建一套手写校验函数；一个 Go 项目明确禁止业务包访问数据库驱动，Agent 可能为了快速修 Bug 直接跨层调用；一个 C++ 项目要求避免异常，模型却可能自然地引入 throw。
**上下文压缩会进一步放大这种不稳定性。**当长任务逼近上下文上限时，Coding Agent 通常会总结此前的对话、工具输出和决策，再以压缩后的内容继续工作。压缩可以保留大方向，却难以保证每条约束都不丢失，尤其是“不要修改某个兼容层”这类出现过一次、但后续没有反复提及的信息。
AGENTS.md 的价值正在这里：它把需要长期保留的信息从对话历史搬回仓库。即使 Agent 更换会话、重新启动或经历上下文压缩，也能再次读取相同的项目约束。
agent.md、AGENTS.md 和 CLAUDE.md 不是一回事
**AGENTS.md 是正在形成跨工具生态的仓库级 Agent 指令约定，而 agent.md 更适合作为这一类文件的泛称。**大小写、位置和文件名是否正确，会直接决定工具能不能自动加载它。
截至目前，主流 Coding Agent 的约束入口并未完全统一：
| 工具或环境 | 主要指令文件 | 是否支持目录分层 | 更适合放什么 |
| --- | --- | --- | --- |
| OpenAI Codex | AGENTS.md | 支持按目录读取更具体的指令 | 通用仓库规则、构建与测试命令、局部模块约束 |
| Claude Code | CLAUDE.md | 支持项目级和目录级组织 | Claude Code 工作流、命令、架构说明与行为约束 |
| GitHub Copilot | .github/copilot-instructions.md、路径级 instructions 文件 | 支持路径匹配 | 仓库惯例和特定文件类型规则 |
| Cursor | .cursor/rules/ 下的规则文件 | 支持按路径或场景应用 | 编辑器 Agent 行为、代码模式和目录约束 |
| Gemini CLI | GEMINI.md | 可按项目组织上下文 | 项目说明、命令和工具行为 |
| 通用或自研 Agent | 取决于实现 | 不一定 | 需要在系统提示或启动流程中显式加载 |
**最稳妥的做法是选择一个通用事实源，再为不同工具增加薄适配层。**例如，把跨模型都适用的规则放进根目录 AGENTS.md，然后让 CLAUDE.md 或其他工具文件只补充工具专属要求，而不是复制一份内容后各自腐化。
如果团队只创建了小写的 agent.md，却没有确认当前工具会自动读取，那么这份文件可能从未进入模型上下文。文件存在不等于规则生效，这是最容易被忽视的第一处坑。
真正有效的规则只有四类
高质量 Agent 规则应该同时满足可执行、可验证、局部明确和长期稳定四个条件。“写出优雅代码”不是规则，因为模型无法知道团队对优雅的定义；“修改后运行 make test-unit，失败时不得声称任务完成”才是规则。
一份根目录指令文件最值得保留以下四类信息。
1. 仓库地图
**仓库地图用于告诉 Agent 应该先读哪里，而不是把整个代码库重新解释一遍。**它不需要逐个列出文件，只需指出入口、关键模块和依赖方向。
例如：
src/domain/保存领域逻辑，不允许依赖数据库和 Web 框架；src/adapters/负责外部系统接入；tests/contract/保存对外接口兼容性测试；docs/adr/保存仍然有效的架构决策记录；- 修改认证逻辑前，先阅读
docs/security-model.md。
这几行信息能够阻止 Agent 从错误的目录开始工作，也能减少它为了理解项目而读取大量无关文件。
2. 可复制执行的命令
构建、格式化、静态检查和测试命令必须完整到可以直接执行。“记得运行测试”几乎没有约束力，因为 Agent 仍然不知道该运行哪一组测试，也不知道从哪个目录运行。
规则应明确区分快速反馈和完整验证：
- 安装依赖：
make bootstrap - 格式检查：
make lint - 类型检查：
make typecheck - 单元测试：
make test-unit - 完整测试：
make test - 单模块测试：
pytest tests/payments -q
如果命令依赖容器、特定工作目录或环境变量，也必须写清楚。不要让 Agent 自行发明命令，更不要让它把“命令不存在”误判成“测试无法运行”。
3. 架构边界和禁止事项
**架构边界应该描述不能跨越的依赖关系，而不是堆积个人风格偏好。**相比“尽量保持模块化”，下面这些规则更有效：
domain不得导入adapters；- 未经确认不得增加生产环境依赖；
- 不得改变已发布的 JSON 字段名称和错误码；
- 数据库迁移必须向后兼容一个发布周期；
- 不得通过删除失败测试来让流水线通过；
- 不得在日志、测试快照或提交内容中写入凭据。
这类约束的共同点是：违反后可以通过依赖检查、测试或代码审查发现。
4. 完成定义
**完成定义是 Coding Agent 停止工作的条件。**没有明确终点的 Agent 很容易在实现功能后继续“顺手优化”，最终把一个 20 行修复扩张成数百行重构。
一项任务只有在以下条件满足后才算完成：
- 修改范围与任务直接相关；
- 新行为有对应测试，或明确说明无法增加测试的原因；
- 格式检查、类型检查和相关测试通过；
- 公共行为变化已经更新文档；
- 最终总结列出修改文件、验证命令和未解决风险；
- 未执行的检查必须明确标注，不能用模糊措辞掩盖。
一份可以落地的 AGENTS.md 模板
**下面这份模板适合作为 40 至 80 行的首版，而不是让团队原样复制后永久不管。**其中的目录和命令必须替换成真实项目内容，错误命令比没有命令更危险。
# AGENTS.md
## Mission
- Make the smallest correct change that satisfies the task.
- Preserve existing public behavior unless the task explicitly changes it.
- Do not perform unrelated cleanup or refactoring.
## Repository map
- src/domain: framework-independent business logic.
- src/adapters: database, network, and external service integrations.
- tests/contract: public API compatibility tests.
- docs/adr: active architecture decisions.
## Architecture boundaries
- src/domain must not import src/adapters.
- Do not add a production dependency without approval.
- Do not rename public fields, routes, or error codes implicitly.
- Prefer existing project abstractions over creating parallel helpers.
## Workflow
1. Read the nearest relevant code and tests before editing.
2. State a short implementation plan for multi-file changes.
3. Make the smallest coherent patch.
4. Run the narrowest relevant test first.
5. Run required repository checks before declaring completion.
## Commands
- Bootstrap: make bootstrap
- Format and lint: make lint
- Type check: make typecheck
- Unit tests: make test-unit
- Full test suite: make test
## Definition of done
- New or changed behavior is covered by tests.
- Relevant checks pass.
- Documentation is updated when public behavior changes.
- The final report lists tests run and tests not run.
## Stop and ask
- Requirements conflict with existing public behavior.
- A destructive database migration appears necessary.
- Credentials, production access, or security policy changes are required.
**这份模板最关键的一句是“完成任务所需的最小正确修改”。**Coding Agent 常见的问题不是不会写代码，而是修改半径失控：修复解析器时顺手重命名公共类型，补测试时改掉测试框架，更新依赖时重新格式化整个仓库。限制差异规模，通常比要求模型“更仔细”有效。
不要把它写成 500 行团队百科
**Agent 指令文件越长，并不意味着约束越完整。**模型同时需要处理系统提示、用户任务、工具说明、文件内容、命令输出和历史记录，仓库规则只是这笔有限注意力预算的一部分。
长文件通常存在三个问题。
第一，真正关键的安全和兼容性约束会被风格细节淹没。禁止破坏数据库迁移兼容性，与“变量名最好不要缩写”不应占据相同权重。
第二，规则越多，冲突概率越高。根文件要求“优先复用现有抽象”，子模块文档却要求“新功能必须独立实现”，Agent 很可能选择更容易执行的那一条，而不是团队认为更重要的那一条。
第三，过期规则会主动制造错误。仓库已经从 Jest 迁移到 Vitest，文件中却仍要求运行旧命令；认证入口已经移动，规则还让 Agent 阅读废弃模块。这不是低价值上下文，而是错误上下文。
**根文件建议先控制在 40 至 80 行，并把模块专属约束下沉到对应目录。**例如，根目录只写通用的测试、兼容性和安全要求，src/api/AGENTS.md 再补充接口输入必须经过 schema 校验，migrations/AGENTS.md 则规定迁移的回滚和兼容策略。
目录分层的本质是让约束靠近代码。前端模块不需要消耗注意力阅读数据库迁移规则，命令行工具也不必接收 Web API 的错误码规范。
从失败记录反推规则，而不是凭空写规范
**构建 Agent 指令文件的最佳起点不是团队风格指南，而是最近 10 至 20 次 AI 辅助提交中的真实失败。**先观察模型在哪里反复犯错，再决定哪条规则值得永久占用上下文。
可以把问题分成四组：
| 失败类型 | 典型表现 | 适合写入的规则 | | --- | --- | --- | | 找错入口 | 修改生成文件、废弃模块或镜像目录 | 仓库地图、源码入口、禁止编辑目录 | | 跨越架构边界 | 领域层直接连接数据库 | 依赖方向、允许调用的接口 | | 验证不足 | 只运行一个测试便声称全部通过 | 明确测试命令和完成定义 | | 修改过度 | 修 Bug 时进行大规模重构 | 最小差异原则、禁止无关清理 | | 遇错掩盖 | 删除测试、添加跳过标记 | 禁止通过弱化检查制造通过 | | 自行决策高风险操作 | 新增依赖、破坏迁移兼容性 | 必须暂停并询问的条件 |
**只有高频、代价高且能明确验证的问题，才值得进入根级文件。**一次性的业务需求应该留在任务描述中；语言基础语法不必重复教育模型；可以由格式化器或 linter 自动执行的规则，应优先交给工具，而不是用自然语言要求 Agent 记住。
把自然语言规则变成工具闭环
**最可靠的 Agent 约束不是一句话，而是“规则、命令和失败信号”组成的闭环。**例如，仅写“不要让领域层依赖数据库”仍然需要模型自觉遵守；如果仓库同时提供架构测试，违规导入就会直接导致检查失败。
因此，规则最好对应已有的自动化机制：
- 代码格式交给 formatter；
- 类型边界交给类型检查器；
- 模块依赖交给架构测试或依赖检查工具；
- 公共接口兼容交给 contract test；
- 安全模式交给静态扫描；
- 文件所有权交给
CODEOWNERS； - Agent 文件自身的变更也应进入代码审查。
这比继续扩写提示词更重要。LLM 擅长提出和实施修改，但不应该成为唯一裁判；测试、编译器和静态分析器才负责给出可重复的结果。
用 30 个任务验证它是否真的有效
**评估 Agent 指令文件应采用同类任务对照，而不是依赖“感觉代码更好了”。**团队可以选择 30 个规模接近的真实维护任务，将其中 15 个作为无规则基线，另外 15 个启用新文件，并尽量保持模型、工具版本和人工提示方式一致。
建议记录以下指标：
| 指标 | 计算方式 | 反映的问题 | | --- | --- | --- | | 首次通过率 | 首次提交即通过检查的任务数 ÷ 总任务数 | 规则是否减少基础错误 | | 人工修正量 | 审查后由人类修改的代码行数 | 产物距离可合并状态有多远 | | 无关变更比例 | 与任务无关的变更行数 ÷ 总变更行数 | 是否控制住修改半径 | | 测试遗漏率 | 缺少必要测试的任务数 ÷ 总任务数 | 完成定义是否生效 | | 平均迭代轮数 | 从首次修改到检查通过的 Agent 循环次数 | 指令是否减少试错 | | 回退率 | 合并后需要回退或紧急修复的任务比例 | 是否真正改善生产质量 |
**如果加入文件后首轮通过率没有改善，应优先检查规则是否被加载，而不是立刻继续加规则。**可以要求 Agent 在开始任务时简短复述当前目录最重要的 3 条约束，或者查看工具日志中的上下文加载记录，但不建议让它每次完整复述文件，那只会再次消耗 token。
如果规则确认加载却没有效果，就应检查它是否可执行。例如，“保持向后兼容”过于宽泛，可以改为“不得删除或重命名已发布的 HTTP 路径、JSON 字段和错误码；如任务要求变更，先暂停并说明兼容方案”。
指令文件本身也有供应链风险
**进入模型上下文的仓库文件本质上属于执行控制面，因此必须像构建脚本一样接受审查。**如果外部贡献者能在普通 PR 中悄悄修改 AGENTS.md，加入“跳过安全测试”或“读取本地凭据进行调试”等指令，Agent 可能在后续会话中执行这些要求。
团队至少应采取四项措施：
- 用
CODEOWNERS指定 Agent 规则文件的审核人； - 禁止在规则中保存令牌、内部地址和生产环境凭据；
- 对下载脚本、外部文档和 Issue 内容保持不信任；
- 高风险命令、生产访问和破坏性迁移必须保留人工确认。
规则优先级也不能想当然。系统提示、组织策略、用户指令、仓库文件和子目录规则之间的覆盖关系取决于具体工具；安全约束应在执行环境和权限系统中再次落实，不能只寄托于 Markdown。
最后：把它当成代码维护
**一份有效的 AGENTS.md 应该随着代码演进，并在每次错误中变得更精确，而不是持续变长。**新增规则前问三个问题：这个问题是否重复发生、是否代价足够高、是否能被验证；删除规则时则确认它是否已由工具自动执行，或对应模块是否已经不存在。
Fabien Sanglard 这次分享真正有价值的地方，不是提供了一段更神奇的提示词，而是强调了一个经常被忽略的工程事实：LLM 辅助编程的质量上限，不只取决于模型，也取决于仓库向模型暴露了怎样的接口。
模型负责推理和生成，AGENTS.md 负责描述道路边界，编译器与测试负责设置护栏。三者缺一不可。
对于已经把 Coding Agent 用进日常开发的团队，现在最值得做的不是继续寻找“最佳提示词”，而是打开最近几次 AI 提交的审查记录，把反复出现的三类错误写成 10 条以内、能执行、能测试、能维护的仓库规则。首版越小，越容易验证；能被验证，才有资格继续扩展。
参考来源
- AGENTS.md 项目：介绍面向 Coding Agent 的仓库级指令文件约定及生态支持情况。
- OpenAI Codex：OpenAI 开源的终端 Coding Agent，可用于核对
AGENTS.md的实际工作方式。 - Claude Code：Anthropic 的 Agent 编程工具仓库，可了解其项目指令与终端工作流。
- Gemini CLI：Google 的开源命令行 Agent，可用于对照不同工具的上下文文件设计。
- AI Agent Book 第五章：系统介绍 Coding Agent 的搜索、文件编辑、工具调用和上下文管理机制。
