Long doc governance

Skill BackToCimaCoppi/Praxis/skills/long-doc-governance

给「AI 驱动开发」立规矩的 Claude Code skill 方法论库：七层文档治理 · 对抗评审 · 任务总控三驾马车，外加老代码考古、施工蓝图等共 16 个 skill —— 让 AI 写代码又快又不失控。

Install

npx -y skills add BackToCimaCoppi/Praxis --skill long-doc-governance

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

长文档治理 skill。当 post-change-check 报 [CRITICAL] 长文档警告，或用户主动要求"拆文档"、"文档太长"时触发。核心机制：增量治理（不主动拆现有文档，仅在对超长文档做实质修改时治理）、微改豁免、拆分预算退路。触发词："拆文档"、"文档太长"、"split doc"、"文档拆分"。

SKILL.md

3.9 KB, as published. Nobody here has run it

长文档治理

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>    # 列出所有 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/ 子目录