Code To 7layer

从代码冷启动生成七层文档反推总控

交付物边界（必读）：本 skill 的交付物是 Phase 0–2（扫描 + 骨架确认 + 任务总控文档创建）。具体层的文档撰写属于 Phase 3，通过 /control 逐子任务推进。本 skill 是编排器，不是文档生成器。代码、实时数据库和运行行为只能形成候选规格与冲突证据；正式 L1~L7 必须经层内裁决与当前态重写后才能冻结。

不适用场景：

• 代码与现有文档的增量同步 → 用 doc-layer-system skill
• 仅补写 L1 需求层 → 用 docs-from-code skill

依赖 skill（子任务执行时按需引用，不需要预加载）：

• doc-layer-system §0.2（项目形态与层裁剪）— 决定哪些层适用
• doc-layer-system §0.3（业务域与功能模块）— 域/模块等价性约定
• docs-from-code（L1 反推方法论）— L1 层子任务执行时引用
• control（总控文档格式与推进机制）— Phase 2 生成总控文档时引用

§1 冷启动流程总览

Phase 0       Phase 0.5        Phase 1              Phase 2         Phase 3（总控驱动）
扫描代码  →  活跃面识别  →  一次性骨架确认  →  生成总控文档  →  逐层逐域逐子任务产出文档
                                                   ↑ 本 skill 止步于此

Phase 3 的执行：通过 /control <关键词> Tn 按子任务推进，每个子任务的提取指南见 §5。

§2 Phase 0：自动扫描项目结构

进入 skill 后，无需用户输入，直接扫描：

2.1 项目形态检测（三层检测）

第一层：仓库级（是否为 monorepo/多子仓）

第二层：子项目级（每个子仓/单仓判断框架）

第三层：运行时入口级（确认实际执行形态）

异步入口检测（同步进行，不单独成层）：

形态判断输出：

形态判断：[全栈 / 纯后端 / 纯前端-外部API / 纯前端-离线 / 混合形态 / 未知形态-需用户裁决]
置信度：[高（多信号一致）/ 中（部分信号）/ 低（单一信号）]
关键证据：[列出 2-3 个命中的信号文件路径]
异步入口：[无 / 定时任务 / MQ 消费者 / 事件 / Webhook / 多种]
层裁剪依据：doc-layer-system §0.2 形态裁剪表（适用层 / 省略层见下）

2.2 域/模块候选发现

按技术栈扫描，产出「域候选 + 证据」，不直接产出「域列表」：

域聚合提示（Phase 1 确认时使用）：

• 合并信号：相同 URL 前缀（/user/ + /user-profile/）、共享同一张核心表、共享 DTO 的多个 Controller → 可能是同一域
• 拆分信号：同名 Controller 内部同时处理 C 端用户和后台用户 → 建议拆为两个域候选
• 最终域边界由用户在 Phase 1 确认，AI 不单方面决定合并/拆分

域/模块发现遵循 doc-layer-system §0.3：有明确领域边界的项目以业务域为轴，无明确边界的项目以功能模块为轴，两者等价，后文统称「域」。

Phase 0.5：活跃面识别

在域候选列表生成后、Phase 1 确认前执行。

目的：避免把废弃代码、历史版本、未启用功能写入正式文档。

检测目标：

产物：

活跃面：[接口/域/功能列表]
疑似废弃：[列表，附信号来源]
多版本并存：[列表，附两个版本的入口路径]
Feature Flag 封锁：[列表，附 flag 名称/配置键]

提取规则：

• 疑似废弃面默认不写入正式文档，归入「待裁决废弃列表」
• 多版本并存 → Phase 1 让用户确认「以哪个版本为准」
• Feature Flag 封锁 → Phase 1 告知用户，由用户决定是否纳入文档

2.3 扫描产物整理

扫描完成后，整理为以下摘要（展示压缩证据，不展示完整目录树）：

[扫描摘要 — 待用户确认]
项目形态：[形态] （置信度：高/中/低，证据：xxx.xml, xxx/）
异步入口：[类型列表 / 无]
适用层（据形态裁剪）：L1 / L3 / L4 / L6 / L7（或其子集）
省略层：[列表]（按形态）

域/模块候选（N 个）：
  - 「用户」（信号：controller/UserController.java, UserService.java）
  - 「订单」（信号：controller/OrderController.java, routes/order.js）
  - ...
  [如发现合并/拆分信号，此处附提示]

活跃面识别：
  疑似废弃：[列表 / 无]
  多版本并存：[列表 / 无]
  Feature Flag：[列表 / 无]

推荐文档输出路径：（见 §7 默认路径）

如需查看某个域的完整目录证据，请告知域名。

§3 Phase 1：一次性骨架确认（不包含 Phase 3 层内澄清）

只问一次，将所有待确认项合并为一条消息呈现给用户：

我扫描了项目结构，整理如下，请一次性确认（有异议直接改）：

1️⃣ 项目形态：[形态]（置信度：高/中/低，证据：xxx）
   适用层：[L1 / L3 / L4 / L6 / L7]
   省略层：[L2 / L5]（如适用）
   异步入口：[类型 / 无]

2️⃣ 域/模块候选（共 N 个）：
   - 「域1」（信号：controller/Xxx.java）
   - 「域2」（信号：routes/xxx.js）
   - ...
   [合并提示 / 拆分提示（如有）]
   [如有遗漏、需要合并/拆分请告知]

3️⃣ 活跃面确认：
   疑似废弃：[列表] → 默认不写入文档，确认？
   多版本并存：[列表] → 以哪个版本为准？
   Feature Flag：[列表] → 纳入文档吗？

4️⃣ 文档输出路径（以下为默认路径，有调整请告知）：
   L1 需求：docs/01-需求/
   L3 契约：docs/03-技术设计/接口/
   L4 持久化规格：docs/03-技术设计/数据库/
   L6 服务端实现规约：docs/03-技术设计/后端/
   L7 测试用例：docs/04-测试/
   [如项目已有 docs/ 结构，优先对齐已有路径]

等待用户回复后进入 Phase 2。不在确认前创建任何文档或目录。

注意：Phase 3 各子任务执行时，会按 §6 协议在层内触发暂停提问（如「L1 需求的产品背景是什么」「L3 这个字段含义是？」），这属于层内澄清，与本阶段的骨架确认是两类交互，不冲突。

§4 Phase 2：生成任务总控文档

用户确认后，创建总控文档：

4.1 总控文档路径

docs/00-任务总控/YYYY-MM-DD-七层文档反推/README.md

YYYY-MM-DD 取执行当天日期。如当天已有同名目录，追加 -2。

4.2 子任务命名规则与类型

子任务分三类：

① 域内层任务（主体）：一个域 × 一个层 = 一个子任务

编号：T{n}
命名：[域名]-[层简写]
层简写：L1需求 / L2交互 / L3契约 / L4持久化 / L5客户端 / L6服务端 / L7测试

② 共享/基础设施任务：跨域共享能力，不属于任何单一域

命名：共享-[层简写]-[描述]
示例：共享-L3-公共错误码、共享-L4-基础表、共享-L6-鉴权链路

③ 跨域专题任务：涉及多个域协同的链路或流程

命名：跨域-[描述]
示例：跨域-L1-用户下单全链路、跨域-L7-端到端回归

粒度规则：同域同层不再二次拆分；跨域共享能力独立成共享/专题任务，不强行归入某一域。

4.3 子任务执行顺序与依赖

按以下批次顺序安排，每批内各域可并行：

4.4 总控 README.md 模板

# 七层文档反推

> 创建日期：YYYY-MM-DD
> 项目形态：[形态]（置信度：高/中/低）
> 域/模块列表：[域1、域2、域3…]
> 适用层：[层子集]
> 活跃面状态：[废弃列表 / 多版本并存情况]
> 参考 skill：`code-to-7layer` / `doc-layer-system` / `docs-from-code`

## 任务背景

项目代码已有可运行版本，七层文档缺失或严重过时。本任务从代码反推，逐层逐域产出完整文档体系骨架；意图性内容（业务背景、交互规格等）在对应子任务中由用户补填。

## 子任务总表

| 编号 | 子任务 | 状态 | 依赖 | 预期输出路径 |
|------|--------|------|------|------------|
| T1 | [域1]-L3契约 | 待完成 | — | docs/... |
| T2 | [域2]-L3契约 | 待完成 | — | docs/... |
| T3 | [域1]-L4持久化 | 待完成 | — | docs/... |
| … | … | … | … | … |
| Tn | 共享-L3-公共错误码 | 待完成 | — | docs/... |

## 进展记录

- YYYY-MM-DD：总控文档创建，共 N 个子任务，按层批次推进

每个子任务详情段需包含：目标层、§5 对应小节的索引、预期输出文件路径、会话启动提示词。

§5 逐层提取指南（Phase 3 各子任务执行时使用）

执行入口：子任务通过 /control <关键词> Tn 逐一推进。

证据与置信度规范（区分"提取底稿"与"最终规格"）

⚠️ 关键：证据/状态/置信度是提取期的工作底稿机制，用来帮你定位代码、追踪不确定项。它不是最终文档的内容。要分清两者，否则文档会退化成谁也读不进去的法证报告。

提取期（工作底稿，可以用）：追踪每个结论的来源（文件/行号）、状态（机械提取/推断/待确认）、置信度，帮自己核对、帮人工裁决定位。

最终 L1~L7 统一规则：来源、状态、置信度、漂移登记全部留在任务底稿或真值收敛清单，不得进入正式规格正文。L3/L4 可保留执行资产引用（Migration/OpenAPI/Schema 快照路径）用于验证，但引用不代表资产拥有裁决权；L5/L6 每条核心项至多保留一个轻量代码锚点供定位。

发现的漂移/缺口/技术债：在提取底稿里登记，但不进 L5/L6 正文——汇总到独立的技术债登记文档，交人工裁决。

5.1 L3 契约层（机械提取 🟢）

从哪里读（优先级从高到低）：

1. 代码自动生成的 OpenAPI（如 springdoc 运行时扫描、NestJS Swagger 模块自动生成）—— 与代码同源，等价优先级
2. 后端注解：@RestController 方法（路径/HTTP 方法/@RequestBody/@RequestParam/@PathVariable/返回类型）；DTO/Request/Response 类字段
3. 路由文件：router.get/post(path, handler)；@Controller + @Get/@Post 装饰器
4. 前端 API 调用封装：services/ / api/ / request.ts 的调用函数签名与类型
5. 手维护的 OpenAPI/Swagger 文件 —— 视为旁证；与代码冲突时并列登记，禁止自动选边

手维护的 OpenAPI 文件在「文档严重过时」场景下与代码同样可能过时，不作为权威来源。

异步契约扩展（如 Phase 0 检测到异步入口，对应域的 L3 需包含）：

• 定时任务契约：任务名、触发规则（cron 表达式）、入参（如有）、副作用
• 事件契约：事件类型名、payload schema、发布方、消费方
• MQ 消费者契约：Topic/Queue 名、消息格式、幂等性说明、重试规则
• Webhook 入站契约：来源系统、路径、验签方式、payload 结构

产出格式：底稿中每个接口/任务/事件一条记录（方法/类型、路径/名称、入参、出参/副作用、鉴权要求、错误码）并带来源/状态/置信度；正式 L3 只保留裁决后的当前契约，不保留提取元数据。

L3 不单独维护状态流图，状态流归 L1。

不确定处理：字段含义不明 → 标 [含义待确认]（状态：待确认，置信度：低）；继续提取，汇总到子任务末尾。触及 §6.1 硬暂停清单的字段必须暂停，不允许继续。

5.2 L4 持久化规格层（机械提取 🟢）

多源证据聚合（所有来源同时参考，冲突时全部列出）：

注意：以上任何单一来源都不直接等于「线上真实 Schema」。多源冲突时，全部列出，并标注「建议对线上库 information_schema 校验后确认」。

冷启动观察模式说明：本阶段为纯观察/提取模式，多源冲突暂挂登记是正常产出，不要求立即裁决。进入 Phase 3 正式补写文档并切换到施工模式后，持续存在的冲突须按 doc-layer-system §2 冲突处理规则升级处理（L2 契约破坏冲突须立即停机）。

产出格式：底稿中每张表一个小节并保留多源证据；正式 L4 只保留裁决后的目标表结构、约束和执行资产绑定，不保留来源/状态/置信度列。Migration、ORM、实时 Schema 都必须收敛到 L4，而不是反过来统治 L4。

不确定处理：多源冲突 → 全部列出，标「各来源冲突，需校验」（置信度：低）；字段语义不明 → 查 Service 层用法辅助推断，标「推断」；仍不明标「语义待确认」。触及 §6.1 硬暂停清单的字段必须暂停。

5.3 L6 服务端实现规约（架构解读 🟡）

从哪里读：

• 服务层：*Service.java / *Service.ts 核心方法签名与主要逻辑分支
• 架构配置：依赖注入 Bean、中间件注册、安全配置（Spring Security / Passport.js 等）
• 模块依赖图：@Autowired / @Resource 注入关系；模块 import 图
• 异步消费链路：@Scheduled / @KafkaListener 方法内的业务逻辑

产出内容（参考 doc-layer-system §5.6 + references/L5L6写作指南.md）：

• 模块边界与核心能力边界
• 跨模块红线（禁止依赖的方向）
• 全部核心业务链路——按决策风险轴判定（"不写下来 AI 会不会裁错？"），不设数量上限，有多少需人拍板的决策点/编排就逐条写多少。提取时重点扫这些决策点：批量查 vs 循环查库、要不要缓存/缓存边界与失效、事务边界放哪、同步 vs 异步、幂等怎么保、并发怎么处理；以及多步复杂编排（顺序+每步为什么+取舍）。必须覆盖所有死亡线区域链路（鉴权/支付/用户数据删除等）。纯 CRUD/透传/转换不进。
• 异步消费主链路（如有定时任务/MQ 消费者，列出核心执行路径与触发/失败处理）
• 域内完整状态机（如有）

表达形式（强制）：精炼语言 / 表格 / 图；每条核心项至多一个轻量代码锚点（类名/模块名）。禁止：代码、伪代码、逐方法实录、逐句证据尾注、状态/置信度标注、漂移登记。一句判定："这句话删掉、读者直接看代码反而更准，它就超标了。"（详见写作指南 §3/§4）

不确定时必须暂停：

• 业务规则中的条件语义无法从代码上下文推断 → 暂停，说明不确定点（底稿可引代码片段，最终文档不留）
• 发现架构模式与标准模式有明显偏差，且不确定是设计意图还是历史债 → 暂停说明；确认是债的 → 进技术债登记文档，不写入 L6 正文

5.4 L5 客户端实现规约（架构解读 🟡）

仅全栈 / 纯前端项目适用。

从哪里读：

• 页面/组件结构：pages/ / views/ / components/ 目录层级
• 状态管理：store/ / Redux slice / Pinia store / MobX observable 结构
• API 调用封装：services/ / api/ / request.ts 调用模式
• 路由配置：router.ts / app-router.tsx / 微信小程序 app.json pages 列表

产出内容（参考 doc-layer-system §5.5 + references/L5L6写作指南.md）：

• 页面路由树
• 状态管理方案概述
• API 调用封装模式
• 全部核心业务链路——按决策风险轴判定，不设数量上限。提取时重点扫这些前端决策点：状态管理粒度、缓存一致性策略、并发更新处理、错误重试/降级策略、乐观更新与否；以及多步交互编排（向导/表单流转与中断恢复）。必须覆盖核心主流程。纯展示/标准取数不进。

表达形式（强制）：与 §5.3 相同——精炼语言/表格/图，至多一个轻量代码锚点；禁止代码/伪代码/逐方法实录/证据尾注/置信度/漂移登记。

不确定时：与 §5.3 相同——暂停说明；确认是债的进技术债登记，不写入 L5 正文。

5.5 L1 需求层（意图重建 🔴）

执行方法：参考 docs-from-code skill 的完整 7 步流程。

从代码可推断的：

• 功能列表（Controller 方法 / 页面路由 → 功能清单）
• 状态值域（枚举类 / 常量定义）
• 权限边界（鉴权注解 / 角色检查）
• 核心业务规则（Service 层条件逻辑）

代码无法推断的（必须问用户）：

• 产品背景与目标用户（「为什么做这个功能」）
• 业务规则的来源与优先级（「为什么是这个阈值/条件」）
• 已废弃代码是否应纳入文档
• 非技术约束（「这个字段是监管要求」）

执行步骤：

1. 从代码提取功能骨架（功能列表、状态定义、权限边界）
2. 标注所有 [待用户确认：具体问题] 项（来源：代码推断，置信度：低）
3. 向用户展示骨架 + [待确认] 清单，等待用户补填意图性内容
4. 用户补填后，合并为完整 L1 文档

降级交付物（当用户无法回答、历史信息已丢失时）：

允许以「候选 L1 底稿 + 未知项登记表」的形式降级交付，但不得把它放进正式 L1 路径或标记为已冻结：

• 候选 L1 底稿：仅记录从代码可观测的功能、字段、状态、业务规则（不含产品意图）
• 未知项登记表：列出所有无法回答的产品意图问题，标「历史丢失 / 待产品裁决」
• 待产品裁决附录：将未知项整理为可独立交给产品负责人的清单

候选底稿放任务总控 _shared/，文件头标注「⚠️ 候选规格：缺少产品意图，不是正式真值」。未知项裁决完并完成当前态重写后，才能物化为正式 L1。

5.6 L2 交互规格层（意图重建 🔴）

仅全栈 / 纯前端项目适用。

从代码可推断的：

• 页面列表与路由层级
• 加载/空/错误状态处理（代码中的 loading/empty/error 分支）
• 基础交互流程（按钮点击 → API 调用 → 页面跳转）

代码无法推断的（必须问用户）：

• 视觉规格（颜色/间距/字体/组件样式）
• 复杂交互细节（手势/动效/特殊 UI 行为）
• 非标准的业务流程在 UI 上的展示逻辑

执行步骤：

1. 生成页面列表 + 基础交互流程骨架
2. 标注 [待视觉稿补充] / [待用户确认：...]（来源：代码推断，置信度：低）
3. 请用户补充交互细节后合并

降级交付物（同 §5.5）：

• 事实版 L2：仅记录从代码可观察的页面列表、路由层级、加载状态处理
• 未知项登记表：视觉规格、复杂交互等列为「待提供」

5.7 L7 测试用例层（派生生成 🔵）

依赖：同域 L1 + L3 均已完成。

生成规则：

• 每个 L3 接口/事件/定时任务：至少 1 条正向用例 + 1 条负向用例（入参非法 / 鉴权失败 / 状态不合法）
• 每个 L1 关键业务规则：生成对应金标准用例
• 用例格式：前置条件 / 操作步骤 / 预期结果 / execution_ref

execution_ref 要求：每条用例必须填写执行绑定。有效类型：

• 测试文件路径（如 src/test/.../UserServiceTest.java#testCreateUser）
• 用例 ID（如 TC-USER-001，配合 runbook 使用）
• 手工验证 runbook 路径（如 docs/04-测试/手工联调/用户模块.md#创建用户）

当前无对应实现时，填 [TODO: 待绑定]，不留空。

§6 对话协议

6.1 不暂停的场景（含硬暂停清单）

以下字段类型不明时，必须暂停，不允许标 [待确认] 后继续（硬暂停清单）：

• 鉴权 / 权限 / 角色字段的语义不明
• 金额 / 余额 / 状态机核心字段的语义不明
• 业务主键 / 外键归属不明（无法确定指向哪张表或哪个域）
• 涉及个人信息合规（身份证 / 手机号 / 位置等）字段的语义不明

以下情况允许标 [待确认] 后继续（软延迟）：

• L3/L4 提取中，非核心辅助字段含义不明 → 标 [含义待确认 | 来源：推断 | 置信度：低] 后继续
• L6/L5 识别到代码结构，但对命名是否准确有小疑虑 → 使用观察到的名称，加极简标记 [待确认命名]（提取底稿里可记来源；L5/L6 最终文档不留置信度尾注）

6.2 必须暂停的场景

6.3 暂停格式

❓ 暂停提问：[层名] [域名]

我无法从代码中推断以下内容：

1. [具体问题]
   - 代码中发现：[代码文件路径 + 行号 / 片段]
   - 不确定的是：[具体不确定点]
   - 对文档的影响：[如果填错会导致什么]
   - 是否属于硬暂停项：[是 / 否，原因]

请回答后我继续。如果历史信息已丢失、无法回答，请告知，我将使用降级交付物（§5.5/§5.6）封版本子任务。

§7 文档输出路径默认约定

用户在 Phase 1 确认后生效。项目已有 docs/ 结构时，展示已有目录树（深度 ≤2 层），让用户选择对齐已有路径还是使用默认路径。

• 新项目（无 docs/ 结构）→ 使用上表默认路径
• 已有 docs/ 结构 → 展示已有目录树，用户确认对齐还是新建
• 不自动覆盖已有文档文件；目标路径已有内容时，先生成差异与冲突清单。裁决后重写为单一当前态，禁止追加“新节覆盖旧节”的补丁正文

§8 执行禁止项

• 禁止在用户确认前（Phase 1 回复前）创建任何文档或目录
• 禁止跳过机械提取层（L3/L4）直接做意图层（L1/L2）
• 代码注释作为二级证据使用：可作为推断意图的来源，但必须在底稿附「注释来源（文件路径 + 行号）+ 状态：待用户确认」；与代码行为冲突时并列登记，禁止自动选边；不允许把注释原文直接作为正式文档的结论性表述
• 禁止把 TODO / FIXME 注释写入正式文档（标 [代码中有 TODO，需处理] 但不引用原始注释）
• 禁止在 L3 记录内部实现细节（L3 只记录对外契约）
• 禁止为 [待确认] 项自行填入推断内容后当作最终文档交付——必须等用户确认或使用降级交付物
• 禁止跨域合并子任务（同域同层不再二次拆分；跨域共享能力独立成共享/专题任务，不强行合并到某个域任务内）
• 禁止把疑似废弃面（Phase 0.5 识别出的）直接写入正式文档——需 Phase 1 用户确认后才能决定是否纳入