Tech Doc Writer — 项目技术文档完整写作体系
> 版本：v2（完全版）
> 前置条件： 本 Skill 需要读取目标项目的源码目录（至少 README + 核心模块文件）才能执行源码映射。
> 参考案例： references/案例-DAA技术方案设计文档-v4.md（191KB 完整实战文档）
一、核心方法论：五步写作工作流
技术文档写作不是"打开编辑器→填模板"的填空游戏，而是一个从信息采集到质量门禁的完整工程流程。以下五步每一步都有明确的输入、输出和检查点。
第一步：信息采集（Input → 素材库）
目标：收集所有必需的信息材料，确保写作时不"无米下炊"。
必采集项：
1. 项目元信息：一句话定义、项目边界（In scope / Out of scope）、关键量化目标
2. 源码目录树：tree /F 目录结构，识别核心模块
3. 核心源码：README + 至少 5 个核心模块的源代码
4. 架构草图：如果已有架构图/部署图，收集；否则准备画
5. 已知问题列表：BUG 列表、TODO、已知决策争议点
6. 同类/竞品分析：同类系统的技术方案（如有）
输出：一份 素材清单.md，标注已获取/未获取
检查点：核心源码未读 → 不能进入第二步（否则必然写出无源结论）
第二步：结构规划（素材库 → 大纲骨架）
目标：根据文档类型和深度级别，确定目录结构和每章的写作重点。
输出：数字序号目录（至少到 ## 级别，建议到 ###）
检查点：目录必须覆盖 What-Why-How 三要素，缺任一要素则返回补充。
第三步：初稿生成（大纲骨架 → 提纲式初稿）
目标：按照大纲快速输出第一版，重点是覆盖所有章节，不纠结细节深度。
写作原则：
- 先写 What/Why（背景、目标、架构决策），再写 How（详细设计）
- 每个设计决策：先用一句话说明"是什么"，然后解释"为什么这么选"
- 方案对比处留标 [TODO] 待补充
输出：提纲式初稿（允许 bullet list，允许 TODO 标记）
检查点：每章至少有 3 句实质内容，无空白章节即可进入下一步。
第四步：深度重写（提纲 → 段落化深度版本）
核心方法论：源码→设计映射
这是本 Skill 区别于普通模板的核心竞争力。提纲到段落的转换不是简单的"把 bullet 改成句子"，而是一次设计与源码的双向验证：
- 抓源码：找到该设计决策对应的源代码文件和方法
- 验证参数：从源码中确认参数名、阈值、算法名称，确保不编造
- 找对立面：思考"如果不这样做，还可以怎么做？为什么没选？"
- 写段落：把"设计决策 ↔ 源码 ↔ 对立方案 ↔ 代价"写成连贯 prose
示例（从提纲到段落）：
> 提纲版：AntiFabricationDetector 用 4 种正则匹配检测编造数值
> 段落版：AntiFabricationDetector 的数值溯源验证不是靠 LLM "判断"数值是否合理——LLM 无法可靠地判断"0.9999 是否为已计算出的准确值"——而是靠四类正则模式匹配来检测数值表述中的溯源缺失。PERCENTAGE_NO_SOURCE 模式匹配带百分号但未标注来源的字段；RANGE_WITHOUT_CITATION 检测数据范围描述；ABSOLUTE_UNVERIFIED 捕获自称的绝对数值；COMPARATIVE_UNVERIFIED 检测"显著高于"等比较性断言。源码见 app/core/quality/anti_fabrication.py 的 verify_statements() 方法。选择正则而非 LLM 判断的原因是：LLM 审查时间成本高（每轮 ~3-5 秒）且准确率不稳定，而正则匹配在 10ms 内完成，零假阴性。
输出：段落化版本，每段 ~200-500 字
第五步：质量门禁（草案 → 终稿）
四层门禁顺序执行：
Layer 1: 结构完整性
├── 有目录 + 数字序号
├── 所有 ## 章节有内容
├── What-Why-How 三要素覆盖
└── 有方案对比（≥2 方案）
Layer 2: 内容真实性
├── 无编造数值/指标（所有数据有来源或计算依据）
├── 无"模板填充"空洞句子
├── 写明了 trade-offs（不能只写好处）
└── 写明了验证方式
Layer 3: 防深度偷懒
├── 核心设计决策有源码→设计映射
├── 参数、阈值、算法名称可追溯到源码
└── 每章 ≥3 段连贯 prose（非 bullet list）
Layer 4: 整体检视
├── 从头到尾通读一遍，检查逻辑连贯性
├── 无矛盾表述
├── 受众匹配
└── Mermaid 图渲染正确
二、三级写作模式
| 级别 | 适用场景 | 核心产出 | 预估长度 | 耗时 |
|---|---|---|---|---|
| L1 快速输出 | 内部备忘、技术讨论 | 提纲式初稿 + 核心决策说明 | 2-5K 字 | ~15min |
| L2 标准文档 | 技术评审、跨团队协作 | 标准模板 + 方案对比 + Mermaid | 10-30K 字 | ~1-2h |
| L3 深度源码级 | 架构复审、新人入职、长期维护 | 段落化深度 + 源码映射 + ADR + 质量门禁全通 | 30-200K 字 | ~3-8h |
三、五种文档模板
3.1 ADR（架构决策记录）
# ADR-{序号}: {决策标题}
## 状态 [Proposed | Accepted | Deprecated | Superseded]
## 背景 — 问题、触发原因、约束条件
## 考虑的方案 — 方案 A/B/C（选 X 不选 Y 的理由）
## 决策 — 逐条对照约束条件
## 影响 — 正面 + 负面影响（必须写）
## 一致性 — 如何确保执行和验证
L3 额外要求：背景含量化数据、方案对比含淘汰根因、影响含可验证预期结果和事后验证状态。
参考案例：v4 文档第 7 章 ADR-001 至 ADR-007
3.2 技术方案设计文档
核心结构：
1. 背景与目标 — What & Why
2. Why 是这个架构（L3 专有：路线探索与淘汰 + 核心决策深度展开 + 已不采用方向）
3. 系统架构 — How 宏观（部署/分层/模块目录）
4. 核心子系统详解 — How 微观（每个子系统：定义→为什么→源码映射→交互）
5. 跨模块联动（L3 专有）
6. 关键问题与权衡决策记录
7. 部署/测试/演进规划
3.3 架构设计文档
需求→5W1H8C→总体方案→架构纵览→核心流程→详细设计→演进规划→质量保障。增强点：技术选型 ≥3 方案对比、架构演进路线图、推翻条件。
3.4 API 设计文档
接口列表→接口详情→变更管理（版本策略、向后兼容、废弃策略）→错误码含场景示例。
3.5 迁移/升级指南
背景→影响范围→方案对比→迁移步骤→回滚决策树→灰度策略→监控。新增破坏性变更清单 + 新老版本共存互操作策略。
四、反模式清单（实战提炼）
| 反模式 | 现象 | 根因 | 防护 |
|---|---|---|---|
| 编造数值 | 写"评分 0.9999"但源码无此逻辑 | LLM 无源码锚定的"合理推测" | Layer 2 + 每个数值标注来源 |
| 无源结论 | "并发度=3"但不说明为什么是 3 | 只记结论不记决策过程 | 每个参数说明"为什么是这个值" |
| 提纲化偷懒 | 整章全部 bullet list | 初稿和终稿不分 | Layer 3: 每章 ≥3 段 prose |
| 选中不选反 | 只写为什么选 A，不写为什么不选 B/C | 默认读者也做了对比 | 要求每个方案标注淘汰根因 |
| 忘记代价 | 只写好处不写 trade-off | 护犊心理 | ADR 模板强制"负面影响"节 |
| 代码注释当文档 | 文档复制代码注释 | 受众混淆 | 文档回答"为什么"，注释回答"什么" |
五、预编译写作引导 Prompt
5.1 L2 标准文档写作 Prompt
请按照 tech-doc-writer Skill 的 {文档类型} 模板写一份技术方案设计文档。
目标项目：{项目名}。深度级别：L2。
已收集素材：{素材清单}
要求：
1. Markdown 格式，数字序号目录
2. 每个 ## 章节至少 3 个句子
3. 核心技术选型包含 ≥2 个方案对比
4. 每个方案写代价（trade-off）
5. 关键流程画 Mermaid 图
6. 无编造数值——所有指标需有来源或标注 [需确认]
请先输出目录结构让我确认，再写正文。
5.2 L3 深度重写 Prompt
请将以下提纲段落升级为 L3 深度版本。
提纲原文：{提纲段落}
要求：200-500 字连贯 prose；每个设计决策锚定到源文件和方法；
说明为什么不选对立方案；参数/阈值/算法名称从源码验证；写明 trade-offs。
可用源码：{源码映射表}
5.3 四层质量检查 Prompt
请对以下文档执行四层质量门禁检查：
Layer 1（结构完整性）：目录？所有 ## 有内容？What-Why-How？≥2 方案？
Layer 2（内容真实性）：无编造？无空洞句？有 trade-offs？有验证？
Layer 3（防偷懒）：核心设计有源码映射？参数有源？每章 ≥3 段 prose？
Layer 4（整体检视）：逻辑连贯？受众匹配？Mermaid 渲染正确？
最终判断：[通过 / 退回至第 X 步]
六、质量自检清单
结构层：[ ] 有目录+数字序号 [ ] 所有 ## 有实质内容 [ ] What-Why-How 覆盖 [ ] 核心章节段落式
内容层：[ ] ≥2 方案对比 [ ] 每个写代价 [ ] Mermaid 图 [ ] 验证方式 [ ] 边界异常处理 [ ] 数据有源
源码映射（L3 必检）：[ ] 核心决策有源码映射 [ ] 参数/阈值可追溯 [ ] 含淘汰原因
排版层：[ ] 中英数空格 [ ] 全角标点 [ ] 专业名词首字母大写 [ ] 代码块标语言 [ ] 超 5 行拆分
七、排版规范
- 中文与英文/数字之间加空格；全角中文标点；技术名词首字母大写
- 代码块标明语言；正文超 5 行必须拆分
- 面向开发→专业术语；技术评审→方案对比权衡分析；非技术→类比说明
八、参考来源
- Michael Nygard — ADR 原创格式
- MADR — 社区标准 ADR 模板
- 腾讯云开发者社区 — 技术文档写作指南（2024）
- 极客时间 — 架构设计文档模板（5W1H8C 框架）
- 知乎 — 技术方案设计模板
- CSDN — 技术方案文档结构化指南
- DataAnalysisAgent 技术方案设计文档 v4 →
references/案例-DAA技术方案设计文档-v4.md - 《金字塔原理》— 结构化写作
- 《一本小小的红色写作书》— 简洁清晰写作
⚠️ Gotchas
- L1/L2 不要强行源码映射 — 源码映射只在 L3 做，L1 不需要
- 别把 ADR 当技术方案的整体格式 — ADR 只记录一个具体决策，技术方案需要完整 What-Why-How
- 子 Agent 写文件必须指定 encoding='utf-8' — 中文 Windows 默认 GBK 会导致乱码
- Mermaid 图只在渲染环境可用 — 如果无法渲染就用 ASCII 图代替
- 不要编造阈值 — "并发度设为 3"必须从源码确认，不能猜
