doc-governance

Documentation Governance Skill

Overview

In the era of AI agent software development, documentation is no longer just a static memo for human engineers, but alsothe core context window and source of truth for agents performing architecture reasoning, interface alignment, and TDD coding。

doc-governance is an integrated documentation governance system for modern software engineering and AI agent collaboration, grounded in four theoretical cornerstones:

1. The Diátaxis four-quadrant architecture: divides Tutorials, How-To, Reference, and Explanation according to reader mentality, strictly prohibiting mixed responsibilities;
2. RFC proposal incubation and crystallization flow model (RFC-to-Crystallization Lifecycle): solves the high cognitive resistance problem of early-stage alignment; during the initial stage, a single file is used for centralized incubation, and after finalization it is deconstructed, crystallized, and distributed downward;
3. Docs-as-Code and automated CI gates: physical link validation, 5-entry sliding window self-healing, zero 404 broken links, and machine-readable index generation;
4. Language convention inheritance and naming standards: respect the continuity of the engineering primary language; initially recommend the kebab-case convention to eliminate fragmentation.

graph TD
    Trigger(["📚 doc-governance 触发"]) --> Select{"选择运行模式"}

    Select -->|"模式 1: 伴随式全向联动 (Sync Mode)"| M1["比对变更集 (Git Diff) ➔ 推导受影响文档<br/>同步 API/模型/规则 ➔ 关闭待办 ➔ 更新 Changelog"]
    Select -->|"模式 2: 全局健康巡检 (Audit & Heal Mode)"| M2["静态扫描 404 断链 ➔ 修订历史滑动裁剪<br/>Frontmatter 合规校验 ➔ 自动生成 llms.txt"]
    Select -->|"模式 3: 脚手架与生命周期 (Scaffold & Archive Mode)"| M3["一键生成 Diátaxis / RFC 标准模板<br/>执行定案结晶下沉 ➔ 提案历史归档防腐"]

M1 --> Verify{"自动化门禁校验"}
M2 --> Verify
M3 --> Verify

Verify -->|存在断链或格式缺陷| Heal["自动化脚本自愈 / 报错阻断"] --> Verify
Verify -->|零警告零断链| Done(["🏁 治理闭环完成 (Governance Completed) ✅"])

---

## 适用场景 (When to Use)

### 必须触发 (Mandatory)
* **API / 契约 / 模型变更**：任何新增、修改、废弃 API 接口、数据字段、枚举值或请求/响应信封时；
* **业务规则与状态机变更**：调整工作流状态机状态节点、权限校验矩阵或安全红线时；
* **核心架构与重大技术决策**：发生框架选型、分层解耦或基础设施演进，需产出 MADR 记录时；
* **项目初期需求与设计对齐**：发起新功能提案（RFC / Proposal），经历多轮审查并最终准备定案结晶时；
* **代码交付前与 PR 合并门禁**：版本交付或合并主干前，必须执行全局断链扫描与健康度巡检；
* **文档重构与既有项目迁移**：将历史瀑布生命周期目录（requirements, design, planning 等）渐进式迁移至标准 Diátaxis 目录。

### 无需触发 (When NOT to Use)
* 纯代码内部单行重构（未改变函数签名、数据模型、API 契约及业务状态流转）；
* 仅修复代码语法警告且不涉及任何外部行为契约变动。

---

## 目录拓扑与职责划分 (Directory Topology)

标准知识库根目录为 `docs/`，严禁在不同象限间混淆内容：

```text
docs/
├── index.md                 # 【全局人类总入口】全景知识库拓扑与分类索引
├── llms.txt                 # 【AI 智能体机器地图】精炼的机器可读知识拓扑与关键参考入口
├── GOVERNANCE.md            # 【知识库治理规程】文档分类、生命周期与 CI 门禁规则
│
├── proposals/               # 💡 0. 需求与设计孵化层 (Inception / RFC Proposals)
│   │                        # ⭐ 项目初期单文件聚焦对齐空间，定案后结晶下沉至 Diátaxis 稳态
│   ├── RFC-0001-xxx.md      # 初期对齐提案草案 (Draft -> In Review -> Accepted)
│   └── archive/             # 已结晶下沉的提案历史归档 (Implemented / Superseded)
│
├── tutorials/               # 🎓 1. 教程象限 (Learning-Oriented / Newcomer Success)
│   ├── quick-start.md       # 5 分钟上手开发与运行首个特性
│   └── onboarding.md        # 新成员/新智能体工作流与环境就绪向导
│
├── how-to/                  # 🛠️ 2. 操作指南象限 (Problem-Oriented / Task Recipes)
│   ├── deployment.md        # 生产环境容器化构建与服务发布 SOP
│   ├── local-setup.md       # 本地多服务联调与数据库初始装配
│   ├── testing-guide.md     # 单元/集成/E2E 测试套件执行与覆盖率校验
│   └── troubleshooting.md   # 隐蔽缺陷排查、异步死锁与框架踩坑手册 (SOP)
│
├── reference/               # 📖 3. 技术参考象限 (Information-Oriented / Machine Truth)
│   │                        # ⭐ AI 智能体生成代码的核心上下文真相源 (Single Source of Truth)!
│   ├── api/                 # 外部与内部 API 契约规格、统一错误信封、Endpoint 清单
│   ├── models/              # 领域数据模型、Schema 契约、数据库实体与 DTO 定义
│   ├── rules/               # 平台业务规则、状态机状态图、权限矩阵与智能体行为协议/提示词契约
│   └── ui/                  # 前端设计 Token、UI 基础组件规范、交互事件契约
│
├── explanation/             # 💡 4. 深度剖析象限 (Understanding-Oriented / The "Why")
│   ├── architecture/        # 系统总体代码架构总纲 (Hub) 与各子系统深度剖析 (Spokes)
│   ├── decisions/           # ADR 架构决策记录 (MADR 3.0 格式, 0001-xxx.md, Append-Only)
│   ├── analysis/            # 技术调研备忘录、第三方框架选型评估、可行性分析报告
│   └── concepts/            # 核心业务领域深层概念、设计哲学与数学/算法模型阐释
│
└── project/                 # 🚀 5. 工程演进与项目管理 (Project Management & Evolution)
    ├── roadmap.md           # 产品规划路线图与版本里程碑矩阵
    ├── changelog.md         # 版本发布日志与交付物归档（已落地成果技术叙事单一事实源）
    ├── backlog.md           # 【热区】现役活跃待办清单（进行中+计划中，严禁堆积关闭项，保持精炼）
    └── archive/             # 【冷区】历史已结项待办归档（按版本 backlog-vX.Y.md 或季度归档沉淀）

---

Core Operational Modes SOP (Operational Modes)

Mode 1: Companion-style omnidirectional linked governance (Sync Mode)

Execute when a development task involves feature evolution or contract adjustments:

1. Reverse derivation of change sets: run git diff --name-only to inspect all modified code files;
2. Compare against the Change Linkage Trigger Matrix(see change-impact-matrix.md）：
   • Modify backend Controller/Service ➔ linked sync reference/api/ and reference/models/；
   • Modify state machine enum/guard ➔ linked sync reference/rules/；
   • Modify frontend component/style Token ➔ linked sync reference/ui/；
   • Core architecture evolution ➔ write one MADR decision and append it to explanation/decisions/；
3. Project evolution record closed loop: in project/changelog.md append release records, and move the to-dos corresponding to project/backlog.md in BK numberinto project/archive/ the corresponding archive file (set to [x], annotate the destination and date, and keep the backlog.md hot area pure and concise; for standards, see backlog-specification.md）；
4. Version numbers and revision history: raise the versions of affected documents according to semantic conventions, following 5-entry sliding window append a revision row at the first row of the revision table (standard descending order), and synchronously update the control header version;
5. Gate validation: run check-doc-links.py and check-doc-control-sync.py to ensure zero broken links and zero version drift.

Mode 2: Global knowledge base inspection and self-healing (Audit & Heal Mode)

Execute before version releases, after large refactorings, or during regular maintenance:

1. Static broken link audit: run python3 scripts/check-doc-links.py --root docs, check the validity of all relative links,.md suffixes, and whether anchors exist;
2. Control header and revision table version consistency audit: run python3 scripts/check-doc-control-sync.py --root docs, assert that the control header version number and the latest revision table row version number are strictly consistent, and eliminate version drift;
3. Automatic revision history trimming: run python3 scripts/trim-revision.py --root docs --fix --keep 5, automatically truncate the revision history of all documents to the most recent 5 entries;
4. Comprehensive health check: run python3 scripts/audit-doc-health.py --root docs, output knowledge base coverage, orphan documents, Backlog evolution metrics, version consistency, and baseline compliance score;
5. Machine map generation: run python3 scripts/generate-llms-txt.py --root docs --output docs/llms.txt, refresh the topology map for agent consumption.

Mode 3: Scaffold & Archive Mode

1. Create document/proposal: run scripts/scaffold-doc.sh <type> <name>(e.g. scaffold-doc.sh rfc canvas-collab), create a scaffold based on the specification template, and automatically fill in the compliance control header;
2. Initial RFC alignment: in docs/proposals/ single document, close the loop on business stories, contract drafts, and option trade-offs;
3. Finalized crystallization and deposition: after the solution is approved, follow rfc-crystallization-lifecycle.md to deconstruct and deposit interfaces, rules, and architecture into the corresponding Diátaxis directories;
4. Proposal archiving and anti-corrosion: mark the original RFC as Implemented and move it to docs/proposals/archive/, with an anti-corrosion historical memo added.

---

⛔ Core Red Lines and Negative Invariants

1. ⛔ Strictly forbidden to mix teaching or reasoning into Reference：reference/ must be pure, recording only authoritative mechanical facts, and strictly forbidden to include "why do it this way" or "how to operate";
2. ⛔ Strictly forbidden for unset experimental drafts to pollute Reference: unapproved ideas must remain aligned in proposals/ , and must never be written as authoritative truth into reference/；
3. ⛔ Strictly forbidden broken links and implicit concept references: references between documents must explicitly preserve the relative path with the .md suffix (e.g. [规则.md](./rules/rule.md)), and strictly forbidden to use suffixless bare routes or absolute physical paths;
4. ⛔ Strictly forbidden unlimited expansion of revision history: revision history is strictly limited to the most recent 5 entries, and excess parts must be trimmed;
5. ⛔ Strictly forbidden to break engineering language continuity: existing Chinese projects must use Chinese for body text and explanations, and mixing Chinese and English chaotically is strictly forbidden; initial file naming should preferably follow all-lowercase kebab-case;
6. ⛔ Strictly forbidden monolithic giant documents: in principle, a single document must not exceed 800 lines, and complex systems must adopt a "master outline - sub-volume" topology separation;
7. ⛔ Strictly forbidden to accumulate cold data and handwritten reconciliation in Backlog：backlog.md is a hot-zone to-do pool, and it is strictly forbidden to accumulate closed entries (they must be migrated out in batches to archive/); it is strictly forbidden to record historical achievement implementation details in Backlog (belongs in changelog.md), and strictly forbidden to handwrite natural-language arithmetic reconciliation diaries (metric statistics are dynamically scanned and output by audit-doc-health.py ).

---

📚 Detailed References

Reference Manual	Core Content Summary
diataxis-standard.md	Diátaxis four-quadrant writing boundaries, classification decision tree, and detailed analysis of anti-patterns
rfc-crystallization-lifecycle.md	Complete SOP for initial proposal incubation, multi-round alignment, and finalized crystallization and deposition
language-naming-conventions.md	Iron rules for inheriting project language habits, file naming rules, and standards for orthogonal separation of Chinese and English
change-impact-matrix.md	Omnidirectional linkage matrix and gate requirements for code modification and contract evolution
backlog-specification.md	Backlog V2.0.0 cold-hot physical isolation, structured entry contract, automated gates, and archiving SOP
adr-specification.md	MADR 3.0 architecture decision record format specification and Append-Only evolution flow
legacy-migration-guide.md	Smooth mapping guidance for legacy waterfall directories (requirements, design, planning, etc.)