这是编写任何智能体会消费的文档的参考：技能、AGENTS.md / CLAUDE.md、由指针触达的文档。封装方式不同；写作方式并无不同：同样的杠杆能让每一种文档可预测，因为智能体每次运行执行的是同样的 _流程_，而不是产出同样的输出。
当你要编写的文档是技能时，请阅读 [SKILL-MECHANICS.md](SKILL-MECHANICS.md)，了解 frontmatter、调用选择以及路由技能。
上下文指针
上下文指针 是保存在智能体上下文中的一个引用，它命名某些上下文之外的材料，并编码触达该材料的条件。技能的 description 就是一个；AGENTS.md 中命名某文档的一行也是同一类对象。指针的 _措辞_，而不是其目标，决定智能体何时触达材料，以及多可靠。一个必须存在的目标背后如果只有弱措辞的指针，就是一个方差缺陷：先锐化措辞，只有锐化失败时才内联材料。
一个指针做两项工作：说明材料是什么，并列出应当触发触达它的 分支（分支是文档处理的一个不同情形，因此不同运行会沿着其中的不同路径进行）。一个始终加载的指针的每个词都会在每一轮花费成本，因此它比正文更值得严厉修剪：
- 前置引导词：指针是它执行触发工作的地方。
- 每个分支一个触发条件。 同义词如果重命名了同一个分支，就是把一个分支写了两次；合并它们，只保留真正不同的分支。
- 删除正文已经携带的身份。
两种负载
你添加的每个文档和指针都会花费两种预算之一：
- 上下文负载 是始终加载的材料在智能体窗口上的成本：一行
AGENTS.md、一个技能 description、任何每轮都坐在上下文中的内容，无论是否触发都会花费 token 和注意力。 - 认知负载 是对人类的成本：存在哪些文档，以及何时取用哪一个。人类是索引。这不是要最小化的成本：它是人类能动性的价格；在人类判断重要的地方花费它，在不重要的地方移除它。
仅通过指针触达的材料以指针自身一行的代价逃避上下文负载；完全没有指针的材料则完全依赖认知负载。
信息层级
文档由两种内容类型构成：步骤（智能体执行的有序动作）和 参考（按需查阅的定义、规则、事实）。两者可以自由混合：全部是步骤（一份配方）、全部是参考（一份评审的规则、本技能），或两者兼有。核心决策是每一块内容位于 信息层级 的哪里，该层级按智能体需要材料的即时程度排列：
- 文件内步骤 是主要层级：智能体按顺序做什么。
- 文件内参考 按需查阅。它常常是一个合理的扁平同级集合（评审的每一条规则都在同一阶），这是一种良好安排，而不是异味。
- 披露的参考 被推到单独文件中，由上下文指针触达，只有指针触发时才加载。它可以通过完全外部引用跨越同一文件夹中的同级文件，也存在于任何位置并可被任何文档指向。
向下推得太少，顶层就会膨胀；向下推得太多，你就会隐藏智能体真正需要的材料。这种张力就是整个决策。
渐进式披露 是沿层级向下的移动（移出主文件并放到指针后面），以保持顶层清晰。它主要不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：内联每个分支都需要的内容，并把只有某些分支会触达的内容推到指针后面。当文档有步骤时，本应披露的文件内参考会埋没它们，并把对它们的注意变成抛硬币：这是一个方差杠杆，而不仅是可读性杠杆。
共置 是文件内的伴随原则：层级决定一块内容 _向下多深_，共置决定它到了那里之后 _旁边是什么_。将一个概念的定义、规则和注意事项保持在同一个标题下，而不是分散各处，这样阅读一部分就会把邻近内容一并带来。测试标准是：文档读起来应当像是为智能体编写的文档。分组后的材料读起来如此；分散的材料不会如此。（这与重复不同：重复在两个地方复述一个含义；分散把一个含义碎片化到许多地方。）
蔓延 是这里的失败模式：文档只是太长，即使每一行都仍然有效且独特。注意力在过量内容中变稀，每一行额外内容都是需要保持相关的一行。解药是层级：把参考披露到指针后面，并按分支或顺序拆分，使每条路径只携带它需要的内容。
步骤与完成标准
每个步骤都以 完成标准 结束，即告诉智能体工作完成的条件。两个属性使它成为杠杆：
- 清晰度：智能体能区分完成与未完成吗？模糊的界限（“已达到理解”）会诱发 过早完成：在步骤真正完成前就结束，注意力滑向 _已经完成_。仍然可见的后续步骤（完成后的步骤）提供拉力；标准的清晰度提供阻力。按顺序防御：先锐化界限（局部且廉价）；只有当它不可约地模糊 _并且_ 你观察到仓促时，才通过拆分顺序隐藏后续步骤。隐藏只在跨越真实上下文边界时有效（交接或子智能体分派；内联调用会让后续步骤留在上下文中，什么也不清除）。
- 要求强度：它要求多少工作。“每个被修改的模型都已说明”会迫使彻底工作，而“产出一份变更清单”不会。要求强度驱动 实际功夫（智能体在工作内部做的挖掘，潜藏在措辞中，而不是写成自己的步骤），并且它不限于步骤：“每条规则都已应用”会约束一组扁平参考，正如“每个步骤都完成”会约束一个顺序，这正是一个全参考文档仍然携带穷尽性标准的方式。
最强的标准既可检查，又穷尽。
何时拆分
把一个文档拆成两个会花费两种负载之一，因此只有当这一刀值得时才拆分：
- 按顺序：当完成后的步骤诱使智能体仓促完成它前面的步骤时，拆分一串步骤。让它们不可见会推动当前任务做更多实际功夫。警惕反向情况：合并顺序会让每个步骤的后续步骤暴露给后续内容，从而诱发过早完成。
- 按调用，技能特定：见 [
SKILL-MECHANICS.md](SKILL-MECHANICS.md)。
引导词
引导词 是已经存在于模型预训练中的一个紧凑概念，智能体在运行文档时用它来思考（_lesson_、_fog of war_、_tracer bullets_）。它作为 token 被重复，而不是作为句子被重复，从而累积出一个分布式定义，并通过调用模型已经拥有的先验，以最少的 token 锚定一整片行为。自己造词也可以，只要你清楚定义它，但人造词不会调用先验：你要用定义 token 支付预训练词免费提供的东西；先寻找现有词。
它会锚定两次。在正文中，它锚定 _执行_：每当该词出现时，智能体都会取用同样的行为，并且在扁平参考中把注意力聚焦到一类要找的东西上。在指针中，它锚定 _调用_：当同一个词存在于你的提示词、文档和代码库中时，智能体会把这种共享语言与材料关联起来，并更可靠地触达它。
寻找用引导词重构的机会。一个三元组在三处被拼写出来，一个指针花一句话来指向一个想法。每一段都在请求坍缩成单个 token：
- “fast, deterministic, low-overhead” → _tight_（一个 _tight_ 循环）。
- “a loop you believe in” → _red_，把模糊的门变成二元可观察状态（循环在 bug 上变 _red_，或者没有）。
你会赢得两次：更少的 token，以及更锋利的钩子，供智能体把思考挂上去。假定每个文档都携带着引导词可以退休的复述。去找出来。
否定 是这个杠杆旁边的失败模式：通过禁令来引导会把被禁止的行为拖入上下文，并让它 _更_ 可用，而不是更不可用。_别想一头大象_，然后大象就是一切；否定是一个弱修饰语，会被强烈激活的概念淹没，因此禁令有一半会被读成执行该事的指令。提示 正面：陈述目标行为（“写一行注释”），使被禁止的行为从不说出。禁令只有在无法用正面方式表述的硬护栏中才有一席之地；即便如此，也要把它与正面目标配对，使注意力落在该做什么上。
修剪
- 让每个含义保留在 单一事实来源 中：一个权威位置，因此改变行为只需在一处编辑。重复（同一个含义出现在多个地方）会带来维护和 token 成本，并夸大一个含义在层级上的显著性，使其超过真实等级。（这是引导词的意外反向：引导词故意重复 token，从不重复含义。）
- 环境 也是事实来源（
package.json脚本、配置文件、目录布局、--help输出），而复述它的文档是一个 缓存：一份查找的副本，只有当查找昂贵时才值得承担负载。缓存智能体无法通过查看找到的东西：未写明的约定、选择背后的原因、任何配置文件都不会承认的坑。把单文件、单命令的查找留给环境，在那里它们不会过时。 - 检查每一行的 相关性：它是否仍然与文档的作用有关？一行会因从不涉及任务（只是阐述，或一个本应披露的分支）而失去相关性，或因所描述的行为或世界变化而过时。更短的文档更容易保持相关。没有修剪纪律时，默认命运是 沉积：过时层会沉积，因为添加感觉安全而移除感觉有风险，直到你必须向下钻透它们才能找到仍然有效的内容。
- 逐句寻找 空操作：模型默认已经遵守的指令只是支付负载而什么也不改变。测试（它是否相对于默认改变行为？）是模型相对的，不是读者相对的：两个人对某个空操作有分歧，是在对默认值有分歧，并且应通过运行文档而不是辩论来解决。当一个句子失败时，删除整个句子，而不是从中删词。该测试也会给引导词评分：一个弱到无法胜过默认值的词（当智能体已经相当彻底时 _be thorough_）就是空操作，修复方式是更强的词（_relentless_），而不是不同技术。