Legacy archaeology

Skill BackToCimaCoppi/Praxis/skills/legacy-archaeology

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

Install

npx -y skills add BackToCimaCoppi/Praxis --skill legacy-archaeology

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

从老旧黑盒代码反推「树形索引、逐层下钻」的知识库（业务逻辑/数据库/接口三层），给重构 AI 注入背景。承诺「边界内可审计覆盖 + 残余风险显式登记」，不承诺零遗漏。触发词：「老代码考古」「反推知识库」「重构前背景」「把老项目翻译成文档」「legacy 调查」。

SKILL.md

27.5 KB, as published. Nobody here has run it

legacy-archaeology（老代码考古）

把一个黑盒老项目反推成「树形下钻、业务/库/接口讲清」的知识库，给后续重构的 AI 做背景注入。 承诺只到「边界内可审计覆盖 + 残余风险显式登记」——不吹「我没漏」，只保证「我已识别的盲区、未证实项、未获取的真值源都显式登记了」。

这个 skill 是一个编排器，不是文档生成器。它指挥主 agent 粗扫、切块、派出 agent team 逐模块调查，把结果汇聚成一棵 README 层层索引的知识库树。一个项目一棵树，多个项目共享一个平台层调用图。重构 AI 平时只读 L1，要哪块钉哪块往下读：省上下文，又能审计到每一处盲区。

§1 干什么 / 不干什么（边界）

1.1 只产三层，不碰其余

产出：业务逻辑 / 数据库 / 接口。这三层讲清楚，足够给重构 AI 注入背景。
不碰：需求文档、代码实现细节、测试。它们要么是重构后才重写的（需求），要么是被替换掉的（代码、测试）。把它们写进来只会增重、过期、抢上下文。
不描述代码：讲的是「系统做什么决策、存什么数据、暴露什么契约」，不是「类怎么继承、方法怎么调」。描述代码 = 把旧包袱原样搬进新系统。

1.2 读者是 AI，不是人

风格索引重、表格化、叙事轻。每个目录一个 README 当导航节点，逐层下钻。
不写给人读的连贯散文；写给 AI 检索：标题密、锚点全、状态标注清楚。

1.3 一次性快照

老项目不再大改、不会继续腐烂，所以不设防过期机制。这是某一时刻的考古快照，带「快照批次号」。
推论：不必为「文档与代码持续同步」付出任何设计成本——那是 doc-layer-system 的活，不是这里的活。

1.4 承诺口径（地基，全文不得违反）

本 skill 不承诺「业务逻辑零遗漏」。 白盒静态扫描无法证明「我枚举出来的 = 系统里全部」，把无法证明的东西写成承诺就是自欺。

本 skill 承诺的是：① 边界内可审计覆盖（写下来的每条都有源码锚点、可回查）； ② 残余风险显式登记（没覆盖到的、没证实的、失传的，全部明确列出来，不藏）。

任何产物、任何对账，禁止出现「已查全 / 零遗漏 / 完整」字样。只能说「在已知枚举边界内已覆盖，未覆盖部分见残余风险清单」。

1.5 与其他 skill 的边界

本 skill 与 code-to-guide、code-to-7layer 机制有重叠，但定位不同。逐机制区别见 references/与现有skill边界对照.md。一句话：本 skill 只产「重构背景知识索引」，不产需求结论、不产七层正式真值；能复用的已验证机制（fan-out、证据分级、硬暂停）尽量复用，不另造轮子。

§2 产出落点 & 路径命名规范（索引承重墙）

这个 skill 的路径就是索引本身。 重构 AI「读 L1 → 钉下去」靠的全是各层 README 里的下钻链接，链接就是相对路径。命名不钉死 → 增量建库（一次一个项目、跨多次运行）时结构漂移、导航断链。所以路径规范是硬约束，不是建议。

2.1 固定骨架（雷打不动）

<知识库根>/
  README.md                    ← 平台总览（导航总入口）
  _platform/                   ← 下划线前缀，永远排最前、区别于业务项目
    service-registry.md        ← 稳定服务标识注册表（防重名 / 防仓名漂移）
    call-graph.md              ← 服务调用图（稳定标识做主键 + 悬空边 + 待接通清单）
    platform-coverage.md       ← 覆盖率总台账（各项目进度 + 残余风险汇总）
  <服务标识>/                   ← 一个项目一棵树
    README.md                  ← L1：概况 + 模块清单 + 可选流程/场景索引 + 台账链接
    discovery-ledger.md        ← 发现来源台账（枚举策略 / 命中范围 / 未识别入口）
    coverage-ledger.md         ← 对象覆盖台账（逐对象认领状态）
    <模块名>/                   ← 裸名，无前缀
      README.md                ← L2：模块概览 + 下钻链接
      business-logic.md        ← L3 叶子（固定 ASCII 文件名）
      database.md              ← L3 叶子
      api.md                   ← L3 叶子

2.2 三条硬规则

每个目录必有 README.md 作导航节点：列出本层子项 + 逐个下钻相对链接。缺一个就断链。
叶子文件名固定三个 ASCII 名：business-logic.md / database.md / api.md。AI 不用猜去哪读。
- 为何 ASCII：文件名是机器导航锚点。中文文件名在不同 OS / core.quotepath / URL 编码锚点 / grep 脚本上行为不一致（会被转义成乱码）。文件名/目录骨架用 ASCII，正文内容全中文。
链接一律相对路径（整库可整体搬迁，本地解析）。

2.3 拆分规则（接 long-doc-governance）

business-logic.md 写长了 → 升级成 business-logic/ 子目录（内含 README.md 索引 + 若干 business-logic-<子主题>.md）。升级方式固定，不让 AI 自由发挥。
拆分必须配套修链：拆完跑一遍全仓链接校验，修复所有指向旧 business-logic.md#锚点 的引用（复用 long-doc-governance 的引用修复步骤）。漏修 = 断链。

2.4 服务标识（去仓名耦合）

<服务标识> 是节点的唯一身份，登记在 _platform/service-registry.md。
新建一个服务目录前，先查注册表防重名。 源仓库名 / 制品名只作「来源字段」记录，不充当唯一身份 ——因为仓名会改、会重复、会合并拆分、可能含敏感缩写，押在它上面会让同一服务在调用图里分裂成两个节点。

2.5 输出落点

引擎只硬要求一件事：一个输出根目录 + 一个快照批次号。
「中央知识库仓」是推荐布局（所有服务树 + 平台层收在一处，重构 AI 一站式读），不是硬前提。没有独立知识库仓的团队，给一个根目录即可。
开工第一件事：向用户确认 ① 输出根目录 ② 本次调查哪个项目 ③ 快照批次号（默认日期）。

§3 编排总则（有预算、有终止、状态落盘）

主 agent 全权调度，但不是无限自由——必须有预算、有终止、状态不放在记忆里。

3.1 工具语义铁律（决定整套编排形状）

子 agent 一旦派出，跑完才返回，无法中途停下来问用户。

所以一切「问用户 / 拿数据库 / 确认业务背景」的交互，只能发生在主 agent 层、在某一轮 fan-out 结束之后。整个流程因此是回合制：派一轮 → 收齐回报 → 主 agent 消化（必要时问用户）→ 决定是否再派。

3.2 阻塞型 vs 非阻塞型不确定（子 agent 必须区分）

子 agent 在指令里被要求区分两类不确定：

非阻塞型：不影响继续写（如「这个字段是否可配，拿不准」）→ 标【推测】或进候选区，继续写完。
阻塞型：不查清这点整篇就建立在错误前提上（如「一个核心状态字段的语义直接决定业务逻辑怎么写」） → 立即停笔、缩小该分支产出、把阻塞点标「未决-阻塞」高优先级返回，其余非阻塞分支继续跑完。

宁可交一篇带明显空洞的半成品，也不要交一篇「自洽的错」。错的前提会污染整篇，对账还会显示「已认领」。

主 agent 收到「未决-阻塞」后，问完用户再补派一轮专门收口那个模块。这个阻塞收口轮也计入该模块的 N 轮预算（见 §3.3）；N 轮耗尽仍有阻塞点，一律降级为「待人工」封板，不无限收口。

3.3 预算与终止（防无限轮次 + 防上下文爆）

状态全落盘，不放主 agent 记忆：未决点、台账、回报，全部写进磁盘文件。主 agent 每轮从文件读、处理、写回；自身上下文只承载摘要，不承载全局状态。一个大平台几十个模块，主 agent 记忆必爆，爆了「记得所有未决点」这条命根子就断了。
单模块轮次上限：单个模块最多深挖 N 轮（默认 3），阻塞收口轮也计入这 N 轮。超限强制封板，把剩余未决点（含未决-阻塞）标「待人工」，不无限挖。
预算模型：先粗扫建骨架（L1/L2），再按风险优先级下钻（核心交易链 > 边缘工具模块）。每一轮都产出可停机的阶段性交付——随时中断都能得到一棵「已枚举对象逐行有归宿、未覆盖部分已登记」的树。

§4 步骤 0 · 认栈 & 定边界 & 批量索要外部输入

4.1 认栈

扫构建文件（pom.xml / build.gradle）、依赖、注解，判定技术栈，推导本项目的枚举套路。不预设栈——常见组合（Spring MVC/Boot、MyBatis、Feign/Dubbo、RocketMQ/Kafka、@Scheduled/Quartz）的枚举锚点见 references/认栈枚举手册.md；认不出的栈走该手册的通用兜底法。

4.2 一次性批量索要外部输入（关键：提到 fan-out 之前）

因为子 agent 中途停不下来（§3.1），凡是「需要用户给、需要外部系统拿」的东西，必须在派 team 之前一次性问全，否则子 agent 只能干等或瞎猜。开工就向用户索要：

数据库 schema / 连接方式：让子 agent 派出时手里就握着 schema。拿不到 → 见 §7.3 降级。
外部真值源（用于 §5 枚举差集，不依赖技术栈）：网关路由表、注册中心服务列表、生产 access log 的 URL 去重、MQ broker 的 topic 列表、DB 的 information_schema 表清单、crontab / 调度平台导出。能拿几样拿几样；拿不到的，在台账里登记「该真值源缺失」。

把「拿不到也得继续」设计进去：外部输入是增强不是前置阻塞。缺了就标低置信 + 登记盲区，不卡死。

§5 步骤 1 · 搭双台账 + 外部真值源差集

覆盖率不能用一本账自证自己（台账由枚举生成，又拿台账给枚举对账 = 循环论证：枚举漏的项，台账里根本没那一行，对账永远绿灯）。所以拆两本台账，再叠一层外部真值源差集。

5.1 发现来源台账（`discovery-ledger.md`）

记录**「我是怎么找的、找的边界在哪」**，而不是「找到了什么」。头部固定声明：

枚举来源：注解扫描 + MyBatis XML + Feign 接口     ← 用了哪些白盒手段
已知未覆盖：反射 RPC / 运行时动态拼接 SQL / 字符串拼 topic   ← 白盒手段照不到的盲区，主动列出
外部真值源：网关路由表[已比对] / information_schema[未获取→DB 层标低置信]   ← 每个真值源的获取与比对状态

「已知未覆盖」这一栏是诚实的核心——把白盒扫描照不到的地方主动列出来，而不是假装不存在。

5.2 对象覆盖台账（`coverage-ledger.md`）

机械枚举出的每个对象一行，认领状态收敛（见 §8）。列：类型 / 标识 / 源码锚点 / 认领文档 / 状态。枚举类型：表、HTTP 接口、RPC、MQ 收发、定时任务、外部调用。模板见 assets/对象覆盖台账模板.md。

5.3 外部真值源差集（盲区探测）

第一步·按服务边界裁剪真值源（关键，否则单项目视角会误报海量盲区）。 网关路由表 / 注册中心 / broker topic / information_schema 通常是整个平台共享的，里面绝大多数路由 / topic / 库表属于 别的服务。一次只查一个项目，直接拿全平台真值源做差集，差出的「盲区」绝大部分是别家服务的噪声，真盲区被淹没。所以先按服务边界过滤：

网关路由表 → 按本服务的路由前缀过滤
broker topic → 按本服务的 producer / consumer group 或 topic 命名约定过滤
information_schema → 按本服务独占的库 / schema 名过滤
真值源切不开服务边界时 → 差出的项标「全局盲区（含他服务，待平台层裁剪）」，而非本项目盲区

第二步·裁剪后再做差集：

本服务的 information_schema 表 − 台账已枚举的表  = 白盒漏掉的表（盲区！）
本服务的网关路由 − 台账已枚举的接口            = 白盒漏掉的接口（盲区！）
本服务的 broker topic − 台账已枚举的 MQ         = 白盒漏掉的 topic（盲区！）

第三步·逐项闭环，不许写一句汇总。 每个差出来的盲区登进发现来源台账的「外部差集盲区清单」（逐项：对象类型 / 外部标识 / 真值源 / 白盒缺失原因 / 处置状态 / 认领文档 / 剩余风险），并且每一项要么补查后补进对象覆盖台账、要么明列入残余风险——禁止只留一句「发现 N 个漏掉的接口」。

拿不到外部真值源时，该类对象在对象覆盖台账的「分类置信度声明」里标「仅白盒、未经运行时校验、可能漏列」——绝不给绿灯。

§5b 粒度标尺（铁律，整 skill 的灵魂）

业务逻辑写到什么粒度，决定这个 skill 是「废话」「抄代码」还是「真有用」。

5b.1 试金石（判定单条该不该记）

「新系统违反了就是 bug」→ 记录；「只是旧代码碰巧这么写」→ 丢弃。 即把「行为等价」翻译成动作：重写后必须保留才一致的，记；纯实现碰巧的，扔。

5b.2 但二分后移——子 agent 不在源头丢弃

判断一条逻辑「是有意的业务规则」还是「碰巧的实现」，需要业务意图，而这恰是黑盒老代码最缺、无业务背景的子 agent 最判不准的。所以：

子 agent 阶段只做三件事：发现 → 保全候选 → 标证据强度。绝不在源头做「业务 vs 碰巧」的丢弃。
模糊项默认进叶子文档的**「候选区」**小节（保留），不静默扔。
「是不是真规则」这个二分，留给主 agent 在有业务输入的归并回合裁决（用户能补背景时）。
理由：源头丢弃的东西，下游任何关卡都找不回来。宁可多保全、后过滤，不可早丢弃、永久失。

5b.3 业务规则单位 = 业务规则（不是方法、不是代码行）

正面 · 按业务决策类型分类（一条不漏）：

状态机：状态 + 合法流转 + 触发条件
判断 / 分支条件：真实谓词、阈值、资格规则
计算规则：公式 + 运算顺序（优惠叠加先后是经典暗雷）
校验规则：校验了什么、规则是什么
副作用 / 触发：发什么事件、调谁、写什么
边界 / 异常的业务处理：超时、幂等、补偿、回滚（是业务行为，不是 try-catch 机制）
隐藏规则：magic number、状态码语义、控制行为的配置开关、定时任务周期
权限策略（谁能做什么）
租户隔离（数据按租户隔离的规则）
数据生命周期（归档、软删、保留期）
补偿流程（失败后的业务补偿）
批处理重跑（批任务的幂等与重跑语义）
灰度开关（按开关切换的业务分支）
配置驱动规则（行为由配置表/中心决定的）

负面 · 条件保留（不再「必丢」）：

默认丢：代码结构 / 继承 / 设计模式 / DI、框架样板。
条件保留：日志、纯技术异常、DTO 字段搬运——若影响外部可见行为 / 合规 / 数据落库则保留。遗留系统里它们可能承载审计、对账、兼容协议、监管留痕——丢了就丢了真规则。

5b.4 三粒度对照例

粒度	写法	判定
太粗	「系统会自动关闭超时订单。」	❌ 废话，重构 AI 学不到东西
刚好	触发:每 5 分钟扫【事实｜OrderJob:30】· 条件:待支付且超 30 分钟【事实｜OrderService:88】· 动作:置已关闭+回滚库存 · ⚠ 30 分钟是否可配【推测】	✅ 阈值/条件/副作用/不确定项齐全、挂锚点
太细	「OrderJob 用 @Scheduled 注入 OrderService，for 循环调 selectExpired()，执行 Mapper 88 行 SQL…」	❌ 在描述代码

5b.5 数据库标尺

丢纯物理 DDL（存储引擎、字符集、物理索引页）。
保留承载业务语义的约束：非空 / 唯一 / 默认值 / 级联 / 精度长度（金额精度、唯一去重规则常就是业务规则）。
外加：字段业务含义、主键、隐式外键（应用层 join 关系）、状态码字典、揭示访问模式的关键索引。
粒度 = 「重建这张表 + 读懂它承载的业务语义所需的一切」，不是 DDL 复制。

5b.6 接口标尺

契约：方法 + 路径、关键入参（带业务约束）、关键出参（带状态码语义）、幂等、鉴权。
运行语义：重试、超时退化、错误码映射、调用顺序限制——失败后业务怎么走，正是重构最易踩雷处。
兼容性约束：兼容旧字段。
谁在调它 拆两栏：
- 本服务内调用方（静态可确定）
- 跨服务调用方（一次只查一个项目看不到别的服务，平台层调用图只给到服务级调用方线索；要精确到「谁调我这个接口」须人工核对，建库不全时标「未知/待补」）
绝不把「调用方:A、B」写成完整列表——跨服务的 C、D 可能在别的服务里，漏写会让重构 AI 误判「可以放心改签名」。

5b.7 安全阀 & 长度

拿不准 → 记【推测】或进候选区，绝不静默丢。
长度靠拆不靠省：业务规则一条都不许为压长度而省略；过长按 §2.3 升级子目录拆开。

§6 步骤 2 · 切模块 & 派 agent team

6.1 主 agent 粗扫切块

先读项目结构（包结构、模块划分、构建子模块），把项目切成若干内聚业务块。切块要点：

跨切面（跨模块事务、共享状态、异步回调链）单独归口，别切碎到两个子 agent 各以为对方负责。
按风险优先级排序（§3.3），核心交易链先查。

6.2 子 agent 会话启动提示词（硬约束模板）

派出的每个子 agent 收到这样一份指令（照 task-control-doc §7.5 的「只读本职、做完即停」笔法）：

你负责调查【模块 X】，只产出三层：业务逻辑 / 数据库 / 接口。硬约束：

1. 不描述代码实现（不写类怎么继承、方法怎么调），只写「系统做什么决策、存什么数据、暴露什么契约」。
2. 每条业务规则必须挂源码锚点（文件:行 或 表.字段）。挂不上锚点的，不许写成事实。
3. 证据分级：代码能证=【事实｜锚点】；行为推断=【推测】；查到痕迹但细节已不可考=【待人工｜疑似失传】
   （你无权直接标「失传」，那是主 agent 走完三件套+人工背书才能定的终态）；是不是业务规则拿不准=进「候选区」。
4. 不做「业务 vs 碰巧」的丢弃——只负责发现、保全候选、标证据强度（见粒度标尺 §5b.2）。
5. 区分两类不确定：
   - 非阻塞 → 标【推测】或进候选区，继续写完。
   - 阻塞型（不查清整篇就建立在错误前提上）→ 立即停笔、缩小该分支产出、
     标「未决-阻塞」高优先级返回，其余非阻塞分支继续跑完。禁止瞎猜补全。
6. 产出落盘到指定文件，回填对象覆盖台账的认领状态。
7. 只做本模块，做完即停，把「待确认清单」（需用户补的业务背景 / DB 信息）随产出一并返回。

6.3 收集回报

所有子 agent 回报落盘成结构化文件，主 agent 只读摘要（§3.3）。回报含：草稿、待确认清单、「未决-阻塞」高优项、台账认领回填。回报落盘格式见 assets/子agent回报模板.md（本轮产出文件 / 台账变更 / 未决-阻塞清单 / 待确认清单 / 建议补派范围 / 轮次计数），主 agent 二轮补派据此稳定消费，不靠从自然语言里捞。

§7 步骤 3 · 消化回报（自由轮次有上限）

7.1 主 agent 逐轮消化

从落盘的回报里读「待确认清单 + 未决-阻塞项」，决定：

需用户补业务背景 → 攒成一批，一次性问用户（不逐条骚扰）。
需深挖 → 在轮次上限内补派子 agent。
用户也不清楚、白盒也挖不动 → 按 §8 的失传门槛处理。

7.2 终止

持续到「无未决点」或触达单模块轮次上限（§3.3）。触上限则封板，剩余未决标「待人工」。

7.3 数据库硬降级（防死锁）

DB schema 在 §4.2 已尝试批量索要。若用户没给：

等一次（明确再问一次）。仍没有 → 该项目数据库层整层进「推测模式」：按代码推断表结构 / 应用层 join 推断隐式外键，整层标低置信，在台账登记「DB 层未经 schema 校验」，带缺口完成。
绝不因为缺 DB 信息就卡住整个流程不结束（那是死锁）。

§8 步骤 4 · 台账对账（盲区显式登记）

8.1 逐行收敛

对象覆盖台账每一行的状态必须收敛到下列终态或显式中间态之一，无「待调查」残留：

状态	含义	进入门槛
已记录	有锚点、已写进某叶子文档	锚点齐
推测	行为推断、未被代码完全证实	标明推断依据
失传	已穷尽白盒 + 已问用户 + 用户确认不可考	三件套齐全 + 人工背书（缺一只能标「待人工」）
待人工	还没问用户 / 超轮次封板	——
未决-阻塞	子 agent 报的阻塞点，待主 agent 收口（仅过程态，对账前必须清空）	——

「失传」是终态，权力很大（标了就不再查、对账也收敛），所以门槛最硬：必须三件套齐全且有人工背书。 任何一件没做到，只能标「待人工」或「推测」，不许图省事洗成「失传」。子 agent 无权标「失传」 （它给不了人工背书），最多标「待人工｜疑似失传」；「失传」只能由主 agent 归并 + 人工背书后回填。

「未决-阻塞」是过程态、不是终态：最终对账前，所有未决-阻塞必须经补派收口转为「已记录/推测」，或封板转「待人工」——诚实陈述里不出现未决-阻塞。

8.2 不给绿灯

对账完成 ≠ 宣称查全。对账的产物是一句诚实陈述：

「在已知枚举边界内，N 个对象已记录 / M 个推测 / K 个失传 / J 个待人工（无未决-阻塞残留）；外部真值源差集发现的盲区见发现来源台账的『已知未覆盖』与『外部差集盲区清单』。」

禁止输出「已查全 / 零遗漏 / 完整」。

§9 步骤 5 · 残缺性审计关卡（复用 adversarial-review）

收尾跑一道 adversarial-review，但职责是「残缺性审计」，不是「完整性保证」。

为什么改名：adversarial-review 拿文档评文档，能挑出「这条规则自相矛盾 / 这个分支讲不通」，但它没有独立真值源去发现「代码里有而文档里没有」的未枚举入口——除非把整个老代码重扫一遍（等于把考古重做）。所以它检不出「漏了什么」，只能检「写错了什么」。把它当完整性关卡是名实不符。

这一关卡让评审 agent 重点审：

覆盖边界：发现来源台账的「已知未覆盖」是否诚实、有没有漏列明显盲区。
枚举策略：认栈枚举有没有明显照不到的入口类型。
未证明区域：哪些【推测】其实证据薄弱、哪些「失传」其实没走够三件套门槛。
若 §5.3 已拿到外部真值源，在此做一遍差集核对。

产物是一份「残缺性审计意见」，补进残余风险清单。不宣称「审计通过 = 完整」。

§10 步骤 6 · 回填平台层（增量）

每查完一个项目，往 _platform/ 增量补一笔，不要求一次建全。

服务标识：先在 service-registry.md 登记 / 查重（§2.4）。
调用图：call-graph.md 的边用稳定服务标识做主键。被调方此刻可能还没建库 → 这条边是悬空边，显式标「被调方未建库」，并登进**「待接通清单」**。
回接：每新建一个服务，强制扫一遍待接通清单，把指向它的悬空边接通。
冲突不静默覆盖：多次运行对同一调用关系可能给不同结论。增量记录带时间 / 来源 / 置信度 / 替代关系；冲突时显式标注两个结论并存，不许后者悄悄盖掉前者。

§11 产物格式 & 可选跨层索引

六个模板见 assets/：发现来源台账、对象覆盖台账、叶子文档（业务逻辑/数据库/接口三合一，含 L2 模块 README 迷你骨架）、项目主 README、平台调用图、子 agent 回报。
可选跨层流程 / 场景索引：异步补偿、事务边界、批量导入这类跨「业务/库/接口」三层的流程，三个叶子各记一段会割裂。在项目 README 的导航里加一个可选「流程索引 / 场景索引」小节，把跨层流程串成一条线指向相关叶子。保留三层叶子结构不变，这只是加一层跨层导航（按需，不强制）。

§12 项目补丁挂载点

项目特定值不硬编码进引擎，运行时由用户提供 / 项目补丁声明：

挂载项	取值方式
输出根目录	运行时问用户
快照批次号	运行时问用户（默认当天日期）
公司特有技术栈的枚举锚点	项目补丁补进 `references/认栈枚举手册.md` 的扩展区
服务标识映射规则	项目补丁声明（如何从仓名/制品名映射到稳定标识）
外部真值源获取方式	运行时问用户（网关/注册中心/DB 在哪）

§13 执行禁止项（红线）

禁脑补当事实：挂不上源码锚点的，不许写成【事实】。
禁描述代码实现：讲决策/数据/契约，不讲类继承、方法调用链。
禁源头丢弃候选：子 agent 不做「业务 vs 碰巧」的二分丢弃，只发现 + 保全 + 标级。
禁给绿灯：拿不到外部真值源 / schema，整层标低置信、登记盲区，绝不输出「查全/零遗漏/完整」。
失传须三件套门槛 + 人工背书，否则只能标「待人工/推测」；子 agent 无权标「失传」。
每个未决点必须有归宿：已记录 / 推测 / 失传 / 待人工 / 未决-阻塞，五选一，无「待调查」残留； 未决-阻塞是过程态，最终对账前必须清空（转已记录/推测，或封板转待人工）。
外部差集必须逐项闭环：每个差出的盲区要么补进对象覆盖台账、要么明列入残余风险，不许只留一句「发现 N 个漏掉的接口」的汇总。
阻塞型不确定高优返回，主 agent 二轮补派，不许子 agent 瞎猜补全写出「自洽的错」。