doc-governance

doc-governance

系统实际做的 vs 团队以为的已分叉，且无一处测量能让人看见分叉；修法一律先让它可见。 —— 一次真实项目复盘的核心诊断，这套东西的总纲

框架从一个大型协议项目的文档体系提炼（framework.md 是判据，含明确不搬的部分）。 它是程序不是规范：道理全在 incidents.md 和测试里—— 136 条测试中 103 条在 docstring 里写明它防的那次事故，跑一次就复述一次； 其余 33 条是正例（验证不该报的情况不报），没有事故可写。

依赖：python3（3.10+，只用标准库）与 git。跑自测需要 pytest。

三个动作

S=/governance.py          # 例如 ~/.claude/skills/doc-governance/governance.py

python3 $S audit --root .            # 诊断：七个组件各自 有/残缺/无 + 缺了会怎样
python3 $S init  --root .            # 只列清单不改
python3 $S init  --root . --yes      # 装
python3 $S check --root .            # 持续检查（九种模式）
python3 $S check --root . pending    # 只跑一种

**首次进一个项目就跑 audit。**它只读、不改任何文件，输出这个项目的治理成熟度， 以及每项缺了会踩哪次事故的坑。

audit 查什么（G1–G7，判据见 framework.md）

⚠️ G3 和 G7 装不出来——只能靠写文档时补。audit 会单独列出来，不假装能一键解决。

init 装四样装置：.doc-governance.json、scripts/governance.py 副本、 .githooks/pre-commit，以及两个 Claude Code hook—— 新建 PLAN-*.md 时先跑全量 check、红了硬拦（这是 CI 拦不住的那个时刻）， 改完决策记录后当场核级联。都放项目里、进 git。另外，决策目录或计划目录缺的时候会补一份 README 模板（已有则不碰）。 pre-commit 里还有一道副本比对：scripts/governance.py 与 skill 源不一致就拦下（找不到源时跳过，CI 不受影响）。 源位置按这个顺序找：环境变量 DOC_GOVERNANCE_HOME → ~/.claude/skills/doc-governance → ~/.cursor/skills/doc-governance → ~/.codex/skills/doc-governance。装在别处就设环境变量。 Cursor 项目得自己写等价的 .mdc。

check 的九种模式

pending 待办挂太久 · cascade 级联备忘没落地 · status 计划状态与实际不符 · refs 决策引用断裂或成环 · links 断链 · sections §章节指错 · index 决策目录与索引对不上 · tables 表格渲染会崩 · contract 文档声明的端点／字段代码里没有

contract 要在 .doc-governance.json 里配 contract_checks（怎么读文档侧、怎么读代码侧）—— 框架各不相同，只能配；配错导致代码侧提取为空时报自检失败，不会假装通过。 文档那一行标了实现状态（已下线／规划中／…）就跳过：诚实标注是解法，不是违规。

自检：配置缺、目录不存在、扫到 0 个文件——一律红。 「检查机制自己失效却不报」正是这套东西要防的病。

这个 skill 自己也被 contract 盯着（test_governance.py 末尾那组自查）： 模式清单与 ALL_MODES 一致 · 不许吹不存在的模式 · 散文里的「N 种模式」必须等于实际 · init 加装的每样东西都得写进说明书 · G1–G7 在代码／SKILL.md／framework.md 三处一致 · 每种模式在 incidents.md 有事故 · 测试计数与文档一致。 功能加了说明书没跟，跑测试就会红。

什么时候跑 check

怎么开口

触发：用户说「教程」「怎么用」「不会用」「帮助」「help」「有啥用」时， 原样给出下面这一块，然后停下——不要追问「你是哪种情况」。 问这个词的人在看，不在做；追问会把阅读请求变成他没打算做的承诺。

---

先说最要紧的：装完之后日常不用调我。 pre-commit、CI 和两个 Claude Code hook 会自己拦你——红了才需要你出面。

真正要开口时，参考下表——这是典型场景，不是固定语法，换个说法系统一样能识别：

命令列省了前缀 python3 $S（S=/governance.py）。 想现在就开始，说 A—F 里任意一句，或直接报字母，都行。只是想看看，那看到这里就够了。

---

（以上是给用户看的原文。下面是给自己的备注：） 打 /doc-governance 与说人话效果一样，只是确定性更高。 python3 $S check --root . 不需要 AI——CI 与 pre-commit 跑的就是它。

这一节被四次真实反馈逼出来： ① 「需要它的命令吗？还是自然语言就可以？」——当时说明书没写怎么开口。 ② 补上后被指出例句全是行话（「文档体系」「spec」「对一遍」）—— 写例句的人已经会用了，视角天然是错的；真新手描述的是症状不是工具。 ③ 原本打算列完清单追问「你像哪种情况」，被否—— 「教程」是阅读意图不是执行意图，追问等于逼对方承诺。改成陈述句留出口。 ④ 加编号列（A–F）与命令列，标题从「你可以这么说」改「典型场景」—— 编号和命令列没有②的风险：它们标的是「这是另一件事」，不是「这是唯一说法」。 但曾提议把标题直接改叫「指令」，会把②刚删掉的「必须照念」暗示重新缝回去， 已改用「典型场景」——句子本身仍是症状形状，只是语气从纯口语收到专业与俗语平衡。

装到新项目

1. audit 看缺什么 → 2. init --yes 装 → 3. 手动把 check 接进项目已有的 verify/CI 链（不新建机制，接现有的）→ 4. 往 incidents.md §「本项目追加」写这个项目自己的事故。

读输出的原则

**红了先看 incidents.md 对应的事故，再看行号。**大多数时候你要的不是「哪行错了」， 是「这类错为什么危险」——那决定你该修文档还是修检查器。

⚠️ 不准的检查器比不检查更糟：它会让人开始不信输出，然后连真的也一起忽略。 首次上真仓运行报出 26 处，其中 7 处是检查器自己的 bug——每一处都补了回归测试。 （这两个数是当时的即时统计，事后无法复算；回归测试本身在仓里，可查。）