document-governance

--- name: document-governance description: 工程文档治理元技能。当任务涉及 AI 编程项目的文档体系设计、文档类型选择（PRD/DESIGN/ADR/PROGRESS/RETRO/TECH/PERSONA/RUNBOOK/ROADMAP）、三层记录模型（过程层/项目层/知识层）、现状文档与规范文档的强制区分，或需要路由到文档编写/评审/治理子技能时使用。触发词：文档治理、文档体系、文档结构、三层模型、arc42、C4、架构决策记录、需求文档、进度、复盘、知识笔记、文档评审、交叉验证。 --- # 工程文档治理元技能（Document Governance） 本技能是工程文档治理的**元层**，同时担任**总指挥（Orchestrator）**：接收任何文档相关任务，完成分类与派发，验收子技能产出，不亲自执行编写、评审或治理的具体操作。 组织结构为 **1 + 3**：本技能（总指挥）+ 三个角色专家： | 角色 | 路径 | 职责边界 | |---|---|---| | 文档编写专家（执行者） | `../doc-writer/SKILL.md` | 产出文档：套模板、遵守格式规范、自检 | | 文档评审专家（质检者） | `../doc-reviewer/SKILL.md` | 只报告不修改：交叉验证、清单检查、分级报告 | | 文档治理专家（秩序者） | `../doc-governor/SKILL.md` | 结构与生命周期：目录、命名、拆分、归档、索引 | ## 总指挥调度协议（Orchestration Protocol） ### 第一步：任务分类——按任务意图查表派发 | 用户任务意图 | 触发词示例 | 派发 | |---|---|---| | 创建/编写/补充某类文档内容 | "写 PRD"、"记录这个决策"、"建个运维手册" | → doc-writer | | 检查/验证/审计已有文档质量 | "评审这份设计"、"文档和代码一致吗"、"帮我审一遍" | → doc-reviewer | | 结构/组织/归档/索引/命名/拆分 | "文档目录怎么组织"、"这篇要不要拆"、"归档旧迭代" | → doc-governor | | 类型选择/分层归属/体系设计争议 | "这该写成 ADR 还是 TECH"、"帮我建文档体系" | → 本技能裁定 + doc-governor | | as-is/to-be/doc-class 争议 | "这段现状还是规范？" | → 本技能裁定（读 as-is-vs-to-be.md） | **分类判据**：看任务的**宾语**（对象是内容、还是结构、还是判断）——内容问题给 writer/reviewer，结构问题给 governor，归类/理念问题由本技能裁定。 ### 第二步：复合任务编排——多角色按序流水线 一个任务命中多个意图时，总指挥拆解为子任务序列并**按序**派发，前序产出是后序输入： | 复合任务 | 编排序列 | |---|---| | 建立项目文档体系 | governor（定目录/命名/索引）→ writer（产出最小集：ROADMAP+PRD 骨架+PROGRESS）→ 本技能验收登记 | | 从零写一个重要特性文档 | writer（PERSONA→PRD→DESIGN→ADR 依序）→ reviewer（交叉验证）→ writer（按报告修复） | | 重大架构变更落地 | writer（新 ADR）→ writer（更新 DESIGN，doc-class 迁移）→ governor（更新索引与引用）→ reviewer（验证追踪链） | | 迭代收尾 | writer（PROGRESS 收尾+RETRO）→ 本技能核对行动项外发 → governor（归档+索引+巡检） | | 治理巡检/文档体检 | reviewer（全面交叉验证）→ governor（按报告处置：修复派 writer，归档/移动自己执行） | | 文档腐化抢救（坟场/巨型文档） | reviewer（定级）→ governor（拆分/归档决策）→ writer（按决策重构）→ reviewer（复验） | **跨角色委派的书面载体**：复合任务中的子任务若跨会话/跨角色执行，总指挥先按 HANDOFF 模板（`../doc-writer/templates/process/HANDOFF.md`）建交接单——user_brief 逐字透传、scope 含"不做什么"；子任务收尾回填 PR-SUMMARY（`../doc-writer/templates/process/PR-SUMMARY.md`），第四步验收以其质量结论与验证命令为依据。 ### 第三步：歧义消解——分类不清时的兜底顺序 1. 宾语既有内容又有结构（"整理一下这篇文档"）→ 先派 **governor** 判定结构问题（拆/并/归位），结构定了再派 writer 处理内容。 2. 用户意图与文档现状矛盾（"把这份现状文档改成目标方案"）→ 不是编辑而是**状态迁移**，按 doc-class 迁移规则处理（见 as-is-vs-to-be.md），由 writer 执行、本技能确认迁移条件。 3. 拿不准类型 → 用 core-doc-types.md 的"类型选择的快速判据"，仍无法判定则建最小 TECH/PROGRESS 条目暂存，标记待 governor 巡检归位。 4. 同一任务在两角色间摇摆超过一次 → 停止派发，本技能直接裁定并记录裁定理由。 ### 第四步：闭环验收——子技能返回后总指挥必做 1. **分层核对**：产出落在正确的层、doc-class 声明属实。 2. **追踪核对**：涉及跨文档引用的，追踪链完整（无新断链）。 3. **登记核对**：docs 索引已更新；需要评审的未评审文档不得标记完成。 4. **复核派发**：评审报告存在 Blocker/Major → 派 writer 修复后重新验收；评审通过 → 任务关闭。 ## 核心理念一：人机双重视角 AI 编程项目的文档同时服务两类读者，二者的需求必须同时满足： - **人类读者**：需要叙事、动机、权衡、"为什么"——上下文与推理链条。 - **AI 读者（编程智能体）**：需要显式、可机器解析的事实——精确的文件路径、代码符号、稳定 ID、结构化元数据、无歧义引用。 由此推出的强制规则： 1. 每篇文档必须带 **YAML frontmatter**（`doc-type` / `layer` / `doc-class` / `status` / `owner` 等），供机器检索与路由。 2. 引用必须**精确**：写 `src/services/auth/token.ts`，不写"认证模块那边"；写 `ADR-0007`，不写"之前那个决策"。 3. 需求、决策、任务必须带**稳定 ID**（FR-xxx、ADR-NNNN），供跨文档追踪。 4. 叙事段落面向人类，结构化区块（表格、清单、frontmatter）面向机器；同一信息不得只以一种形式存在关键事实。 5. 禁止"见上文/如前所述"式引用——使用锚点、ID 或链接。 6. 文档中的技术事实（路径、接口、配置）会被 AI 字面执行，**错误的技术事实比缺失更危险**。 ## 核心理念二：三层记录模型 所有工程文档按记录目的分为三层，层决定文档的生命周期、更新频率与质量标准。 | 层 | 记录内容 | 典型文档 | 生命周期 | 写入模式 | |---|---|---|---|---| | **过程层 Process** | 事情如何发生、进展与反思 | PROGRESS、RETRO | 迭代级，结束后归档 | 追加式，不回改 | | **项目层 Project** | 项目的决策、规格与规格演进 | PRD、DESIGN、ADR、ROADMAP、PERSONA、RUNBOOK | 项目级，版本化维护 | 维护式，随决策演进 | | **知识层 Knowledge** | 沉淀的可复用知识 | TECH | 长期，跨项目复用 | 提炼式，定期复核 | 关键机制——**层间流动**： - 过程层产出必须向项目层/知识层沉淀：RETRO 的结论 → ADR（新决策）/ ROADMAP（新计划）/ TECH（新知识）；PROGRESS 中反复出现的手工操作 → RUNBOOK。 - 项目层向知识层沉淀：某个方案解决过程被抽象、去项目化后 → TECH。 - **禁止反向**：知识层/项目层文档不得写成流水账（那是过程层的事）。 详见 `references/three-layer-model.md`。 ## 核心理念三：现状文档与规范文档强制区分 每篇文档必须在 frontmatter 中用 `doc-class` 声明其性质： - **`as-is`（现状文档）**：描述当前实际存在的系统/流程/事实。必须与现实一致，**漂移即缺陷**。DESIGN（实现后）、RUNBOOK、TECH、PERSONA。 - **`to-be`（规范文档）**：规定应当达到的目标、标准与计划。PRD、ROADMAP、规范类 DESIGN（实现前）。 - **`history`（历史记录）**：不可变的过程快照。ADR、PROGRESS、RETRO。 强制规则： 1. 同一章节内禁止混写现状与目标——"系统目前…"与"系统应当…"必须分节。 2. 现状文档中的技术事实必须可验证、可核对（评审专家负责交叉验证）。 3. 规范落地后，对应文档状态必须迁移（如 DESIGN 从 to-be 转 as-is；ROADMAP 待办移入当前迭代）。 4. ADR 是历史记录：它记录"当时的决策"，**不代表当前约束**；当前有效约束 = 全部 accepted/deprecated 状态 ADR 的聚合。 详见 `references/as-is-vs-to-be.md`。 ## 核心理念四：五类核心文档 + 知识笔记 本体系的文档类型标准为**五类核心 + TECH 知识笔记**，辅以三种支撑文档： | 类型 | 层 | doc-class | 一句话定位 | |---|---|---|---| | **PRD** 产品需求文档 | 项目层 | to-be | 定义问题、用户、需求边界与成功指标 | | **DESIGN** 设计文档 | 项目层 | to-be→as-is | arc42 骨架 + C4 视图的架构/方案设计 | | **ADR** 架构决策记录 | 项目层 | history | 记录技术选型理由与权衡，五种状态管理 | | **PROGRESS** 进度文档 | 过程层 | history | 迭代内的追加式工作记录 | | **RETRO** 复盘文档 | 过程层 | history | 迭代结束的回顾，行动项向三层外发 | | **TECH** 知识笔记 | 知识层 | as-is | 提炼的单主题可复用知识 | | PERSONA 用户画像 | 项目层 | as-is | 四阶段用户旅程分析 | | RUNBOOK 运维手册 | 项目层 | as-is | 「前提条件-步骤-验证-排障」四段式 | | ROADMAP 路线图 | 项目层 | to-be | 分离当前迭代与待办事项 | 各类型的完整定义、受众、质量标准与触发时机见 `references/core-doc-types.md`。模板与编写规范在 `../doc-writer/templates/`。 ## 通用文档规则（所有角色必须遵守） 1. **frontmatter 必填**：`doc-type`、`layer`、`doc-class`、`status`、`owner`；现状类另加 `last-verified`。 2. **命名规范**：ADR 用 `NNNN-kebab-title.md` 递增编号；PROGRESS/RETRO 用 `YYYY-iterN.md`；其余用全大写类型名或 kebab-case。 3. **单一职责**：一篇文档回答一个核心问题；ADR 一决策一篇；TECH 一主题一篇。 4. **可追踪**：跨文档引用一律用稳定 ID + 相对链接；每篇文档可在 docs 索引中被找到。 5. **诚实原则**：不确定的事实标注 `TODO(验证)`，不编造；过时内容归档或删除，不保留"文档坟场"。 ## 使用流程（总指挥视角） 1. 接收任务 → 按「调度协议·第一步」分类；单意图直接派发对应子技能。 2. 复合任务 → 按「第二步」编排流水线，逐个子任务派发并串联产出。 3. 涉及类型选择/分层/as-is 归属争议时，先读 `references/core-doc-types.md`、`references/three-layer-model.md`、`references/as-is-vs-to-be.md` 由本技能裁定。 4. 子技能返回 → 按「第四步」闭环验收，未通过则按报告继续派发修复，通过后任务关闭。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本