AGENTS.md不是 Agent 的大脑，更像是它的宪法。真正让 AI Coding 稳定交付的，不是把更多内容塞进一个文件，而是把上下文、动作和质量边界分到正确的位置。
一份什么都写的 AGENTS.md，最后往往什么都没管好
很多团队使用 AI Coding 一段时间后，都会经历同一个阶段：给项目根目录加一份 AGENTS.md，然后不断往里面补规则。
开始时它只有几十行，写着代码风格、测试命令和目录约定。后来又加上接口说明、业务背景、发布流程、历史踩坑、常见任务模板。再后来，文件变成几百行，Agent 看起来知道很多事情，实际执行却仍然会：
- 漏掉一个必须调用的接口；
- 把已经失效的约定当成当前规则；
- 知道"应该先确认"，却仍然直接执行写操作；
- 生成了看起来合理、但没有通过项目质量门禁的代码。
问题通常不在模型又变笨了，而在于我们把不同生命周期、不同可信等级、不同执行方式的信息，混进了同一个上下文容器。
本文只讨论一个问题：一个前端团队应该如何为 Coding Agent 分层组织上下文，让它既能理解任务，又不会被无关信息淹没。
先把职责拆开
一份臃肿的 AGENTS.md，通常同时承担以下职责：
原本都塞进 AGENTS.md 的内容 |
它真正要解决的问题 | 更合适的归属 |
|---|---|---|
| Agent 的角色、边界、不可违反的规则 | 你是谁，什么不能做 | AGENTS.md / CLAUDE.md |
| 当前需求、范围和验收标准 | 这次任务要完成什么、怎样算完成 | Spec |
| 项目架构、接口、术语和目录知识 | 这个项目是什么 | Wiki / Reference |
| 重复执行的步骤，以及查询、修改、发布等平台操作 | 这类任务具体怎么做、如何安全地碰外部系统 | Skill + CLI / MCP |
| 测试、Review、审计和人工确认 | 如何证明做对了 | CI / Review 门禁 |
这张表里最容易被忽略的是生命周期。
项目规则可能几个月才变一次，当前任务的 Spec 可能几天后就失效，某次任务产生的临时上下文在任务结束后应该直接丢弃。它们如果共用一份常驻文件，模型不仅要花注意力区分信息，还要自行判断哪些内容已经过期。
Anthropic 在 Effective context engineering for AI agents 中把这类问题称为 context rot：上下文不断变长，并不意味着有效信息不断增加。相反，无关内容和过时内容会稀释真正重要的信号。
上下文分层：每一层只回答一个问题
我更愿意把一个 Coding Agent 的工作环境看成下面这套分层系统，而不是一份越来越长的 Prompt：
AGENTS.md：宪法，不是百科全书
它适合放三类东西：
- Agent 在这个仓库里的角色；
- 必须遵守的安全和协作边界；
- 入口级的工作约定，例如"修改后必须运行哪些检查"。
它不适合承载整个项目的业务知识，也不适合记录每一次任务的具体步骤。
一个好的判断标准是：如果这条内容只对某一次任务有效，就不应该写进常驻的 AGENTS.md。
Spec：当前任务的合同
Spec 负责把"帮我做一下"变成可执行的任务边界：
- 背景和目标是什么；
- 哪些范围内的文件可以修改；
- 什么情况算完成；
- 哪些行为必须先得到确认；
- 需要留下哪些验证证据。
Spec 不是需求文档的另一种格式，而是 Agent 和人共同使用的当前任务合同。任务结束后，它可以归档、提炼，或者直接丢弃。
Wiki：长期知识，但不直接充当指令
架构说明、接口语义、术语定义、历史决策和经过验证的踩坑经验，都应该进入可检索的知识库。
这里有一个边界：知识库回答"项目是什么、为什么这样设计"，Skill 才回答"这类任务具体怎么做"。把两者混在一起，知识会越来越像一份没人敢改的操作手册。
Skill：把重复动作变成流程
Skill 适合承载有明确输入、步骤和输出的任务，例如：
- 检查一个页面是否符合项目的路由约定；
- 按固定格式生成接口联调清单；
- 对一个变更执行测试、Review 和风险检查；
- 先 dry-run，再生成待确认的变更计划。
Skill 的价值不在于"写得很长"，而在于它能把稳定的动作顺序固定下来，同时把需要临时检索的知识留在外部。
CLI / MCP：让操作能力有边界
Agent 可以理解"请把配置改成 X"，不代表它应该拥有一把可以直接写入生产系统的钥匙。
查询、修改、发布等动作应该经过有明确契约的 CLI 或 MCP 工具，并且提供：
- 参数校验；
--dry-run或等价的预览能力；- 明确的确认步骤；
- 最小权限；
- 可追溯的执行记录。
Building effective agents 提醒我们，复杂 Agent 系统应该从简单、可验证的组合开始。工具面越大，越需要先把每一个工具的边界定义清楚。
一个任务到底应该怎么跑
下面是一条脱敏后的典型链路。它不依赖某个具体平台，任何需要 Agent 查询和修改外部系统的团队都可以套用。
没有分层时
Agent 读到一份包含所有业务背景和历史规则的长文档后，可能会直接从"理解需求"跳到"调用工具"。这中间少了三个关键问题：
- 当前任务的范围到底是什么？
- 这次操作是查询、预览，还是实际写入？
- 执行结果需要由谁、通过什么方式验证？
于是问题常常不是代码写错，而是动作顺序错了。
分层之后
Spec 把范围钉住，Skill 固定动作顺序，CLI 把预览和执行分开，Review/CI 负责最后的质量判断。Agent 仍然可以自由推理，但它不能跳过系统边界。
在一次实际的上下文优化实践中，一个配置查询接口曾经一次返回 2 万 token 级别 的全量数据。把返回方式拆成 full、summary、select、out 等渐进式层级后，调用者可以先拿摘要，再按需展开字段；内部 benchmark 的最大裁剪比例约为 96% 。这里真正起作用的不是某一句 Prompt，而是"信息按需展开"的接口设计。
这也是上下文工程经常被误解的地方：减少上下文，不等于减少能力；是把不该在当前时刻出现的信息延后。
可以直接复制的目录结构
下面是一种足够小、但能开始工作的目录组织方式：
bash
project/
├── AGENTS.md # 身份、硬规则、入口级约定
├── docs/
│ ├── specs/ # 当前任务合同与验收标准
│ ├── architecture/ # 架构、接口、术语与长期知识
│ └── memories/ # 已验证的踩坑与经验
├── skills/
│ ├── feature-check/ # 功能变更检查
│ ├── api-change/ # 接口变更流程
│ └── release-check/ # 发布前检查
├── cli/
│ └── platform-cli/ # 查询、dry-run、confirm、审计
└── .github/
└── workflows/
└── agent-quality.yml # 自动化质量门禁不需要一开始就把所有目录都建齐。可以从三个文件开始：
- 一份只写边界、不写百科的
AGENTS.md； - 一份当前任务 Spec；
- 一份能被验证的 Skill。
等某类经验被重复验证，再把它升级为长期知识或团队规则，而不是把每次对话都复制进去。
我更在意的三个判断
第一，Agent 的竞争力不是 Prompt 长度
长 Prompt 会让系统看起来"知识丰富"，但它很难同时保证新鲜度、相关性和可执行性。真正值得优化的是上下文的命中率：当前任务需要什么，就只加载什么。
第二，工具边界比措辞更可靠
"请不要直接改生产环境"是一句提醒；预览接口、最小权限和强制确认才是约束。能写进工具契约的规则，就不要只写在 Prompt 里。
Pi 的设计也体现了类似的取舍：把约束尽可能放进工具和运行时，而不是继续堆叠系统提示词。可以参考作者对 Pi coding agent 的设计说明。
第三，知识沉淀必须有升级条件
不是每次 Agent 犯错都值得新增一条规则。更稳妥的流程是：
一次问题
→ 记录现象
→ 判断是否可复现
→ 验证解决方式
→ 决定进入 Wiki、Skill 还是硬规则否则团队会得到一套越来越长、越来越互相矛盾的"经验集合"。
这套方法什么时候不值得用
上下文分层不是所有项目的必选项。
- 个人一次性脚本，通常不需要完整的 Skill 和质量门禁；
- 项目规模很小、任务边界很清楚时，一份短小的
AGENTS.md就够了； - 工具不会触碰外部系统，也没有明显的安全边界时，不必为了"企业级"而增加确认流程；
- 团队还没有稳定的重复任务时，先积累真实案例，再抽象目录和规范。
复杂度应该跟着风险和重复度增长，而不是跟着概念数量增长。
写在最后
AI Coding 的工程化，不是把更多规则塞进 Agent 的脑子，而是给它一套能够被检索、执行、验证和回收的工作环境。
AGENTS.md 管身份和边界，Spec 管当前任务，Wiki 管长期知识，Skill 管动作，CLI/MCP 管系统交互，Review 和 CI 管质量。每一层都不完美，但每一层都知道自己不该负责什么。
AGENTS.md 是宪法，不是大脑。让 Agent 记得更少，但在需要的时候拿到更准确的信息。
参考资料
- Anthropic：Effective context engineering for AI agents ------ 上下文选择、压缩与长期有效性
- Anthropic：Building effective agents ------ 从简单 Agent 逐步增加复杂度
- Mario Zechner：Pi coding agent ------ 轻量 Harness、工具约束与状态外置的设计思路