长文档治理

1. 何时触发

三种入口（任一成立即触发本 skill）：

1. 增量触发：本轮任务要对某文档做"实质修改"，且该文档行数 ≥ 强制阈值（见下方阈值表）
2. 主动调用：用户说"帮我拆 XXX"、"这个文档太长了"
3. 检测报告：post-change-check 输出了 [CRITICAL] 行且本轮有实质修改

不触发：归档目录（默认匹配路径含「归档」的目录，项目可在配置里改）下的文档；AGENTS.md / SKILL.md 不受管控。

2. 实质修改 vs 微改

实质修改（触发治理）

• 新增章节或 H2/H3 标题
• 新增接口、字段、业务规则
• 改设计描述或状态流转
• 重写段落（语义增量 > 20 行）

微改（豁免）

• 错别字、纯排版调整
• 链接修复、版本号 bump
• 纯措辞润色（< 20 行改动）

自检方式：git diff --stat 看增删行数；语义增量 > 20 行 或 新增 H2/H3 → 实质修改。

反例（不能当微改）：重写一段 50 行的设计描述；把一个功能从一处搬到另一处；新增接口参数说明。

3. 阈值表

只对 docs/ 下业务文档生效；AGENTS.md / SKILL.md 不扫描。

扫描命令：bash <本 skill 目录>/scripts/doc-length-check.sh --format human --scope <file>（脚本随本 skill 附带，默认阈值在同目录 doc-length-config.default.json，项目可用 .agents/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 锚点仍然存在。

步骤五：验证

# 若项目存在文档层级检查门禁脚本（如 .agents/hooks/pre-commit-check.sh）则运行；没有则人工核对
bash .agents/hooks/pre-commit-check.sh

确认层级编号检查通过。

步骤六：提交

重构: 长文档治理 — 03-01-前后端接口协议 拆分为 03-01/ 子目录