write-docs

write-docs

选择要编写的文档，阅读对应文件，然后开始写作。不要加载多个文件——不同文档的规范各不相同，混用会让文档对所有人都毫无帮助。

编写内容……	阅读	服务的读者
面向公众的库、CLI 或 Agent 工具的 README	READMES.md	需要在 30 秒内决定是否使用它的人
开发者指南、教程、运行手册、迁移指南或弃用说明	GUIDES.md	希望完成任务、不想靠猜的人
CLI 标志、子命令、--help、错误文本、输出约定	CLI.md	在提示符下输入命令的人，以及封装这些命令的脚本
代码注释、文档字符串、行内说明	COMMENTS.md	在故障期间阅读这些内容的维护者
AGENTS.md / CLAUDE.md 操作指南	AGENTSMD.md	对项目毫无记忆的 Agent
提交消息、PR 描述、变更日志条目	PR.md	两年后运行 git log 的维护者

本技能不适用于：博客文章和随笔（使用 blog-review）、设计文档、ADR（使用 grill-me）、内部服务维基，或编写技能（使用 write-skill）。

工作流

1. 阅读能够确认事实的实现、架构、测试、--help 或差异。
2. 明确读者是谁，以及文档必须帮助读者完成什么操作。
3. 为每个反复出现的概念选定一个规范术语。保留准确的 API 名称和标识符。
4. 根据所选文档类型的视角起草。
5. 检查每项说法、命令、注意事项和边界是否仍与来源一致。
6. 应用下方的清晰度模式，然后运行检查器。将启发式检查结果视为问题，而非自动修改建议。

清晰度模式

• 严格 — 适用于操作流程、安全规则、Agent 工作流、CLI 帮助和恢复说明。也适用于读者无法追问的所有文本：工具和函数说明、错误消息，以及供其他 Agent 或脚本解析的输出。把条件写在命令之前。使用祈使句，一步一项操作，使用直接动词和简单时态，每句话不超过 20 个词。
• 自然 — 适用于 README 叙述、解释、注释和 PR 理由。保持术语和行动者清晰，但允许使用缩略形式、分号、不同的句子节奏，以及在行动者未知或无关时使用被动语态。

根据内容块应用模式。README 快速入门部分可以采用严格模式，而动机说明可以采用自然模式。

通用规则

• 从读者的目标和最短路径开始。背景和历史放在后面，或省略。
• 写得真诚。像维护者帮助读者那样写，而不是模仿自信口吻的产品说明。
• 用证据代替质量形容词。给出支撑说法的测量值、示例或边界。
• 一件事只用一个名称。除非同义词指代不同概念，否则不要轮换使用。
• 在句子的前八个词内写明行动者和动作。抽象名词作主语（the configuration of、the handling of）会掩盖行动者：让行动者作主语，让动作作谓语。
• 每句话表达一个想法。以读者已知的内容开头，以新名称或新值收尾；这比主动语态更重要。超过十个词的条件应另写成一步。
• 拆分由四个或更多词组成的名词堆叠：“calibration of the connection resistance”，而不是“connection resistance calibration procedure”。
• 每项事实只说一次。省略不会改变读者下一步行动的模板章节。
• 删去用于宣布或安抚的词语：This document describes、simply、obviously。读者会默认强化语气词所暗示的反面；步骤失败时，simply 会让他们觉得是自己的问题。
• 流程中的含糊语气意味着缺少条件：写成 if X, do Y，而不是 you may need to do Y。解释中，一个含糊语气词可以表达不确定性；一句话中出现两个，则会掩盖不确定之处。
• 说明不支持的情况和权衡。简化措辞时不得抹去精确的技术含义。

检查草稿

python3 scripts/prose_lint.py --mode strict <path>
python3 scripts/prose_lint.py --mode natural <path>

使用 - 表示标准输入，使用 --json 输出结构化检查结果。退出码为 1 表示严格错误；仅供审阅的检查结果返回 0。添加 `` 可忽略一行。检查器无法在缺少项目上下文的情况下检测同义词轮换，因此请手动检查术语。这不是 STE 认证，也不能替代事实审查。关于理由和来源，请参阅 CLARITY-REFERENCE.md。

重写现有文档

• 在调整文档结构前，先搜索测试和 CI 中是否有从文档固定下来的字符串。如果测试固定了措辞，请将断言改为检查要求（顺序、是否包含链接），而不是精确文本。在 PR 中注明更改的断言。
• 找出基于该文档衍生的副本：软件包 README、文档网站、译文。更新这些副本，或说明它们不在本次处理范围内。

审阅而非撰写

采用相同的视角，但方向相反：根据源文档核验目标文档，然后指出目标读者无法做什么、无法信任什么，或必须反复阅读什么。先说明缺陷及其位置，而不是先夸奖。