write-for-agents

为 Agent 编写

编写能让 Agent 每次运行都遵循相同流程的说明。

流程

1. 阅读文档、所有指向它的内容、所有引用它的文档，以及它描述的文件和命令。
2. 按照以下规则起草或修订文档。
3. 按照每条规则检查每个句子，然后执行 unslop。确保每个句子都符合所有规则，且所有调用方的步骤仍然成立，之后再结束。

指针

指针是指向始终加载的上下文中其他材料的引用，例如技能说明或带有文档链接的 AGENTS.md 条目。指针中的每个词都会在每一轮消耗令牌和注意力。

• 将用户或 Agent 会用来描述该任务的词放在最前面。
• 每种不同情况写一个触发条件。删除已有情况的同义表达。
• 删除目标文档中已有的信息。
• 如果 Agent 跳过了必需材料，先改写指针。只有改写无效时才将材料内联。

内容位置

• 将所有情况都需要的内容保留在主文件中。将只有部分情况需要的内容移至单独文件，并添加指向该文件的指针。
• 将某个主题的定义、规则和例外放在同一个标题下。

完成标准

• 每个步骤都以可检查的完成标准结束。优先使用详尽的界定（“每个发现的问题都已修复，或附有跳过理由”），而不是含糊的界定（“理解代码”）或形容词（“彻底”）。
• 如果 Agent 为了进入后续步骤而匆忙完成某一步，就明确该步骤的标准。如果 Agent 仍然匆忙完成该步骤，就将这一步交给一个全新的子 Agent，并确保其上下文不包含后续步骤。

措辞

• 说明希望实现的行为，而不是要避免的行为。硬性约束使用禁止性措辞。
• 对同一概念始终使用同一个术语。优先使用含义与预期行为完全一致的成熟术语，例如 YAGNI 或 tracer bullet，而不是用句子重述其含义。定义自创术语。明确写出 Agent 必须检查的每项条件。

精简

• 每条规则只保留在一个地方，其他地方通过指针引用。
• 不要写下 Agent 通过一次查找就能找到的内容，例如脚本、配置、目录结构或 --help 输出。写下它无法查到的惯例、原因和易错之处。
• 如果某个句子与模型默认行为相比不会改变行为，就删除它。删除整个句子，不要只删改其中的词。先检查历史记录；为修复已观察到的失败而新增的规则，应予以保留，直到某次运行表明该失败已消失。
• 如果无法确定某个句子是否会改变行为，就进行测试。在全新会话中分别进行至少三次有该句子和无该句子的测试，不要透露测试目的。选择一个足以适用该句子的任务，然后比较 Agent 的行为。
• 删除过时或与文档任务无关的行。