Living Docs Governance

活文档治理（Living Docs Governance）

长期项目最先腐烂的是文档层：README 在撒谎、架构笔记描述着一次从没上线的重构、每次进会话 agent 都在重新推导本该一读就懂的上下文。活文档治理把项目文档当成一个小的、各司其职的系统，而不是一堆散文件：四份互相链接的文档，每份只干一件事，外加一个 agent 进会话时读它们的固定顺序。

本技能覆盖首次 setup 与后续维护。setup 把真实项目资料接成可维护的文档入口；维护让它在几个月的改动后依然为真。只想了解陌生代码库、不准备配置文档时，用代码库 onboarding 类技能。

在 Claude Code 中，可由配套的 docs-governor / docs-auditor agent 执行；在 Codex 或没有这些自定义 agent 的宿主中，由当前 agent 直接按本 skill 执行，必要时再使用宿主提供的只读探索或执行型子 agent。本 skill 始终是方法论唯一来源。

什么时候启用

满足任一条就启用：

• 项目长过几个模块，文档开始和代码漂移。
• agent 或队友在会话之间丢失上下文，反复重新发现同一套结构。
• 没人能从单一位置回答"这项目现在健康度如何？""上周改了啥？"。
• 死文件和废弃实验堆积，偶尔被误重建。
• 你想给一个单人/小团队项目一层耐用、低开销的治理，又不想上大型多人仓库那套重 CI 机器。

不要在用完即弃的脚本、或活不过这周的仓库上用——那是过度治理。

渐进式采用：从最小开始，但提前看到下一级

别一上来铺满四件套——那本身就是过度治理。从最小起步，真正关键的不是"按需补"，是提前认出"下一级快需要了"的预警信号，在它真痛之前就备好。等漂移出事（STATUS 撒谎、重建已删文件）才补，文档已经烂了一轮、返工已经发生——治理的价值在防患，不在救火。

预警信号的意义：让你在痛之前上对应那一级，而不是等它腐烂出事再救火。

团队共享 vs 个人：治理文件放哪一层

四件套是项目级、团队共享的——进 git，所有协作者 / agent 共用，写的是"团队共识的真相"。个人临时偏好别塞进去（会污染团队视图）：那些放 CLAUDE.local.md（同目录、不提交）或 ~/.claude/（全局个人）。判据一句话：帮整个团队一致 → 进项目四件套；只是你一个人的习惯 → 进 .local / 全局。

怎么运作

这套系统 = 四份脊柱文档（角色严格分离）+ 分级读取协议 + 让它们保持最新的更新规则 + 阶段收尾时的查漏补缺矩阵。CONTEXT.md、docs/adr/、契约、测试和回归台账都是按真实需要长出的血肉，不是第五到第九份必建脊柱。

本文以插件现有的 CLAUDE 主源布局说明文档角色；项目若已有 AGENTS 主源，沿用其约定。入口具体写什么、依据什么事实生成、如何精简与检查，统一执行 skills/documentation/agent-entrypoints/SKILL.md；本文继续负责其他载体及读序。审计脚本和模板仍有 CLAUDE 默认布局，采用不同布局时按目标项目核对适配，不自动迁移规则主源。

Claude Code / Codex 入口适配

两端共用本 skill，不复制方法论：

所有宿主直接执行本文对应模式。Claude commands/agents 只选择模式和执行角色；Codex / ChatGPT 由当前 agent 执行，不反向读取 commands/agents。只读审计、只读复盘保持只读。

审计支持 spine、context、adr、artifacts、full 五种范围。先运行 scripts/audit-cheap.sh <scope> 做确定性检查；断链失败就短路，只有通过后才进入语义判断。默认只读；只有用户明确要求保存时，才把报告写入 docs/audits/YYYY-MM-DD-*.md。

四份文档与各自的职责

让它生效的纪律是非重叠：每个事实只有一个权威来源，其他载体只引用。"auth 模块在哪？"→ 地图。"覆盖率现在健康吗？"→ STATUS。"旧解析器啥时候删的、为啥？"→ LOG。每份只干一件事，就不会一起烂。

事实按类型认来源：规则、决策与历史由相应文档维护，接口字段由唯一机器契约定义；测试与审查结论引用实际运行的版本、范围、结果和证据位置。项目已有工程 Skill 继续负责代码审查，治理层只核对与引用其证据。STATUS 保存带来源的健康快照，相关实现或验收条件变化后标待复验，不把旧绿色结果延续为当前结论；无法确认版本或范围时明确写未验证。

可选文档与排期

• 需要判断项目是否应建立架构文档，或生成、完善、审查现有架构说明 → skills/documentation/architecture-docs/SKILL.md；返回必要性、依据和主记录位置。
• 稳定领域术语、概念关系和歧义反复影响协作时，才创建根目录 CONTEXT.md；它不写实现、状态、任务、需求全文或决策。具体边界见 context-and-decisions。
• 出现架构、数据库、认证、部署、数据模型或 API 版本等难回退决策时，才创建 docs/adr/README.md 和一项决策一个 ADR 文件。MAP 只指向 ADR 索引，不枚举所有决策。
• 任务、负责人、阻塞和项目排期由 GitHub Issues、Linear 或项目已有 Tracker 管理；没有外部 Tracker 时再采用本地 .scratch/。PROJECT_STATUS.md 只保留当前健康快照，不承担排期。

分级读取协议（按需读，但红线常驻）

不要每次进会话把四份全量灌进上下文——那是把"文档存在"当成"此刻相关"。读取按分级，判别只有一句话：需求会不会自己报到？

• 会自己报到的（bug 跳出来、要定位某文件、要查健康度）→ 触发时才读，按需。
• 不会报到、却会悄悄咬人的（你正要重建一个故意删掉的文件，没任何信号提醒你）→ 必须常驻，不能等触发。

按这个分，四份文档各自的读取策略：

使用 Codex 或多个宿主时，由 agent-entrypoints 确定实际入口与共享主源，并挂上本文的分级读取路标。项目以 CLAUDE 为主源时才使用 templates/AGENTS.example.md 薄桥接；已有完整 AGENTS 主源时保留正文，不套桥接模板覆盖。

常驻成本压到最小：CLAUDE 全文 + STATUS 红线几行。大头（完整 MAP、ARCHITECTURE、STATUS 指标、整本 LOG）全按需。LOG 之外的当前真相载体是 projection（决定此刻喂什么），LOG 是 transcript（记录发生了什么）。

两条护栏（防"该读没读"——这是按需读唯一的真风险）：

1. 不确定就升级全读。 拿不准这次要不要读完整 MAP/STATUS → 默认读全，不要为省 token 赌一把。省 token 是小钱；在过期地图上铺代码、重建已删文件是大坑。
2. 动手改文件前必读，不只是进会话时。 真正的危险不在进会话，在你准备新建 / 删除 / 重命名文件、跨目录改动那一刻——这些操作强制先读完整 CLAUDE_MAP.md 对应段 + PROJECT_STATUS.md 删除区，确认没踩禁区、没复活已删文件。

LOG 防腐：按事件计数 + 复盘 + 可重建索引。 PROJECT_LOG.md 的事件格式是 ## [日期] 类型 | 摘要；阈值按事件数计算，不按原始行数。活跃事件不超过 200 条时只用 Markdown；超过 200 条后：

1. 先只读复盘：识别重复问题和应下沉的 lint / TEST-ID / 回归保护。
2. 经用户确认再归档：运行 python3 <插件目录>/scripts/project-log-index.py archive --root <项目根> --yes。旧事件原样进入 PROJECT_LOG.archive.md，活跃 LOG 默认保留最近 100 条；归档是受控压缩例外，不得手工删改历史。
3. 建立派生索引：脚本从活跃 LOG + archive 重建 .governance/project-log.sqlite。数据库默认进 .gitignore，不是唯一事实源；损坏或删除后运行 rebuild 即可恢复。
4. 分类不猜：类型取事件头；模块只在明确写出或能从真实路径解析时登记，否则为 unclassified；引用只提取 commit、TEST-ID、ADR、CONTRACT 和明确路径。内容哈希保证幂等。
5. 失败不伤原文：解析、归档或建库失败时，不得留下被截断的 PROJECT_LOG.md。审计以活跃文件和 archive 的事件合集判断只追加完整性。
6. 目录 + 内容分层：主 LOG 只当目录——每条一行（## [日期] 类型 | 一句话），需要长详情（完整审计报告、大段修复记录）时下沉到独立文件（如 docs/log-details/2026-07-03-audit.md），目录行尾挂链接。主 LOG 永远短、可整读；详情按需点开。这就是「脊柱保持瘦、血肉下沉」用在 LOG 自己身上。
7. 复盘统计（LOG 不只是负担，是资产）：归档前跑一次 /governance-retro，统计哪个模块出错最多、哪类错误重复出现、标准变更了几次——重复 TOP 的错误 = "该下沉成 lint / 回归测试"的候选清单（见 module-regression 铁律"坑必下沉"）。同一个坑在 LOG 里出现第二次，说明它还没被机器接管。

防腐烂的更新规则

• 改了路径、入口、知识载体或误导区 → 同一次改动里更新 CLAUDE_MAP.md。
• 模块分工、状态、接口、依赖或核心流程变化 → 同次按 architecture-docs 核对受影响的架构记录。
• 指标越过阈值，或你故意删了某文件 → 更新 PROJECT_STATUS.md，并把路径加进删除区，免得被重建。
• 有意义的变更、决策或验证结果 → 往 PROJECT_LOG.md 追加一行，说明结果与必要理由；写入前按阶段归纳，不为重复读取、重试或相同结论另写流水账。已有提交护栏仍按项目约定执行。
• AGENTS.md / CLAUDE.md 的长度与精简按 agent-entrypoints 第 1 条执行，每份不超过 200 行；关键约束留在入口，细节下沉并保留路标。
• 标准变更留痕：任何验收阈值 / 联动规则 / 契约字段的修改（如 <0.01 放宽到 <0.1、REGRESSION 联动规则改松），必须在 PROJECT_LOG.md 追加一条「标准变更：旧值 → 新值 + 理由」。审计时对照 Git 历史检查标准变化和对应记录；缺失时报告具体变化、可能影响和待补依据，按下述规则分级，不直接认定为 P0。

风险分级与维护成本

• 优先沿用项目已定义的严重级别。未定义时，P0 用于有证据表明必须立即阻止的严重损害（如正在发生的数据丢失或越权）；P1 用于已确认会误导实现或阻塞关键路径、需要优先修复的问题；P2 用于一般维护改进。证据不足时标“待核实”，写清可能影响和缺少的证据。
• 覆盖率、测试数量、审计间隔和一般文档行数是检查线索，阈值由项目约束决定；Agent 入口另有 agent-entrypoints 的 200 行硬验收，不能降为建议。越线不凭单一数值自动定为 P0，严重级别仍看实际影响；普通验证缺口和维护建议放按需读取区，任务安排仍归 Issue Tracker。
• 只更新本次变更实际影响的文档。业务项目试点时，可在现有审计或复盘记录中观察接手耗时、重复解释、提前发现的问题和文档维护成本；没有测量就标未知，不另建一套指标台账。

阶段收尾同步

当用户说"同步一下"、"整理文档"、"收尾"、"这个阶段做完了"、"新人能接手"，或运行 /governance-sync 时，不要只追加 PROJECT_LOG.md。先按 references/governance-sync-matrix.md 判断本次变化应该影响哪份治理文档：

• 路径、入口、知识载体、误导区、跳转表 → CLAUDE_MAP.md
• Module 权责、状态归属、Interface、代码依赖方向、核心流转 → ARCHITECTURE.md（若已启用或已达到启用条件）
• 风险、测试缺口、指标、待删区 → PROJECT_STATUS.md
• 长期硬规则、读序、不可妥协约定 → CLAUDE.md
• 重要历史事件 → PROJECT_LOG.md（只追加）
• 前后端接口字段 → CONTRACT.md（若项目有契约治理）
• 领域术语或关系变化 → CONTEXT.md（若存在且证据已确认）
• 难回退技术决策 → docs/adr/（若触发 ADR）
• 产品十阶段产物、PRD 基线、需求评审和运营反馈 → product-evolution；复用 docs 下产品入口，任务状态留在 Tracker

关键区别：PROJECT_LOG.md 是记录员，只追加历史；CLAUDE_MAP.md / ARCHITECTURE.md / PROJECT_STATUS.md / CLAUDE.md 是编辑过的当前真相，发现旧事实过期要修正、合并或删除。

文档角色分层（管 4 件套之外的全部文档）

四件套是脊柱，但真实项目还有规范、设计记录、参考、审计产物等一大堆血肉文档。治理纪律（一文一职、非重叠、按需读、防漂移）对全体文档都适用，不止四份。给任意一份文档定位，用一条判据 + 三条纪律。