writing-for-agents-zh

为 agent 消费的任何文档——一项 skill、一份 AGENTS.md / CLAUDE.md、一个通过 pointer（指针）触达的文档——提供撰写参考。包装形式不同，写作方法不变：相同的杠杆（levers）让每一份文档都可预测——agent 每次运行都走相同的_过程_，而不是产出相同的输出。

当你撰写的文档是一项 skill 时，请阅读 SKILL-MECHANICS.md，了解 frontmatter、调用方式选择和 router skills（路由类 skills）。

上下文指针（Context pointers）

context pointer（上下文指针） 是保存在 agent 上下文中的一种引用：它指名某些上下文之外的材料，并编码了触达该材料的条件。skill 的 description 就是一个例子；AGENTS.md 中指名某文档的一行也是同一类对象。决定 agent 何时、以及多可靠地触达材料的，是指针的_措辞_，而不是它的目标。一个必须触达的目标藏在措辞软弱的指针后面，就是一次 variance bug（方差性缺陷）：先打磨措辞，只有当打磨无效时才把材料内联进来。

指针承担两项工作——说明材料是什么，并列出应触发触达它的 branches（分支）（一个 branch 是文档处理的某个独立情形，不同的运行会走不同的路径）。常驻加载的指针每个词每一轮都在消耗成本，因此它比正文更应被严格修剪：

• 把 leading word 前置——指针正是在这里完成它的触发工作。
• 每个 branch 一个触发词。 为同一个 branch 换名的同义词，等于把同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。
• 删掉正文已承载的身份信息。

两种负载（The two loads）

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

• Context load（上下文负载）——常驻材料对 agent 窗口的消耗：一行 AGENTS.md、一条 skill description、任何每一轮都待在上下文里的东西，无论是否触发都在消耗 tokens 和注意力。
• Cognitive load（认知负载）——对人的消耗：存在哪些文档、何时该使用哪一份。人是索引。这不是需要最小化的成本——它是人类能动性的代价；在人类判断重要的地方投入它，在不重要的地方移除它。

只通过指针触达的材料，以指针自身那一行为代价躲开 context load；完全没有指针的材料则完全承载在 cognitive load 上。

信息层级（Information hierarchy）

一份文档由两种内容类型构建——steps（步骤）（agent 执行的有序动作）和 reference（参考）（按需查阅的定义、规则、事实）——它们可以自由混合：全是 steps（一份菜谱）、全是 reference（一次 review 的规则、本 skill），或两者兼有。核心决策是每一块内容在**information hierarchy（信息层级）**上的位置——这是一把按 agent 需要该材料的紧迫程度排序的梯子：

1. In-file step（文件内步骤）——最顶层：agent 按顺序做什么。
2. In-file reference（文件内参考）——按需查阅。常常是一组合法的扁平同级内容（一次 review 的所有规则在同一级）——这是合理的安排，不是坏味道。
3. Disclosed reference（外置参考）——被推送到单独的文件中，通过 context pointer 触达，仅在指针触发时加载。范围从同一文件夹中的同级文件，一直到完全外部的参考——后者可以存在于任何地方，任何文档都可以指向它。

往下推得太少，顶层会臃肿；推得太多，你会藏起 agent 真正需要的材料。这种张力就是整个决策本身。

Progressive disclosure（渐进式披露） 是沿梯子向下的动作——移出主文件、放到指针之后——让顶层保持易读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：把每个 branch 都需要的内容内联，把只有部分 branch 会触达的内容放到指针之后。当文档含有 steps 时，本应被披露的 in-file reference 会埋没它们，把对步骤的关注变成一次抛硬币——这是 variance 杠杆，而不仅是可读性杠杆。

Co-location（共置） 是文件内的配套动作：梯子决定一块内容_向下放多深_，co-location 决定它_旁边放什么_。把某个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样阅读其中一部分时会把相邻内容一起带出来。检验标准：文档读起来应当像是专门为 agent 写的文档——分组的内容读起来如此；散落的内容则不然。（这不同于 duplication（重复）：重复是在两处重复同一个含义；散落是把一个含义拆散到多处。）