---
name: writing-for-agents
description: 写、改或审查给 agent 读的文档时使用：skill、AGENTS.md、术语表与项目文档。
---

# 给 agent 写文档

适用于一切会被 agent 读到的文档。目标是让每次运行走同样的过程，用最少的字。

## 唯一检验

每句话都要回答：删掉它，当前模型的行为会不会变差？不会就是无操作，整句删掉，不只删几个字。有分歧时跑一次文档看结果，不靠争论。

常见的无操作：

- 模型默认就会做的步骤：理解需求、自查、"要彻底"。
- 为旧模型写的验证与复查指令。Opus 5 起模型会自行验证，这类指令只造成过度验证；删掉，不改写。
- 全大写和"必须""务必"式强调。新模型对系统提示更敏感，强调会让它过度触发；写成平实的"在……时做……"。

## 写什么

- **环境是事实源**：脚本、配置、目录结构、`--help` 查得到的不重述。文档只缓存查不到的：未写明的约定、某个选择的理由、配置没承认的坑。
- **单一事实源**：同一含义只有一个权威位置；发现第二份就合并，不维护两处同步。
- **越短越正确**：每次改动顺手删掉失效、过时或已被别处覆盖的内容。不删的结局是层层沉积，有效内容被埋在过时内容下面。

## 指针

AGENTS.md 里指向某份文件的一行、skill 的 description，都是指针：说明材料是什么，以及什么情形去读。

- 触发词放最前；每种情形只留一个触发词，同义改写合并掉。
- 该读的材料没被读到，先加强指针措辞、写清触发情形（"等合并与发布只用 `make land`"），加强无效才把内容内联。
- 指针每轮都在上下文里，比正文裁剪得更狠；正文已说明的身份信息不在指针里重复。

AGENTS.md 是地图：命令入口、代码看不出的约束、"遇到某种情形去读某份文件"的条件指针。架构概述、目录树、`rg` 一下就能找到的东西不写。

## 结构

文档由两种内容组成：agent 按顺序做的**步骤**，和按需查的**参考**。

- 每条路径都用到的内容写在正文；只有部分情形用到的移到单独文件，正文留指针。步骤被参考资料埋住时，agent 注意不注意到全看运气。
- 同一概念的定义、规则、注意事项放在同一标题下，不散在各处。
- 每个步骤以**完成标准**结尾：可检查（分得清做完没做完），且要求穷尽（"每个被改的调用点都已核对"，而不是"列出改动"）。标准含糊，agent 会提前收工。

## 措辞

- 写目标行为（"写单行注释"），不写笼统禁令（"别啰嗦"）：禁令会把被禁的东西带进上下文。硬性护栏才直接禁止。
- 观察到具体失败模式时逐项点名（"奶油色背景、标题里的斜体强调词、01/02/03 编号标签"），同时写出要什么。
- 用模型预训练里已有的常用词（tracer bullet、expand–contract），不自造术语。自造词要花字定义，还会被 agent 带进给用户的回复，变成用户看不懂的黑话。

## 术语表 WORDS.md

项目术语表只收代码看不出的约束，一条一行：

```md
- **桌仔**（Guide）→ `guide`；避免：主持
```

- 只收两种：带「避免」的（这个概念在本项目叫什么、不能叫什么，含改名后退役的旧名），和易混概念的一句区分（会话 vs 分段）。只有「词 → 模块」映射的不收：搜代码就能找到。
- 业务规则写进所属模块的头注释，不进术语表。
- "避免"项能做成禁词检查的，做成 lint 后从表里删掉。

## Skill

- description 每轮常驻上下文，按「指针」写；模型需要自己发现时才开放自动触发。
- 只靠手动命令或其他 skill 明确指向的，加 `disable-model-invocation: true`，它就不进自动列表；登记到 skill 库 `AGENTS.md` 的手动表。
- 正文超过 500 行就按情形拆出参考文件，引用只走一层。