writing-for-agents

撰写任何智能体会消费的文档的参考——一个技能、一份 AGENTS.md / CLAUDE.md、一份通过指针取用的文档。包装不同；写法不变：同样的那些杠杆让每一种都变得可预测——智能体每一次运行都采取同样的_过程_，而非产出同样的输出。

当你正在撰写的文档是一个技能时，读 SKILL-MECHANICS.md，了解 frontmatter、调用选择，以及路由器技能。

上下文指针

一个**上下文指针（context pointer）**是持在智能体上下文里、点名某份上下文之外材料并编码取用它之条件的一份引用。一个技能的描述是其中之一；AGENTS.md 里点名某文档的一行是同一个对象。指针的_措辞_、而非它的目标，决定了智能体何时去取用那份材料——以及多可靠。一个措辞薄弱的指针背后放一个必备目标，是一个方差 bug：先把措辞磨锋利，只有当磨锋利失败时才把材料内联。

一个指针做两件事——陈述材料是什么，并列出应当触发去取用它的那些分支（branches）（一个分支是文档所处理的一个不同情形，所以不同的运行走过它的不同路径）。一个始终加载的指针的每一个字都在每一轮上花费代价，所以它挣得比正文更狠的修剪：

• 把引导词前置 —— 指针正是它做触发工作的地方。
• 每个分支一个触发。 给单一分支改名的同义词，是把一个分支写了两遍；把它们合并，只保留真正不同的分支。
• 砍掉正文已经承载的身份信息。

两种负载

你每添加一份文档和一个指针，都花费两种预算之一：

• 上下文负载（Context load） —— 始终加载的材料在智能体窗口上的代价：一行 AGENTS.md、一段技能描述，任何每轮都坐在上下文里、无论是否触发都花费词元和注意力的东西。
• 认知负载（Cognitive load） —— 落在人类身上的代价：哪些文档存在，以及何时去取用每一个。人类就是索引。这不是一项要最小化的代价——它是人类能动性的价格；把它花在人类判断力重要之处，把它移除于无关紧要之处。

只通过一个指针取用的材料，以指针自己那一行为代价而逃离上下文负载；完全没有指针的材料，则整个骑在认知负载上。

信息层级

一份文档由两种内容类型构成——步骤（steps）（智能体按顺序执行的动作）与参考（reference）（按需查阅的定义、规则、事实）——它们自由混合：全是步骤（一份食谱）、全是参考（一次审阅的规则、这个技能），或两者兼有。核心决策是每一块坐在信息层级上的哪个位置，这是一道按智能体多急切地需要该材料来排名的阶梯：

1. 文件内步骤 —— 首要层级：智能体做什么，按顺序。
2. 文件内参考 —— 按需查阅。常常是一个名正言顺的扁平同级集（一次审阅的每一条规则在同一档上）——一种妥当的安排，而非一种坏味道。
3. 被披露参考 —— 推出到一个单独的文件里，由一个上下文指针取用，只在指针触发时加载。范围从同一文件夹里的一个同级文件，一直到住在任何地方、任何文档都能指向的完全外部参考。

往下推得太少，顶端会臃肿；往下推得太多，你会藏起智能体真正需要的材料。那份张力就是整个决策。

**渐进式披露（Progressive disclosure）**是沿这道阶梯向下的动作——移出主文件、置于一个指针背后——好让顶端保持清晰可读。它主要不是一项词元优化：它是层级如何被保护的方式。分支是最干净的披露测试：内联每一条分支都需要的东西，把只有部分分支才取用的东西推到一个指针背后。当一份文档有步骤时，本该被披露的文件内参考会把它们埋起来，并把留意它们变成一次抛硬币——这是一个方差杠杆，而不只是一个清晰度杠杆。

**同址（Co-location）**是文件内的伴侣：阶梯决定一块材料坐得_多靠下_，同址则决定它一旦到了那里_旁边坐着什么_。把一个概念的定义、规则和注意事项放在一个标题之下，而非散落各处，好让读到其中一部分就把它的邻居一并带来。判据是：文档应当读起来像是为智能体写的文档——成组的材料读起来是那样，散落的材料则不然。（与重复不同：重复是把一个含义放在两处；散落是把一个含义割裂在许多处。）

**蔓生（Sprawl）**是这里的失败模式：一份文档单纯太长，即便每一行都在生效且独一无二。注意力在这份过量里变薄，而每一多出的行都是又一行要去保持相关。解药是那道阶梯：把参考披露到指针背后，并按分支或顺序拆分，好让每条路径只承载它需要的东西。

步骤与完成标准

每个步骤都结束于一个完成标准（completion criterion）——那个告诉智能体活儿干完了的条件。有两个属性让它成为一个杠杆：

• 清晰度（Clarity） —— 智能体分得清完成与未完成吗？一个含糊的边界（「达成理解」）会招致过早完成（premature completion）：在步骤真正完成之前就结束它，注意力滑向_已经完成_。仍在前方可见的那些步骤——完成后步骤（post-completion steps）——提供拉力；标准的清晰度是阻力。按顺序防御：先把边界磨锋利（局部且廉价）；只有当它不可化约地模糊_并且_你观察到那种急躁时，才通过拆分顺序把后面的步骤藏起来——而藏起来只在一个真正的上下文边界上才起作用（一次交接或一次子智能体派发；一次内联调用会把后面的步骤留在上下文里，什么都不清除）。
• 要求度（Demand） —— 它要求多少。「每一个被修改的模型都被交代清楚」逼出彻底的工作，而「产出一份改动清单」则不会。要求度驱动跑腿功夫（legwork）——智能体在工作内部所做的挖掘，潜伏在措辞里而非写成它自己的一个步骤——而且它不受步骤约束：「每一条规则都被应用」约束一体扁平参考，正如「每一步都完成」约束一个顺序，这就是一份全是参考的文档仍然承载一道穷尽性门槛的方式。

最强的标准既可核查又穷尽。

何时拆分

把一份文档拆成两份会花费两种负载之一，所以只有当这一刀挣得回来时才拆：

• 按顺序 —— 当完成后步骤诱使智能体去急赶眼前这一步时，拆分一串步骤。把它们移出视野会驱动对当前任务更多的跑腿功夫。当心相反的情况：合并顺序会把每一步的后续步骤暴露给后面的东西，招致过早完成。
• 按调用 —— 技能专属：见 SKILL-MECHANICS.md。

引导词

一个**引导词（leading word）**是一个已住在模型预训练里的紧凑概念，智能体在运行文档时用它来思考（lesson、fog of war、tracer bullets）。作为一个词元反复出现、绝不作为一个句子，它累积起一份分布式定义，并用最少的词元锚定一整个行为区域，靠的是招募模型早已持有的先验。自造你自己的词，只要你清楚地定义它也行，但一个杜撰的词招募不到任何先验——你用定义词元付出的，正是一个预训练词免费给出的；先伸手去取一个已有的词。

它锚定两次。在正文里，执行：那个词每次出现，智能体都伸手去取同样的行为，而在扁平参考内部，它把注意力聚焦到一类要去找的东西上。在一个指针里，调用：当同一个词住在你的提示词、你的文档和你的代码库里时，智能体会把那份共享语言与材料联系起来，并更可靠地取用它。

去猎取用引导词重构的机会。一个在三处被拼写出来的三元组，一个花一句话去指涉一个想法的指针——每一个都是一段乞求坍缩成单个词元的文字：

• 「fast, deterministic, low-overhead」→ tight（一个 tight 循环）。
• 「a loop you believe in」→ red —— 一个模糊的门槛变成一个二元的可观察状态（循环在这个 bug 上变_红_，或者不变）。

你赢两次：更少的词元，以及一个更锋利、供智能体挂靠其思考的钩子。假定每一份文档都在承载着引导词能退役的那些重述——去把它们找出来。

否定（Negation）是这个杠杆旁边的失败模式：靠禁止来引导，会把被禁的行为拖进上下文，让它_更_可用，而非更不可用。别想大象，于是大象就是全部；否定是一个弱修饰词，被强烈激活的概念淹没，所以那道禁令有一半读起来像是去做那件事的指令。提示那个正向的——陈述目标行为（「写一行注释」），好让被禁的那个从不被说出口。一道禁令只有作为一道你无法正向措辞的硬护栏时才挣得它的位置；即便如此，也把它与正向目标配对，好让注意力落在该做什么上。

修剪

• 把每个含义保持在一个**唯一真理来源（single source of truth）**里：一个权威的地方，好让改变行为是一处编辑。重复（Duplication）——同一个含义出现在不止一处——花费维护和词元，并把一个含义在阶梯上的显要性抬高到超过它真实的排名。（它是引导词的意外反面，引导词故意重复一个词元，绝不重复含义。）
• 环境（environment）也是一个真理来源——package.json 脚本、配置文件、目录布局、--help 输出——而一份重述它的文档是一份缓存（cache）：一份查找的副本，只有当查找昂贵时才挣得它的负载。缓存智能体靠查看找不到的东西：那条不成文的约定、一个选择背后的理由、任何配置都不坦白的那个坑。把单文件、单命令的查找留给环境，那里它们不会过时。
• 逐行检查相关性（relevance）：它是否仍关乎文档所做的事？一行失去相关性，是因为它从不关乎任务（纯粹的说明，或一条本该被披露的分支），或者因为它随着它所描述的行为或世界的改变而过时。更短的文档更容易保持相关。没有一套修剪纪律，默认的命运是沉积（sediment）：陈旧的层层堆积，因为添加感觉安全、移除感觉冒险，直到你不得不向下钻穿它们才能找到仍在生效的东西。
• 逐句猎取空操作（no-ops）：一条模型默认就服从的指令，付着负载却什么都没说。那个测试——它相对于默认改变了行为吗？——是相对于模型的，而非相对于读者的：两个人在一个空操作上意见相左，是在默认上意见相左，而了结它靠的是运行文档，而非争辩。当一句话没通过时，删掉整句，而不是从中削词。这个测试也给引导词打分：一个弱到打不过默认的词（智能体已经差不多够彻底时的_be thorough_）是一个空操作，而修法是一个更强的词（relentless），而非一种不同的技巧。