---
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 条）/ 不适用范围（1~3 条）**
- **权威性声明（它管什么）**

> 其余“规则、检查清单、评分标准、去重机制”一律留在本 Skill 中，不写进治理层文档正文，以防噪声污染。

## 5. 内容重叠与边界模糊的处理机制（留在 Skill，不落文档正文）
### 5.1 权威来源规则（去重）
- 每个概念/规则/定义只能有一个“权威来源”（owner）。
- 其他文档禁止复制粘贴，只允许：
  - 1~2 句摘要 + 指向权威来源的引用/索引。

### 5.2 术语引入规则（防漂移）
- 新增术语必须：
  - 不与既有术语冲突
  - 不制造同义词漂移
  - 明确其权威定义归属（哪份治理层文档/或 CLAUDE 概念层）

## 6. 提案与复审（贯穿工作流的统一依据）
### 6.1 vN.md（修改/优化意见文档）锚点
- 用户不满点（尽量保留原话）
- 诊断：术语/重叠/边界/噪声问题分别在哪里（逐文档）
- 改造策略：引用与索引如何调整（减少噪声、按需展开）
- 具体改动：按文档列出“删/移/引/补索引”的清单
- 验收口径：问题解决 + 规则遵守（见 6.2）

### 6.2 vN-review.md（打分制简报）评分锚点（只评两项）
1) **问题解决（针对用户不满点）**：0-5（给证据位置）
2) **规则遵守（是否破坏规范）**：0-5（重点查术语一致/去重/边界/CLAUDE 是否被污染）

## 7. 新增信息的放置决策与扩展报备（强约束）
- 任何新增信息先判断放置位置，避免长段内容污染文档定位：
  - AI 永远需要知道的全局信息 → 才进入 CLAUDE.md（仍需极简）
  - 面向人类入口信息 → README
  - 特定治理主题规则/边界 → 其他治理层文档（渐进加载）
- 如需新增“新的治理层文档/新的 Skill”：
  - **必须向用户报备申请**，不可自行创建
  - 未获批准前：允许在 CLAUDE.md 写一句占位索引（含 TODO），但不生成实体内容
    - 示例：`关于 XX，请查看 @{索引路径} # TODO`