Route-Tree 文档路由树协议

铁律

入口永远轻：接收方第一个读的文件是路由树；单层路由表 ≤30 行步骤，超过必须分层（主路由 Phase 级 + 子路由步骤级）。
禁止全文加载：存在路由树的文档，禁止 Read 汇总文档，只能按路由树指引取副文件。
副文件自包含：每个副文件可独立读懂并执行，不依赖其他副文件的内容在场。
共享上下文单点存放：跨步骤共享的信息（项目快照/约束/构建命令）抽到 00-context.md，禁止在每个副文件里重复抄写。
副文件是唯一事实源：路由树只放指针与一行摘要；修改任何副文件后，必须同步更新路由树对应行（摘要/依赖/验收变化时），禁止只改一边。

收益判定：看消费模式，不看文档长相

收益 = 单次加载省下的上下文 × 调用次数 − 路由维护成本

| 变量 | 高收益 | 低收益 | |------|--------|--------| | 单次消费占比 | 每次只用 5-20%（只执行当前步骤/只查一个词条） | 每次要通读 80%+ | | 调用次数 | 反复消费（跨会话执行、多次查阅） | 读一次就归档 | | 文档绝对量 | ≥200 行 | <200 行（全读也不贵，路由开销反而亏） |

两类高收益模式：①阶段式——实施路径，每次只执行一步；②随机查阅式——术语表/ADR/规范/调研存档，按关键词抽查。分条目/分阶段只是信号，不是依据。

反例（分条目也不拆）：一次性审查报告（消费模式是一次通读）；叙事型调研结论（论证链前后依赖，强拆会导致副文件复述内容而膨胀）。

前置评估（收到写计划/规划请求时最先执行）

动手前先估两个数，据此决定产出形态，保证命中准确：

步骤/节点数：计划预计包含几个执行步骤
预估总体量：文档大致总行数

| 评估结果 | 产出形态 | |----------|----------| | 步骤 ≥3 或体量 ≥200 行 | 启用本协议：路由树 + 步骤副文件 | | 步骤 <3 且体量 <200 行 | 直接产出普通小文档，不建路由树 |

跳过评估直接生成路由树（过度拆分），或对达标大文档直接生成单文件（欠拆分），都属违反协议。

适用范围

必须启用：

实施路径 / 执行计划类文档（handoff 的"最快实现路径"、writing-plans 产物），步骤 ≥3 个或预估总量 ≥200 行时
需多次调用的大文档：术语表/ADR 集、项目规范、调研存档

协议级豁免（协议自身的裁剪条款，非执行者自由裁量）：

<200 行且一次性读完的文档（全量加载成本低于路由开销；阈值依据：现有 handoff 实测 64-103 行，200 行约为其两倍）
HTML 报告（浏览器渲染给人看，不是 Agent 执行依据）
一次性阅读的审查报告

生成侧：目录结构

落位规则：项目已有文档目录约定（如 _handoffs/、docs/ 等）则遵循；无约定时创建 _plans/{主题}/。下例以 _handoffs/{主题}/ 示意：

_handoffs/{主题}/
├── route.md              # 主路由树（唯一入口）
└── steps/
    ├── 00-context.md     # 共享上下文（项目快照/约束/命令），按需读
    ├── 01-{步骤名}.md    # 步骤副文件，每个 ≤150 行
    ├── 02-01-{子步骤}.md # 二次拆分：父-子连字号编号
    └── ...

route.md 模板

# 路由树：{主题}

- 目标：{一句话}
- 总步骤：{N}；版本：{V1}
- 共享上下文：steps/00-context.md（首次执行前读一次）
- 进度：最近完成 {S0/无}，下一步 {S1}（{执行者} 更新于 {日期}）

| 步骤 | 副文件 | 依赖 | 一句话验收 |
|------|--------|------|-----------|
| S1 | steps/01-xxx.md | - | {可判定条件} |
| S2 | steps/02-xxx.md | S1 | {可判定条件} |
| S2-1 | steps/02-01-yyy.md | S2 | {二次拆分子步骤，平铺于父步骤下方} |

## 修订记录
| 版本 | 日期 | 变更 | 需重跑步骤 |
|------|------|------|-----------|

大计划分层（步骤 >30 时强制）

route.md 只列 Phase 行（每 Phase 一行，指向子路由）
每个 Phase 一个子路由：steps/{NN}-route.md，内部表格与主路由同构
接收方先读主路由（≤30 行），进入某 Phase 时才读该 Phase 子路由

副文件规则

自包含：包含执行该步骤所需的全部信息——目标文件绝对路径、具体动作、验收方式；拿到单个副文件即可开工
≤150 行：超过则按子步骤拆分，编号用父-子连字号（02 → 02-01、02-02），路由树中平铺于父步骤下方；依赖列支持多依赖（S1, S3）与并行标记（并行）
依赖显式：依赖其他步骤的产出时，副文件头部写明"前置：S1 产出的 XXX"，不复述 S1 的内容
路径绝对化：副文件中引用的所有文件路径必须是完整绝对路径（接收方在新 Quest 无上下文）

接收侧：执行协议

只读 route.md，建立步骤全景、依赖关系与当前进度（一次加载，执行中不回读路由树全文）
首次执行前读一次 00-context.md（若存在）
按"进度"行定位当前步骤 → 只 Read 该步骤副文件 → 执行 → 按副文件内验收方式自验
步骤完成 → 更新 route.md 的进度行（最近完成/下一步/日期），再从已加载的路由树取下一个满足依赖的步骤
遇到缺失信息 → 精确补读单个目标副文件或代码文件，禁止回退到"读全部"

失败处理

步骤执行失败：在 route.md 该步骤行前加 ⚠，并在副文件头部追加"失败记录：{现象+原因}"；重跑还是跳过拿不准时问用户，禁止静默跳过。

中断恢复

新会话接续时：只读 route.md 的进度行即可定位，从"下一步"继续，不重读已完成步骤的副文件。

计划修订

出 V2 时：steps/ 目录全量替换为新版副文件，修订记录表加一行（变更内容 + 需重跑步骤），进度行标注"V2 生效，从 {SX} 重跑"。

生成侧：下游触发提示词（强制输出，提示词即协议）

接收方所在的新 Quest 未必加载本 skill，因此下游触发提示词必须自带执行协议。文档产出后输出：

---
请按路由树协议执行（禁止全文读取任何汇总文档）：
1. 只读路由树入口：{route.md 完整绝对路径}
2. 若存在共享上下文，读一次 steps/00-context.md
3. 按路由树"进度"行定位下一步 → 只读该步骤副文件 → 执行并按副文件内标准自验
4. 每步完成后更新 route.md 进度行；失败在步骤行加 ⚠ 并记录原因

路由树入口：{route.md 完整绝对路径}
---

与既有协议的关系（均为可选联动，未安装对应 skill 时忽略）

| 协议 | 关系 | |------|------| | handoff（若安装） | 功能二产出含实施路径的文档达到阈值时改按本协议生成；本协议的下游提示词替代 handoff 默认提示词（协议内置，不依赖 handoff 修改） | | writing-plans / executing-plans | builtin 不可修改；生效机制完全依赖生成侧输出的下游提示词携带接收协议（提示词即协议），不依赖对方感知本 skill（此项与平台无关，独立生效） | | red-team-attack（若安装） | 其 knowledge/_registry.md + playbooks/ 是本模式的特化实现，结构兼容 |

输出格式：路由树交付说明

生成完成后向用户输出：

## 路由树已生成
- 入口：{route.md 完整绝对路径}
- 步骤数：{N}（副文件 {N} 个，二次拆分 {N} 个），共享上下文 {有/无}
- 下游提示词已携带接收协议，接收方无需加载本 skill