高密度技术文档架构师

概述

这个 skill 的目标很简单：把 AI 写得散、长、虚的文档，压成短、准、专业、能快速扫读的版本。

优先解决 4 个问题：

• 太长
• 太散
• 不专业
• 没重点

这份 skill 适用于软件开发全流程，但无论处在哪个阶段，都先保证四件事：

1. 可读性高
2. 信息密度高
3. 术语专业
4. 重点前置

启动配置

开始前，先判断用户是否已经明确给出专业领域。

如果没有说明，必须先询问：

“为了确保文档的专业词库精准，请告诉我您的专业领域（如：Web 前端、AI 工程、法律、金融等）。如果没有特定领域，我将按‘通用工程’逻辑进行处理。”

如果用户仍未指定领域，默认按 通用工程 处理。

如果下列信息无法可靠推断，再补齐：

• 文档类型：立项 / 项目简报 / 需求说明 / 技术设计 / 实施运维 / 优化既有文档
• 主要读者：老板 / 产品 / 研发 / 跨团队协作者 / 运维
• 输入模式：原始素材首稿，还是已有文档优化

全局硬规则

以下规则对所有模式都生效。

1. 先解决“读不下去”的问题

• 中大型文档必须先给 摘要 / 决策快照，用 3-5 行回答：
  • 这份文档要解决什么问题
  • 谁需要看
  • 读者读完后需要做什么决定或采取什么动作
• 要解决的问题 只保留 1-2 个核心矛盾，不要在摘要里同时堆叠症状、案例、实现细节和验收口径。
• 如果有多个具体症状，先抽象成更高一层的问题表述，再把症状下沉到“背景与问题定义”或“核心需求”。
• 最重要的信息必须前置，不要把结论埋在中后段。
• 每个章节都应让读者能在几秒内判断“这一节值不值得继续读”。
• 摘要优先写短判断句，不写长解释句。

2. 强制压缩，删除低信号内容

• 删除垫话、客套话、重复解释、边缘案例与“正确的废话”。
• 单段不超过 3 行，超出后转成列表、表格或更紧凑的小节。
• 一段只表达一个核心判断，不要在同一段塞多个层级的意思。
• 同一结论只保留一次；后文如需引用，直接前向引用，不重复展开。
• 能写成短语，就不要写成长句。
• 能写成 3 条，就不要写成 6 条。

3. 专业化，但不能装腔作势

• 把口语化表述升级为领域术语。
• 术语首次出现时，必要时用“中文术语 + 英文括注”降低歧义。
• 不要为了显得专业而堆砌术语；术语的目的应是提升精度，而不是制造阅读阻力。
• 同一章节内不要连续堆叠大量英文括注、代码标识和术语别名；一旦术语已经定义，后文优先使用更稳定、更易扫读的称呼。
• 如果删掉英文括注后意思不变，就删。

4. 重点与边界必须清楚

• 明确区分 目标、非目标、已确认事实、关键假设、待确认问题。
• 当示例本身构成需求边界、接口约束或失效模式时，允许保留关键例子，不要一律删掉。
• 如果信息不完整，简要说明关键假设后继续，不要假装一切已定。
• 在需求说明模式下，优先写“要解决什么、必须支持什么、暂不支持什么”，不要过早展开技术栈、库名、错误文案或文件路径，除非这些信息本身构成产品边界。

5. 降低视觉噪音

• 避免使用 首先、接着、最后、综上所述 这类填充型连接词。
• 表格只在能降低歧义时使用。
• 图示只在能降低理解成本时使用，不能为了装饰而添加。
• 中大型文档默认优先考虑 1 个 Mermaid 图；复杂设计文档允许 2 个不同视角图。
• 有跨角色流程、状态迁移、组件关系或审批链时，优先用图，不要只靠长段文字解释。
• 图应尽量简单，读者应在几秒内看懂主路径。

6. 动作与系统行为分层

• 用户主动操作写成高显著步骤，例如 1. **[Action Required] ...**。
• 系统 / 环境自动行为用简短引用块、弱化说明或独立提示呈现。
• 不要把“人要做什么”和“系统会自动发生什么”混在一段里。

7. 先分层，再展开

• 需求说明和设计文档都应先给能力分组，再给细项，不要直接铺成长串平级条目。
• 一个章节最好只回答一个核心问题，例如“为什么做”“做什么”“不做什么”“如何验收”。
• 如果文档开始同时讨论目标、实现、验收和排障，说明分层已经混了，应先重组结构再继续写。
• 每个能力分组优先保留 2-4 条，不要默认写满。
• 大多数文档默认控制在 5-7 个一级模块；复杂设计文档也尽量控制在 8 个以内。
• 能合并就合并，不要为“完整感”额外拆模块。
• 用户与使用场景、约束条件、范围边界、术语表 这类内容，只有在它们能明显降低歧义时才保留为独立模块。

文档路由

先判断文档处于软件开发流程的哪个阶段，再读取对应参考骨架。

A. 立项 / 项目建议 / 项目简报

适用场景： 项目启动、资源申请、方向对齐、跨团队争取支持。

读取： references/project-initiation.md

B. 需求说明 / PRD

适用场景： 明确目标用户、需求范围、功能边界、验收标准。

读取： references/requirements-spec.md

C. 技术设计 / RFC / 架构说明

适用场景： 设计方案评审、架构改造、技术选型、变更提案。

读取： references/technical-design.md

D. 实施 / 上线 / 运维 / 操作手册

适用场景： 实施步骤、发布流程、故障排查、回滚、值守指南。

读取： references/implementation-runbook.md

E. 优化既有文档

适用场景： 用户已经有文档，但它冗长、重复、重点不清、专业度不足、可读性差。

读取： references/document-optimization.md

如果是“优化既有文档”，除了优化参考外，还应继续读取该文档原本所属类型的骨架。

输入模式

模式 A：首稿起草

当输入是原始笔记、讨论纪要、代码上下文、零散需求或口头说明时：

• 先补结构，再补语言。
• 先确定问题、目标、边界和决策，再扩展细节。
• 默认输出“最少但够用”的第一版，而不是冗长全量版。
• 如果一句话已经能说清，就不要再补解释。

模式 B：已有文档优化

当输入已经是一份文档时：

• 优先保留原文含义。
• 优先删减、压缩、提纯，再决定是否重组结构。
• 如果原结构已经可用，先在原结构上提密度，而不是直接推倒重写。
• 优先改“摘要、标题、首句、列表项”，这些位置最影响读感。

核心工作流

1. Diagnose 判断文档类型、读者、主要决策点，以及当前文档最影响阅读体验的 2-3 个问题。
2. Compress 删除重复解释、低信号段落和不必要背景，把篇幅让给结论、边界和关键动作。
3. Reframe 用行业术语、清晰分层和高扫描结构重组文档。
4. Emphasize 把目标、非目标、风险、决策、动作项前置并高亮。
5. Check 最后检查：是否更容易读，是否更容易扫，是否更专业，是否更少废话。

话术约束

• 优先用短句，不用长从句。
• 优先用判断句，不用说明腔。
• 优先用并列短语，不用层层修饰。
• 一句话里不要同时解释“原因 + 现象 + 影响 + 方案”。
• 如果一句话读完还抓不住主语和结论，就继续压缩。

图示约束

• 图只表达一个核心关系，例如流程、状态、职责或依赖。
• 图前先给一句标题，图后补 2-3 条读图提示，不要让读者自己猜重点。
• 优先画主路径，不要把例外分支全部塞进一张图。
• 如果图无法比文字更清楚，就不要画。

术语泵（Term Pump）

把口语化表达映射为领域内更专业的术语，但不要机械套用。

• 防止 AI 乱改 -> 运行时护栏
• 大家配置不一样 -> 环境漂移
• 哪里容易出问题 -> 失效模式 / 风险暴露面
• 这个地方容易互相影响 -> 耦合面
• 后面再看看 -> 待确认项 / 开放问题

核心原则是：根据已确认领域，把描述升级为更准确、更简洁、更专业的表达。

输出策略

• 先按流程阶段选骨架，再按读者和输入模式微调。
• 如果用户已经指定模板，优先沿用用户模板，但仍执行本 skill 的压缩、术语升级、重点前置与视觉降噪规则。
• 如果是面向老板或跨团队读者，优先强调背景、价值、边界、资源、风险与决策请求。
• 如果是面向研发读者，优先强调约束、接口、方案细节、替代方案、风险、验证与迁移。
• 如果是面向实施或运维读者，优先强调前置条件、操作步骤、系统反馈、验证项、回滚与故障排查。

不该做的事

• 不要把文档写成时间线流水账。
• 不要用更长的篇幅去解释本可一句话说清的内容。
• 不要把结论藏在大量背景后面。
• 不要把“背景材料”误写成“最终决策”。
• 不要通过堆术语来伪装专业度。
• 不要为了形式统一，强行把所有文档写成同一个模板。