技能介绍

技术文档为什么难写

团队常见的景象是：架构决策散落在聊天记录和会议纪要里，半年后没人说得清当初为什么选 A 不选 B；文档里写着 并发度 = 3，源码里却找不到出处；整章全是 bullet list，新人读完依然不知道系统怎么跑起来的。技术文档的失败往往不是文笔问题，而是写作过程缺少工程约束——没有素材采集、没有源码锚定、没有质量门禁，写作者只能靠"合理推测"填坑。

这套体系如何工作

该技能把文档写作拆成五步工作流，每一步都有明确的输入、输出和检查点：

信息采集：先收集项目元信息、源码目录树、核心模块源码与已知问题列表，产出一份素材清单；核心源码未读，不允许进入下一步
结构规划：按文档类型确定目录骨架，检查点要求覆盖 What-Why-How 三要素
初稿生成：先写背景与目标，再写详细设计，方案对比处允许留 [TODO] 标记
深度重写：这是核心步骤——把提纲转成段落时做"设计决策 ↔ 源码 ↔ 对立方案 ↔ 代价"的双向验证，每个参数和阈值必须能追溯到源码，而不是靠推测
质量门禁：结构、内容、源码映射、排版四层检查依次执行

三级模式对应不同场景：L1 快速提纲（2-5K 字）、L2 标准文档（含 Mermaid 图与方案对比）、L3 源码级深度文档（含 ADR、跨模块联动与完整质量门禁）。内置五种模板：ADR、技术方案设计、架构设计、API 设计、迁移升级指南。

适用边界与注意点

源码映射只在 L3 做，L1 快速输出不要强行挂源码。ADR 只记录单个决策，不能当成整份技术方案的格式。最常踩的坑是编造数值——文档里写"评分 0.9999"而源码无此逻辑，因此每个数字都必须标注来源。另外，子 Agent 写文件要指定 encoding='utf-8'，中文 Windows 默认 GBK 会乱码；Mermaid 图在无法渲染的环境用 ASCII 图代替。