document-governance
工程文档治理元技能。当任务涉及 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),第四步验收以其质量结论与验证命令为依据。
第三步:歧义消解——分类不清时的兜底顺序
- 宾语既有内容又有结构("整理一下这篇文档")→ 先派 governor 判定结构问题(拆/并/归位),结构定了再派 writer 处理内容。
- 用户意图与文档现状矛盾("把这份现状文档改成目标方案")→ 不是编辑而是状态迁移,按 doc-class 迁移规则处理(见 as-is-vs-to-be.md),由 writer 执行、本技能确认迁移条件。
- 拿不准类型 → 用 core-doc-types.md 的"类型选择的快速判据",仍无法判定则建最小 TECH/PROGRESS 条目暂存,标记待 governor 巡检归位。
- 同一任务在两角色间摇摆超过一次 → 停止派发,本技能直接裁定并记录裁定理由。
第四步:闭环验收——子技能返回后总指挥必做
- 分层核对:产出落在正确的层、doc-class 声明属实。
- 追踪核对:涉及跨文档引用的,追踪链完整(无新断链)。
- 登记核对:docs 索引已更新;需要评审的未评审文档不得标记完成。
- 复核派发:评审报告存在 Blocker/Major → 派 writer 修复后重新验收;评审通过 → 任务关闭。
核心理念一:人机双重视角
AI 编程项目的文档同时服务两类读者,二者的需求必须同时满足:
- 人类读者:需要叙事、动机、权衡、"为什么"——上下文与推理链条。
- AI 读者(编程智能体):需要显式、可机器解析的事实——精确的文件路径、代码符号、稳定 ID、结构化元数据、无歧义引用。
由此推出的强制规则:
- 每篇文档必须带 YAML frontmatter(
doc-type/layer/doc-class/status/owner等),供机器检索与路由。 - 引用必须精确:写
src/services/auth/token.ts,不写"认证模块那边";写ADR-0007,不写"之前那个决策"。 - 需求、决策、任务必须带稳定 ID(FR-xxx、ADR-NNNN),供跨文档追踪。
- 叙事段落面向人类,结构化区块(表格、清单、frontmatter)面向机器;同一信息不得只以一种形式存在关键事实。
- 禁止"见上文/如前所述"式引用——使用锚点、ID 或链接。
- 文档中的技术事实(路径、接口、配置)会被 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。
强制规则:
- 同一章节内禁止混写现状与目标——"系统目前…"与"系统应当…"必须分节。
- 现状文档中的技术事实必须可验证、可核对(评审专家负责交叉验证)。
- 规范落地后,对应文档状态必须迁移(如 DESIGN 从 to-be 转 as-is;ROADMAP 待办移入当前迭代)。
- 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/。
通用文档规则(所有角色必须遵守)
- frontmatter 必填:
doc-type、layer、doc-class、status、owner;现状类另加last-verified。 - 命名规范:ADR 用
NNNN-kebab-title.md递增编号;PROGRESS/RETRO 用YYYY-iterN.md;其余用全大写类型名或 kebab-case。 - 单一职责:一篇文档回答一个核心问题;ADR 一决策一篇;TECH 一主题一篇。
- 可追踪:跨文档引用一律用稳定 ID + 相对链接;每篇文档可在 docs 索引中被找到。
- 诚实原则:不确定的事实标注
TODO(验证),不编造;过时内容归档或删除,不保留"文档坟场"。
使用流程(总指挥视角)
- 接收任务 → 按「调度协议·第一步」分类;单意图直接派发对应子技能。
- 复合任务 → 按「第二步」编排流水线,逐个子任务派发并串联产出。
- 涉及类型选择/分层/as-is 归属争议时,先读
references/core-doc-types.md、references/three-layer-model.md、references/as-is-vs-to-be.md由本技能裁定。 - 子技能返回 → 按「第四步」闭环验收,未通过则按报告继续派发修复,通过后任务关闭。
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 5d ago
- Current version
- v0.1.0
- License
- MIT-0
