Code to 7layer
从现有代码冷启动、生成七层文档反推总控文档的 skill（用户级通用）。本 skill 的交付物是「扫描摘要 + 任务总控编排文档」，不包含具体层的文档撰写（Phase 3 由 /control 驱动，单独消耗会话预算）。适用场景：项目无文档或文档严重过时、需要系统性规划七层文档补写任务。触发词：「冷启动建文档骨架」「反推文档体系总控」「从代码反推文档」「代码到七层」「反推文档体系」。From its SKILL.md
npx -y skills add BackToCimaCoppi/Praxis --skill code-to-7layerAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- skips confirmationTells the agent to proceed without asking first, 1 time: "无需用户输入，直接扫描".
- 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.
SKILL.md
28.3 KB, ~10.8k tokens by cl100k_base, as published. Nobody here has run it
从代码冷启动生成七层文档反推总控
交付物边界（必读）：本 skill 的交付物是 Phase 0–2（扫描 + 骨架确认 + 任务总控文档创建）。具体层的文档撰写属于 Phase 3，通过
/control逐子任务推进，每个子任务单独消耗会话预算。不要期望一次执行能拿到全部文档——本 skill 是编排器，不是文档生成器。
不适用场景：
- 代码与现有文档的增量同步 → 用
doc-layer-systemskill - 仅补写 L1 需求层 → 用
docs-from-codeskill
依赖 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 契约层（机械提取 🟢）
从哪里读（优先级从高到低）：
- 代码自动生成的 OpenAPI（如 springdoc 运行时扫描、NestJS Swagger 模块自动生成）—— 与代码同源，等价优先级
- 后端注解：
@RestController方法（路径/HTTP 方法/@RequestBody/@RequestParam/@PathVariable/返回类型）；DTO/Request/Response 类字段 - 路由文件：
router.get/post(path, handler)；@Controller+@Get/@Post装饰器 - 前端 API 调用封装：
services//api//request.ts的调用函数签名与类型 - 手维护的 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.jsonpages 列表
产出内容（参考 doc-layer-system §5.5 + references/L5L6写作指南.md）：
- 页面路由树
- 状态管理方案概述
- API 调用封装模式
- 全部核心业务链路——按决策风险轴判定，不设数量上限。提取时重点扫这些前端决策点：状态管理粒度、缓存一致性策略、并发更新处理、错误重试/降级策略、乐观更新与否；以及多步交互编排（向导/表单流转与中断恢复）。必须覆盖核心主流程。纯展示/标准取数不进。
表达形式（强制）：与 §5.3 相同——精炼语言/表格/图，至多一个轻量代码锚点；禁止代码/伪代码/逐方法实录/证据尾注/置信度/漂移登记。
不确定时：与 §5.3 相同——暂停说明；确认是债的进技术债登记，不写入 L5 正文。
5.5 L1 需求层（意图重建 🔴）
执行方法：参考 docs-from-code skill 的完整 7 步流程。
从代码可推断的：
- 功能列表（Controller 方法 / 页面路由 → 功能清单）
- 状态值域（枚举类 / 常量定义）
- 权限边界（鉴权注解 / 角色检查）
- 核心业务规则（Service 层条件逻辑）
代码无法推断的（必须问用户）：
- 产品背景与目标用户（「为什么做这个功能」）
- 业务规则的来源与优先级（「为什么是这个阈值/条件」）
- 已废弃代码是否应纳入文档
- 非技术约束（「这个字段是监管要求」）
执行步骤：
- 从代码提取功能骨架（功能列表、状态定义、权限边界）
- 标注所有
[待用户确认：具体问题]项（来源：代码推断，置信度：低） - 向用户展示骨架 +
[待确认]清单，等待用户补填意图性内容 - 用户补填后，合并为完整 L1 文档
降级交付物（当用户无法回答、历史信息已丢失时）：
允许以「事实版 L1 + 未知项登记表」的形式封版交付：
- 事实版 L1：仅记录从代码可观测的功能、字段、状态、业务规则（不含产品意图）
- 未知项登记表：列出所有无法回答的产品意图问题，标「历史丢失 / 待产品裁决」
- 待产品裁决附录：将未知项整理为可独立交给产品负责人的清单
事实版 L1 在文件头标注「⚠️ 事实版：缺少产品意图，详见未知项登记表」。
5.6 L2 交互规格层（意图重建 🔴）
仅全栈 / 纯前端项目适用。
从代码可推断的：
- 页面列表与路由层级
- 加载/空/错误状态处理（代码中的 loading/empty/error 分支）
- 基础交互流程（按钮点击 → API 调用 → 页面跳转）
代码无法推断的（必须问用户）：
- 视觉规格（颜色/间距/字体/组件样式）
- 复杂交互细节（手势/动效/特殊 UI 行为）
- 非标准的业务流程在 UI 上的展示逻辑
执行步骤：
- 生成页面列表 + 基础交互流程骨架
- 标注
[待视觉稿补充]/[待用户确认：...]（来源：代码推断，置信度：低） - 请用户补充交互细节后合并
降级交付物（同 §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 用户确认后才能决定是否纳入
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.