#/writing-for-agents

写给 agent 的文档。写任何 agent 消费的文档的参考：skill、AGENTS.md/CLAUDE.md、被指针指向的文档。打包方式不同，写作本身不变——同样的杠杆让每个文档可预测，因为 agent 每次运行走的是同一个过程，而不是产出同样的输出。

#概述

核心洞察：agent 的行为由文档的措辞驱动，不是由文档的目标驱动。所以这份参考全是关于措辞的杠杆：指针、负载、层级、完成标准、引导词、修剪。

#日常使用

> 帮我写一个 AGENTS.md
> 这个 skill 写得太长了，怎么精简？
> 帮我写一个自定义 skill

#实战

#上下文指针

上下文指针是上下文里持有的引用，命名某份上下文外的材料并编码触达条件。skill 的 description 是一个；AGENTS.md 里命名某文档的一行是同一个东西。指针的措辞（不是目标）决定 agent 何时触达材料、以及多可靠。目标很重要但指针措辞薄弱，就是变异性 bug——先磨尖措辞，只有磨尖失败才把材料内联。

指针做两件事：说明材料是什么、列出应触发触达的分支（分支 = 文档处理的一个不同情形，不同运行走不同路径）。永远加载的指针每个字都在花每一轮上下文的成本，所以修剪比正文更狠：

• 引导词前置：指针在它做触发工作的地方
• 每个分支一个触发器：给同一分支改名的同义词是一个分支写两遍——合并，只留真正不同的分支
• 砍掉正文已承载的同一性

#两种负载

• 上下文负载：常驻材料的 token 成本——AGENTS.md 一行、skill description，任何每轮都坐在上下文里的东西，无论是否触发都花 token 和注意力
• 认知负载：人脑的成本——有哪些文档、何时取用哪个。人类是索引。这不是要最小化的成本：它是人的能动性的价格，花在人判断重要的地方，移除在人判断不重要的地方

#信息层级

文档由两种内容构成：步骤（agent 执行的有序动作）和参考（按需查阅的定义、规则、事实）。核心决策是每块材料放在信息层级的哪一级：

1. 行内步骤：首要层——agent 做什么，按顺序
2. 行内参考：按需查阅。常是合法的扁平同级集（审查的每条规则在一级上）——这是好安排，不是味道
3. 披露参考：推到单独文件，由上下文指针触达，只在指针触发时加载

渐进披露是把材料推下层级、保持顶部可读的动作。不是主要为了省 token——它是保护层级的方式。分支是最干净的披露测试：每个分支都需要的内联，只有部分分支触达的推后指针。

共置是文件内的配套决策：概念的定义、规则、注意放在一个标题下而不是散开——读一部分就带出邻居。测试：文档读起来像给 agent 写的文档。

蔓延是这里的失败模式：文档太长，即使每行都活而唯一。注意力被稀释。解药是层级：参考披露到指针后面，按分支或序列拆分，让每条路径只带它需要的。

#步骤和完成标准

每一步以完成标准收尾。两个属性让它成为杠杆：

• 清晰：agent 能区分完成和未完成。模糊的边界（"达成理解"）招致过早完成——步骤没真做完就滑向"做完"。可看到的后续步骤（完成后步骤）提供拉力；标准的清晰是阻力。防御顺序：先磨尖边界（本地且便宜）；只有它确实模糊且观察到赶工，才拆分序列隐藏后续步骤。隐藏只在真实上下文边界（交接或子 agent 派遣）起效——行内调用把后续步骤留在上下文里，什么都没清掉
• 苛求：要求多少。"每个被改的模型都算到"强过"出个变更清单"。苛求驱动苦功（工作内部 agent 自己挖的、措辞里潜伏的而非写成独立步骤的挖掘）

最强标准既可检查又穷尽。

#什么时候拆分

拆一个文档成两个花一种负载，所以只在切分值得时拆：按序列（一段步骤里完成后步骤诱使 agent 赶当前这步——移出视野驱动更多苦功；警惕反向：合并序列暴露每步的后续步骤，招致过早完成）；按调用方式（见 SKILL-MECHANICS.md）。

#引导词

引导词是模型预训练里已存在的紧凑概念（lesson、fog of war、tracer bullets），agent 跑文档时用它思考。以 token 重复（永不重复含义），累积分布式定义，用最少的 token 锚定整片行为区——招募模型已有的先验。自己造词也行但要定义清楚——人造词不招募先验：定义成本你用 token 付，预训练词免费给。先找已有词。

它双重锚定：正文里锚执行（每次出现 agent 伸手取同一行为）；指针里锚调用（同一词住在你的提示、文档、代码库里，agent 把共享语言链接到材料，更可靠地触达）。

猎取重构机会："fast, deterministic, low-overhead" → tight（一个 tight 循环）；"一个你相信的循环" → red（模糊门变成二元可观察状态——循环在 bug 上变 red 或不变）。一箭双雕：更少 token + 更锐利的钩子。

否定是引导词旁边的失败模式：用禁令引导会把被禁行为拖进上下文让它更可用——"别想大象"，大象反而到处都是。提示正面目标（"写一行注释"），让被禁的那个从不被说出。禁令只作为无法正面表述的硬护栏，即便如此也要配正面目标。

#修剪

• 每个含义保持单一事实来源：一个权威位置。重复（同一含义在多个位置）花维护和 token，还把含义在层级上的突出度抬到真实级别之上（引导词是有意重复 token、永不重复含义的意外逆反）
• 环境也是事实来源（package.json 脚本、配置文件、目录布局、--help 输出）——文档复述环境就是缓存：查找的副本，只在查找昂贵时赚回负载。缓存 agent 找不到的东西：未写下的约定、选择背后的原因、配置不肯承认的坑
• 逐行查相关性：还对文档的职责有影响吗？从不影响任务的行（纯说明、该披露的分支）或随行为/世界变化过期的行，失去相关性
• 逐句猎杀空操作：模型默认就遵守的指令，付负载说废话。测试（相对默认是否改变行为）是模型相对的，不是读者相对的。句子失败就删整句，别只剪词。引导词也用此测试：弱到打不过默认的词（agent 已经够 thorough 时写 "be thorough"）是空操作，修法是更强的词（relentless），不是换技巧

#与其它技能的关系

• 写 skill 时：先读 SKILL-MECHANICS.md（frontmatter、调用选择、路由技能）
• 产物：AGENTS.md/CLAUDE.md/skill 是其它所有技能的载体