tech-doc-writer skill 解析¶

tech-doc-writer 是一套面向工程文档写作、审查与改进的技术写作框架。它的核心设计思想是：高质量技术文档的目标是让目标读者在不找人追问的情况下独立完成理解、执行、排障、查阅或决策；因此写作过程必须先判断文档类型和读者目标，再决定结构、深度、验证方式、降级策略与维护机制，而不能把所有文档都当成同一种 markdown 输出。 因此它把仓库上下文扫描、文档类型与受众分类、质量评分卡、降级策略、结构化元数据、防陈旧机制和输出契约串成了一条固定流程。

1. 定义¶

tech-doc-writer 用于：

• 编写、审查、改进工程文档
• 覆盖概念文档、任务文档 / runbook、参考文档、故障排查文档、设计文档 / RFC / ADR 等不同类型
• 先按读者目标和受众能力决定结构与深度
• 用质量门禁约束元数据、结论前置、可执行性、回滚、术语一致性等关键质量项
• 在信息不足时按降级策略交付，而不是直接编造内容

它输出的不只是文档正文，还包括：

• 执行模式
• 降级级别
• 文档类型
• 受众
• 评分卡
• 涉及文件
• 维护建议
• 前提假设

从设计上看，它更像一个“技术文档治理框架”，而不是一个泛化的文档润色提示词。

2. 背景与问题¶

这个 skill 要解决的，不是“模型不会写技术文档”，而是技术文档任务天然容易出现几种高风险失真：

• 文档写得很完整，但目标读者并不能照着做
• 文档内容像知识堆砌，缺少明确类型和使用场景
• 文档短期可读，长期却很快过时

如果没有明确流程，常见问题通常集中在 8 类：

tech-doc-writer 的设计逻辑，就是先明确“这是一篇什么文档、给谁看、读者要完成什么任务、哪些事实必须验证、哪些信息缺口需要降级处理、这份文档以后什么时候必须更新”，再允许开始写作或评审。

3. 与常见替代方案的对比¶

先看它与几种常见做法的区别：

它的价值，不只是让文档“更会写”，而是把工程文档从一次性写作行为提升成可验证、可维护、可审查的交付流程。

4. 核心设计逻辑¶

4.1 把“仓库上下文扫描”放在最前面¶

tech-doc-writer 在真正写作前，先要求快速扫描：

• docs/
• CONTRIBUTING.md
• .markdownlint.json
• .vale.ini

这层设计很重要，因为技术文档不是独立作品，而是仓库的一部分。项目已有的写作规范、语气、目录组织、lint 规则，往往比 skill 默认规则更高优先级。skill 把这一点写成 1 号门禁，等于明确承认：文档一致性首先服务仓库，而不是服务某种抽象写作最佳实践。

评估里这一步没有形成显著 assertion 增量，但它仍然是重要的工程防线，因为它避免了“写得不错但不符合仓库习惯”的文档漂移。

4.2 先分类文档类型和受众 vs 直接开写¶

这个 skill 强制先确定：

• 文档类型
• 读者是谁
• 读者要完成什么
• 读者已经知道什么

并把常见文档分成：

• concept
• task
• reference
• troubleshooting
• design

这一步是整个 skill 的结构中轴，因为技术文档最常见的问题之一，不是内容不足，而是类型错位。比如：

• 任务文档缺少前置条件、预期输出、回滚路径
• 故障排查文档把根因埋在背景知识后面
• 设计文档只写“选择了什么”，不写“为什么不选别的”

评估也说明了这一点：with-skill 在 task / troubleshooting / review 三类场景里都能稳定套到正确模板，而 without-skill 的结构虽然不一定差，但更依赖即兴发挥，导致形式不稳定。

4.3 把“受众分析”单独做成强制门禁¶

tech-doc-writer 不只问“写什么文档”，还要求明确：

1. 谁是读者
2. 读者要做什么
3. 读者已知什么

如果受众混合，还要求使用漏斗式分层结构：

• 执行摘要
• 总览
• 技术细节
• 附录

这层设计很重要，因为很多工程文档的失败点，不在于事实错，而在于信息层次不对。对混合受众，如果直接把技术细节平铺，管理者抓不到结论，执行者又找不到细节入口。skill 通过漏斗式分层结构，把“不同读者在不同深度停下也能获得完整信息”变成了显式要求。

评估里“受众分析”没有形成可量化增量，但它仍是写作正确性的前提层，而不是可选装饰。

4.4 “质量评分卡”是整个 skill 的核心¶

这个 skill 的最大设计亮点之一，是把技术文档质量拆成：

• Critical
• Standard
• Hygiene

并按文档类型附加条件。

例如：

• 任务文档 / 故障排查文档必须有可复制命令和预期输出
• 所有文档都要有 owner、last_updated、status
• 任务文档必须有回滚路径 / 失败路径
• 故障排查文档必须有预防措施和监控阈值

这层设计非常关键，因为它把“文档看起来不错”和“文档真的可交付”区分开来。评估里明确点名的最大单项差异是 YAML 结构化元数据，而简洁收益准确标题、预期输出、回滚路径、输出契约等其他差异也都与这套质量门禁直接相关。说明这个 skill 的核心增量，不在于更会写 prose，而在于更会执行写作质量检查。

4.5 0 号门禁要强调“执行真实性”¶

tech-doc-writer 明确规定：

• 不验证就不能把命令、配置、参数写成仓库事实
• 没实际跑过就不能宣称命令可运行
• 不能确认的内容必须标成 <!-- UNVERIFIED: ... -->

这层设计非常务实，因为工程文档最危险的错误，不是句子不优雅，而是读者把未验证内容当成事实。skill 用 UNVERIFIED 标记，把“我不确定”显式化，避免文档在表面上显得权威却暗含幻觉性内容。评估里的 Go 代码示例对比也说明，基础模型本来就会写不错的代码，但 with-skill 多了一层未验证声明，这正是工程文档更需要的谨慎。

4.6 把“降级策略”设计成 1 / 2 / 2.5 / 3 四级¶

这个 skill 不要求在信息不足时硬写完整文档，而是要求根据情况降级：

• 1 级：完整交付
• 2 级：部分交付
• 2.5 级：主动检索
• 3 级：脚手架交付

其中最关键的是 2.5 级。它要求在降级成脚手架交付之前，必须先做一轮主动检索，看仓库里是否能补齐事实。

这层设计很成熟，因为技术文档写作里最难处理的问题，不是“完全没信息”，而是“信息缺口可能在仓库里，只是还没找出来”。2.5 级把主动检索固定成一道门，能显著减少过早降级，也减少直接编造。即使这条路径在本次评估里没有充分触发，它仍然是这个 skill 区别于普通写作提示词的重要设计。

4.7 坚持“结论前置”¶

这个 skill 在所有文档类型上都强调：

• 核心结论放在第一段
• troubleshooting 尤其要把 root cause 放前面

这层设计非常关键，因为工程文档的读者通常带着明确任务进来，不是来做沉浸式阅读。结论埋得太深，会直接增加搜索和定位成本。评估里的 deadlock troubleshooting 场景就是最清晰的例子：with-skill 一开始就给出 root cause；without-skill 则先解释 deadlock 背景，再逐步展开。两篇都能读懂，但读者到达结论的路径差异很大。

4.8 把 Task / Troubleshooting 的“可执行性”做得这么硬¶

tech-doc-writer 对 task 和 troubleshooting 文档的要求非常明确：

• 命令必须可复制执行
• 每个关键步骤必须有 expected output
• 必须有 verification
• task 文档必须有 rollback trigger 和 rollback steps

这层设计的意义在于，把工程文档从“描述性说明”变成“可操作 runbook”。没有 expected output，读者即使跑了命令也不知道是否成功；没有 rollback，读者在故障时无从退回；没有 verification，文档只能指挥动作，不能确认结果。评估里这些点正是 without-skill 最容易漏掉的地方。

4.9 “简洁-收益-准确”标题规则会被纳入门禁¶

skill 明确要求标题遵循“简洁-收益-准确”规则：

• 简洁
• 收益明确
• 准确

这看起来像写作细节，实际上是检索与维护问题。工程文档的标题如果只是：

• Notes
• Guide
• Documentation

几乎无法支持后续查找和复用。“简洁-收益-准确”标题规则让标题天然具备：

• 关键词命中能力
• 读者收益提示
• 范围边界

评估里这也是 skill-only 差异之一：with-skill 的标题更短、更具体、更便于检索；without-skill 更容易泛化或过长。

4.10 要求“结构化元数据”和 applicable_versions¶

这个 skill 要求所有文档都带：

• title
• owner
• status
• last_updated
• applicable_versions

这层设计很关键，因为技术文档会陈旧，而陈旧文档比没有文档更危险。owner 决定谁负责，status 决定当前是否可用，last_updated 决定时效，applicable_versions 决定读者是否能安全套用当前内容。评估里结构化元数据是最稳定的优势项，也说明这是最容易被默认写作忽略、但对文档治理最重要的一层。

4.11 Review 模式强调 severity、before/after 和正面反馈¶

在 Review 模式下，tech-doc-writer 不满足于指出问题，而要求：

• findings 按 Critical / Major / Minor 分组
• 给出 concrete before/after fixes
• 指出哪些部分已经做对

Improve 模式本身则更强调最小差异修改与保留原作者有效结构；正面反馈更多来自评审模式的协作要求。整体上，这层设计很成熟，因为文档评审不是为了证明审查者更懂，而是为了让作者知道下一步怎么改。只有问题描述，没有修改前 / 修改后示例，往往还是要二次沟通；只有负面评价，没有肯定，协作体验会很差。评估里的评审场景也说明，两边的问题发现能力接近，但 with-skill 在结构化反馈和可执行性上更强。

4.12 把“防陈旧机制”单独做成维护机制¶

tech-doc-writer 明确规定文档必须声明：

• 什么时候必须更新
• 推荐复查频率
• 状态如何从 active 演化到 needs-update 或 deprecated

并列出典型触发条件：

1. 命令、配置、参数变化
2. 版本升级导致默认行为变化
3. incident handling / on-call routing 变化
4. 读者按文档操作却失败

这层设计非常有治理价值，因为大多数文档不是一开始就烂，而是后来过期。skill 把维护触发条件写进文档生产流程，等于把“文档会过期”从隐性常识变成显式 contract。

4.13 references 要按类型选择性加载¶

这个 skill 的 references 不是一口气全读，而是按场景取用：

• templates.md 按文档类型只读对应模板
• writing-quality-guide.md 按 funnel、BAD/GOOD examples、code examples、review patterns、anti-examples、visual expression 分段加载
• docs-as-code.md 只在 CI / PR / 自动生成等基础设施场景下加载

这种设计很合理，因为技术文档覆盖面非常广，不同类型的高质量标准并不相同。通过 selective loading，skill 把高频通用规则留在 SKILL.md，把低频专项规则放进 references，兼顾了能力覆盖和 token 成本。

5. 这个设计解决了哪些具体问题¶

结合当前 SKILL.md、关键 references 和评估报告，可以把它解决的问题归纳为：

6. 主要亮点¶

6.1 它把技术文档写作变成读者任务驱动的流程¶

不是先决定写什么，而是先决定读者要完成什么，再反推文档形态。

6.2 文档类型分类是最显著的结构亮点之一¶

task、troubleshooting、design、reference、concept 的边界被明确写进流程后，文档更不容易写错形。

6.3 质量评分卡是当前版本最大的实际增量来源¶

评估已经说明，元数据、结论前置、简洁收益准确标题、预期输出、回滚路径等差距，主要都来自这套质量门禁。

6.4 它对“不确定信息”的处理非常工程化¶

UNVERIFIED 标记和分级降级策略，让文档在事实不足时仍能诚实交付，而不是假装完整。

6.5 防陈旧机制很有治理价值¶

很多文档工具只关注“怎么写”，tech-doc-writer 还把“什么时候必须更新”纳入 contract，这让文档更接近可维护资产。

6.6 当前版本的真正增量，在文档治理而不在基础写作能力¶

评估已经说明：基础模型本来就能写出结构不错的工程文档，也能给出不错的代码示例和 troubleshooting 分析；真正的差距在 metadata、type routing、conclusion-first、expected output、rollback、structured review 和 maintenance rules。这说明 tech-doc-writer 的核心价值是技术文档治理，而不是单纯“文笔更好”。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

tech-doc-writer 的真正亮点，不是它能把技术文档写得更像标准答案，而是它把工程文档里最容易失真的判断系统化了：先判定文档类型和受众，再决定结构，再用质量门禁检查结论前置、可执行性、元数据与术语一致性，在信息不足时明确降级，在交付时附上结构化输出，并为未来维护留下触发条件。

从设计上看，这个 skill 很清楚地体现了一条原则：高质量技术文档的关键，不是信息写得越多越好，而是让目标读者更快找到结论、知道如何执行、知道怎样验证、知道出错时怎么回退，并且让团队清楚这份文档什么时候必须被更新。 这也是它特别适合工程团队的 runbook、troubleshooting、API docs、设计文档和文档 review 场景的原因。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/tech-doc-writer/SKILL.md 中的执行模式、强制门禁、质量评分卡、降级策略、输出契约、语言规则或防陈旧机制发生变化。
• skills/tech-doc-writer/references/templates.md、writing-quality-guide.md 或 docs-as-code.md 中的关键模板、质量规则或文档工程实践发生变化。
• evaluate/tech-doc-writer-skill-eval-report.md 或 evaluate/tech-doc-writer-skill-eval-report.zh-CN.md 中支撑本文判断的核心结果发生变化。

建议按季度复查一次；如果 tech-doc-writer 的文档类型路由、质量评分卡、降级策略、元数据规则或防陈旧机制有明显重构，则应立即复查。

10. 相关阅读¶

• skills/tech-doc-writer/SKILL.md
• skills/tech-doc-writer/references/templates.md
• skills/tech-doc-writer/references/writing-quality-guide.md
• skills/tech-doc-writer/references/docs-as-code.md
• evaluate/tech-doc-writer-skill-eval-report.md
• evaluate/tech-doc-writer-skill-eval-report.zh-CN.md