BackToCimaCoppi 长文档治理
1. 何时触发
三种入口（任一成立即触发本 skill）：
- 增量触发：本轮任务要对某文档做"实质修改"，且该文档行数 ≥ 强制阈值（见下方阈值表）
- 主动调用：用户说"帮我拆 XXX"、"这个文档太长了"
- 检测报告：
post-change-check输出了[CRITICAL]行且本轮有实质修改
不触发：归档目录（默认匹配路径含「归档」的目录，项目可在配置里改）下的文档；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-技术设计/、00-任务总控/（非归档）、施工蓝图 / goal 章程、任务总控、技术方案 |
800 行 | 1500 行 |
扫描命令：bash <本 skill 目录>/scripts/doc-length-check.sh --format human --scope <file>（脚本随本 skill 附带，默认阈值在同目录 doc-length-config.default.json，项目可用 .claude/doc-length-config.json 覆盖）
4. 拆分预算评估
拆分前先估算工作量：
预估时间 ≈ 目标文档行数 / 200 × 5 分钟
若 预估时间 > 主任务工作量 × 1.5 → 停下来问用户三选一，不要自作主张：
「
<文件名>共 X 行，拆分预估约 Y 分钟，主任务约 Z 分钟。建议： A. 先拆再做（一次付清） B. 单独排一个拆分任务，本次先改完 C. 本次例外，在任务级设计文档（轻量设计方案/任务总控）写明原因」
5. 拆分操作流程
步骤一：分析结构
grep -n "^## " <file> # 列出所有 H2 标题与行号
wc -l <file> # 总行数
识别业务边界（按功能模块，不按行数）。
步骤二：规划子文件
目标：每个子文件 < 警告阈值 × 70%。
拆分模板：
原文件: 03-01-前后端接口协议.md
↓
03-01-前后端接口协议/
├── 00-总览与公共约定.md ← 鉴权、错误码、分页、命名约定
├── 01-用户模块.md
├── 02-订单模块.md
└── 03-第三方集成.md
步骤三：执行拆分
- 原文件改名并移入新目录，保留索引（
00-总览列各子文件链接） - 子文件路径遵守层级编号规则（
NN-名称.md）
步骤四：修复引用
# 全仓搜旧路径引用（.md / .java / .ts 均查）
grep -rn "旧文件名" . --include="*.md" --include="*.java" --include="*.ts"
逐个修复为新路径，确保 anchor 锚点仍然存在。
步骤五：验证
# 若项目存在文档层级检查门禁脚本（如 .claude/hooks/pre-commit-check.sh）则运行；没有则人工核对
bash .claude/hooks/pre-commit-check.sh
确认层级编号检查通过。
步骤六：提交
重构: 长文档治理 — 03-01-前后端接口协议 拆分为 03-01/ 子目录