long-doc-governancelisted

# 长文档治理 ## 1. 何时触发 三种入口（任一成立即触发本 skill）： 1. **增量触发**：本轮任务要对某文档做"实质修改"，且该文档行数 ≥ 强制阈值（见下方阈值表） 2. **主动调用**：用户说"帮我拆 XXX"、"这个文档太长了" 3. **检测报告**：`post-change-check` 输出了 `[CRITICAL]` 行且本轮有实质修改 **不触发**：归档目录（`05-归档/`、`06-05-归档/`）下的文档；`CLAUDE.md` / `AGENTS.md` / `SKILL.md` 不受管控。 --- ## 2. 实质修改 vs 微改 **实质修改（触发治理）** - 新增章节或 H2/H3 标题 - 新增接口、字段、业务规则 - 改设计描述或状态流转 - 重写段落（语义增量 > 20 行） **微改（豁免）** - 错别字、纯排版调整 - 链接修复、版本号 bump - 纯措辞润色（< 20 行改动） **自检方式**：`git diff --stat` 看增删行数；语义增量 > 20 行 或 新增 H2/H3 → 实质修改。 **反例（不能当微改）**：重写一段 50 行的设计描述；把一个功能从一处搬到另一处；新增接口参数说明。 --- ## 3. 阈值表 只对 `docs/` 下业务文档生效；`CLAUDE.md` / `AGENTS.md` / `SKILL.md` 不扫描。 | 类型 | 覆盖范围 | 警告阈值 | 强制阈值 | |---|---|---|---| | 接口协议 / 测试 / Schema | `*接口*`、`*数据库*`、`*schema*`、`04-测试/` 等路径模式（由项目自定义） | 600 行 | 1000 行 | | 设计文档 / 总控 | `01-需求/`、`02-页面设计/`、`03-技术设计/`、`06-任务总控/`（非归档）、施工蓝图 / goal 章程、任务总控、技术方案 | 800 行 | 1500 行 | 扫描命令：`bash ~/.claude/scripts/doc-length-check.sh --format human --scope <file>` --- ## 4. 拆分预算评估 拆分前先估算工作量： ``` 预估时间 ≈ 目标文档行数 / 200 × 5 分钟 ``` 若 `预估时间 > 主任务工作量 × 1.5` → **停下来问用户三选一**，不要自作主张： > 「`<文件名>` 共 X 行，拆分预估约 Y 分钟，主任务约 Z 分钟。建议： > A. 先拆再做（一次付清） > B. 单独排一个拆分任务，本次先改完 > C. 本次例外，在任务级设计文档（轻量设计方案/任务总控）写明原因」 --- ## 5. 拆分操作流程 ### 步骤一：分析结构 ```bash grep -n "^## " <file> # 列出所有 H2 标题与行号 wc -l <file> # 总行数 ``` 识别业务边界（按功能模块，不按行数）。 ### 步骤二：规划子文件 目标：每个子文件 < 警告阈值 × 70%。 拆分模板： ``` 原文件: 03-01-前后端接口协议.md ↓ 03-01-前后端接口协议/ ├── 00-总览与公共约定.md ← 鉴权、错误码、分页、命名约定 ├── 01-用户模块.md ├── 02-订单模块.md └──