writing-for-agents

用于编写 Agent 所消费的任何文档的参考：技能、AGENTS.md / CLAUDE.md，或经由指针引用的文档。打包方式各不相同，但写作方法相同：同样的几个杠杆能让每种文档都可预测，因为 Agent 每次运行都遵循相同的 过程，而不是产出相同的输出。

当你所编写的文档是技能时，请阅读 SKILL-MECHANICS.md，了解前置元数据、调用方式选择和路由技能。

上下文指针

上下文指针是保存在 Agent 上下文中的一项引用，它指明某些不在上下文中的材料，并编码了访问该材料的条件。技能的描述就是一种上下文指针；AGENTS.md 中指向某份文档的一行同样是这种对象。决定 Agent 何时、以多大可靠性访问材料的，是指针的_措辞_，而不是其指向的目标。若一个必需的目标藏在措辞薄弱的指针之后，就是一个方差缺陷：应先强化措辞，只有在强化无效时才将材料内联。

指针承担两项职责：说明材料是什么，并列出应触发访问该材料的分支（分支是文档所处理的一个不同情形，不同运行会沿不同路径经过它）。每个始终加载的指针的每个字都会在每一轮消耗成本，因此它比正文更需要精简：

• 将关键词前置：指针正是它发挥触发作用的地方。
• 每个分支一个触发词。 只是改写同一分支的同义词，等于把一个分支写了两遍；应将其合并，只保留真正不同的分支。
• 删去正文已包含的身份描述。

两种负载

你添加的每份文档和每个指针，都会占用以下两种预算之一：

• 上下文负载是始终加载的材料对 Agent 窗口的成本：一行 AGENTS.md、一条技能描述，或任何每轮都位于上下文中的内容。无论是否触发，它都会消耗 token 与注意力。
• 认知负载是人类承担的成本：存在哪些文档，以及何时使用每一份。人类本身就是索引。认知负载并非需要尽量压低的成本，而是人类保有自主权的代价：应将其用在人类判断至关重要之处，在其并不重要之处则予以消除。

仅通过指针访问的材料，以指针自身那一行的代价规避上下文负载；完全没有指针的材料，则全部由认知负载承担。

信息层级

一份文档由两类内容构成：步骤（Agent 按顺序执行的操作）和参考内容（按需查阅的定义、规则和事实）。两者可以自由组合：全部是步骤（例如一份菜谱）、全部是参考内容（例如一份评审规则，即本技能），或二者兼有。核心决策在于每一部分应放在信息层级的哪一层。这是一个按 Agent 即时需要程度排序的阶梯：

1. 文件内步骤是首要层级：Agent 按顺序执行的操作。
2. 文件内参考内容按需查阅。它常常是一组扁平的同级内容（例如评审的每条规则都位于同一层），这是一种合理的安排，而非坏味道。
3. 外置参考内容被移到一个单独的文件中，通过上下文指针引用，仅在指针触发时加载。它的范围从同一文件夹中的同级文件，到可以存放于任何位置、且任何文档都可以指向的完全外部参考资料。

下放的内容过少，顶层会变得臃肿；下放过多，则会隐藏 Agent 真正需要的材料。这种张力正是整个决策的核心。

渐进式披露是沿阶梯向下的操作（将内容移出主文件，置于指针之后），使顶层保持清晰可读。它主要不是为了节省 token，而是为了保护这一层级结构。分支是检验披露是否得当的最佳方式：每个分支都需要的内容应内联，只有部分分支会用到的内容则放在指针之后。当文档包含步骤时，若将本应外置的文件内参考内容留在其中，就会淹没这些步骤，使 Agent 对它们的关注变成一场碰运气的赌博。这是一个影响方差的杠杆，而不仅仅是可读性的问题。

共置是文件内部的配套原则：阶梯决定一项内容_位于多深_，共置则决定它到达后_与哪些内容相邻_。将某个概念的定义、规则和注意事项放在同一标题之下，而非分散各处，使读者阅读其中一部分时，其相关内容也随之而来。判断标准是：文档应读起来像是专为 Agent 撰写的说明文档。分组后的内容读起来如此，分散的内容则不然。（这与重复不同：重复是将同一含义在两处重复出现；分散则是将同一含义碎片化到多处。）

冗长是这里的失败模式：文档本身过长，即便每一行都有效且各不相同。注意力会被多余的内容稀释，而每多一行，就多一处需要保持相关性。解决办法同样是借助阶梯：将参考内容放到指针之后，并按分支或顺序拆分，使每条路径只承载其所需的内容。

步骤与完成标准

每个步骤都以完成标准结束，即告诉 Agent 工作已完成的条件。有两个属性使其成为一个杠杆：

• 清晰度：Agent 能否判断已完成还是未完成？一个模糊的边界（例如“达到理解”）会引发过早完成：在步骤真正完成之前就结束它，注意力滑向已经完成。其后仍待执行的可见步骤（即完成后步骤）提供拉力，而完成标准的清晰度则构成阻力。应按以下顺序应对：首先收紧边界（局部且成本低）；只有当它本质上无法消除模糊，_并且_你观察到了急于收尾的现象时，才通过拆分序列来隐藏后续步骤。隐藏只有在真实的上下文边界（交接或子 Agent 派发）之上才有效；内联调用会让后续步骤留在上下文中，什么也清除不了。
• 要求强度：标准要求多少工作量。“所有已修改的模型都已核对”会迫使工作彻底，而“产出一份变更清单”则不会。要求强度驱动额外工作（Agent 在工作过程中进行的深入挖掘，潜藏于措辞之中，而非单独作为一个步骤写出）。它并不局限于步骤：“所有规则均已应用”同样约束一组扁平的参考内容，正如“所有步骤均已完成”约束一个序列。这也是为什么全部由参考内容构成的文档仍然带有穷尽性的要求。

最强的完成标准既可检查，又具有穷尽性。

何时拆分

将一份文档拆成两份，会占用两种负载中的一种，因此只有当拆分的收益足以抵偿代价时才拆分：

• 按顺序拆分：当一连串步骤中，后续步骤容易诱使 Agent 草率完成前面的步骤时，就将其拆分。把这些后续步骤移出视野，能促使 Agent 在当前任务上投入更多实际工作。反过来也要注意：若把多个序列合并，每个步骤都会暴露在其后续步骤之下，容易引发过早完成。

• 按调用方式拆分（针对 skill）：参见 SKILL-MECHANICS.md。

引导词

引导词是一个已存在于模型预训练中的紧凑概念，Agent 在执行文档时会以它进行思考（lesson、fog of war、tracer bullets）。以词元而非句子的形式反复出现时，它会累积出一个分布式的定义，用最少的词元锚定一整片行为区域，并调用模型已掌握的先验知识。自创词汇同样可行，但前提是要清晰定义；而自造的词无法调用任何先验，你需要用定义词元来补偿预训练词汇免费提供的内容。因此应优先使用现成的词。

引导词会在两处起锚定作用。在正文中，它作用于_执行_：每当该词出现，Agent 都会调用同一套行为模式；在扁平的参考材料中，它会把注意力聚焦到某一类需要留意的事物上。在指针中，它作用于_调用_：当同一个词同时出现在你的提示词、文档和代码库中时，Agent 会把这种共享语言与材料关联起来，从而更可靠地找到所需内容。

要主动寻找可用引导词进行重构的机会。例如，一个三元组在三处被完整写出，或一个指针花一句话去指代某个概念，这些都是适合压缩为单一词元的段落：

• "快速、确定性强、低开销" → tight（一个 tight 循环）。
• "一个你相信的循环" → red，将模糊的门禁转化为二元可观测状态（循环在缺陷处变为 red，否则不会）。

这样你能获得两方面的收益：词元更少，同时为 Agent 的思考提供了更清晰的挂钩。假设每份文档都存在引导词可以替代的重复表述，并去把它们找出来。

否定是与这一杠杆相对的失败模式：以禁止来引导行为，会把被禁止的行为带入上下文，反而使其更容易被调用。不要想象一头大象，结果满脑子都是大象。否定只是一个较弱的修饰语，会被强激活的概念压过，禁令反而被理解为去做这件事的指令。应当使用正向提示：直接描述目标行为（例如"编写单行注释"），使被禁止的行为根本不被提及。只有当某条约束无法用正向措辞表达、必须作为硬性护栏时，禁止才值得保留；即便如此，也应搭配正向目标，使注意力落在该做什么上。

精简

• 每个含义只保留一个唯一事实来源：一个权威位置，使修改行为只需在一处编辑。重复（同一含义出现在多处）会增加维护成本和 token 消耗，并使该含义在阶梯中的重要性超过其实际等级。（与之相对的是开头词的意外反面，即有意重复某个 token，但绝不重复含义。）

• 环境同样是唯一事实来源（package.json 脚本、配置文件、目录结构、--help 输出），而复述环境的文档即为缓存：它是对某次查询结果的副本，只有在查询成本高昂时才值得载入。应缓存那些 Agent 无法通过查看获得的内容：未成文的约定、选择背后的原因、配置中未明示的陷阱。对于单文件、单命令即可查到的信息，则交由环境本身处理，因为这样不会过时。

• 逐行检查相关性：它是否仍与文档所描述的内容相关？一行可能因从未与任务相关（纯粹的阐述性文字，或本应单独披露的分支）而失去相关性，也可能因其所描述的行为或现实发生变化而过时。文档越短，越容易保持相关。若没有精简纪律，默认结局便是沉积：过时的层层堆积，因为添加让人感觉安全、删除却让人担心，直到你必须层层深挖，才能找到仍然有效的内容。

• 逐句排查空操作：Agent 默认就会遵守的指令，只会白白占用载入成本而毫无作用。判断标准（它是否相对于默认行为改变了行为？）是相对于模型而言的，而非相对于读者：两人对某句是否为空操作存在分歧，说明他们对默认行为的理解不同，应通过运行文档来验证，而非争论。若某句未通过测试，应整句删除，而不是删减其中的个别词。该测试同样适用于开头词：若某个词的力度不足以超越默认行为（例如 Agent 本就相当认真时使用"认真对待"），它就是空操作，修正方法是换用更有力的词（如"锲而不舍的"），而非换一种技巧。