AGENTS.md 上下文策略层：Agent 上下文工程与记忆管理实践

1. 为什么单独一个 AGENTS.md 文件值得被叫做"上下文策略层"

第一次看到 AGENTS.md 这个命名，很多人的反应是：不就是又一个配置文件吗，跟.editorconfig、.prettierrc有什么区别？我一开始也这么想，直到在一个多 Agent 协作的项目里被上下文污染坑了整整两天，才意识到这个文件解决的根本不是"配置"问题，而是上下文供给策略问题。

先把概念摆清楚。Agent 在运行时，每一轮推理都要往模型里塞一大坨东西：系统提示词、工具定义、历史对话、检索到的文档、当前任务状态、上一步的执行结果。这些东西加起来就是"上下文"。上下文不是越多越好，塞多了会稀释注意力、拉高成本、拖慢响应；塞少了模型又缺信息，开始瞎猜。所以真正难的不是"怎么把内容拼进 prompt"，而是"在什么时机、按什么优先级、以什么粒度把哪些内容放进去"。这件事现在有个专门的说法叫Context Engineering（上下文工程），它和 Prompt Engineering 是两回事——后者关心"这句话怎么写"，前者关心"这一轮到底该看到什么"。

AGENTS.md 就是把这个策略显式地落成一个文件。它不负责具体某一句提示词的措辞，而是规定：这个 Agent 是谁、能碰哪些工具、记忆怎么读写、什么情况下该把哪段上下文拉进来、什么情况下该丢掉。你可以把它理解成 Agent 的"上下文宪法"——所有临时的 prompt 拼接都要服从它。

为什么是 Markdown 而不是 JSON/YAML？这是我在实际项目里体会最深的一点。策略层的内容大量是自然语言描述的判断规则，比如"当用户问题涉及历史订单时，优先检索订单库而不是通用知识库"。这种规则用 JSON 写会变成一堆嵌套的字符串字段，可读性极差，改一次要对着括号数半天；用 Markdown 写就是一句话加一个列表项，人和模型都能直接读懂。而且 Markdown 天然适合做分层：一级标题是模块，二级标题是规则组，列表是具体条目。模型读 Markdown 的解析稳定性也明显好于读深层嵌套的 YAML。

这里要区分一个容易混淆的点：AGENTS.md 和 harness 不是一回事。Harness 是跑 Agent 的那套运行时外壳——负责调度循环、调用工具、管理沙盒、处理重试。AGENTS.md 是喂给这个外壳的策略输入。打个比方，harness 是发动机和变速箱，AGENTS.md 是驾驶手册。你换发动机（换框架）的时候，驾驶手册大部分还能用；但你改驾驶手册，发动机本身不用动。这个解耦非常关键，它意味着你的上下文策略可以跨框架迁移，不会被某个 Agent 框架绑死。

还有一个高频疑问：这东西和 system prompt 有什么区别？System prompt 是"这一轮我要对模型说的话"，AGENTS.md 是"我决定这一轮该说哪些话、按什么顺序说、说多细"的规则来源。System prompt 是执行层，AGENTS.md 是决策层。很多项目把两者混在一起写，结果就是策略散落在几十个 prompt 模板里，改一处漏三处，最后没人说得清 Agent 到底遵循什么规则。

2. 一个能落地的 AGENTS.md 该有哪些区块

光讲概念没用，直接看结构。下面这份是我在多个项目里反复迭代后沉淀下来的骨架，你可以直接拿去改。它不是标准答案，但每个区块的存在都有明确的工程理由，我会逐块解释为什么这么切。

# AGENTS.md ## 1. 身份与职责边界 - 角色：订单售后处理助手 - 服务范围：仅处理已支付订单的退换货咨询 - 明确不做：不处理支付失败、不处理账户安全、不回答与订单无关的问题 ## 2. 工具清单与调用约束 | 工具名 | 用途 | 调用前置条件 | 禁止场景 | |--------|------|--------------|----------| | query_order | 查订单详情 | 已获得订单号 | 订单号缺失时禁止猜测 | | refund_api | 发起退款 | 已确认退款金额与原因 | 金额超过 500 需人工确认 | | kb_search | 检索知识库 | 通用政策问题 | 不用于查具体订单 | ## 3. 上下文装配优先级 1. 当前用户消息（最高优先级，永远保留） 2. 本轮已确认的订单号与关键实体 3. 最近 3 轮对话摘要 4. 检索到的知识库片段（最多 3 条，每条截断到 200 字） 5. 历史对话全文（仅在需要追溯时按需加载） ## 4. 记忆读写规则 - 短期记忆：当前会话内的实体槽位，会话结束即清空 - 长期记忆：用户偏好（如常用收货地址），写入前需用户确认 - 禁止写入：身份证号、完整银行卡号等敏感字段 ## 5. 失败与降级策略 - 工具连续失败 2 次：停止重试，向用户说明并转人工 - 检索无结果：明确告知"未找到相关政策"，禁止编造 - 上下文超限：按第 3 节优先级从低到高裁剪

身份与职责边界放第一位，是因为 Agent 跑偏最常见的原因就是"它不知道自己不该做什么"。只写"你是售后助手"没用，必须显式列出"不做什么"。我在一个项目里就是因为没写"不处理支付失败"，结果 Agent 遇到支付问题硬答，编了一套退款流程，用户照着操作白等三天。

工具清单用表格而不是列表，是因为工具的三个属性——用途、前置条件、禁止场景——天然是二维对照关系。前置条件这一列是重点，它把"什么时候能调"写死了。很多 Agent 乱调工具，根因就是工具定义里只写了"这个工具能干嘛"，没写"什么时候不许调"。

上下文装配优先级是整个文件的核心，也是它被称为"策略层"的原因。这里用有序列表而不是无序列表，因为顺序本身就是信息——它同时定义了"装配顺序"和"裁剪顺序"。裁剪时从优先级最低的开始丢，这条规则让上下文超限时的处理变成确定性的，而不是靠模型临场发挥。

记忆读写规则要区分短期和长期。短期记忆是会话级的槽位，长期记忆是跨会话的持久化。这里最容易出事的是写入规则——什么能写、什么不能写、写之前要不要确认。敏感字段的禁令必须写死，不能指望模型自己判断。

失败与降级策略是很多人会漏的一块。Agent 不是永远成功的，工具会挂、检索会空、上下文会爆。这些情况下的行为必须提前规定，否则模型会用"编造"来填补失败，这是最危险的。

提示：这份骨架里的每个区块都不是必须的，小项目可以只保留第 1、3、5 节。但只要你开始做多工具、多轮次的 Agent，第 2 和第 4 节迟早要补上。

3. 上下文装配的优先级设计：从"全塞进去"到"按需供给"

这一节单独拎出来讲，因为它是 AGENTS.md 里技术含量最高、也最容易做错的部分。我见过太多项目，上下文装配就是一句context = system + history + retrieved_docs，全塞进去完事。小规模能跑，一旦对话轮次上去、检索结果变多，立刻崩。

先说清楚"全塞进去"为什么会崩。模型的注意力是有限的，上下文里无关内容越多，真正关键的信息被"淹没"的概率越大。这不是玄学，是实测能观察到的现象：同样一个问题，上下文里塞 10 条检索结果和塞 3 条精准结果，后者的回答准确率明显更高。另外成本也是实打实的，上下文长度直接决定 token 消耗，长上下文还会拖慢首 token 响应时间。

所以装配策略的核心是分层 + 按需。我在 AGENTS.md 里把上下文分成四层，每层有不同的加载时机和生命周期：

L0 是"宪法"，永远在。L1 是"当前工作记忆"，会话内保持。L2 是"临时查的资料"，用完即弃——这一点特别重要，检索结果不应该跨轮累积，否则几轮下来上下文里全是过期文档。L3 是"翻旧账"，只有用户明确要求追溯时才加载。

具体到装配逻辑，我在 AGENTS.md 里会写清楚触发条件，而不是让代码硬编码。比如：

## 检索触发规则 - 用户问题包含"政策""规定""流程"等通用词：触发 kb_search - 用户问题包含具体订单号：优先 query_order，不触发 kb_search - 用户问题同时包含两者：先 query_order 拿到订单状态，再根据状态决定是否检索

这种规则写成自然语言，好处是模型自己也能读懂并在推理时参考，而不只是被代码执行。这就是 AGENTS.md 作为"策略层"和普通配置文件的区别——它既是给程序读的，也是给模型读的。

再讲一个实操细节：摘要的粒度。L1 里的"最近对话摘要"到底多长？我的经验是控制在 3 轮、每轮不超过 100 字。太短会丢关键信息，太长等于没摘要。摘要的生成时机也有讲究——不要每轮都重新摘要（成本高且不稳定），而是每积累 3 轮做一次滚动摘要，把更早的内容压缩掉。

还有一个反直觉的点：不是所有工具结果都值得进上下文。比如query_order返回的订单 JSON 可能有 30 个字段，但 Agent 真正需要的可能只有订单号、状态、金额、时间这 4 个。所以在 AGENTS.md 里我会规定每个工具结果的"投影规则"——只保留哪些字段进上下文。这一步能省掉大量 token，也减少干扰。

4. 记忆管理：短期槽位与长期偏好的读写边界

Agent 的"记忆"这个词被用得很泛，实际工程里至少要拆成两类，混在一起必然出问题。

短期记忆是会话级的工作记忆，本质是一组槽位（slot）。比如售后场景里，order_id、refund_amount、refund_reason就是三个槽位，随着对话推进被逐步填满。它的特点是：会话结束就清空，不跨会话。这类记忆的管理重点是"槽位定义要清晰"——每个槽位什么时候填、填不上怎么办、填错了怎么改，都要在 AGENTS.md 里写明白。

长期记忆是跨会话的持久化信息，比如用户偏好、历史交互摘要。它的管理重点是"写入要谨慎"。我的原则是：长期记忆的写入必须满足两个条件之一——要么用户显式确认，要么是低风险的客观事实。用户说"以后都用这个地址"，这是显式确认，可以写；模型自己推断"用户可能喜欢顺丰"，这是猜测，不能写。

在 AGENTS.md 里，记忆规则我通常这么写：

## 记忆读写规则 ### 短期槽位 - order_id：从用户消息或 query_order 结果中提取，提取失败则主动询问 - refund_amount：必须来自 query_order 的实付金额，禁止用户口述覆盖 - refund_reason：用户原话，不做改写 ### 长期偏好 - 可写入：常用地址、偏好联系方式（需用户确认） - 禁止写入：任何证件号、完整卡号、密码类字段 - 写入前话术："是否记住这个地址方便下次使用？" ### 记忆冲突处理 - 新信息与长期记忆冲突时：以当前会话为准，并提示用户"检测到与历史记录不一致"

这里有个我踩过的坑：槽位被用户口述覆盖。早期版本里，用户说"退款 800"，Agent 就把refund_amount改成 800，结果和订单实付金额对不上，退款接口直接报错。后来我在规则里写死"金额必须来自 query_order，禁止用户口述覆盖"，问题才解决。这类规则不写进 AGENTS.md，光靠 prompt 里提醒，模型十次里总有一两次会忘。

另一个坑是记忆的时效性。长期记忆不是永久有效的，用户三个月前的偏好可能已经变了。所以我在规则里加了一条：长期记忆超过 90 天未更新，使用时需向用户二次确认。这条规则看起来啰嗦，但避免了"用过期偏好做决策"的尴尬。

关于记忆存储，热词里有个"agent 存储 working memory"值得说一句。Working memory 的存储位置有两种选择：一是放在上下文里（简单但占 token），二是放在外部存储、按需加载（省 token 但多一次 IO）。我的建议是：高频访问的小数据放上下文，低频的大数据放外部。槽位这种每轮都要用的，放上下文；历史交互日志这种偶尔查的，放外部。

5. 工具调用约束：把"什么时候不许调"写进策略层

工具调用是 Agent 最容易失控的地方。模型天生倾向于"多调工具显得自己很努力"，但很多调用是多余的、甚至有害的。AGENTS.md 在这一块的价值，就是把调用约束从"事后校验"前移到"事前规定"。

约束分三类，我在文件里分开写：

第一类是前置条件约束——不满足条件不许调。比如refund_api的前置条件是"已确认退款金额与原因"，两个都齐了才能调。这类约束防止的是"信息不全就动手"。

第二类是互斥约束——某些工具不能同时或连续调。比如query_order和kb_search在同一个问题里，如果已经拿到了订单详情，就不该再去检索通用政策，因为具体订单优先于通用规则。这类约束防止的是"重复劳动和规则打架"。

第三类是频率约束——同一个工具连续失败几次就停。我一般设 2 次，连续失败 2 次就停止重试、转人工。这条特别重要，否则 Agent 会陷入"失败-重试-再失败"的死循环，烧钱又烧时间。

写成表格最清楚：

这里有个经验：约束要写在工具定义旁边，不要散落在别处。我见过把权限约束写在"身份"章节、把频率约束写在"失败策略"章节的项目，改的时候要满文件找。工具相关的约束就集中在工具章节，维护成本最低。

还有一个细节是工具结果的信任级别。不是所有工具返回的数据都同等可信。内部数据库查询的结果可信度高，可以直接用；外部检索的结果可信度低，需要交叉验证。这个信任级别也应该在 AGENTS.md 里标注，影响后续的决策逻辑。比如检索结果和订单数据冲突时，以订单数据为准——这条规则不写清楚，模型可能就按检索结果答了。

6. 多 Agent 协作时 AGENTS.md 的拆分与共享

单 Agent 场景下，一个 AGENTS.md 就够了。但一旦进入多 Agent 协作，问题就来了：是每个 Agent 一份，还是共享一份？我的答案是分层共享——公共部分抽出来共享，专属部分各自维护。

具体做法是三层结构：

• 全局层（shared.md）：所有 Agent 都遵守的规则，比如安全红线、敏感字段禁令、通用失败策略。
• 角色层（role-xxx.md）：每个 Agent 的身份、职责、专属工具。
• 任务层（task-xxx.md）：具体任务流的临时规则，任务结束即失效。

装配时按"全局 → 角色 → 任务"的顺序拼接，任务层优先级最高，可以覆盖上层的规则。这样既保证了公共约束的一致性，又给了单个 Agent 灵活空间。

多 Agent 协作里最容易出问题的是上下文隔离。Agent A 的会话上下文不应该直接泄漏给 Agent B，否则 B 会被 A 的历史污染。正确做法是：A 把结果摘要后传给 B，而不是把原始上下文整个丢过去。这个"摘要传递"的规则要写进 AGENTS.md 的协作章节。

## 多 Agent 协作规则 - 上下文传递：仅传递结构化摘要（实体+结论），禁止传递原始对话 - 冲突处理：两个 Agent 结论冲突时，以数据源可信度高的为准 - 超时处理：下游 Agent 超过 30 秒无响应，上游降级为单 Agent 处理

关于"ai agent 怎么扛并发"这个热词，多 Agent 场景下并发压力主要来自上下文装配和工具调用。AGENTS.md 本身不解决并发，但它能通过"约束调用频率""规定降级策略"来减轻并发压力。比如规定"同一用户 1 秒内最多触发 1 次检索"，这类规则写进策略层，比在代码里到处加限流要清晰得多。

7. 版本管理与演进：AGENTS.md 不是写完就锁死的

最后聊一个容易被忽视的点：AGENTS.md 是要持续演进的。Agent 上线后，你会不断发现新的边界情况、新的失败模式，这些都应该反哺到策略层。所以它必须纳入版本管理，和代码一样对待。

我的做法是给 AGENTS.md 加一个变更日志区块，记录每次改动的动机：

## 变更日志 - v1.3 (2024-06)：新增"金额禁止用户口述覆盖"规则，修复退款金额错乱 - v1.2 (2024-05)：检索结果改为单轮有效，修复上下文累积导致的响应变慢 - v1.1 (2024-04)：新增工具频率约束，修复失败重试死循环

这样做的好处是，当线上出问题时，你能快速定位是哪次策略变更引入的。我吃过这个亏——有一次 Agent 突然开始乱答，排查半天才发现是三天前改了一条检索触发规则，但没有记录，谁都不知道。

演进时有个原则：每次只改一个维度。不要一次同时改身份、工具、记忆三块，否则出问题无法归因。改完要跑回归测试，用固定的测试用例集验证核心场景没退化。这个测试集本身也应该和 AGENTS.md 一起维护。

注意：策略层的改动往往比代码改动影响更大，因为它影响的是 Agent 的"判断逻辑"而非"执行逻辑"。改代码可能只影响一个功能，改策略可能影响所有场景。所以策略变更要更谨慎，灰度发布、观察指标、随时回滚。

关于"agent 安全"这个热词，AGENTS.md 其实是安全防线的第一道。敏感字段禁令、权限约束、失败降级，这些写进策略层，比在代码里零散地做校验要可靠。因为策略层是模型能读到的，模型在推理时就会遵守；而代码校验是事后的，模型可能已经生成了不该生成的内容。

我个人在实际操作中的体会是：AGENTS.md 写得越细，Agent 上线后你救火的时间越少。前期多花两天把规则想清楚，后期能省两周的调试。这个投入产出比，在 Agent 项目里是我见过最高的之一。