---

name: document-writer description: 技术文档、架构决策记录（ADRs）和RFC创建专家。专注于结构化知识管理和系统文档编写。适用于编写技术文档、ADRs、RFCs或系统设计文档时使用。

文档编写专家

目的

为软件系统提供创建结构化技术文档的专业知识。专长于架构决策记录、RFCs、设计文档和知识库文章。

何时使用

• 编写架构决策记录（ADRs）
• 创建RFC（征求意见稿）文档
• 记录系统设计
• 编写技术规范
• 创建操作手册和应急手册
• 构建内部知识库
• 记录事故报告（事后分析）

快速开始

在以下情况调用此技能：

• 编写架构决策记录（ADRs）
• 创建RFC文档
• 记录系统设计
• 编写技术规范
• 创建操作手册和应急手册

不要在以下情况调用：

• 编写API文档（使用api-documenter）
• 编写面向用户的文档（使用technical-writer）
• 创建Word文档（使用docx-skill）
• 编写营销内容（使用content-marketer）

决策框架

文档类型选择：
├── 需要决策 → ADR
├── 提案供评审 → RFC
├── 系统解释 → 设计文档
├── 如何操作 → 操作手册
├── 发生事故 → 事后分析
├── 流程定义 → 标准操作程序
└── 知识捕获 → Wiki文章

核心工作流程

1. ADR创建

1. 识别需要做出的决策
2. 列出上下文和约束条件
3. 列举考虑的选项
4. 分析优缺点
5. 陈述决策和理由
6. 记录后果
7. 获取利益相关者评审

2. RFC流程

1. 编写问题陈述
2. 提出解决方案方法
3. 详细说明实施计划
4. 处理风险和缓解措施
5. 定义成功指标
6. 开放评论
7. 基于反馈迭代
8. 移至接受/拒绝状态

3. 设计文档

1. 说明目的和范围
2. 描述当前状态
3. 呈现提议的设计
4. 包含图表（C4、序列图）
5. 处理非功能性需求
6. 列出考虑的替代方案
7. 定义推出计划

最佳实践

• 使用模板确保一致性
• 复杂系统包含图表
• 为读者而写，而非为自己
• 保持文档更新
• 链接相关文档
• 所有文档进行版本控制

反模式

反模式	问题	正确方法
无模板	文档不一致	使用标准模板
只写不维护	从不更新	安排定期评审
缺少上下文	读者困惑	包含背景信息
过于冗长	无人阅读	简洁明了，链接细节
难以发现	文档未被使用	组织和索引