编写智能体消费的任何文档的参考：技能、AGENTS.md / CLAUDE.md、通过指针引用的文档。包装形式不同，但写作原则相同：因为智能体每次运行时执行的是相同的流程，而不是产生相同的输出，所以相同的杠杆能让每个文档变得可预测。
当你正在编写的文档是一个技能时，请阅读 SKILL-MECHANICS.md 了解前言、调用选择和路由技能。
上下文指针
上下文指针是智能体上下文中持有的一个引用，它命名了某些不在上下文中的材料，并编码了访问该材料的条件。技能的描述就是一个指针；AGENTS.md 中指向某个文档的一行也是同样的对象。指针的措辞（而非其目标）决定了智能体何时以及多可靠地访问到该材料。一个措辞不当的指针指向一个必须访问的目标，就是一个变异错误：首先应优化措辞，只有优化失败后才考虑内联该材料。
指针承担两项工作：说明材料是什么，以及列出应触发访问它的分支（分支是文档处理的不同情况，因此不同的运行会走不同的路径）。始终加载的指针的每个词在每一轮对话中都有成本，因此它比正文更需要严格精简：
- 前置引导词：指针是其触发工作的位置。
- 每个分支一个触发器。 对单个分支的不同命名是同一次分支写了两次；合并它们，只保留真正不同的分支。
- 删去正文已经承载的身份信息。
两种负载
你添加的每个文档和指针都会消耗两种预算之一：
- 上下文负载 是始终加载的材料在智能体窗口中的成本：一条
AGENTS.md行、一个技能描述，任何在每一轮对话中都会出现在上下文中且消耗令牌和注意力的内容，无论它是否被触发。 - 认知负载 是人类方面的成本：存在哪些文档，以及何时需要查阅它们。人类是索引。这不是需要最小化的成本：它是人类代理权的代价；在人类判断重要的地方付出它，在不重要的地方移除它。
仅通过指针访问的材料避免了上下文负载，代价是指针本身的一行；完全没有指针的材料则完全依赖于认知负载。
信息层级
一个文档由两种内容类型构成：步骤（智能体执行的有序动作）和参考（根据需要查阅的定义、规则、事实）。两者可以自由组合：全部是步骤（一个配方），全部是参考（审查规则、本技能），或两者兼有。核心决策是每个片段在信息层级中的位置，该层级根据智能体需要材料的即时性排序：
- 文件内步骤 是主要层级：智能体按顺序执行的操作。
- 文件内参考 是根据需要查阅的内容。通常是一个合法的扁平对等集（审查的所有规则在同一层级上），这是很好的安排，不是坏味道。
- 外部引用参考 被推送到一个单独的文件中，通过上下文指针访问，仅当指针触发时才加载。包括同一文件夹中的同级文件，以及任何位置、任何文档都可以指向的完全外部参考。
向下推送得太少，顶层会膨胀；推送得太多，你会隐藏智能体实际需要的材料。这种张力就是整个决策的核心。
渐进式披露 是向下移动层级（从主文件移出并置于指针之后）的操作，使顶层保持清晰可读。它主要不是为了优化令牌：它是保护层级结构的方式。分支是最清晰的披露测试：内联每个分支都需要的内容，将仅部分分支需要的内容置于指针之后。当一个文档有步骤时，应该被披露的文件内参考会埋没这些步骤，使得关注它们变成抛硬币一样的事：这不仅影响可读性，更是一个变异杠杆。
共置 是文件内的伴生原则：层级决定一个片段向下多远，而共置决定一旦到了那里，什么应该放在它旁边。将一个概念的定义、规则和注意事项放在一个标题下，而不是分散开来，这样阅读一部分时其邻接部分也会被读到。检验标准：文档读起来应该像为智能体编写的文档。分组的内容读起来就是这样；分散的内容则不然。（这不同于重复：重复是在两个地方表达同一含义；而分散是将一个含义碎片化到多个地方。）
蔓延 是这里的失败模式：一个文档过长，即使每一行都是活跃且独特的。注意力在过长内容中稀释，每一行额外内容都增加了保持相关性的负担。对策是层级结构：将参考披露到指针之后，按分支或序列拆分，使每条路径只携带其所需的内容。
步骤与完成标准
每个步骤以一个完成标准结束，该标准告诉智能体工作何时完成。两个属性使其成为杠杆：
- 清晰性：智能体能区分完成与未完成吗？模糊的边界（如“达成理解”）会引发过早完成：在步骤真正完成之前就结束它，注意力滑向已完成的状态。仍然可见的后续步骤（完成后步骤）提供了拉力；标准的清晰性则是阻力。按顺序防御：首先加强边界（本地且成本低）；仅当边界不可消除地模糊且你观察到冲动的行为时，通过拆分序列来隐藏后续步骤。隐藏仅在真正的上下文边界（交接或子智能体分派；内联调用使后续步骤仍在上下文中，无法清除）上有效。
- 要求程度：它需要多少工作量。“每个修改过的模型都已说明”强制彻底工作，而“生成变更列表”则不会。要求程度驱动实际工作（智能体在工作中进行的深入挖掘，隐藏在措辞中而非写成一个单独的步骤），并且它不局限于步骤：“每条规则都已应用”约束一个扁平参考体，就像“每个步骤都已执行”约束一个序列一样，这就是为什么一个全参考文档仍然包含一个彻底的完成度要求。
最强的标准既是可检查的，也是彻底的。
何时拆分
将一个文档拆分成两个会消耗两种负载中的一种，因此只有在拆分值得时才进行拆分：
- 按序列拆分：拆分一段步骤运行，其中完成后步骤会诱使智能体急于完成当前步骤。将它们移出视野会在当前任务上驱动更多的实际工作。注意反向效果：合并序列会使每个步骤的后续步骤暴露在后面的内容中，从而诱发过早完成。
- 按调用拆分，技能特有：参见
SKILL-MECHANICS.md。
引导词
引导词 是已经存在于模型预训练中的紧凑概念，智能体在运行文档时会用它进行思考（例如“教训”、“战争迷雾”、“曳光弹”）。以令牌形式重复，而非句子，它能积累一个分布式定义，并用最少的令牌锚定整个行为区域，通过利用模型已有的先验知识。自己创造引导词也可以，前提是定义清晰，但人为创造的词语无法利用任何先验知识：你需要用定义令牌来支付预训练词汇免费提供的东西；因此优先使用现有词汇。
它在两层方面起到锚定作用。在正文中，执行：智能体每次看到该词时都会采取相同的行为，在扁平参考中它聚焦注意力于寻找哪类事物。在指针中，调用：当同一个词出现在你的提示、文档和代码库中时，智能体将该共享语言与材料链接起来，并更可靠地访问它。
寻找机会用引导词重构。三个站点拼写出的三元组，或一个指针用一句话来指代一个想法。每一处都渴望被压缩成一个单一令牌：
- “快速、确定性、低开销” → 紧凑（一个紧凑的循环）。
- “你相信的循环” → 变红，将一个模糊的门限变成一个二值的可观察状态（循环在出现 bug 时变红，否则不变）。
你获得双重收益：更少的令牌，以及更清晰的钩子让智能体挂载其思考。假设每个文档都携带了可以用引导词替换掉的重复陈述。去找到它们。
否定 是这个杠杆旁边的失败模式：通过禁止来引导会将禁止的行为带入上下文，并使其更可用，而不是更少。别想大象，结果满脑子都是大象；否定是一个较弱的修饰语，被强烈激活的概念所覆盖，因此禁令有一半读像是指导去做这件事。提示正向：说明目标行为（“写一行注释”），这样被禁止的行为就永远不会被提及。禁令只有在作为你无法用正向表述的硬性护栏时才有其位置；即便如此，也要与正向目标配对，使注意力落在该做的事情上。
精简
- 将每个含义保持在单一真实来源中：一个权威的地方，这样改变行为就是一个地方的编辑。重复（同一含义出现在多个地方）消耗维护成本和令牌，并将该含义在层级中的重要性提升到其真实级别之上。（这是引导词的有意重复令牌而非含义的相反意外。）
- 环境 也是一个真实来源（
package.json脚本、配置文件、目录布局、--help输出），而复述环境的文档是一个缓存：一种查找的副本，只有在查找成本很高时才值得加载它。缓存智能体无法通过查找找到的内容：未成文的惯例、选择背后的原因、配置文件未暴露的陷阱。将“一个文件、一个命令”的查找留给环境，在那里它们不会过时。 - 逐行检查相关性：它是否仍然与文档的功能有关？一行可能因为从未与任务相关（仅仅是论述，或应该被披露的分支）而失去相关性，或者因为它所描述的行为或世界发生变化而过时。更短的文档更容易保持相关性。没有精简纪律的默认命运是沉积：过时的层级层层堆积，因为添加感觉安全而删除感觉有风险，直到你必须向下钻探才能找到仍然活跃的内容。
- 逐句寻找空操作：模型已经默认遵守的指令，说了等于没说，却要付出负载。测试（它是否改变了相对于默认行为的行为？）是与模型相关的，而不是与读者相关的：两个人对空操作的分歧是对默认行为的分歧，通过运行文档来解决，而不是通过辩论。当一句话失败时，删除整句话，而不是修剪其中的词汇。该测试同样适用于评估引导词：一个太弱而无法击败默认单词的引导词（当智能体已经相当全面时还要求“要全面”）是一种空操作，解决方法是用一个更强的词（锲而不舍），而不是用不同的技巧。