code-to-7layer

name	code-to-7layer
description	从现有代码冷启动、生成七层文档反推总控文档的 skill（用户级通用）。本 skill 的交付物是「扫描摘要 + 任务总控编排文档」，不包含具体层的文档撰写（Phase 3 由 /control 驱动，单独消耗会话预算）。适用场景：项目无文档或文档严重过时、需要系统性规划七层文档补写任务。触发词：「冷启动建文档骨架」「反推文档体系总控」「从代码反推文档」「代码到七层」「反推文档体系」。

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

交付物边界（必读）：本 skill 的交付物是 Phase 0–2（扫描 + 骨架确认 + 任务总控文档创建）。具体层的文档撰写属于 Phase 3，通过 /control 逐子任务推进，每个子任务单独消耗会话预算。不要期望一次执行能拿到全部文档——本 skill 是编排器，不是文档生成器。

不适用场景：

• 代码与现有文档的增量同步 → 用 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 模板

# 七层文档反推

> 创建日期：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 逐一推进。

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

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

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

最终文档按层分两套规则：

层	证据形态
L3 / L4（🟢 机械提取，表格层）	表格结尾保留 来源 状态 置信度 三列——它们本就是"对照代码的事实表"
L5 / L6（🟡 设计型层，决策锁定层）	正文禁止逐句证据尾注、状态/置信度标注、漂移登记；每条核心项至多留一个轻量代码锚点（类名/模块名）供定位。详见 doc-layer-system/references/L5L6写作指南.md
L1 / L2（🔴 意图重建）	段落末尾可加证据尾注辅助人工确认，但意图性结论以用户确认为准

发现的漂移/缺口/技术债：在提取底稿里登记，但不进 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 结构

产出格式：每个接口/任务/事件一条记录（方法/类型、路径/名称、入参、出参/副作用、鉴权要求、错误码）；参考 doc-layer-system §5.3。表格末尾附「来源」「状态」「置信度」列。

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 契约破坏冲突须立即停机）。

产出格式：每张表一个小节（表名、字段列表：名称/类型/约束/注释、索引、外键）；参考 doc-layer-system §5.4。表格末尾附「来源」「状态」「置信度」列。

不确定处理：多源冲突 → 全部列出，标「各来源冲突，需校验」（置信度：低）；字段语义不明 → 查 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 异步、幂等怎么保、并发怎么处理；以及多步复杂编排（顺序+每步为什么+取舍）。必须覆盖所有死亡线区域链路（鉴权/支付/用户数据删除/VIP 等）。纯 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 在文件头标注「⚠️ 事实版：缺少产品意图，详见未知项登记表」。

---

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 用户确认后才能决定是否纳入