Code to 7layer
给「AI 驱动开发」立规矩的 Claude Code skill 方法论库：七层文档治理 · 对抗评审 · 任务总控三驾马车，外加老代码考古、施工蓝图等共 16 个 skill —— 让 AI 写代码又快又不失控。
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.
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
从现有代码冷启动、生成七层文档反推总控文档的 skill（用户级通用）。本 skill 的交付物是「扫描摘要 + 任务总控编排文档」，不包含具体层的文档撰写（Phase 3 由 /control 驱动，单独消耗会话预算）。适用场景：项目无文档或文档严重过时、需要系统性规划七层文档补写任务。触发词：「冷启动建文档骨架」「反推文档体系总控」「从代码反推文档」「代码到七层」「反推文档体系」。
SKILL.md
28.3 KB, 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 用户确认后才能决定是否纳入