Code To 7layer

---
name: code-to-7layer
description: 从现有代码证据冷启动、生成七层文档反推总控文档的 skill（用户级通用）。代码只用于发现现状与候选规格，不取得正式文档裁决权。本 skill 交付「扫描摘要 + 任务总控编排文档」，不直接撰写具体层文档；Phase 3 由 $control 驱动。适用场景：项目无文档或文档严重过时、需要系统性规划七层文档补写任务。触发词：「冷启动建文档骨架」「反推文档体系总控」「从代码反推文档」「代码到七层」「反推文档体系」。
---

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

> **交付物边界（必读）**：本 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/多子仓）

| 信号 | 判断 |
|---|---|
| `pnpm-workspace.yaml` / `lerna.json` / `nx.json` / `rush.json` | monorepo，进入子项目级检测 |
| `packages/` / `apps/` / `services/` 下存在多个独立子目录（各自有构建文件） | 多子仓，每个子目录独立判断 |
| 无上述信号 | 单仓，直接进入子项目级检测 |

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

| 信号文件 | 框架/语言 | 初步形态 |
|---|---|---|
| `pom.xml` / `build.gradle` | Java/Kotlin 后端 | 纯后端候选 |
| `requirements.txt` / `pyproject.toml` | Python 后端 | 纯后端候选 |
| `go.mod` | Go 后端 | 纯后端候选 |
| `package.json` 含 `express`/`koa`/`fastify`/`nestjs` | Node 后端 | 纯后端候选 |
| `package.json` 含 `react`/`vue`/`angular`/`next`/`nuxt` | 前端框架 | 前端候选 |
| `.wxml` 文件 / `wx:` 标签 | 微信小程序 | 前端候选 |
| 同一构建单元同时含后端框架 + 前端框架 | 全栈 | 全栈候选 |

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

| 信号 | 判断修正 |
|---|---|
| `main()` / `Application.run()` / `app.listen()` | 确认后端服务形态 |
| `handler` / `serverless.yml` / `template.yaml`（SAM） | serverless 函数形态，输出接口契约但无长驻服务 |
| `Dockerfile CMD` / `entrypoint.sh` | 确认容器化形态 |
| 无 `fetch`/`axios`/`xhr` 调用（前端项目） | 确认离线前端形态 |

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

| 信号 | 类型 |
|---|---|
| `@Scheduled` / `@Cron` / `cron` 表达式 | 定时任务 |
| `@KafkaListener` / `@RabbitListener` / `@SqsListener` | 消息队列消费者 |
| `@EventListener` / `ApplicationEvent` / EventEmitter | 内部事件 |
| WebSocket handler / `@SubscribeMessage` | WebSocket |
| `/webhook` 路由 / callback 路由 | 外部 Webhook 入站 |

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

### 2.2 域/模块候选发现

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

| 技术栈 | 扫描位置 | 候选规则 |
|---|---|---|
| Spring Boot | `controller/` 包的 Controller 类 | `UserController` → 候选「用户」，证据：该文件路径 |
| NestJS | `modules/` 目录名；`*.module.ts` | `auth.module.ts` → 候选「认证」 |
| Express / Koa | `routes/` 文件名；`src/` 功能目录 | `routes/order.js` → 候选「订单」 |
| Django | `apps/` 子目录名 | `apps/payments/` → 候选「支付」 |
| React / Vue | `pages/` / `views/` 一级目录；`src/features/` | `pages/profile/` → 候选「个人中心」 |
| 微信小程序 | `app.json` pages 数组一级路径 | `pages/home/` → 候选「首页」 |
| 通用兜底 | 顶层功能包/目录名，排除 `common/` `utils/` `config/` `middleware/` | — |
| 异步触发器 | 定时任务类 / MQ 消费者类 / Webhook 路由 | 独立出「异步任务」候选（若无对应同步域） |

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

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

### Phase 0.5：活跃面识别

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

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

**检测目标**：

| 检测类型 | 信号 |
|---|---|
| 疑似废弃 | `@Deprecated` 注解；注释含「废弃/deprecated/legacy/已停用」；路由前缀 `/v1/` 旁有 `/v2/` |
| 多版本并存 | 同一资源存在 `/v1/*` `/v2/*` 两套路由；同一功能存在两个版本的 Service |
| Feature Flag / 灰度 | 功能代码被 `if (featureEnabled(...))` / 配置键 / 环境变量包裹 |
| 引用计数为零 | 控制器方法/路由从未被路由注册文件引用（静态可分析时） |

**产物**：
```
活跃面：[接口/域/功能列表]
疑似废弃：[列表，附信号来源]
多版本并存：[列表，附两个版本的入口路径]
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 子任务执行顺序与依赖

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

| 批次 | 层 | 依赖 | 理由 |
|------|---|------|------|
| 第一批 | L3 契约 | 无 | 机械提取，无依赖 |
| 第一批 | L4 持久化 | 无 | 机械提取，可与 L3 并行 |
| 第二批 | L6 服务端实现规约 | 同域 L3 + L4 | 架构解读需契约和 Schema 作参照 |
| 第二批 | L5 客户端实现规约 | 同域 L3 | 仅全栈/纯前端适用 |
| 第三批 | L1 需求 | 同域 L3 + L4 + L6 | 意图重建需以事实层为基础 |
| 第三批 | L2 交互规格 | 同域 L1 | 仅全栈/纯前端适用 |
| 第四批 | L7 测试用例 | 同域 L1 + L3 | 从业务规则和契约派生 |

### 4.4 总控 README.md 模板

```markdown
# 七层文档反推

> 创建日期：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 持久化规格层（机械提取 🟢）

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

| 来源 | 说明 |
|---|---|
| Migration 文件（Flyway/Liquibase/Knex/TypeORM） | 历史变更记录，反映「理论上应有的结构」 |
| 原始 DDL 文件（schema.sql / init.sql） | 可能是初始化快照，需确认是否同步更新 |
| ORM 实体类（`@Entity` / `schema.prisma` / `models.py`） | 代码视角，可能与实际 Schema 有 drift |
| MyBatis Mapper（`*Mapper.xml` SQL + 实体字段） | 查询实际使用的字段，是反向推断字段实际存在的证据 |

**注意**：以上任何单一来源都不直接等于「线上真实 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 必须暂停的场景

| 场景 | 暂停动作 |
|---|---|
| L3：发现多套 API 版本，不确定哪个是当前激活版本 | 展示两套，问「哪个是当前版本」 |
| L4：同名表出现在多个 schema 或数据库中 | 列出发现，问「以哪个为准」 |
| L4：Migration、DDL、ORM 实体多源冲突 | 展示冲突，建议校验 information_schema |
| L6/L5：核心业务规则代码语义完全无法从上下文推断 | 引用具体代码片段，说明不确定点 |
| L6/L5：架构模式与常规明显偏差，无法判断是设计意图还是债 | 描述观察，请用户确认；确认是债 → 进技术债登记，不写入 L5/L6 正文 |
| L1：需要产品背景、用户意图、业务决策来源 | 列出具体问题清单（可接受降级交付，见 §5.5）|
| L2：需要视觉/交互规格，代码中完全无信息 | 说明缺失内容，可接受降级交付（见 §5.6）|
| 任何层：发现代码中同一事实存在明显矛盾 | 引用矛盾点，请用户裁决 |
| 任何层：触及 §6.1 硬暂停清单的字段语义不明 | 立即暂停 |

### 6.3 暂停格式

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

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

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

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

---

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

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

| 层 | 默认输出路径 |
|---|---|
| L1 需求 | `docs/01-需求/{域名}/` |
| L2 交互规格 | `docs/02-交互规格/{域名}/` |
| L3 契约 | `docs/03-技术设计/接口/` |
| L4 持久化规格 | `docs/03-技术设计/数据库/` |
| L5 客户端实现规约 | `docs/03-技术设计/前端/` |
| L6 服务端实现规约 | `docs/03-技术设计/后端/` |
| L7 测试用例 | `docs/04-测试/` |

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

---

## §8 执行禁止项

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