面向 Agent 的写作

写给 agent 消费的任何文档的通用参考:skill、AGENTS.md、CLAUDE.md、任何被指针引用的文档。载体不同,写法相同:同样的手段让每次运行产生一致的过程,从而产出一致的产物。

写的是 skill 时,读 SKILL-MECHANICS.md 了解 frontmatter、调用方式选择与路由 skill。

上下文指针

上下文指针(context pointer)是 agent 上下文中持有的一条引用,它指出某份不在上下文中的材料,并编码了到达它的条件。skill 的 description 是一条;AGENTS.md 里指向某文档的一行也是。指针的措辞,而非它的目标,决定了 agent 何时到达材料、到达得多可靠。必达的材料挂在弱措辞的指针后面是一个触发缺陷:先磨措辞,磨不动才内联。

一条指针做两件事:说明材料是什么,列出应触发到达的分支(branch,文档处理的不同情形,不同运行走不同路径)。常驻指针的每个词每回合都在花钱,值得比正文更狠地修剪:

• 领词前置:触发词放在指针最前面,那是它做触发工作的地方;
• 一个分支一条触发:同一分支的同义词改写是分支写了两遍,合并,只保留真正不同的分支;
• 身份信息让正文承担:正文已有的内容不在指针里重复。

两种负载

新增的每份文档与指针都要花两种预算之一:

• 上下文负载(context load):常驻材料对 agent 窗口的占用。AGENTS.md 的一行、skill 的 description,凡每回合都在上下文里的,无论是否触发都在花钱;
• 认知负载(cognitive load):对人的占用——哪些文档存在、何时用哪个。人就是索引。这不是要压到零的负载:它是人的主动性的价格,在人类判断重要的地方花,在无关紧要处省。

只靠指针到达的材料,以指针自身一行的代价躲开上下文负载;没有任何指针的材料,全部落在认知负载上。

信息层级

文档由两类内容构成:步骤(steps,agent 依次执行的动作)与参考(reference,按需查阅的定义、规则、事实)。核心决策是每条内容放在信息层级的哪一层:

1. 文内步骤:第一梯队,agent 依次要做的事;
2. 文内参考:按需查阅,平铺的规则集是正当形态;
3. 外置参考:推到独立文件,由指针到达,指针触发时才加载。

下推太少顶层臃肿;下推太多会藏起 agent 真正需要的。渐进披露(progressive disclosure)就是沿阶梯下移以保顶层可读:它主要不是省 token,是保护层级。分支是最干净的披露判据:每个分支都需要的内联,只有部分分支到达的放到指针后面。有步骤的文档里,该披露的文内参考会淹没步骤,让注意变成掷硬币。就近集中(co-location)是文内同伴:概念的定义、规则、注意事项放同一个标题下,读一处带动邻位;散落一义于多处,与重复一义于多处同病。蔓延(sprawl)是此处的失败形态:文档单纯太长,注意力摊薄,多一行就多一行要维护。解药仍是阶梯:参考外置,按分支或时序拆分。

步骤与完成判据

每个步骤终止于一个完成判据:告诉 agent 这步做完了的条件。两个属性使它成为杠杆:

• 清晰:agent 能分辨完成与未完成吗?模糊的边界("达成了理解")邀请过早完成:步骤尚未真正结束,注意力滑向"做完"。判据的清晰是阻力,后续步骤的可见性是拉力;
• 要求度:它要求多少。逐条核对"每个修改过的 model 都已对账"逼出彻底,"列出变更清单"则不。要求度驱动腿功(legwork,agent 在工作内的挖掘,潜藏在措辞里而非写成独立步骤),它不限于步骤:"每条规则都已应用"对平铺参考的约束,与"每步都做完"对序列的约束相同。

最强的判据既可核对又穷尽。

领词

领词(leading word)是模型预训练里已有的紧凑概念,agent 运行文档时用它思考(红绿、接缝、贯通切片)。作为 token 重复,绝不作为句子重复:它积累分布式定义,以最少 token 锚定一整片行为,因为它招募模型已有的先验。自造词也可,但要付定义 token 的代价;先用现成的词。

它锚定两次:正文里锚定执行(词每次出现,agent 伸手拿同一行为);指针里锚定调用(同一个词出现在你的提示、文档、代码库里时,agent 把共享语言关联到材料,更可靠地到达)。随手找机会用领词重构:三处铺陈一个三元组、指针花一整句示意一个概念,都是等着坍缩成一个 token 的段落。

否定式是它旁边的失败形态:用禁止来引导,会把被禁行为拉进上下文,让它更可用而非更不可用——别想大象,满脑子都是大象。正面表述:说出目标行为("写一行注释"),让被禁的永不开口。禁令只配得上无法正面表述的硬护栏,即便如此也要配上正面目标。

修剪

• 一义一处单一事实源:改行为只改一处。重复(一义多处)付出维护与 token,还把一个义的显著度抬过它的真实层级;
• 环境也是事实源(package.json 的 scripts、配置文件、目录结构、--help 输出):复述环境的文档是缓存,只在查询昂贵时值得。缓存 agent 自己查不到的:没写下来的约定、选择背后的原因、配置不说的坑;一次文件一次命令的查询留给环境,那里不会过期;
• 每行检查相关性:它还与文档的职责相关吗?一行因从未相关(纯说明,或该披露的分支)或因过时(它描述的行为或世界变了)而失去相关性。没有修剪纪律,默认命运是沉积(sediment):加是安全的、删是危险的,陈旧层不断沉底,直到要一路钻透才找得到还活着的;
• 逐句猎杀 no-op:模型默认就会照做的指令,说了等于没说,白花负载。判据(它改变默认行为吗?)是模型相对的,不是读者相对的:两人对 no-op 有分歧,分歧在默认行为,跑一遍文档而不是辩论。一句不合格,删整句而不是修剪词。判据同样给领词打分:打不过默认行为的词("要彻底")是 no-op,换更强的词("无情"),不是换技巧。