07 第二篇 · 准备：每个项目做一次

steering 的内容与加载

steering 是 Kiro 按不同条件加入 Agent 上下文的项目说明。放进去的内容会影响 Agent 先看什么、遵守什么，也会增加读取和推理成本。本章讨论两件事：一条信息是否值得进入 steering，以及它应该常驻、条件加载，还是交给机器执行。

目标不是追求最短，而是让必须出现的信息稳定出现，让低频内容只在需要时进入，并让每条规则都能说明自己为什么存在。

7.1 常驻内容的成本

上下文文件不一定越全越好。一项针对真实代码任务的研究比较了没有上下文文件、模型生成的上下文文件和开发者编写的上下文文件。研究覆盖的任务里，模型生成的文件通常降低任务成功率，开发者编写的文件只有小幅正收益；两类文件都会让 Agent 扩大探索和测试范围，增加推理成本。研究者据此建议，人工文件只保留必要要求。

这项研究检验的是 coding agent 处理代码任务的表现，没有比较 Kiro 的几种加载方式，也没有覆盖规划、调研和文档任务。它支持的工程判断是减少无关的常驻要求，而不是把所有 steering 都删掉。

内容还要能在需要时被找到。Augment 在内部单轮编码任务中观察到，孤立文档的发现率远低于自动加载的 AGENTS.md 和由它指向的材料；Agent 也会通过文本搜索和语义搜索找到没有直接引用的文档。因此，需要在任务早期稳定出现的信息应放进主入口或由主入口指向，低频参考材料则应保持标题和正文可检索，不必全部塞进主入口。

常驻内容应从最小集合起步。先保留高风险约束、高频入口和代码无法推出的事实；遇到真实偏航后，再补有针对性的规则。这样不需要先承担一批未经验证的规则，再寄希望于以后把它们删掉。

7.2 steering 的加载方式

本节以 Kiro CLI V3 的 workspace steering 为默认环境。四种 inclusion mode 决定 steering 文件在什么条件下进入上下文。

模式何时包含适合什么内容
always每次交互自动包含；不声明模式时也是这个默认值每次都必须看到的短约束
fileMatchKiro 处理匹配 fileMatchPattern 的文件时自动包含只和某类文件有关的约定
manual用户用 #文件名 或对应命令显式加入当前对话低频、调用时机明确的材料
autoKiro 根据必填的 name 和 description 判断当前请求是否相关，相关时自动包含能用情境描述清楚触发条件的材料

fileMatch 的官方文档只保证处理匹配文件时自动包含，没有承诺由哪一次文件操作触发，也没有承诺固定在下一轮注入。auto 同样只应按它对外保证的行为理解，不需要假设内部先放描述、再由 Agent 调工具读取正文。

AGENTS.md 和 hook 不属于这四种 inclusion mode。AGENTS.md 不支持切换加载模式，会始终包含在 steering context 中。它的常驻效果接近 always，适合作为项目入口，但它不是一份声明了 inclusion: always 的普通 steering 文件。

hook 是事件自动化机制。指定事件发生且匹配条件满足时，它可以执行命令或加入提示；支持哪些事件，要看当前客户端、CLI 版本和 trigger。它适合把规则落到特定动作上，不能替代每次交互都要可见的上下文。

因此，要区分两种”必须生效”。跨任务、每次交互都要看到的红线，放进 always 或作用域合适的 AGENTS.md；只在某个事件发生时必须执行或提醒的规则，才交给 hook。fileMatch、manual 和 auto 用来减少无关上下文，不承担全程可见的红线。

7.3 内容分流的六步判断

候选内容可能同时是红线、模块约定和机器可检查项，不能只贴一个类别标签。按下面的顺序判断，先决定机器能否执行，再为仍需 Agent 提前知道的信息选择加载入口。

顺序判断去向
1机器能否直接提供事实或判断对错动态事实以权威文件为准，规则由 lint、hook 或 CI 执行；如果 Agent 必须提前知道，再保留一句指引
2是否跨任务、每次交互都不能缺席always 或作用域合适的 AGENTS.md
3是否只在特定事件发生时执行或提醒hook
4是否只和某类文件有关fileMatch
5用户是否清楚什么时候需要它manual
6是否能用当前请求的情境描述触发auto；漏加载不可接受时回到更确定的入口

六步都不满足的内容留在可检索文档里，不进入 steering。代码无法推出的稳定事实和决策理由也按同一顺序处理：跨任务都需要就常驻，只在局部情境需要就条件加载，低频参考信息则留在邻近文档。

机器执行和上下文提醒可以组合，不是二选一。禁止某项依赖可以由 CI 拒绝，同时在相关文件的 steering 中用一句话给出替代方案。机器负责判错，文字负责让 Agent 在动手前选对，并告诉它失败后去哪里修复。

AGENTS.md 适合当项目路由，不适合当百科。它保留必须在任务早期出现的约束、高频命令和少量入口；只对某个目录或情境有用的正文留在邻近文档或按需 steering 中。OpenAI 和 Augment 的实践都支持”短入口加按需材料”这个方向，但具体行数取决于仓库规模、任务类型和周边文档，不能当成通用通过标准。

不是所有材料都要从根 AGENTS.md 直接可达。必须稳定发现的内容需要明确入口；低频参考资料只要位置合理、命名清楚、可以被搜索找到即可。判断标准是任务中会不会漏掉必要信息，而不是主入口列了多少链接。

7.4 steering 的增补与审计

steering 要随着真实使用增补，不靠起草时把所有可能性写全。可以按下面的顺序维护：

  1. 新想法先记为候选，不立即加入常驻上下文。
  2. 出现真实偏航、发现不可接受的高风险，或需要补充代码无法推出的关键事实时，把候选提升为规则，并记录它要防什么。
  3. 按六步判断选择最窄但足够可靠的加载方式。只有跨任务都要看到的内容进入常驻入口。
  4. 用代表性任务检查规则是否送达，并比较加入前后的任务结果、误触发和额外工作。
  5. 项目结构、工作方式或模型变化后，重跑同一组任务；证明确实不再需要，再降级或删除规则。

审计不能只数规则有没有被 Agent 引用。频繁引用可能意味着规则造成了额外探索；没有被提及，也可能是规则被静默遵守，或者期间没有出现适用任务。更有用的记录是：这条规则有多少次适用机会、是否被遵守、任务结果是否改善、有没有误触发，以及增加了多少额外工作。

一条规则通过审计，要同时满足三个条件：有明确的准入依据，能通过所选入口可靠送达，在代表性任务中的收益或风险控制值得它带来的成本。真实偏航要指向项目证据；未发生过的高风险要写清后果和触发场景；项目事实要确认无法从权威文件直接推出。

不同入口的送达标准不同。fileMatch、auto 和 hook 要在适用任务中触发、在无关任务中不干扰；manual 要在用户显式调用后正确进入当前对话；always 和 AGENTS.md 要检查内容是否确有跨任务常驻的必要。机器规则还要用一个故意违规的样例证明它能拦住错误，并给出可执行的修复信息。

模型升级只触发复测，不直接证明旧规则已经失效。高风险规则只有在同类风险已经消失，或替代控制已经验证后才能移除。Agent 可以起草候选规则，人负责决定哪些进入项目上下文。

7.5 本手册配套的 steering file

本手册配套的 steering file 采用”预置覆盖面，再逐步收敛”的做法，不是从最小集合起步。项目、技术、结构、测试、风格、API 和红线先有文件骨架，通用的方法论信条与编码纪律直接随文件分发；项目专属内容再由对应命令或人工确认后填写。AGENTS.md 作为入口，保留路由、常用命令和回复标记约定，详细内容留在各 steering file 中。

其中，principles.md 吸收并融合了 Cursor pstack 的 principles；项目、技术、结构、测试、风格、API 和红线则是每个项目都必须建立的基础内容。

这是一个有代价的选择。项目早期很难预判哪条约束真正重要，预置骨架可以减少遗漏，但填入过多规则仍会增加常驻成本和干扰。

配套机制目前能做的是合规审计。每份 steering file 都有固定的 steering-id，需要追踪的规则使用稳定规则 ID；AGENTS.md 要求 Agent 在回复末尾自报本轮实际依据的规则。

本章小结

常驻上下文要控制成本，真实偏航、不可接受的高风险和不可推导的事实才推动规则增补。Kiro 的四种 inclusion mode 分别处理常驻、文件匹配、人工调用和情境匹配；AGENTS.md 是常驻入口，hook 处理特定事件。候选内容按六步选择去向，再用准入依据、可靠送达和实际收益审计。本手册配套的 steering file 预置覆盖面，但合规审计只能提供线索，最终仍要靠效果复测决定规则是否继续常驻。

参考与出处