living-docs-governance
把长期项目的文档当成一个小系统来维护,防止文档腐烂——四份各司其职的脊柱文件(CLAUDE.md 共享章程 / CLAUDE_MAP.md 地图 / PROJECT_STATUS.md 健康仪表盘 / PROJECT_LOG.md 流水账)+ Codex 的 AGENTS.md 入口桥接 + 固定读序,并按需连接 ARCHITECTURE、CONTEXT、ADR、契约、测试、回归和 Issue Tracker。用于治理初始化、只读审计、阶段同步、LOG 复盘与超过 200 条事件后的归档索引。中文触发:文档治理、活文档、防文档漂移、治理初始化、治理审计、治理同步、治理复盘、AGENTS.md、项目状态追踪、项目地图、架构图、模块流转图、健康仪表盘、流水账、日志归档、长期项目治理。English triggers: living documentation, docs governance, governance init, governance audit, governance sync, governance retrospective, AGENTS.md bridge, architecture document, module flow diagram, prevent doc rot, project status dashboard, project map, append-only changelog, project log archive.
qshanx · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add qshanx/docs-governance --skill living-docs-governance技能说明
name: living-docs-governance description: >- 把长期项目的文档当成一个小系统来维护,防止文档腐烂——四份各司其职的脊柱文件(CLAUDE.md 共享章程 / CLAUDE_MAP.md 地图 / PROJECT_STATUS.md 健康仪表盘 / PROJECT_LOG.md 流水账)+ Codex 的 AGENTS.md 入口桥接 + 固定读序,并按需连接 ARCHITECTURE、CONTEXT、ADR、契约、测试、回归和 Issue Tracker。用于治理初始化、只读审计、阶段同步、LOG 复盘与超过 200 条事件后的归档索引。中文触发:文档治理、活文档、防文档漂移、治理初始化、治理审计、治理同步、治理复盘、AGENTS.md、项目状态追踪、项目地图、架构图、模块流转图、健康仪表盘、流水账、日志归档、长期项目治理。English triggers: living documentation, docs governance, governance init, governance audit, governance sync, governance retrospective, AGENTS.md bridge, architecture document, module flow diagram, prevent doc rot, project status dashboard, project map, append-only changelog, project log archive. metadata: origin: ECC
活文档治理(Living Docs Governance)
长期项目最先腐烂的是文档层:README 在撒谎、架构笔记描述着一次从没上线的重构、每次进会话 agent 都在重新推导本该一读就懂的上下文。活文档治理把项目文档当成一个小的、各司其职的系统,而不是一堆散文件:四份互相链接的文档,每份只干一件事,外加一个 agent 进会话时读它们的固定顺序。
这是维护期的实践。"我刚 clone 了一个陌生仓库"那种一次性问题,用代码库 onboarding 类技能。本技能负责的是:让 onboarding 出来的那张图,在几个月的改动之后依然为真。
在 Claude Code 中,可由配套的
docs-governor/docs-auditoragent 执行;在 Codex 或没有这些自定义 agent 的宿主中,由当前 agent 直接按本 skill 执行,必要时再使用宿主提供的只读探索或执行型子 agent。本 skill 始终是方法论唯一来源。
什么时候启用
满足任一条就启用:
- 项目长过几个模块,文档开始和代码漂移。
- agent 或队友在会话之间丢失上下文,反复重新发现同一套结构。
- 没人能从单一位置回答"这项目现在健康度如何?""上周改了啥?"。
- 死文件和废弃实验堆积,偶尔被误重建。
- 你想给一个单人/小团队项目一层耐用、低开销的治理,又不想上大型多人仓库那套重 CI 机器。
不要在用完即弃的脚本、或活不过这周的仓库上用——那是过度治理。
渐进式采用:从最小开始,但提前看到下一级
别一上来铺满四件套——那本身就是过度治理。从最小起步,真正关键的不是"按需补",是提前认出"下一级快需要了"的预警信号,在它真痛之前就备好。等漂移出事(STATUS 撒谎、重建已删文件)才补,文档已经烂了一轮、返工已经发生——治理的价值在防患,不在救火。
| 当前规模 | 该有 | 下一级的预警信号(看到就准备上) |
|---|---|---|
| 单文件 / 用完即弃 | 什么都不用 | —— |
| 长过几个模块、要维护一阵 | CLAUDE.md(几条硬规则 + 路标) | 开始有人问"这项目现在健康吗" → 备 STATUS |
| 有健康 / 风险 / 待删要追 | + PROJECT_STATUS.md | AI/新人开始"找不到某功能""改错地方" → 备 MAP |
| 找东西 / 跨 Module 改开始费劲 | + CLAUDE_MAP.md | Module 权责、状态归属、依赖或主流程开始说不清 → 备 ARCHITECTURE |
| Module 架构需要共享 | + ARCHITECTURE.md(可选血肉) | 反复问“为什么这样设计” → 备 ADR;要追历史 → 备 LOG |
| 要追溯决策与历史 | + PROJECT_LOG.md(四件套齐) | 分出前后端、接口字段对不上 → 备 CONTRACT |
| 分前后端 / 多服务 | + CONTRACT.md(见 contract-first) | —— |
预警信号的意义:让你在痛之前上对应那一级,而不是等它腐烂出事再救火。
团队共享 vs 个人:治理文件放哪一层
四件套是项目级、团队共享的——进 git,所有协作者 / agent 共用,写的是"团队共识的真相"。个人临时偏好别塞进去(会污染团队视图):那些放 CLAUDE.local.md(同目录、不提交)或 ~/.claude/(全局个人)。判据一句话:帮整个团队一致 → 进项目四件套;只是你一个人的习惯 → 进 .local / 全局。
怎么运作
这套系统 = 四份脊柱文档(角色严格分离)+ 分级读取协议 + 让它们保持最新的更新规则 + 阶段收尾时的查漏补缺矩阵。CONTEXT.md、docs/adr/、契约、测试和回归台账都是按真实需要长出的血肉,不是第五到第九份必建脊柱。
Claude Code / Codex 入口适配
两端共用本 skill,不复制方法论:
| 用户意图 | Claude Code 入口 | Codex / ChatGPT 入口 | 详细执行流程 |
|---|---|---|---|
| 空项目初始化 | /governance-init | $living-docs-governance + “初始化空项目治理” | 本文“空项目初始化”执行模式 |
| 已有项目治理 | /governance | $living-docs-governance + “治理当前项目” | 本文“已有项目治理”执行模式 |
| 只读审计 | /governance-audit | $living-docs-governance + “只读审计” | 本文“只读审计”执行模式 |
| 阶段同步 | /governance-sync | $living-docs-governance + “阶段收尾同步” | 本文“阶段同步”执行模式 |
| LOG 复盘 | /governance-retro | $living-docs-governance + “复盘 PROJECT_LOG” | 本文“日志复盘”执行模式 |
所有宿主直接执行本文对应模式。Claude commands/agents 只选择模式和执行角色;Codex / ChatGPT 由当前 agent 执行,不反向读取 commands/agents。只读审计、只读复盘保持只读。
审计支持 spine、context、adr、artifacts、full 五种范围。先运行 scripts/audit-cheap.sh <scope> 做确定性检查;断链失败就短路,只有通过后才进入语义判断。默认只读;只有用户明确要求保存时,才把报告写入 docs/audits/YYYY-MM-DD-*.md。
四份文档与各自的职责
| 文档 | 唯一职责 | 该放什么 | 绝不能放什么 |
|---|---|---|---|
CLAUDE.md | 宪法:永远生效的硬规则和路标 | 不可妥协的约定、读序、指向其他文档的路标 | 长篇解释(链接出去)、实时状态、历史 |
CLAUDE_MAP.md | 地图:只记文件树看不出来的导航语义 | 非显然定位跳转表、架构/决策/契约等知识入口、"树真实但误导"清单(废弃/生成物/兼容目录)、别动区 | 目录树镜像(ls 就有)、Module 权责与流程图(属 ARCHITECTURE)、接口字段细节(属 CONTRACT/代码 Interface)、健康指标(属 STATUS)、历史(属 LOG) |
PROJECT_STATUS.md | 健康仪表盘:当前状态一眼看清 | 指标对阈值、删除区(故意删掉别重建的文件)、未决违规、P0 行动 | 项目是什么(属 MAP)、发生了什么的叙事(属 LOG) |
PROJECT_LOG.md | 流水账:只追加的历史 | 每件有意义的事一行(## [日期] 类型 | 摘要),新条目追加到底 | 当前状态(属 STATUS)、结构(属 MAP);永不改/删旧行 |
让它生效的纪律是非重叠:每个事实只有一个权威来源,其他载体只引用。"auth 模块在哪?"→ 地图。"覆盖率现在健康吗?"→ STATUS。"旧解析器啥时候删的、为啥?"→ LOG。每份只干一件事,就不会一起烂。
事实按类型认来源:规则、决策与历史由相应文档维护,接口字段由唯一机器契约定义;测试与审查结论引用实际运行的版本、范围、结果和证据位置。项目已有工程 Skill 继续负责代码审查,治理层只核对与引用其证据。STATUS 保存带来源的健康快照,相关实现或验收条件变化后标待复验,不把旧绿色结果延续为当前结论;无法确认版本或范围时明确写未验证。
ARCHITECTURE.md 的 Module 架构契约(按需)
当项目已经出现多个长期 Module,并开始发生跨 Module 修改、状态互相改写或依赖方向说不清时,按 templates/ARCHITECTURE.example.md 创建根目录 ARCHITECTURE.md,让它成为当前架构的唯一说明入口。CLAUDE_MAP.md 只留一行链接,不复制表格或图。ARCHITECTURE 回答六件事:
- Module 权责:每个关键 Module 只用一句话说明唯一职责;能从文件名和文件头稳定推出的普通目录不要逐项登记。
- 状态归属:共享可变状态只指定一个主要拥有者;其他 Module 必须通过它的 Interface 请求读写,不能越过 Interface 直接修改实现细节。
- Interface 与 Seam:只写调用方必须知道的 Interface 名称、入口和约束载体;字段、错误码、枚举等细节继续留在
CONTRACT.md、代码 Interface 或专门规格中,ARCHITECTURE 只挂链接,避免双源真相。 - 依赖方向:用一张小型 Mermaid 图或一行规则表示允许的代码依赖,并明确禁止的反向依赖。依赖图的箭头必须始终表示“源代码依赖目标”,每条边都应有 import、调用、注册或配置证据。
- 核心流转:仅当运行时消息/数据链路不直观时,再画一到三条主链路。流转图必须标明箭头表示运行时数据或事件,不能拿它代替依赖图;数据可以往返,代码依赖仍可保持单向。
- Adapter 关系:只有确实存在多个实现或明确替换点时,才标出 Interface 后面的 Adapter;不要为了图看起来完整而制造没有消费者的假 Seam。
判断一个 Module 是否清楚,依次问:它只负责什么、拥有什么状态、向外暴露哪个 Interface、允许依赖谁、禁止谁绕过 Interface。内部实现改变而 Interface 不变时,调用方原则上不应跟着修改——这就是架构图要保护的局部性。
生成或更新时必须先读真实代码,不能凭目录名猜:
- 权责、状态拥有者或依赖证据不足 → 标“未验证”或暂不落图,不编造完整架构。
- 小项目、单文件工具、只有两个直观目录 → 不创建
ARCHITECTURE.md,保留最小 MAP。 - ARCHITECTURE 开始过长 → 拆出下级架构文档,但根
ARCHITECTURE.md仍保留总图和索引;不要把细节塞回 MAP。 - 审计时抽查表格、两类箭头和真实代码是否一致;发现跨层直连、状态多头修改、绕过 Interface 或已删除 Module 仍留在图里,按漂移报告。
可选架构、上下文、决策与排期
- Module 权责、状态归属、代码依赖方向或核心流转开始需要团队共享时,才创建根目录
ARCHITECTURE.md;它只记录当前结构,不记录选择理由、Interface 字段、任务或历史。MAP 只指向它。 - 稳定领域术语、概念关系和歧义反复影响协作时,才创建根目录
CONTEXT.md;它不写实现、状态、任务、需求全文或决策。具体边界见context-and-decisions。 - 出现架构、数据库、认证、部署、数据模型或 API 版本等难回退决策时,才创建
docs/adr/README.md和一项决策一个 ADR 文件。MAP 只指向 ADR 索引,不枚举所有决策。 - 任务、负责人、阻塞和项目排期由 GitHub Issues、Linear 或项目已有 Tracker 管理;没有外部 Tracker 时再采用本地
.scratch/。PROJECT_STATUS.md只保留当前健康快照,不承担排期。
分级读取协议(按需读,但红线常驻)
不要每次进会话把四份全量灌进上下文——那是把"文档存在"当成"此刻相关"。读取按分级,判别只有一句话:需求会不会自己报到?
- 会自己报到的(bug 跳出来、要定位某文件、要查健康度)→ 触发时才读,按需。
- 不会报到、却会悄悄咬人的(你正要重建一个故意删掉