| name | long-doc-governance |
| description | 长文档治理 skill。当 post-change-check 报 [CRITICAL] 长文档警告，或用户主动要求"拆文档"、"文档太长"时触发。核心机制：增量治理（不主动拆现有文档，仅在对超长文档做实质修改时治理）、微改豁免、拆分预算退路。触发词："拆文档"、"文档太长"、"split doc"、"文档拆分"。 |
长文档治理
1. 何时触发
三种入口（任一成立即触发本 skill）：
- 增量触发：本轮任务要对某文档做"实质修改"，且该文档行数 ≥ 强制阈值（见下方阈值表）
- 主动调用：用户说"帮我拆 XXX"、"这个文档太长了"
- 检测报告：
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-任务总控/（非归档）、施工蓝图、任务总控、技术方案 | 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. 拆分操作流程
步骤一：分析结构
grep -n "^## " <file>
wc -l <file>
识别业务边界（按功能模块，不按行数）。
步骤二：规划子文件
目标：每个子文件 < 警告阈值 × 70%。
拆分模板：
原文件: 03-01-前后端接口协议.md
↓
03-01-前后端接口协议/
├── 00-总览与公共约定.md ← 鉴权、错误码、分页、命名约定
├── 01-用户模块.md
├── 02-订单模块.md
└── 03-第三方集成.md
步骤三：执行拆分
- 原文件改名并移入新目录，保留索引（
00-总览 列各子文件链接）
- 子文件路径遵守层级编号规则（
NN-名称.md）
步骤四：修复引用
grep -rn "旧文件名" . --include="*.md" --include="*.java" --include="*.ts"
逐个修复为新路径，确保 anchor 锚点仍然存在。
步骤五：验证
bash .claude/hooks/pre-commit-check.sh
确认层级编号检查通过。
步骤六：提交
重构: 长文档治理 — 03-01-前后端接口协议 拆分为 03-01/ 子目录
