writing-for-agents 是一份面向智能体消费文档的写作参考。其核心主张是：无论文档是技能、AGENTS.md、CLAUDE.md 还是通过指针触达的参考文档，包装形式不同，但写作方法一致。所有杠杆都服务于一个根本美德——可预测性：智能体每次运行遵循相同过程，而非产出相同结果。
文档首先引入上下文指针的概念：指针是智能体上下文中持有的引用，指向上下文之外的材料并编码触达条件。技能描述、AGENTS.md 中命名文档的一行都是指针。指针的措辞而非目标决定智能体何时触达材料及可靠程度。必备目标配弱措辞指针是方差缺陷，应先锐化措辞，若失败再内联材料。指针承担两项任务：说明材料是什么，列出应触发触达的分支。始终加载的指针每个词每轮都有成本，因此需更严格修剪：前置引导词、每个分支一个触发、合并同义重命名、删除正文已承载的身份信息。
文档区分两种负载：上下文负载是始终加载材料对智能体窗口的成本（如 AGENTS.md 行、技能描述），消耗令牌与注意力；认知负载是 human 的成本——哪些文档存在、何时使用。人类是指引者，认知负载不是要最小化的成本，而是人类能动性的代价，应花在人类判断重要之处。仅通过指针触达的材料以指针自身一行为代价逃脱上下文负载；无指针材料完全依赖认知负载。
信息层级将文档内容分为步骤（智能体执行的有序动作）与参考（按需查阅的定义、规则、事实）。核心决策是每部分在层级上的位置：文件内步骤（主要层级）、文件内参考（按需查阅，常为扁平同级集）、披露参考（推入单独文件，通过上下文指针触达，仅在指针触发时加载）。推得太少顶层臃肿，推得太多隐藏必要材料。渐进披露是沿层级下移的动作，主要不是令牌优化，而是保护层级。分支是最清晰的披露测试：内联每个分支都需要的，推入仅部分分支触达的。共置是文件内伴侣：将概念的定义、规则、注意事项置于同一标题下。蔓延是失败模式：文档过长，注意力稀薄。
每个步骤以完成标准结束。两个属性使其成为杠杆：清晰性（智能体能否区分完成与未完成？模糊边界易导致过早完成，需先锐化边界，若不可约模糊且观察到匆忙，再通过拆分序列隐藏后续步骤，隐藏仅跨真实上下文边界有效）与要求度（需要多少努力，“每个修改模型都已说明”迫使彻底工作，“产出变更列表”则不然）。最强标准既可检查又详尽。
拆分文档消耗一种负载，仅当切割值得时拆分：按序列拆分（后续步骤诱使智能体匆忙当前步骤，保持不可见驱动更多功夫；警惕反向：合并序列暴露后续步骤，邀请过早完成）；按调用拆分（技能特定，见 SKILL-MECHANICS.md）。
引导词是紧凑概念，已存在于模型预训练中，智能体运行文档时用以思考（如 lesson、fog of war、tracer bullets）。作为令牌重复而非句子，积累分布式定义，以最少令牌锚定整个行为区域。引导词锚定两次：正文中执行（每次词出现智能体触达相同行为，扁平参考中聚焦注意力于某类事物）；指针中调用（同一词存在于提示、文档、代码库中，智能体将共享语言链接到材料，更可靠触达）。应寻找用引导词重构的机会：三处拼写的三元组（重复）、用句子指向一个想法的指针，皆可折叠为单一令牌。否定是此杠杆旁的失败模式：通过禁止引导会将禁止行为拖入上下文，使其更可用。应提示正面行为，仅当无法正面表述的硬护栏才用禁止，并搭配正面目标。
修剪：每个意义保持单一真理源，一处权威位置，改变行为即一处编辑。重复（同一意义多处）成本维护与令牌，并虚增意义在层级上的突出度。环境也是真理源（composer.json/package.json 脚本、配置文件、目录布局、--help 输出），文档重述是缓存：查找副本，仅当查找昂贵时才值得加载。缓存智能体无法通过查看找到的：未写下的约定、选择背后的原因、配置不承认的陷阱。将单文件单命令查找留给环境，避免过时。检查每行相关性：是否仍关乎文档所做？行因从未关乎任务（纯说明或应披露的分支）或随行为变化而过时失去相关性。更短文档更易保持相关。没有修剪纪律，默认命运是沉积：过时层因添加感觉安全、移除感觉风险而沉积，直到必须钻透寻找仍活跃者。逐句寻找无操作：模型默认已遵守的指令付出负载却什么也没说。测试（是否改变行为相对于默认？）是模型相对的，非读者相对的：两人对无操作有分歧即对默认有分歧，通过运行文档解决，而非辩论。当句子失败，删除整句而非修剪词语。测试也评级引导词：太弱无法击败默认的词（当智能体已大致彻底时要求彻底）是无操作，修复是更强词（relentless），而非不同技术。