| name | governance-docs-standard |
| description | 【WHEN】当用户要新增/修改/评审“治理层文档”（README.md、CLAUDE.md、以及用户显式指定的其他治理层文档）时启用； 【WHEN】当输出提案 vN.md、落地修改治理层文档、或产出 vN-review.md 时启用。 【WHEN NOT】不用于业务功能开发、不用于代码实现细节、不用于非治理层文档（如普通开发笔记/模块设计/接口文档）。 |
治理层文档全局规范（Governance Docs Standard）
0. 全局术语（强约定）
- README.md / CLAUDE.md / 用户显式指定的其他治理层文档：统称为「治理层文档」。
- 治理层最大风险：迭代过程中术语混乱、内容重叠、边界模糊 → 最终“屎山”。
1. 两条最高优先级目标（反屎山锚点）
1.1 术语治理优先（防术语屎山）
- 原则：一词一义、一义一处权威定义（Single Source of Truth）
- 任何新增/修改必须优先检查：
- 是否引入同义词/近义词导致漂移
- 是否破坏既有术语含义
- 是否造成“同一概念在多处被不同表述定义”
- 处理方式：选定唯一“权威来源”，其他位置只允许引用/索引，禁止复制粘贴。
1.2 上下文成本与噪声治理（防上下文屎山）
- 目标：降低上下文成本、降低噪声污染，避免治理层文档越写越重。
- 原则：引用优先、按需展开、渐进加载
- 能引用不复制
- 能索引不展开
- 永远加载的内容（CLAUDE.md）保持极简，其余内容渐进加载
2. 加载事实与由此推导的策略（事实 → 设计）
2.1 事实：CLAUDE.md 会被默认自动加载
- 该事实不需要任何设定，也不应被表述成“规则”。
2.2 推导：基于自动加载事实，采用渐进式加载策略
- CLAUDE.md：必须极简、承载最全局通用信息，并作为治理层索引枢纽（指向其他治理层文档/Skill）。
- 其他治理层文档：用于按主题承载规则/边界/裁决口径，按需渐进加载。
- README.md：面向人类的项目入口与 QuickStart，保持自然通俗简洁。
3. 文档分工（定位与约束）
3.1 CLAUDE.md（AI 永远加载：全局宪法 + 索引枢纽）
应包含（仅最必要项）：
- 环境与运行前提（开发环境、路径约定、工具可用性等）
- 全局强约定 / 强偏好（必须遵守）
- 全局概念层术语（最小必要词汇表/指代体系）
- 索引：指向其他治理层文档与按需 Skill（用于渐进展开） 强约束：
- 必须简洁；禁止堆长段解释/检查清单
- 避免与 README/其他治理层文档内容重叠（重叠=噪声）
3.2 README.md（面向人类：简介 + QuickStart + 特点）
应包含：
- 项目是什么/适合谁/解决什么
- 自然通俗的 QuickStart（面向人类）
- 项目特点与导航入口 强约束：
- 不把 AI 规则/工程强约定/术语规范写成规章大全
- 不写实现细节；治理规则下沉到 CLAUDE 索引的治理层文档/Skill
3.3 其他治理层文档（渐进式加载：按项目清单占位）
- 占位符：
{GOVERNANCE_DOCS}由项目显式给出（路径清单）。 - 每份文档必须“聚焦一个治理主题”，避免泛化到全局。
4. 治理层文档本体的“最小画像块”（唯一要求写进文档本体）
目的：让每份治理层文档在不堆规则的情况下，仍然定位清晰、边界清晰、权威归属清晰。
每份治理层文档（包括 CLAUDE/README/其他）都应在开头提供一个极短画像块，至少包含：
- 定位一句话
- 适用范围（1
3 条）/ 不适用范围（13 条） - 权威性声明（它管什么）
其余“规则、检查清单、评分标准、去重机制”一律留在本 Skill 中，不写进治理层文档正文，以防噪声污染。
5. 内容重叠与边界模糊的处理机制（留在 Skill，不落文档正文）
5.1 权威来源规则（去重）
- 每个概念/规则/定义只能有一个“权威来源”（owner）。
- 其他文档禁止复制粘贴，只允许：
- 1~2 句摘要 + 指向权威来源的引用/索引。
5.2 术语引入规则（防漂移）
- 新增术语必须：
- 不与既有术语冲突
- 不制造同义词漂移
- 明确其权威定义归属（哪份治理层文档/或 CLAUDE 概念层）
6. 提案与复审（贯穿工作流的统一依据）
6.1 vN.md（修改/优化意见文档）锚点
- 用户不满点（尽量保留原话）
- 诊断：术语/重叠/边界/噪声问题分别在哪里（逐文档）
- 改造策略：引用与索引如何调整（减少噪声、按需展开）
- 具体改动：按文档列出“删/移/引/补索引”的清单
- 验收口径：问题解决 + 规则遵守（见 6.2）
6.2 vN-review.md（打分制简报）评分锚点（只评两项）
- 问题解决（针对用户不满点）：0-5（给证据位置）
- 规则遵守（是否破坏规范）：0-5（重点查术语一致/去重/边界/CLAUDE 是否被污染）
7. 新增信息的放置决策与扩展报备（强约束）
- 任何新增信息先判断放置位置，避免长段内容污染文档定位：
- AI 永远需要知道的全局信息 → 才进入 CLAUDE.md（仍需极简）
- 面向人类入口信息 → README
- 特定治理主题规则/边界 → 其他治理层文档（渐进加载）
- 如需新增“新的治理层文档/新的 Skill”：
- 必须向用户报备申请，不可自行创建
- 未获批准前：允许在 CLAUDE.md 写一句占位索引（含 TODO），但不生成实体内容
- 示例：
关于 XX，请查看 @{索引路径} # TODO
- 示例：