writing-for-agents

一份用于编写智能体所阅读的任何文档的参考：一个技能、一份 AGENTS.md / CLAUDE.md、一份通过指针触达的文档。包装方式各异，但写作规则是一致的：同样的杠杆让每份文档都变得可预测，因为智能体每次运行采取的是同一个流程，而不是产出同一个输出。

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

上下文指针

上下文指针（context pointer） 是智能体上下文中持有的一条引用，它指向一份"上下文之外"的资料，并编码了触达该资料的条件。技能的 description 就是一条；AGENTS.md 中指向某份文档的一行也是同一回事。决定智能体何时、以多高的可靠性触达这份资料的，是这条指针的措辞，不是它的指向。一个本应被触达的指向目标，却藏在一段措辞含糊的指针背后：这是一个方差 bug：先打磨措辞；只有当打磨失败时，才把资料直接内联进去。

一条指针承担两件事：说明这份资料是什么，以及列出应当触发触达它的分支（branch 是这份文档所处理的一种独立情形，所以不同次运行会走不同的路径）。每一条始终加载的指针里的每一个词，在每一次轮次中都在付代价，所以它需要比正文更严格的精简：

• 把"引导词"前移：指针是触发工作真正发生的地方。
• 一个分支对应一个触发词。 同义词把同一个分支换了个说法写两遍，本质上是一个分支；把它们合并，只保留真正不同的分支。
• 去掉正文已经承载的身份信息。

两种负载

你新增的每一份文档与每一条指针，都在花两种预算之一：

• 上下文负载（Context load）：始终加载的资料占据智能体窗口的代价：一行 AGENTS.md、一条技能描述，任何始终留在上下文里、无论是否触发都在消耗 token 与注意力的东西。
• 认知负载（Cognitive load）：消耗在人类身上的代价：有哪些文档存在、各自在什么时候用。人类就是这个索引。它不是要被最小化的代价：它是人类能动性的价格；把它花在需要人类判断的地方，在不需要的地方去除。

只通过指针触达的资料，逃脱了上下文负载，代价是这条指针自身那一行；完全没有指针的资料，则完全依靠认知负载。

信息层次

一份文档由两种内容类型组成：步骤（steps）（智能体按顺序执行的动作）和参考资料（reference）（按需查阅的定义、规则、事实）。两者可以自由混合：全是步骤（一份操作指南）、全是参考资料（一份审查规则，就像本技能）、或者两者兼具。核心决策是：每块内容应该放在信息层次的哪一级：这是一架按"智能体对资料的即时需要程度"排序的梯子：

1. 文件内步骤（In-file step） 是主要层级：智能体按顺序做的事情。
2. 文件内参考资料（In-file reference） 按需查阅。常常是合理的扁平同级集合（一条审查规则就是一个层级），这是妥当的安排，不算坏味道。
3. 披露型参考资料（Disclosed reference） 被推到一份独立的文件中，通过一条上下文指针触达，仅在该指针触发时才加载。跨度可以是从同一文件夹里的相邻文件，到放在任何地方的完全外部参考资料：任何文档都可以指向它。

向下推得不够，顶层就会臃肿；向下推得太多，就会把智能体真正需要的资料藏起来。这种张力就是整个决策。

渐进披露（Progressive disclosure） 是沿着这架梯子向下移动（移出主文件、藏到指针背后）的过程，目的是让顶层保持清晰可读。它主要不是为了优化 token：它是保护这架层次结构的手段。分支是最干脆的披露测试：每个分支都需要的内容内联，只有部分分支才会触达的内容推到指针背后。当一份文档有步骤时，本应被披露的文件内参考资料会把它们埋掉，让关注它们变成一件靠运气的事：这是一个方差杠杆，不只是一个可读性杠杆。

共置（Co-location） 是文件内的同伴概念：层次结构决定一块内容要放得多深，共置决定一旦放到那里，什么内容与它并排。把一个概念的定义、规则、注意事项放在同一个标题下，而不是散布在各处，这样读到一处时，它旁边的内容也会跟着进入视野。检验标准是：这份文档读起来，应该像为智能体写的文档。归在一处的资料读起来是这样；分散的资料则不是。（这与"重复"是不同的概念：重复是把同一个意思说两遍；分散是把一个意思碎成多块。）

蔓延（Sprawl） 是这里的失败模式：一份文档即使每行都是活的、独特的，也只是单纯地太长。注意力会在冗余中变薄，每多出一行就多一分维护相关性的负担。治疗手段就是这架梯子：通过指针披露参考资料，并按分支或顺序拆分，让每条路径只携带它需要的内容。