light-writing-for-agents

供编写任何 Agent 会读取的文档参考——无论是 skill、AGENTS.md / CLAUDE.md，还是通过指针访问的文档。包装方式各不相同，写作方法却一样：相同的杠杆能让每份文档都更可预测——让 Agent 每次运行都采用相同的 流程，而非产出相同的结果。

如果你要写的是 skill，请阅读 SKILL-MECHANICS.md，了解 frontmatter、调用方式选择和路由 skill。

上下文指针

上下文指针是 Agent 上下文中的一条引用，用于指明某些不在上下文中的材料，并编码访问这些材料的条件。skill 的描述就是一种；AGENTS.md 中指向某篇文档的一行也是同一种东西。决定 Agent 何时访问材料、以及访问的可靠程度的，是指针的 措辞，而非目标材料本身。必须访问的目标若被措辞含糊的指针指向，就会造成方差问题：先改进措辞，只有改进无效时才将材料内联。

指针有两项职责：说明材料是什么，并列出应触发访问的分支（分支是文档处理的一个独立情况，因此不同运行会经过不同路径）。始终加载的指针中每个词都会在每一轮产生开销，因此比正文更需要精简：

• 把关键触发词放在最前面——指针正是通过它来触发访问的。
• 每个分支只设一个触发条件。 用同义词为同一个分支换个说法，等于把一个分支写了两遍；应合并，只保留真正不同的分支。
• 删掉正文已说明的标识信息。

两种负载

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

• 上下文负载——始终加载的材料对 Agent 上下文窗口造成的开销：AGENTS.md 中的一行、skill 描述，以及每轮都留在上下文中的任何内容；无论是否触发，都会消耗 token 和注意力。
• 认知负载——对人的开销：有哪些文档，以及何时应查阅每份文档。人就是索引。这不是要尽量降低的开销，而是人类自主决策所需付出的代价；应把它用在需要人类判断的地方，并在不需要时去除。

只有通过指针访问的材料不会产生上下文负载，但指针本身会占用一行；完全没有指针的材料则全部依赖认知负载。

信息层级

文档由两种内容构成——步骤（Agent 按顺序执行的操作）和参考资料（按需查阅的定义、规则、事实），二者可以自由组合：可以全是步骤（操作流程），全是参考资料（评审规则、本技能），也可以兼有。核心决策在于每部分处于信息层级的哪个位置：这是一个按 Agent 需要材料的紧迫程度排序的阶梯：

1. 文件内步骤——首要层级：Agent 按顺序要做什么。
2. 文件内参考资料——按需查阅。通常可以是合理的扁平同级集合（评审的每条规则都位于同一层）——这种安排很合适，并非异样。
3. 已披露的参考资料——移至单独文件，通过上下文指针访问，仅在指针触发时加载。范围从同一文件夹中的同级文件，到存放在任意位置、可供任何文档指向的完全外部参考资料。

向下移得太少，顶部就会臃肿；移得太多，又会藏起 Agent 实际需要的材料。这种权衡正是整个决策的核心。

渐进式披露就是沿阶梯向下移动——从主文件移出，并置于指针之后——让顶部保持清晰易读。这主要不是为了优化 token，而是为了保护层级。分支是检验是否应披露的最清晰方式：每个分支都需要的内容放在文档内；只有部分分支会用到的内容则置于指针之后。文档包含步骤时，应披露的文件内参考资料会将步骤埋没，让是否留意到它们变成掷硬币般的随机结果——它不只是影响易读性，也会增加结果的波动。

就近组织是文件内的配套原则：层级决定某部分要放得_多靠下_，就近组织则决定它在该处_与什么内容并列_。将一个概念的定义、规则和注意事项放在同一标题下，而不是散落各处，这样读者阅读某部分时，也能一并看到相关内容。检验方法：文档应读起来像是为 Agent 编写的文档——内容分组时是这样，分散时则不是。（这与重复不同：重复是在两个位置表达同一个含义；分散则是把一个含义拆散到多个位置。）

内容膨胀是这里的失效模式：文档过长，即使每一行都仍然有效且独一无二也是如此。内容过多会分散注意力，而每多一行，就多一行需要保持相关。解决方法是利用层级：将参考资料置于指针之后，并按分支或顺序拆分，让每条路径只包含所需内容。

步骤与完成标准

每个步骤都以一个完成标准结束——用于告知 Agent 工作已完成的条件。两个特性使其成为有效的杠杆：

• 清晰度——Agent 能否分辨已完成与未完成？模糊的界限（“已充分理解”）会导致过早完成：步骤尚未真正完成就结束，注意力转向_完成这件事_。眼前仍可见的后续步骤——即完成后的步骤——会形成牵引力；标准的清晰度则提供阻力。按顺序应对：先明确界限（局部且成本低）；只有当界限确实无法明确_且_观察到匆忙倾向时，才通过拆分顺序来隐藏后续步骤——而隐藏只有跨越真正的上下文边界才有效（交接或派发给子 Agent；内联调用仍会让后续步骤留在上下文中，无法清除任何内容）。
• 要求力度——标准要求做到什么程度。“每个修改过的模型都有记录”会迫使 Agent 彻底完成工作，而“生成一份变更清单”则不会。要求力度决定投入的功夫——Agent 在工作过程中进行的挖掘，隐含在措辞中，而不是写成独立步骤——而且它不受步骤限制：“应用每条规则”约束的是一组扁平参考资料，就像“完成每个步骤”约束一个顺序一样；这正是全为参考资料的文档仍能设定全面性要求的方式。

最有力的标准既可核查，又全面。

何时拆分

将一份文档拆成两份会占用两个加载额度中的一个，因此只有拆分确有价值时才进行：

• 按顺序拆分 — 拆分一串步骤：完成后的步骤会诱使 Agent 仓促处理眼前的步骤。让后续步骤暂不出现在视野中，能促使 Agent 为当前任务做更多功课。也要留意反面情况：合并步骤序列会让每一步都暴露在后续内容面前，诱使 Agent 提前完成。
• 按调用拆分 — 视技能而定：参见 SKILL-MECHANICS.md。

引导词

引导词是模型预训练中已有的简洁概念，Agent 在处理文档时会借助它来思考（教训、战争迷雾、曳光弹）。将它反复作为词语而非句子使用，会逐渐形成分布式定义，并通过调用模型已有的先验知识，用最少的词锚定一整片行为区域。自己创造词语也行，只要定义清晰，但生造词无法调用任何先验知识——预训练词语可以免费提供定义，你却要为生造词付出定义所需的词数；优先考虑使用现成词语。

它有两重锚定作用。在正文中，它锚定_执行_：每次看到这个词，Agent 都会采用相同的行为；在扁平参考资料中，它会将注意力聚焦到一类需要查找的事物上。在指针中，它锚定_调用_：当提示词、文档和代码库中都出现同一个词时，Agent 会将这种共通语言与相关材料关联起来，从而更可靠地找到它。

留意运用引导词进行重构的机会。在三个地方都完整写出的三项特征、用一句话指向某个概念的指针——每一处都在等待被压缩成一个词：

• “快速、确定性、低开销” → 紧凑（一个_紧凑_循环）。
• “一个你信得过的循环” → 红色——模糊的关卡变成二元的可观测状态（循环遇到 Bug 时会变_红色_，否则不会）。

你能一举两得：减少词数，也为 Agent 提供一个更清晰的思维锚点。假设每份文档都包含可以由引导词取代的重复表述——去找出来。

否定是与这一杠杆相伴的失效模式：通过禁止来引导，会把被禁止的行为拖入上下文，使它变得_更_容易被想起，而不是更难。不要想大象，脑海里就只剩大象；否定词只是一个微弱的修饰语，强烈激活的概念会压过它，所以禁令读起来往往像是在指示你去做那件事。提示正向目标——直接说明目标行为（“写单行注释”），这样就不用提及被禁止的行为。只有在无法用正向表述的情况下，禁令才值得保留为硬性护栏；即便如此，也要配上正向目标，让注意力落在应该做什么上。

精简

• 每个含义都应只有一个唯一可信来源：一个权威位置，这样修改行为时只需改一处。重复——在多个位置表达相同含义——会增加维护成本和 Token 占用，还会让某个含义在优先级阶梯上的显著程度超过其实际等级。（与引导词相反的意外情况，是有意重复一个 Token，而不是重复含义。）
• 环境也是唯一可信来源——package.json 脚本、配置文件、目录布局、--help 输出——而复述这些内容的文档就是缓存：一份查询结果的副本，只有在查询成本高昂时才值得加载。缓存 Agent 无法通过查找获知的信息：未写明的约定、选择背后的原因、配置中不会坦白的陷阱。只需查一个文件或运行一条命令就能找到的信息，就留给环境处理，这样它们就不会过时。
• 检查每一行的相关性：它是否仍与文档的用途有关？如果某一行从未与任务相关（只是说明性内容，或是应该披露的分支），或者随着所述行为或环境发生变化而过时，它就失去了相关性。文档越短，越容易保持相关。如果没有精简的纪律，最终就会积淀：过时的层层内容不断沉积，因为添加让人安心，删除让人担忧，直到你不得不逐层剖开，才能找到仍然有效的内容。
• 逐句查找无效指令：模型默认就会遵循的指令，写出来只会增加负担，却毫无作用。判断标准是——它是否会改变相对于默认行为的表现？这取决于模型，而非读者：两个人若对某条指令是否无效意见不一，实际上是对默认行为有分歧，应通过运行文档来解决，而不是争论。若某句话未通过检验，就删除整句话，而不是只删减其中的词语。这个检验也适用于引导词：如果某个词太弱，无法胜过默认行为（Agent 本来就算比较认真，却还要求它 be thorough），那它就是无效指令；解决办法是换用更有力的词（relentless），而不是换一种技巧。