用途:当需要撰写、起草、审阅或改进技术文档时使用,包括 RFC、设计文档、ADR、运维手册(runbook)、事后复盘(postmortem)、单页提案(one-pager)、公告、PR 描述和异步消息。核心原则是面向略读的读者:把结论前置,删去不影响决策的内容。
主要能力:用三条法则指导写作。法则一,先给结论,第一句即结论、建议或请求,读者只看一句也应知道你要什么。法则二,写得比你以为的更少,砍掉不改变决策的上下文。法则三,深度匹配受众规模:给团队发 Slack 一句话,给 3 至 5 人评审的 ADR 展开权衡,面向全公司则要 30 秒可扫读。
使用方式:先分类文档类型、目的、受众与长度;用户提供模板时严格保留其结构,并在各节内应用三法则。随后填写受众简报,明确读者角色、已有知识、要做的决策、后续动作和注意力预算;再写出能独立成句的关键句,作为标题、TL;DR 或主题前缀;接着按对应模板起草,RFC 需含 TL;DR、背景、目标与非目标、方案、备选方案(第一个必须是“什么都不做”)、跨领域关注点、风险与缓解、开放问题;ADR 含背景、决策、后果;运维手册强调“最后验证时间”;复盘强调可验证、有负责人和截止日的行动项。最后做检查:首句测试、所以呢测试、陌生人测试、压缩测试和决策测试。
适用场景与限制:适用于工程团队的文档写作与评审。资料指出,若文档没有真实的备选方案和权衡,应改写 ADR;2 至 3 人且无争议的事应改为对话,不要写文档;模板只是起点,需按组织适配。资料未提供该技能的安装命令、运行环境、平台支持和收费信息。