writing-for-agents

本参考适用于智能体会阅读的任何文档：技能、AGENTS.md / CLAUDE.md，或通过指针找到的文档。它们的包装不同，写作方法相同：相同的手段让文档变得可预测，因为智能体每次采用相同的_过程（process）_，而不是产出相同的结果。

编写技能时，阅读 SKILL-MECHANICS.md，了解 frontmatter、调用方式选择和路由技能。

上下文指针（Context pointers）

**上下文指针（context pointer）**是保存在智能体上下文中的引用：它指向上下文之外的材料，并编码何时应当读取该材料。技能的 description 是一种指针；AGENTS.md 中指向文档的一行也是同一种对象。决定智能体何时、以多高可靠性读取材料的是指针的_措辞（wording）_，而不是目标。必读材料藏在弱指针后面，会产生行为差异：先磨砺措辞，只有无效时才将材料内联。

指针承担两项任务：说明材料是什么，并列出应触发读取的分支（branches）。分支是文档处理的不同情形，因此不同运行会经过不同路径。始终加载的指针中每个词都会在每一轮消耗资源，所以比正文更需要修剪：

• 把引导词放在最前面（Front-load the leading word）：它在指针中承担触发作用。
• **每个分支只保留一个触发条件（One trigger per branch）。**用同义词改写同一分支，就是重复表达；合并它们，只保留真正不同的分支。
• 删除正文已经表达的身份信息（Cut identity the body already carries）。

两种负载（The two loads）

每份新增文档和指针都会消耗两种预算之一：

• **上下文负载（Context load）**是始终加载的材料对智能体窗口的成本：AGENTS.md 的一行、技能描述，以及每轮都在上下文中的任何内容，无论是否触发都会消耗 tokens 和注意力。
• **认知负载（Cognitive load）**是人类的成本：有哪些文档、何时应使用哪一份。人类就是索引。它不是需要一味最小化的成本，而是保留人类主动权的代价；在人类判断有价值的地方花费，在没有价值的地方移除。

仅通过指针读取的材料，以指针本身一行的成本避开上下文负载；完全没有指针的材料则全部依赖人类认知负载。

信息层级（Information hierarchy）

文档包含两类内容：**步骤（steps）**是智能体按顺序执行的动作；**参考（reference）是按需查阅的定义、规则和事实。它们可以任意组合：全部步骤（配方）、全部参考（审查规则、本技能），或两者兼有。核心决策是把每项内容放在信息层级（information hierarchy）**的哪一级；这架梯子按智能体需要材料的紧迫程度排序：

1. **文件内步骤（In-file step）**是主要层级：智能体依次做什么。
2. **文件内参考（In-file reference）**按需查阅。通常是一组平等的规则，例如审查的所有规则位于同一层；这是一种合理安排，不是坏味道。
3. **披露式参考（Disclosed reference）**放到独立文件中，通过上下文指针读取，仅在指针触发时加载。范围可以从同目录的邻接文件，到位于任何位置、可被任意文档引用的外部参考。

下移太少会使顶层膨胀；下移太多则会隐藏智能体真正需要的材料。这种张力就是决策的核心。

**渐进式披露（Progressive disclosure）**是把内容沿梯子下移到主文件之外、指针之后，让顶层保持清晰。它主要是保护层级，而非优化 tokens。分支是最清晰的披露判断：所有分支都需要的内容内联，只有部分分支需要的内容放到指针后。当文档包含步骤时，本该披露的文件内参考会埋没步骤，让智能体是否关注它们变成掷硬币；它影响的是行为差异，不只是可读性。

**共置（Co-location）**是文件内的配套原则：梯子决定内容放得_多深（how far down），共置决定放下去后_旁边是什么（what sits beside it）。把一个概念的定义、规则和注意事项放在同一标题下，避免散落各处，这样阅读一部分时自然能看到相邻内容。判断标准是：文档应当读起来像写给智能体的文档。成组的材料符合这一点，散落的材料不符合。这与重复不同：重复把同一含义写在两个地方；散落把一个含义拆碎到许多地方。

**蔓延（Sprawl）**是这里的失败模式：即使每行都有效且唯一，文档仍然过长。多余内容稀释注意力，每新增一行也增加保持相关性的负担。解法是使用层级：把参考放到指针后，按分支或顺序拆分，让每条路径只携带自身需要的内容。

步骤与完成标准（Steps and completion criteria）

每个步骤都以**完成标准（completion criterion）**结束，即告诉智能体工作已经完成的条件。两项属性使它成为有效手段：

• 清晰度（Clarity）：智能体能区分完成和未完成吗？“已达成理解”这样的模糊边界容易导致过早完成（premature completion）：步骤尚未真正完成就结束，注意力滑向_已经完成（being done）_。眼前尚未执行的步骤，即完成后的步骤（post-completion steps），提供向前的牵引；标准的清晰度提供阻力。依次防守：先明确边界（sharpen the bound first），这局部且便宜；只有边界确实无法明确_并且（and）_已经观察到抢跑，才拆分顺序来隐藏后续步骤。隐藏只在真实上下文边界上有效，例如交接或派出子代理；内联调用仍让后续步骤留在上下文中，无法清除它们。
• 要求力度（Demand）：标准要求多少工作。“每个修改过的模型都已说明”会迫使工作更彻底，而“产出变更清单”不会。要求力度驱动调查工作（legwork）：智能体在任务内深入挖掘，其要求藏在措辞中，不必写成独立步骤。它不限于步骤：“每条规则都已应用”约束平铺参考，与“每个步骤都已完成”约束顺序相同，所以全参考文档仍然可以要求穷尽检查。

最强的标准同时可检查、覆盖全面。

何时拆分（When to split）

把一份文档拆成两份会消耗两种负载之一，只有收益足以抵偿时才拆分：

• 按顺序（By sequence）：当后续步骤诱使智能体草草完成当前步骤时，拆分这段顺序。让后续步骤离开视野，促使当前任务获得更多调查工作。也要警惕反向操作：合并顺序会让每步看到更多后续工作，诱发过早完成。
• 按调用方式（By invocation）：这是技能特有的维度，见 SKILL-MECHANICS.md。

引导词（Leading words）

**引导词（leading word）**是模型预训练中已有的紧凑概念，智能体执行文档时借它思考，例如_课题（lesson）_、战争迷雾（fog of war）、曳光弹（tracer bullets）。重复词而不重复句子，会积累分布式定义，以极少 tokens 借用模型已有先验来锚定一大片行为。明确定义后也可以自造词，但自造词没有先验：现有词免费提供的内容，需要额外定义 tokens 才能获得；先寻找已有词。

它有两种锚定作用。在正文中锚定_执行（execution）：每次出现都引出同一行为，在平铺参考中聚焦一类需要查找的事项。在指针中锚定_调用（invocation）：当提示词、文档和代码库共享一个词时，智能体更可靠地把共同语言关联到对应材料。

寻找用引导词重构的机会：在三处重复的三元描述，或花费整句表达一个概念的指针。每一处都可以压缩成一个词：

• “快速、确定、低开销” → tight，即一个_tight_ loop。
• “你相信的循环” → red，把模糊门槛变为可观察的二元状态：循环在该缺陷上变_red_，或没有变红。

收益有两项：更少的 tokens，以及更清晰的思维挂钩。假设每份文档都有可由引导词替代的重复表述，主动找出来。

否定（Negation）是相邻的失败模式：用禁止来引导，会把被禁止行为拖入上下文，让它_更容易（more）_出现。“别想大象（Don't think of an elephant）”会让脑中只剩大象；否定是弱修饰，压不过强烈激活的概念，所以禁令容易被读成执行该行为的指示。提示正向目标（positive）：直接说明目标行为，如“写单行注释”，使被禁行为不必被说出。只有无法正向表达的硬性护栏才值得保留禁令；即便如此，也应配上正向目标，让注意力落在要做的事情上。

修剪（Pruning）

• 把每个含义保存在**单一事实来源（single source of truth）**中：一个权威位置，改变行为只需改一处。**重复（Duplication）**把同一含义写在多处，增加维护和 tokens 成本，也让该含义在梯子上的显著程度超出其真实等级。这是引导词的意外反面：引导词故意重复词，从不重复含义。
• 环境（environment）也是事实来源，例如 package.json 的脚本、配置文件、目录布局和 --help 输出；重述它们的文档是缓存（cache），即查询结果的副本，只有查询昂贵时才值得承担负载。缓存智能体无法查到的内容：未成文约定、选择背后的原因、配置没有说明的坑。单文件、单命令的查询留给环境，避免文档陈旧。
• 检查每行的相关性（relevance）：它仍然影响文档执行吗？从未关联任务的说明、应披露的分支，以及随行为或世界变化而过时的内容，都会失去相关性。短文档更容易保持相关。没有修剪纪律时，默认结局是沉积（sediment）：添加显得安全、移除显得冒险，陈旧层逐渐堆积，直到必须钻探才能找到仍有效的内容。
• 逐句寻找无效指令（no-ops）：模型默认就会遵守的指令，付出负载却没有增加信息。判断标准是是否改变默认行为，它取决于模型，而不是读者；两个人争论一条指令是否无效，是在争论默认行为，应通过实际运行文档解决，而非辩论。句子不通过时删除整句，而不是缩减字数。该标准也适用于引导词：弱到无法改变默认行为的词，例如智能体本就较彻底时要求_彻底（be thorough），是无效指令；修复应换成更强的词，如_relentless，而不是换一种技巧。