vLLM AI Agent 指令文档维护指南：Token 预算思维、内容归属规则与反模式清单

在 vLLM 仓库中，AGENTS.md 及其链接的领域指南（domain guide）是所有 AI 辅助贡献（AI-assisted contributions）的行为准则来源。本文基于 editing-agent-instructions.md 展开，系统讲解这套指令文档体系的 Token 预算约束、"何时不该加内容"的六项判定、内容的归属划分、以及提交修改前必须通过的七项检查清单。读完本文，你可以独立、合规地修改 AGENTS.md 或任一领域指南，而不会让指令文档膨胀失控。

为什么需要专门的编辑规范

vLLM 通过一套分层的指令文件体系来约束 AI Agent 的行为：

• 根目录 AGENTS.md 是**项目级不变量（project-wide invariants）**的唯一载体，涵盖贡献政策、环境搭建、测试与 lint 命令、提交规范等；
• 根目录 CLAUDE.md 只有一行内容 @AGENTS.md，即通过引用指令把 Claude 系 Agent 的入口收敛到 AGENTS.md，避免维护两份内容——这正是"单点维护、其余处引用"原则的直观体现；
• 各子目录可以有自己的 AGENTS.md，作为该区域的领域指南。例如 rust/AGENTS.md 定义了 Rust 前端工作区的编码风格与测试约定，rust/src/bench/AGENTS.md 则进一步描述 vllm-bench 基准客户端的构建、测试与架构要点，且其 CLAUDE.md 同样只做转发（先检查 AGENTS.override.md，再遵循 @AGENTS.md）。

这种分层加载机制决定了编辑时必须遵循第一条原则：AGENTS.md 在每一次 agent 请求中都会加载，领域指南在进入相关区域时才加载。加载频率不同，Token 成本模型完全不同，这也是后文预算规则的根源。

Token 预算思维：200 行与 300 行红线

原文档给出的硬性预算是：

文件	行数预算
AGENTS.md	少于 200 行
每个领域指南	少于 300 行

并且明确要求：当文件超出预算时，应拆分或裁剪（split or prune），而不是压缩行文来硬塞（do not compress prose to fit）。压缩行文会牺牲可读性与可执行性，对 Agent 而言等于把规则变得难以遵循。

用当前仓库的实际行数可以验证这套预算的执行情况：

文件	行数	说明
AGENTS.md	158	处于 200 行预算之内
docs/contributing/incremental_build.md	149	AGENTS.md 链接的领域指南，预算内
docs/contributing/model/tests.md	57	AGENTS.md 链接的模型测试指南，预算内
docs/contributing/vulnerability_management.md	62	安全审查入口之一，预算内
docs/contributing/editing-agent-instructions.md	74	本指南本身，预算内
docs/contributing/model/multimodal.md	732	明显超出 300 行预算，是"需要拆分"的典型候选

从仓库现状看，AGENTS.md 当前只有 158 行，距离 200 行预算仍有约 30 行余量；而像 multimodal.md 这类已超预算的指南，恰好印证了规则中"超预算就拆分"的要求。这给后续维护者一个可操作的判断信号：新增内容前，先跑 wc -l 看看目标文件离预算还有多远。

何时不应该添加内容

在写下任何一条新规则之前，原文档要求先过一遍以下六项判定。只要命中其中任意一项，就不应添加该内容：

1. Agent 本来就能做对（Agents already do it）。 先用一个 prompt 实测。如果 Agent 在没有这条规则的情况下行为也是正确的，就不要加。这是"实测优先"的防冗余手段——规则的价值只体现在纠正 Agent 实际会犯错的场景。
2. 一次性事故（One-off incident）。 优先用代码层面的修复——lint 规则、CI 检查、测试断言——而不是新增一条文档规则。文档规则是长期负担，代码检查是一次性投入、永久生效。
3. 硬编码路径（Hardcoded paths）。 文件路径会随重构改变，应改用"搜索 X"（search for X）式的描述来定位目标，而不是写死文件路径。
4. 上游工具文档（Upstream docs）。 不要复述 pytest、ruff 等外部工具的文档，直接链接到上游即可。
5. 与既有规则矛盾（Contradicts an existing rule）。 添加前先搜索 AGENTS.md 及其链接的所有指南；如果发现两条规则冲突，应合并为一条，而不是并存。
6. 他处已覆盖（Already covered elsewhere）。 在 AGENTS.md 和每个被链接的指南中检索是否有重叠的指导，避免多处重复。

这六项判定的共同逻辑是：指令文档的每一行都有持续的加载成本，添加的门槛应当高于删除。这也解释了为什么 AGENTS.md 的贡献政策采用"fail-closed"（默认拒绝）姿态——重复劳动和琐碎 PR 直接不推进，而不是事后补救。

内容应该放在哪里

原文档的总目标是：一份精简的 AGENTS.md + 一份份内容丰富的领域指南，领域指南专门教授"Agent 无法从代码中自行学会"的东西。

归属划分表（原文档原表）：

作用域	应放入的文件
项目级不变量：贡献政策、环境搭建、测试/lint 命令、提交规范	AGENTS.md
区域特定知识：模型实现模式、格式细节、弃用时间表	领域指南

配套的三条经验法则：

• 只对一个区域有用的内容，放领域指南。
• 对所有区域都有用的内容，才考虑放 AGENTS.md——但先验证 Agent 不是本来就能做对。
• 当积累了 5 条以上同属一个内聚作用域、且非显而易见的指令时，才创建新的领域指南。 这个"5 条阈值"防止为单条指令单独建文件，也防止指南碎片化。

对照 vLLM 仓库的实际结构可以看到这套划分的落地形态：AGENTS.md 主体只保留环境、测试、lint、提交等全局流程，然后把领域知识外置——例如 C/C++/CUDA 改动指向 incremental_build.md（增量编译工作流），模型相关测试指向 model/tests.md，安全审查指向 SECURITY.md、docs/usage/security.md 与 vulnerability_management.md。值得注意的是 AGENTS.md 中"Domain-Specific Guides"一节还规定了冲突处理规则：如果领域指南与请求的修改相冲突，Agent 应拒绝该修改并解释原因。

什么样的领域指南是好指南

原文档给出了内容选择标准——只添加 Agent 无法从代码或公开文档中推断的信息，具体包括三类：

1. 项目特有约定：与标准模式不同、只有本项目这么做的惯例；
2. 需要跨文件上下文才能理解的正确做法：单看一个文件学不会的流程；
3. 对反复出现错误的修复说明：Agent 历史性地踩过的坑。

并且要求每条指令满足三个词：短（short）、具体（specific）、可执行（actionable）。原文档给出的可执行性范例是：指明要动哪些文件、按什么顺序改、以及改完要跑哪些测试。以 rust/src/bench/AGENTS.md 为例，其中"构建与测试"部分直接给出从 rust/ 工作区根目录执行的 cargo build -p vllm-bench --release、cargo test -p vllm-bench 等命令，符合"可执行"标准；而 rust/AGENTS.md 的"错误处理"条目则给出了 foo!(...) 与 bail_foo!(...) 宏的适用位置区分（表达式位置用前者、语句位置用后者），属于典型的"跨文件上下文才能理解的正确做法"。

保持文档精简的五条实践

原文档"Keeping Docs Lean"一节要求，每一次新增都应触发对周边内容的审视，检查是否存在过时或冗余条目。具体做法：

• 示例优先于解释——3 行代码片段胜过一段文字描述；
• 把相关的并列条目合并为一条原则，而不是罗列各种变体；
• 用"search for X"替代硬编码文件路径，让描述对重构保持鲁棒；
• PR 编号引用在领域指南中是允许的（为了可追溯性），但应避免出现在 AGENTS.md 中，因为后者每次请求都加载，PR 号会快速失效。

四类反模式

原文档以表格形式列出了四类应当避免的编辑反模式，这里完整继承并加以说明：

反模式	问题	应对
反应式堆积（Reactive accumulation）	每出一事就加一条规则，从不裁剪，必然膨胀	每次新增同步做裁剪/合并，见下方检查清单第 4 项
指南间复制粘贴（Copy-paste between guides）	重复内容会各自漂移；应在一处维护，另一处只放链接	仓库中 CLAUDE.md 仅写 @AGENTS.md 即为"单点维护"的范例
命令式长墙（Imperative walls）	大段"DO NOT"清单会被 Agent 略读跳过；应合并为原则	一条原则 + 少量反例，优于十条禁令
配置快照（Config snapshots）	把具体取值写死在文档里会过时	写"获取该值的命令"，而不是值本身

提交修改前的七项检查清单

原文档要求：在向任何 agent 指令文件提交修改之前，逐项确认以下内容（原文档以 checkbox 形式给出，此处完整保留）：

• [ ] 非显而易见？ 没有这条规则时，Agent 是否会做错事？
• [ ] 无冲突？ 已搜索所有被链接的指南确认没有矛盾？
• [ ] 放对文件了吗？ 项目级内容进 AGENTS.md，区域特定内容进领域指南？
• [ ] 为新增做了对冲吗？ 删除或合并了其他内容以抵消体积增长？
• [ ] 在预算内吗？ AGENTS.md 少于 200 行，领域指南少于 300 行？
• [ ] 没有硬编码路径吗？ 路径可能变化的地方是否使用了"search for X"？
• [ ] 实测过了吗？ 已验证 Agent 确实会遵循这条新指令？

七项中值得强调的两点：第 4 项"对冲新增"意味着指令文档总体上倾向于零净增长——加一条规则，最好同时删掉一条过时规则；第 7 项"实测"与"何时不该加"第 1 条呼应，即新指令必须通过 prompt 实测证明 Agent 真的会遵循，否则它只是在消耗 Token 预算。

结合仓库现状的落地建议

基于上述规则与仓库当前状态，可以归纳出维护者实际操作时的流程：

1. 先定位归属：判断修改是项目级（进 AGENTS.md）还是区域级（进对应领域指南，或按"5 条阈值"新建）。当前仓库中，AGENTS.md 的"Domain-Specific Guides"一节本身就是新增领域指南链接的登记处，修改 AGENTS.md 前应先阅读 editing-agent-instructions.md——该文件明确写着"Read this before modifying AGENTS.md or any guide it links to"。
2. 查预算余量：用 wc -l AGENTS.md 与 wc -l <domain-guide> 查看距 200/300 行的余量。当前 AGENTS.md 为 158 行；若某指南已接近或超过 300 行（如 docs/contributing/model/multimodal.md 已 732 行），应优先拆分而不是继续追加。
3. 过"不该加"六项判定：命中任一项即放弃添加，或改用 lint/CI/测试断言等代码级手段。
4. 按"短、具体、可执行"写条目：给出要动的文件、改动顺序、要跑的测试命令（可参考 rust/src/bench/AGENTS.md 的构建/测试命令写法）。
5. 提交前逐项完成七项检查清单，特别是"对冲新增"与"实测"两项。

小结

vLLM 对 AI Agent 指令文档的治理，核心是把"文档行数"当作一种需要预算化管理的稀缺资源：AGENTS.md 每次请求必载，故 200 行封顶；领域指南按需加载，300 行封顶；超预算先拆分而非压缩。配合"六项不该加判定"、"AGENTS.md 与领域指南的归属划分"、"单点维护、他处引用"的反模式清单，以及提交前的七项 checklist，整套规范保证了 Agent 指令体系在持续演进中保持精简、无冲突、且每条规则都经过实测证明其必要性。