Doc Layer System

---
name: doc-layer-system
description: AI 驱动开发七层文档体系的可执行通用 skill。在任何涉及代码开发、文档同步、代码审查、测试编写的任务中，Agent 必须遵循此体系的分层规则、授权角色裁决规则、同步流程和变更钩子机制。项目特定规则（目录路径、治理角色、域列表、死亡线区域清单、金标准领域清单等）通过项目级 skill 补丁扩展，本 skill 不硬编码任何项目特定内容。触发场景：编写/修改代码或文档后需要同步、新增接口/数据库/页面功能、执行 /review、编写测试用例、处理文档与代码之间的矛盾、询问「这个东西该放哪里」或「这几个文档矛盾了听谁的」。
---

# 七层文档体系

本 skill 是七层文档体系的**可执行版本**，用户级通用，可跨项目使用。

项目特定约定（目录路径、域列表、死亡线区域清单、金标准领域清单等）通过**项目级 skill 补丁**扩展，不写进本文件。

---

## 0. 适用范围与形态映射

本 skill 的七层划分是**功能性抽象**，可跨技术形态使用。

| 抽象层 | 通用含义 | 常见实现形态 |
|---|---|---|
| L1 需求层 | 产品意图与业务规则的完整载体 | 功能文档、业务需求书、线框/原型图 |
| L2 交互规格层 | 用户可见的交互规格（**可选层**：无 UI 项目可省略） | Web/移动端页面视觉规格；CLI 的命令行交互规格；低保真交互流程图；状态页（loading/empty/error/disabled） |
| L3 契约层 | 系统对外暴露的接口契约 | HTTP REST API；RPC/gRPC；CLI 命令签名；事件 Schema；消息队列消息格式 |
| L4 持久化规格层 | 数据存储结构规格 | 关系型数据库表结构；KV Store Schema；文件格式规范；消息存储结构 |
| L5 客户端实现规约（**可选层**：无客户端项目可省略） | 客户端/前端的架构规范与主要链路 | Web/移动端前端；桌面端；CLI 客户端逻辑层 |
| L6 服务端实现规约 | 服务端/后端的架构规范与主要链路 | REST 后端；微服务；数据管道；定时任务系统；事件消费者 |
| L7 测试用例层 | 对 L1~L6 各层设计意图的验证规格 | 自动化测试用例规格；手工验证场景规格 |

**L2 与 L5 是可选层**：纯后端服务、CLI 工具、数据管道、事件驱动系统等项目，可在项目级补丁中声明省略 L2 和/或 L5，直接从 L1 接入 L3/L4/L6/L7。

### 0.1 审核能力矩阵

每层文档的每次正式变更，需要由具备对应审核能力的人确认。能力要求是通用约束，具体绑定到哪个角色/岗位/人，由**项目级补丁**声明；若项目缺失某项能力，也应在补丁中显式声明降级方案（例如「L4 副审由主审兼任」）。

| 层 | 主审所需能力 | 副审所需能力 |
|---|---|---|
| L1 需求 | 业务判断能力（能确认功能边界与业务规则） | 技术可行性判断能力 |
| L2 交互规格层 | 视觉与交互判断能力 | 客户端实现判断能力 |
| L3 契约层 | 契约设计能力（客户端 + 服务端双侧） | 测试设计能力 |
| L4 持久化规格层 | 存储设计能力 | 架构判断能力 |
| L5 客户端实现规约（架构治理类） | 架构判断能力 | 全体技术可参与 |
| L5 客户端实现规约（实现方案类） | 客户端实现判断能力 | 业务判断能力（涉及业务时） |
| L6 服务端实现规约（架构治理类） | 架构判断能力 | 全体技术可参与 |
| L6 服务端实现规约（实现方案类） | 服务端实现判断能力 | 业务判断能力（涉及业务时） |
| L7 测试用例 | 测试设计能力 | 业务判断能力（金标准） |

### 0.2 项目形态与层裁剪

不同项目形态适用不同的层组合。项目级补丁应在文件开篇声明当前形态（如 `> 项目形态：纯后端`）。

| 项目形态 | 适用层 | 省略层 |
|---|---|---|
| **全栈**（前端 + 后端） | L1 / L2 / L3 / L4 / L5 / L6 / L7 | 无 |
| **纯后端**（无独立客户端） | L1 / L3 / L4 / L6 / L7 | L2（无 UI）/ L5（无客户端） |
| **纯前端**（对接外部 API） | L1 / L2 / L3 / L5 / L7 | L4（无自有持久化）/ L6（无自有服务端） |
| **纯前端**（离线 / 无后端） | L1 / L2 / L5 / L7 | L3 / L4 / L6 |

说明：
- 「纯前端对接外部 API」场景中 L3 仍然适用，用于记录前端所依赖的**外部 API 契约**（只读，非自有）
- 裁剪后不适用的层在本项目中跳过，对应文档路径和扫描矩阵条目无效
- 项目补丁声明形态后，`code-to-7layer` 反推 skill 会据此自动裁剪子任务列表

### 0.3 业务域与功能模块

本 skill 使用**「域/模块」**作为贯穿各层的组织轴：

- **有明确领域边界的项目**（DDD 实践、微服务等）：以**业务域**（如「用户」「订单」「支付」）为轴
- **无明确领域边界的项目**（按技术模块或功能分组）：以**功能模块**（如「认证」「消息推送」「管理后台」）为轴

两者组织方式完全等价，后文「域」均指「业务域或功能模块」，以项目实际情况为准。项目级补丁应在文件开篇声明域/模块列表。

---

## 1. 七层定义速查

| 层级 | 名称 | 核心问题 | 审核强度 |
|:---:|------|---------|:---:|
| L1 | 需求层 | 产品是什么形态、有哪些功能、业务链路如何、交互原型是什么样的 | 🔴 diff 逐字审 |
| L2 | 交互规格层 | 用户/调用方看到的交互流程、界面状态、视觉规格具体是什么样的 | 🟡 方向性确认 |
| L3 | 契约层（接口层） | 系统与外部之间约定什么接口契约 | 🔴 diff 逐字审 |
| L4 | 数据库层 | 数据如何存储 | 🔴 diff 逐字审 |
| L5 | 客户端实现规约层（前端技术层） | 客户端/前端用什么技术、走什么主要业务链路、遵守什么架构规范 | 🔴 diff 逐字审（治理类） / 🟠 关键面抽查（实现方案类） |
| L6 | 服务端实现规约层（后端技术层） | 服务端/后端用什么技术、走什么主要业务链路、遵守什么架构规范 | 🔴 diff 逐字审（治理类） / 🟠 关键面抽查（实现方案类） |
| L7 | 测试用例层 | 怎样验证 L1~L6 各层的设计意图是否被正确实现 | 🟠 关键面抽查（金标准）/ 🟡 方向性确认（其余） |

**审核强度说明**：
- 🔴 **diff 逐字审**：对本次 diff（新增/修改行）逐字确认；存量内容不重审但评审人须确认 diff 与上下文一致。死亡线区域任何 diff 自动升级为 diff 逐字审 + 死亡线双轨审查。
- 🟠 **关键面抽查**：重点审架构规范的禁止模式清单、主要链路覆盖度、技术选型记录；其他细节抽查。
- 🟡 **方向性确认**：整体浏览方向一致、重要字段/状态无缺漏即可。

### 1.1 层间关系

```
裁决链（排序参考，非自动执行依据）：

  L1 需求
     ↓
  L2 交互层（可选：无 UI/交互界面时跳过）
     ↓
  L3 契约层  ‖  L4 持久化规格层    （无一一映射，但有显式耦合面，见下方说明）
     ↓
  L5 客户端实现规约（可选：无客户端时跳过）  ‖  L6 服务端实现规约
     ↓
  L7 测试用例
```

**关于 L5/L6 与代码的关系**：L5/L6 是**设计型**层，不是代码镜像层。它们是**重大业务/技术裁决的锁定层**——人在此审核拍板、锁定决策，AI 后续施工只能在框架内执行，**不得自行重裁、不得违反已锁定的链路思维**。L5/L6 文档对以下内容有效力：① 架构骨架与分层方向（脚手架结构、禁止越层方向）；② 跨模块红线/禁忌清单；③ 关键技术选型；④ **本层级/域/模块的全部核心业务链路**——"核心业务链路"按**决策风险轴**判定（定义见 §5.5/§5.6 与 `references/L5L6写作指南.md`），**不设数量上限**：有多少条需人拍板的决策点/复杂编排，就逐条说明多少。真正的实现细节（私有方法、SQL、DTO/VO 转换、标准 CRUD、纯透传/字段映射）属于**文档未规定的实现自由**：实现者可自行选择手段，但必须满足冻结规格与验证条件。任何层都不得用“以代码/实现为准”描述这条边界。

**关于同级层关系**：L3 与 L4 没有一一映射关系，但存在**显式耦合面**——以下情形改动一层时需扫描另一层：① 接口字段直接透传表字段（字段名/类型相同）；② 表字段被接口响应引用；③ 枚举值在接口与表中共用。其他改动（如索引调整、内部注释变化）不触发跨层扫描。L5 ↔ L6 互不强制驱动，两者通过 L3 接口层对话。

### 1.2 版本归属与生命周期状态

**禁止进度状态词**（这些归任务总控/任务级设计文档，不进正式文档）：
`已完成`、`开发中`、`已上线`、`测试中`、`待发布`

**版本归属字段**（必填，记录能力属于哪个版本）：

| 场景 | 写法 |
|---|---|
| 文档对应单一版本 | `> 版本归属：V2` |
| 文档跨多版本共用 | `> 适用版本：V1、V2` |
| 跨版本长期成立 | `> 版本归属：通用` |

**生命周期状态不进入正式规格正文**：正式 L1~L7 默认表示对应版本的当前有效规格；草稿、过时、待修订、施工中、已废弃等状态统一记录在任务总控、真值收敛清单、归档索引或 Git 历史。项目补丁不得把“过时待修订”当作正式规格的合法终态。

### 1.3 文档元数据要求

每份 L1~L6 正式文档顶部必须包含以下**必填字段**：

| 字段 | 说明 |
|---|---|
| `版本归属` | 见 §1.2 规则；项目可采用等价的适用版本字段 |

**推断元数据**（不强制人工维护，由 Git/PR 系统推断）：

| 字段 | 推断来源 |
|---|---|
| 最后审核日期 | 对应 PR 合并时间 / 最后一次 commit 时间 |
| 最后审核人 | 对应 PR Reviewer / commit author |

项目补丁可声明推断脚本，将 Git 元数据注入文档头部的可选字段。

AI 在冲突分级（§2）时，若能推断出「文档上次合并时间早于代码相关变更时间」，应在报告中附注「文档可能过时（最后合并 X，相关代码已于 Y 变更）」作为裁决参考，不直接据此修改任何层。

### 1.4 真值不得下放（强制）

- L1~L7 是规格；代码、Migration、实时数据库、运行日志、任务总控、轻量设计和测试脚本是证据、执行投影或上游过程资产，**不得取得正式规格的裁决权**。
- 正式规格禁止出现“以代码/实现/Entity/Mapper/Migration/数据库现状/施工结果为准”“施工时确定”等把规范内容留给下游决定的表述。
- 允许描述运行时权威关系（如“客户端状态以服务端响应为准”），但文档必须同时完整定义该响应语义；不得借运行时权威逃避规格定义。
- 正式正文只保留当前有效规则。禁止“后节覆盖前节”“新条款优先于旧条款但旧条款保留”的补丁式演进；旧方案留 Git、任务总控或归档。
- 轻量设计只保存决策理由；其全部有效规格语义必须在冻结前物化到 L1~L7。施工者不应依赖轻量设计或任务总控才能补全正式规格。

### 1.5 业务语义来源与授权裁决记录

- 正式 L1~L7 是最终规格真值，但**修改正式真值的来源必须可审计**。凡新增/改变业务结果、死亡线规则、对外契约、持久化语义或不可逆架构归属，必须来自既有正式上游真值，或由业务决策负责人作出的任务级 `_shared/用户裁决记录.md#DEC-x`。文件名为兼容既有工具保留，不表示当前交互方自动拥有裁决权。
- `DEC-x` 必须保存授权角色原话或明确选项、实际角色、日期、来源位置和适用范围。AI 摘要、评审建议、主线程偏好、代码现状和任务发起行为都不能伪装成“已批准”。
- 多项独立业务选择必须逐项编号，不得捆成一句“用户总体同意”。AI 应把本切片全部真实缺口合并成一张表一次询问，减少用户打断，但留痕仍逐项。
- 评审者只能暴露缺口；若没有有效 `DEC-x`，不得把候选方案写入“已决策·不得重开”区，也不得物化为正式业务规则。
- 正式正文完成物化后独立自足；可以保留一行“日期 + DEC-x”来源注记，但不得依赖任务资产才能理解规则。

---

## 2. 冲突处理规则

> [!CAUTION]
> 这是本 skill 相对旧式文档法的**最大改动**：推翻了"AI 按裁决链自动修正低优先级层"的旧规则，改为三级分级处理。

**适用范围**：所有跨层冲突、任何层与代码的冲突。

### 2.1 三级冲突分级

| 级别 | 定义 | AI 动作 |
|---|---|---|
| **L0 表面冲突** | 措辞/排版/字段注释/同义词差异，不影响语义 | AI 直接按裁决链上游对齐；在 PR 描述中列出已对齐项，无需停机 |
| **L1a 局部语义冲突** | 业务规则/状态流/字段含义不一致，且影响面**仅限**单一未发布功能、非死亡线区域 | 标注 `[SEMANTIC-DEFER]`，允许继续当轮编码；但**交付前必须完成裁决**，未裁决不可合并 |
| **L1b 跨域语义冲突** | 同 L1a 定义，但影响面跨已发布功能、跨域，或命中死亡线区域 | AI 立刻停止，明确报告冲突，请求人工裁决后继续 |
| **L2 契约破坏冲突** | 接口签名/字段类型/数据库字段名/枚举值/鉴权方式不一致 | AI 立即停机 + 标红 + **默认拒绝继续编码**，必须人工裁决后解锁 |

**判断分级的辅助输入**：变更面（是否涉及契约面）+ 死亡线标记（死亡线区域的任何语义冲突自动升级到 L2；非死亡线但跨已发布功能的语义冲突升级到 L1b）。

### 2.2 人工裁决流程（适用 L1 / L2 级）

1. **停止对冲突条款的写入或施工**，但继续完成当前已声明任务切片的有界只读扫描
2. **明确报告冲突**：「发现 [来源 A] 与 [来源 B] 不一致：[具体不一致内容]」
3. **合并询问而非逐条打断**：把本切片全部真实决策缺口收集成一张裁决表，再一次性请人裁决；不得每发现一处就问一次
4. **等待人的决定**，不允许 AI 用裁决链"猜"哪个对
5. 人做出决定后，AI 按人的指示统一更新所有相关层

**禁止行为**（L1 / L2 冲突）：

- ❌ AI 看到 L3 和代码不一致，自己按 L3 改代码
- ❌ AI 看到 L6 文档和代码主要链路不一致，自己按代码反写 L6
- ❌ AI 看到 L1 决策和 L2 页面不一致，自己按 L1 改 L2
- ❌ 任何"我觉得显然是 X 对"的自动行为

**裁决链的唯一用途**：告诉人"理论上谁优先"，供人做决定时参考；也作为 L0 表面冲突自动对齐的依据。不允许 AI 用它自动解决 L1/L2 冲突。

### 2.3 goal 执行态例外（结果管控模式）

> **适用前提（三条全中，缺一不适用）**：
> ① 本次任务的规格**已在施工前一次性冻结**（五项冻结闸门全绿，含 `spec_hash` 或等价锚点；`spec_hash` 计算规范见 `test-case-design` §5），**不是**仓库里的存量陈旧文档
> ② 冻结件由 goal **之外**产出并已过评审
> ③ 存在**飞行决策日志**，每条自愈留痕，用户事后逐条追认
>
> **轻量档（`plan-goal`）取值**：前提②的「已过评审」= 用户对计划逐条拍板批准（`plan-goal` §3 评审等价物）；「计划赢」仅覆盖计划明写语义，未覆盖的语义冲突仍照 §2.2 停机。

满足前提时，§2.2 的「立刻停止 + 人工裁决」在 goal 自主执行期间让位于下表。**否则 goal 每撞一次文档不一致就要停机，结果管控当场退化回过程管控**——这正是要治的病。

| 情况 | goal 内动作 |
|---|---|
| 代码 ≠ **本次冻结的规格** | **按规格改代码**，记飞行日志，不停机 |
| 未规定事项属于**纯实现自由**：任一选择都不改变可观察结果、契约、数据语义、架构边界，也不影响按规格重建 | 在代码中选取合规实现并记日志；**不写 L1–L7**，避免把代码细节污染成规格 |
| **规格有洞但不需要新业务裁决**：影响可重建的 L5/L6 选择，且现有正式真值给出唯一合法方向 | 暂停当前施工切片，走“有界重新冻结”：补轻量设计 `SD-x` → 职责正确的正式层 → 对应 `AC-x`，更新哈希、主题唯一性账、业务语义差异表与覆盖报告，五项冻结闸门重跑全绿后继续；不问用户、不重开对抗评审 |
| goal 中**意外发现**的存量陈旧描述，且最新冻结真值已给出唯一答案 | 同样走有界重新冻结，保证轻量设计、正式规格、L7 与覆盖报告同步；若开工前已知，则说明原冻结无效，必须退回冻结阶段 |
| 规格错了 / 洞会改变业务结果 / 命中死亡线 / **两份都已冻结的真值真矛盾** | **例外不覆盖，照 §2.2 停机**（停机后默认按 goal-charter §4 修改方案热修续跑；回炉 = 终止本 goal 退回上游子任务重来，例外档，定义见 `goal-charter` §5） |

**禁止只补 L5/L6**：任何正式层变更都必须同步其 `SD-x / TOPIC-x / AC-x / provenance_refs / semantic_diff` 与最新覆盖报告。否则“施工时补漏”会让轻量设计、测试和七层重新分叉，直接制造下一轮文档腐烂。

**飞行日志无规格裁决权**：日志只能记录施工事实、证据与纯实现自由。出现“不再”、“改为”、“取消原”、“与正式规格不同但”、“实现选择”等可能改写结果的表述时，必须立即证明它满足“任一选择均不改变可观察结果、契约、数据语义、架构边界与可重建性”；无法证明就回退至冻结或按 §2.2 停机，不得靠日志使新语义生效。

**为什么 §2.2 禁止行为第 1 条（「AI 看到 L3 和代码不一致，自己按 L3 改代码」）在此不适用**：那条防的是**按"陈旧"文档改代码**——文档可能早就过时，盲目对齐会毁掉正确的代码。而本次冻结件**刚刚产出并经评审，不陈旧**，它就是本次施工的法律。**前提①存在的全部意义就是分开这两种情况。**

**没有冻结件 = 没有"文档赢"的资格**：日常改动、bug 修复、探索性工作一律照 §2.2 原样执行。本例外不能靠声明"我在跑 goal"取得。

---

## 3. 变更钩子机制

「变更钩子」是当文档/代码改动时，主动扫描有依赖关系的下游层是否需要跟着改的机制。

### 3.1 改动扫描矩阵

| 改动来源 | 必须扫描的下游 |
|---|---|
| L1 需求变更 | L2 页面、L3 接口、L4 数据库、L7 金标准测试；L5/L6 核心业务链路（仅当 L1 调整命中已登记的决策点/编排时） |
| L2 页面变更 | L3（页面新增字段/操作时）、L5 前端技术、L7 测试 |
| L3 接口变更 | L5 前端技术、L6 后端技术、L7 接口测试 |
| L4 数据库变更 | L6 后端技术、L7 实现验证测试；L3（命中显式耦合面：字段透传/接口引用/共用枚举时） |
| L5 前端技术变更 | 前端代码、L7 前端测试 |
| L6 后端技术变更 | 后端代码、L7 实现验证/金标准测试 |
| 代码变更（按位置细化）| 见下方展开表 |

**代码变更扫描展开表**：

| 代码改动位置 | 必须扫描 |
|---|---|
| Controller / DTO / VO / 接口签名 | L3 接口层、L7 接口验证测试 |
| Entity / Migration / Repository 映射 | L4 数据库层、L7 实现验证测试 |
| Service / Repository 业务规则、状态机、判定逻辑 | L1 业务规则、L6 状态机描述、L7 金标准测试 |
| 架构骨架（包结构/分层/命名规范）变更 | L5/L6 架构治理类 |
| 前端页面/组件/状态管理/服务层封装 | L2 视觉规格（如有）、L5 业务链路 |
| 算法核心（死亡线区域） | L1 业务规则、L7 金标准、要求项目指定的真人审查角色审查 |
| 私有方法、严格不改变结果集语义的 SQL 优化（同结果集/同顺序/同分页语义）、样式微调 | 不触发扫描 |
| SQL 优化涉及 join 方式/去重策略/排序/分页语义/隔离级别变化 | L4 数据库层、L6 后端技术、L7 实现验证测试 |

### 3.2 钩子实现三层联动

1. **AI 主动扫描层**：AI 在执行任务时，按 §3.1 矩阵主动扫描；发现不一致 → 人工裁决
2. **脚本检查层**：项目可选地实现 `post-change-check` 脚本，文件改动后自动跑（示例（MyApp）：`.agents/hooks/post-change-check.sh`）
3. **评审拦截层**：评审工作流中作为强制检查项（项目可自定义触发器与命名，如 /review）

### 3.3 冻结前跨层可实现性检查（强制）

`SD → 正式规格 → AC` 全部有引用，只能证明“传播完整”，不能证明“能够实现”。进入施工冻结前必须再做一次**跨层可满足性**检查：

| 规格要求 | 必须证明 |
|---|---|
| L5/L6/L7 要求读取某个业务状态 | L3 有合法输入/输出或域内有合法读取来源；不得靠未定义接口猜值 |
| L5/L6/L7 要求冻结、快照、预留、幂等或跨时点保持状态 | L4 有合法承载与生命周期，或正式说明为什么该状态可无持久化地唯一推导 |
| L7 断言某个错误码、状态或数据终态 | L1/L3/L4/L5/L6 中有职责正确的正式来源，且测试数据可合法构造 |
| 跨域链路需要对方信息或写入 | 正式契约中有合法接口面与一致性边界，不得依赖跨域直读/写 |

任一要求只有 L6/L7 描述、却找不到合法 L3/L4/域内承载路径，判定为**规格不可满足**，不得冻结，不得留给 Goal 发明接口或 Schema。

### 3.4 业务主题唯一性检查（强制）

“每条设计都已回写”不等于“回写后只有一个业务答案”。冻结件必须建立 `semantic_topics`，把任务切片内每个可改变用户可观察结果、契约、持久化语义或架构边界的问题登记为稳定 `TOPIC-x`。每个主题至少包含：

- `question`：本主题只回答的一个问题
- `positive_rule`：唯一生效的正向规则
- `forbidden_outcomes`：至少一个明确禁止的反向结果
- `boundary`：生效时刻、入口、平台、并发、失败与超时边界
- `failure_closure`：失败后的唯一收口结果
- `formal_spec_refs`：承载该规则的全部正式 L1–L7 锚点
- `provenance_refs`：对应 `SD-x`、上游真值或 `DEC-x`

检查器和主线必须对每个 `TOPIC-x` 打开**全部** `formal_spec_refs`，对比正向规则、禁止结果、边界与失败收口。同一主题在两个正式锚点中可同时成立相反结果，即为真值矛盾，不得用“下游更新”、“以测试为准”或“按代码实现”解消。

覆盖报告必须同时给出 `materialization_pass / semantic_uniqueness_pass / satisfiability_pass / decision_provenance_pass / semantic_diff_pass`；**五项全真**才可进入章程。`semantic_uniqueness_pass=true` 必须由完整主题账和已执行的跨锚点比对支撑——该比对必须由检查器机械执行（逐 `TOPIC-x` 解析全部 `formal_spec_refs` 锚点做交叉核对）；项目暂无法机器化时，该项降级为候选终审的人工检查项，**不得以自报布尔充数**。评审闭环不设独立布尔：冻结前检查「凡触发过对抗评审的对象，其评审报告的封闭式整改验收终态 = PASS」，以报告本身为证据（见 `adversarial-review` / `closed-remediation-review`），不自证。

**冻结闸门的诚实定位**：闸门审的是覆盖报告的**结构与追溯完整性**，不审规格本身是否正确；语义正确性的防线是 goal 运行时停机与候选终审。闸门全绿不得被表述或理解为语义担保。

同时生成一次**业务语义差异表**：对比评审前设计基线、用户 `DEC-x` 与最终正式规格，逐条列出新增/删除/改写的业务结果。任何无法追到上游真值或 `DEC-x` 的变化都必须撤销或停机裁决。

---

## 4. 开发流程同步规则

### 4.0 工作模式选择

在开始具体开发流程前，先选定当前工作模式：

| 模式 | 适用场景 | 文档要求 |
|---|---|---|
| **施工模式**（默认） | 正常功能开发、计划内修改 | 按 §4.1~§4.4 线性流程，先更新文档再编码 |
| **设计探索窗口** | 技术预研、产品原型、PoC 验证，或需求边界未定时的并行实现 | 允许先编码（提交标注 `[EXPLORATORY]`），步骤 1~3 文档与代码可并行推进；**必须选择以下两个出口之一**：① 探索结束 → 冻结 L3/L4 契约（进入「已审核」状态）→ 切换到施工模式；② 探索作废 → 弃稿，不留 [EXPLORATORY] 残骸在主干 |
| **止血模式** | 线上故障紧急修复、安全漏洞 | 允许直接改代码（提交标注 `[HOTFIX]`）；要求 24 小时内补齐 L3/L4/L6 变更记录与 L7 回归测试 |
| **RCA 模式** | Bug 归因不明，需要先做证据收集 | 先复现 + 收集证据，再判定属哪一层的偏差；不强制开局判定层，进入 §4.3 时再走对应流程 |

§4.3 Bug 修复：若可立刻判定 bug 属哪层偏差，直接按原有步骤；若不可判定，先进入 RCA 模式做证据收集和归因，再决定走哪条路径。

**契约冻结定义**：L3/L4 文档的生命周期状态进入「已审核」即视为契约冻结。契约冻结后，任何 L3/L4 修改按 §4.2「改接口/数据库」分支处理，不得退回设计探索窗口。

### 4.1 新增功能开发

```
步骤 1：确认 L1（需求是否已覆盖此功能）
    ↓ 如果 L1 未覆盖 → 先与用户确认，更新 L1
步骤 2：更新 L2（页面视觉规格，如适用）（无 UI 的项目跳过此步骤）
步骤 3：更新 L3（接口契约）+ L4（数据库设计）
    ↓ 用户确认 → "L3/L4 已审核"
步骤 4：编写代码（按 L5/L6 架构规范执行）
步骤 5：检查 L5/L6 主要链路描述是否与新代码对齐（如有偏差 → 人工裁决）
步骤 6：编写/更新 L7（测试用例）
步骤 7：执行评审动作（项目可自定义触发器与命名，如 /review）
```

### 4.2 修改现有功能

```
步骤 1：判断修改范围
    ├─ 仅实现优化（不改接口/行为）
    │   → 改代码 → 检查 L5/L6 主要链路是否需要更新 → 更新 L7
    ├─ 改接口/数据库
    │   → 先更新 L3/L4 → 用户确认 → 改代码 → 检查 L5/L6 → 更新 L7
    └─ 改功能设计
        → 先更新 L1/L2 → 用户确认 → 改代码 → 检查 L3/L4/L5/L6 → 更新 L7
```

遇到冲突：任何步骤中发现两层不一致 → **人工裁决**，不继续执行。

### 4.3 Bug 修复

```
步骤 1：定位 bug 属于哪一层的偏差
    ├─ 代码不符合 L3/L2 → 报告冲突，等用户确认是改代码还是改文档
    └─ 某层设计本身有问题 → 请示用户修改对应层
步骤 2：按用户决定修改代码
步骤 3：检查相关层是否需要更新
步骤 4：补充/更新 L7 测试（确保此 bug 不再回归）
```

### 4.4 版本调整

```
步骤 1：在 L1（项目总览）更新当前发布版本或版本边界
步骤 2：更新对应模块 L1 的版本归属
步骤 3：更新 L2/L3/L4/L5/L6 的版本归属（如受影响）
步骤 4：更新 L7 的版本归属，只让当前发布版本资产进入当前准入
```

---

## 5. 各层文档编写规则

> 每层规则的完整字段结构：层定位 / 核心问题 / 职责边界 / 应包含 / 不应包含 / 文档路径模板 / 审核强度 / 裁决位置 / 变更触发 / 下游联动 / 与代码的关系

### 5.0 第一原则：七层全是规格层，不是代码镜像

> [!IMPORTANT]
> **重建判据（唯一试金石）**：**把代码全删了，能不能照文档重做出来？**
> 这就是 SDD（规格驱动开发）里「规格」的定义，也是判断"这段内容该不该进七层"的唯一标准。

由此推出三条，贯穿 §5.1~§5.7：

| | 内容 | 地位 |
|---|---|---|
| **七层 L1~L7** | 需求 / 交互 / 契约 / 表结构 / L5·L6 的**管辖范围** / L7 用例规格 | **规格。先于代码存在**，是施工的输入 |
| **代码自由范围** | 函数内部逻辑、样式写法、DTO/VO 转换、SQL 实现、标准 CRUD、性能微调 | **不进任何文档**——删了也能照规格重做，写进来只会让文档追代码 |
| **执行产物** | 测试脚本、测试执行记录、交付记录、飞行日志、截图证据 | **不是规格，不进七层**。落任务过程资产目录或项目执行记录路径 |

**没有"实录层"这种东西。** 七层里不存在"施工后按代码回写"的层——那是代码镜像层的定义，而 §5.5/§5.6 明确写着 L5/L6 **不是**代码镜像层、**不腐烂正是因为不追代码细节**。任何要求"施工后把实现细节回写进 L5/L6"的流程设计都是错的：它会亲手把这两层变成腐烂源。

**修订纪律（适用 L1~L7 全部正式文档）**：修订经裁决后必须**改写正文为当前真值**——禁止追加式演进：不得用「与前节冲突以后节为准」的优先序规则、「上文应理解为」式补丁标注、整节"已撤销留痕"让读者自行合并出真值；版本历史归 git，正文至多一行版本注记。正文亦**不得引用任务过程产物**（任务总控工作包 / 蓝图 / 评审报告）作为效力依据——效力依据是裁决本身，至多留一行「日期 + 决策号」出处。

> **实测教训**：篇幅失控的施工蓝图之所以自己跟自己打架（同一文件前后给出相反的施工指令），根因就是它承载了"施工指令书"这种**无上游、只能靠猜**的内容。把同类内容塞进 L5/L6，只是给它换了个地位更高的马甲，腐烂了更难纠正。

### 5.1 L1 需求层

**层定位**：七层体系最高层，是产品形态的完整载体。使用**产品/业务语言**（文字描述）或**交互原型**（Figma 线框/原型图）表达。所有下游层的设计必须能回溯到某条 L1 的功能或业务规则。

**核心问题**：产品是什么形态、有哪些功能、业务链路如何、交互原型是什么样的。

**职责边界**：

L1 管：产品目标与用户价值；功能列表（用户能做哪些操作）；业务链路（含关键判定点与分支）；业务规则（约束条件/触发逻辑/计算规则的业务语言表述）；异常边界；交互原型（线框图/Figma 链接/文字描述布局与交互）；版本边界。

L1 不管：UI 视觉规格（颜色/字体/样式，归 L2）；接口字段契约（归 L3）；表名/字段/SQL（归 L4）；框架/库/中间件选型（归 L5/L6）；测试验证规格（归 L7）；进度状态词。

**应包含**：产品目标、用户价值、功能列表、业务链路（含分支）、业务规则、异常边界、交互原型（满足以下之一：Figma 线框/原型图截图、Figma 链接、文字描述布局与交互）、版本归属。

**禁止用实现语言替代需求表达**（口诀：这里写的是「业务是什么」还是「代码怎么做」？）：
- ❌ 用调用链替代需求（「调用 `UserService.checkPermission`」）、用循环替代规则（「`for` 遍历订单」）
- ✅ 允许**引用**精确字段名/错误码/枚举值/公式名作为需求规则的精确锚点：「VIP 等级满足 `level >= 3`」「错误码 `USER_BANNED`」「积分按消费金额百分比计算」
- 区别：**引用**精确标识 ≠ **用实现替代**需求表达；精确锚点是让需求可以无歧义地被验证

**L1 与 L2 分工**：L1 保留业务目标、用户流程主干、核心场景与业务规则；交互细节（含低保真流程图、状态页、交互说明）归 L2 交互规格层。L2 是高保真视觉设计稿或交互规格文档（"交互流程/界面状态具体是什么样"）。

**文档路径模板**：
```
通用模板：{docs_root}/01-需求/01-{NN}-{domain_name}/
示例（MyApp）：docs/01-需求/01-{NN}-{domain}/
```

**审核强度**：🔴 diff 逐字审。每条业务规则、每张原型图都必须人类逐字确认。

**裁决位置**：顶端。与其他层冲突时理论上 L1 优先——但发现冲突时**不允许 AI 自动覆盖下游**，必须人工裁决。

**变更触发**：产品方向调整、功能增减、业务链路变化、业务规则/异常边界变更、交互原型实质性改动、版本边界调整。不触发：UI 视觉规格调整（归 L2）；接口/数据库/前后端技术变化（归对应层）。

**下游联动**：L2（功能/交互形态变化）、L3（接口相关业务规则变化）、L4（持久化业务概念变化）、L7 金标准（核心业务规则变化）。发现不一致 → 人工裁决。

**与代码的关系**：**描述型**。代码行为必须与 L1 功能描述一致；代码实现细节变化不要求 L1 更新；发现不一致 → 人工裁决。

---

### 5.2 L2 交互规格层

**层定位**：可选层，位于 L1 之下、L3 之上。回答交互规格问题：用户/调用方看到的交互流程、界面状态（正常/加载/空/错误/禁用）、视觉呈现如何规格化。读者是设计师、界面开发者、交互评审者。L2 支持**精简形态**（文字描述交互流程 + 状态页说明，无专职设计师时合法）和**完整形态**（高保真设计稿 + 交互规格）。

**核心问题**：这个功能区的交互流程、界面状态、视觉规格具体是什么样的。

**职责边界**：

L2 管：配色方案（颜色规格）；字体规格（字号/字重/行高）；组件视觉样式；间距与布局；视觉状态（正常/禁用/加载中/空/错误的视觉形态）；图标与图片的视觉规格；高保真设计稿。

L2 不管：业务目标/用户流程主干/业务规则（归 L1）；接口字段契约（归 L3）；数据库结构（归 L4）；前端组件实现方案/CSS 代码/动画细节（归 L5）；进度状态词。

**应包含**（精简/完整形态二选一）：
- 精简形态（对视觉要求不高时）：每个功能区的交互流程描述（步骤级）；所有界面状态的文字说明（正常/loading/empty/error/disabled/permission）；全局视觉约定（如有则注明来源）。**允许低保真 wireflow、状态页流程图**。
- 完整形态（有专职设计师时）：高保真设计稿截图或 Figma 高保真页面链接；颜色/字体/间距规格；所有重要视觉状态的设计稿；交互流程图

两种形态均需标明：所属功能域、版本归属。

**Figma 归属规则**：同一 Figma 文件中，线框/原型页面 → L1；高保真视觉设计页面 → L2。

**文档路径模板**：
```
通用模板：{docs_root}/02-交互规格/{platform_or_domain}/
示例（MyApp）：docs/02-交互规格/{platform}/
```

项目级补丁挂载点（项目特例，不进通用规则）：多平台项目可按平台或业务域组织子目录，每份文档元数据头声明所属业务域（`所属业务域`）。

**审核强度**：🟡 方向性确认。整体浏览确认视觉方向一致、重要状态覆盖完整。

**裁决位置**：第二层。L2 向 L1 负责；L2 对 L5 有约束（前端视觉还原须与 L2 一致）。冲突时人工裁决。

**变更触发**：L1 功能/交互变化（检查页面视觉设计是否需要跟进）；品牌/视觉规范调整；设计评审反馈；视觉还原后设计稿不可实现（前端反馈）。不触发：接口字段/数据库/前端实现方案变化；业务规则文字变化但页面视觉不变（归 L1）。

**下游联动**：L5（页面视觉规格变化）、L7（重要视觉状态新增/修改）。发现不一致 → 人工裁决。

**与代码的关系**：**描述型**。前端实现的颜色、字体、间距须与 L2 一致（在 L2 管辖范围内）；代码实现手段（用什么 CSS/库）自由；发现不一致 → 人工裁决。

---

### 5.3 L3 契约层（接口层）

**层定位**：系统对外暴露契约的规格层。调用方读 L3 知道"能发什么请求/调用、期望收到什么响应"；实现方读 L3 知道"必须遵守什么契约"。L3 以**字段级契约**（字段名/类型/必填性/语义）表达，不限定传输协议形态。**L3 与 L4 同级独立**，互不强制驱动对方变更。

**核心问题**：前后端之间约定什么字段、什么契约。

**职责边界**：

L3 管：HTTP 方法 + 请求 URL；请求参数（含 query 参数和 body 字段）；响应体结构（含列表分页结构）；接口专属错误码；前置条件；状态流（接口触发或依赖的状态变更）；版本归属。

L3 不管：数据库表结构/字段/索引（归 L4）；后端实现细节（算法/缓存/中间件，归 L6）；前端调用实现（状态管理/错误重试，归 L5）；业务功能背景/用户价值（归 L1）；UI 视觉（归 L2）；测试脚本（归 L7）；进度状态词。

**应包含**：HTTP 方法 + URL；请求参数表（字段/类型/必填/说明，含列表接口的游标分页字段）；响应体结构（外壳 + data 字段）；接口专属错误码表（code/含义/触发条件）；前置条件；状态流（如适用）；版本归属。

**字段边界判定**（口诀：调用方看到这个字段，能知道"发什么、收什么"吗？）：
- ✅ `cursor: string，选填，上次响应返回的 cursor 值`
- ❌ `cursor 存储在 Redis Hash，key 格式为 user:{uid}:cursor`（实现细节，归 L6）
- ✅ `错误码 10001：资源已过期`；❌ `当 resource_token 在 DB 中不存在时返回 10001`（触发实现细节，归 L6）

**L3 与 L6 状态/错误责任划分**：

| 类别 | L3（外部可观察，由 L3 负责） | L6（内部实现，引用 L3 不重述） |
|---|---|---|
| 状态枚举值 | 定义并列出 | 引用 L3，不重述 |
| 接口调用导致的外部可观察状态转换 | 是 | 引用 L3 |
| 内部状态机（重试/补偿/定时回收等不经接口暴露） | 否 | 是 |
| 错误码（code + 含义 + 业务语言触发条件） | 是 | 引用 L3 |
| 失败处理策略（重试/降级/回滚/补偿） | 否 | 是 |

**L3 不单独维护状态流图**：L3 只声明对外可观察状态枚举与转移规则（哪些外部接口调用触发哪个状态转换），不维护完整的状态机图。完整领域状态机（含内部子态、超时、补偿）由 L6 持有，L6 同时维护「对外可观察状态投影表」映射到 L3 枚举值。

**L3 文档组织**：**全局规则文件**（一份：HTTP 方法约束、鉴权方案、响应外壳格式、分页规则、全局错误码、模块索引）+ **域级接口文件**（每业务域一份：字段级契约）。

**文档路径模板**：
```
全局规则：{docs_root}/{L3_root}/00-全局接口规则.md
域级接口：{docs_root}/{L3_root}/{NN}-{domain_name}接口.md
示例（MyApp）：docs/03-技术设计/接口/00-全局规则.md（全局）
              docs/03-技术设计/接口/{NN}-{domain}接口.md（域级）
```

项目级补丁挂载点（项目特例，不进通用规则）：项目可在此声明 HTTP 方法约束（如仅 GET/POST）、参数规范（POST 参数放 body）、翻页规则（游标/页码）、响应包装格式（如统一包装体）、鉴权方案（如 JWT）等。

**审核强度**：🔴 diff 逐字审。接口字段是前后端技术合同，每个细节都可能导致联调失败。

**裁决位置**：第三层，与 L4 同级。向 L1/L2 负责；下游 L5/L6/L7 依赖 L3。L4 不在 L3 联动范围内（同级独立）。冲突时人工裁决。

**变更触发**：L1 新增/删除接口相关功能；L2 变更导致新增/修改字段；联调发现字段不匹配；鉴权方案变更；错误码新增/修改。不触发：数据库新增索引（归 L4）；后端实现优化（接口行为不变，归 L6）；前端调用方式调整（接口契约不变，归 L5）。

**下游联动**：L5（请求参数/响应/错误码变化）；L6（接口新增/字段变化/状态流变化）；L7 接口验证测试（任何接口变更）。L4：仅当触发「L3/L4 耦合面」（§1.1）时需主动扫描；其他情形不在联动范围内。发现不一致 → 冲突分级处理（§2）。

**与代码的关系**：**契约型**。L3 是对外承诺，代码实际行为必须与 L3 一致；代码内部的算法/数据结构/调用链路变化（接口行为不变）不要求 L3 更新；发现不一致 → 人工裁决。

---

### 5.4 L4 数据库层

**层定位**：存储结构的真值层。后端开发者/DBA 读 L4 知道"有哪些表、哪些字段、类型和约束是什么、表间如何关联"，无需读代码或逆向数据库。**L4 与 L3 同级独立**，互不强制驱动对方变更。

**核心问题**：数据如何存储。

**职责边界**：

L4 管：表名与用途说明（业务语言）；字段列表（字段名/数据类型/是否可空/默认值/说明）；索引（索引名/字段组合/类型/用途说明）；约束（唯一/非空/外键）；表关系（业务语言描述引用关系）；版本归属。

L4 不管：接口字段格式/请求响应体（归 L3）；ORM 实体代码（归 L6）；业务状态机/状态流转逻辑（归 L6）；SQL 查询语句（归 L6）；数据迁移脚本 Migration（归代码库）；进度状态词。

**应包含**：表名与用途说明；字段列表（覆盖全部字段）；索引表（含用途说明）；约束；表关系（业务语言）；版本归属。

**字段边界判定**（口诀：开发者看到这个字段描述，能知道"存什么、类型是什么、有什么约束"吗？）：
- ✅ `status tinyint NOT NULL DEFAULT 0，枚举：0=进行中 1=已完成`
- ❌ `当 status=1 时触发积分结算，调用 PointService.settle()`（业务逻辑，归 L6）

**与执行资产的关系**：DDL 建表语句和 Migration 脚本是 L4 的**执行绑定资产**，L4 文档是其规格。每条 L4 表结构条目必须与至少一个 migration 文件建立稳定引用（仓库相对路径 + 版本/序号），使 L4 可追溯验证。Migration 必须实现 L4；实时数据库必须由同一迁移链收敛到 L4。三者不一致时按 §2.1 L2 契约破坏冲突处理，禁止把任一执行现状反升为规格。

**不包含**：ORM 实体类代码；接口 DTO/VO；SQL 查询语句。

**L4 文档组织**：**全局规则文件**（一份：全局约束、Owner 矩阵、域列表与文件导航）+ **域级数据库文件**（每业务域一份）。

**文档路径模板**：
```
全局规则：{docs_root}/{L4_root}/00-README.md
域级文件：{docs_root}/{L4_root}/{NN}-{domain_name}.md
示例（MyApp）：docs/03-技术设计/数据库/00-README.md（全局）
              docs/03-技术设计/数据库/{NN}-{domain}.md（域级）
```

项目级补丁挂载点（项目特例，不进通用规则）：项目可在此声明 ID 生成策略（如 Snowflake/UUID）、必填公共字段（如 `create_time`/`update_time`）、ORM 映射规范、跨域引用约束等。

**审核强度**：🔴 diff 逐字审。字段名/类型/约束直接影响 ORM 映射和数据完整性。

**裁决位置**：第三层，与 L3 同级。向 L1/L2 负责；下游 L6/L7 依赖 L4。L3 与 L4 之间按「显式耦合面」规则（§1.1）决定是否互扫：耦合面被触发才扫，其他情形不触发。冲突时按 §2 冲突分级处理。

**变更触发**：L1 新增/变更业务实体；DDL Migration 执行后（需同步 L4 保持规格与现实一致）；索引新增/删除；约束变更；表新增/废弃。不触发：接口字段格式变化（归 L3）；后端业务逻辑变化（不影响表结构，归 L6）；ORM 代码重构（不改字段名/类型）。

**下游联动**：L6（字段名/类型/约束/表变化）；L7 实现验证测试（字段/约束变化）。发现不一致 → 人工裁决。

**与代码的关系**：**契约型**。L4 是存储规格说明，DDL 和 ORM 代码必须实现规格；Migration 脚本是实现手段，属代码库，不归 L4 跟踪；发现不一致 → 人工裁决。

---

### 5.5 L5 客户端实现规约层（前端技术层）

**层定位**：可选层，与 L6 同级，适用于有独立客户端的项目（Web/移动端前端、桌面端、CLI 客户端等）。**同时承担两个等重职责，缺一不可**：

1. **防腐约束**：记录前端架构宪法——脚手架结构、目录规范、框架分层、编码哲学、禁止模式。跨会话长期有效，防止开发者（人或 AI）跨时间做出漂移的架构决策（跨会话失忆导致的一致性缺失）。
2. **技术实现方案的唯一用户审核层**：记录主要业务链路的前端实现方案、状态管理策略、服务层调用模式、关键技术选型。用户无需读代码，在 L5 层面与开发方形成共识并作为验收基准。

**L5 是设计型层，不是代码镜像层**。在 L5 管辖范围内，文档 > 代码；代码细节（函数内部逻辑、样式写法）自由实现；**L5 不腐烂**，因为不追代码细节。

**L5 是重大决策的锁定层**：所有需人拍板的前端业务/技术裁决在此审核、锁定；AI 后续施工只能在框架内执行，**不得自行重裁、不得违反已锁定的链路思维**。人据此验收，AI 据此施工——人和 AI 都看得懂是硬要求。

**核心问题**：前端用什么技术、走什么主要业务链路、遵守什么架构规范。

**职责边界**：

L5 管：脚手架与目录结构（精确到模块级）；框架分层设计（层级名称/各层职责/禁止越层方向）；模块划分；文件命名约定；编码规范与禁止模式（含明令禁止的反模式及理由）；主要业务链路（步骤级端到端流程，不精确到代码行）；状态管理策略；服务层调用模式；关键技术选型。

L5 不管：函数/方法内部实现；CSS/样式代码（可说"使用 SCSS"，不写具体规则）；第三方库内部 API 说明；与 L3 重复的接口字段定义；后端业务链路（归 L6）；UI 视觉规格（归 L2）；进度状态词。

**应包含**（拆为两类，可合并为单文件）：
- 架构治理类（防腐约束）：脚手架结构图（到模块级，每目录标注职责）；框架分层设计（分层名称/各层职责/层间通信/禁止越层方向需明确标注）；模块划分；文件命名约定；编码规范清单（命名约定/代码风格/明令禁止的反模式）
- 核心业务链路清单（用户审核层）：**本层级/域/模块的全部核心业务链路**——按决策风险轴判定（见下方「核心业务链路定义」），**不设数量上限**，有多少需人拍板的决策点/复杂编排就逐条写多少；状态管理策略（机制选型/主要 store 划分/跨组件数据流向）；服务层调用模式（API 封装方式/统一错误处理）；关键技术选型决策记录。纯实现细节（函数内部逻辑、CSS 写法、第三方库具体用法）不进入 L5；实现手段自由，但必须满足冻结规格与验证条件。
- 表达形式（强制）：核心链路用**精炼语言 / 表格 / 图**说明，每条至多附**一个轻量代码锚点**（组件/模块名）供定位。**禁止**：代码、伪代码、逐方法实录（"A 组件调 B 服务"式的代码复述）、逐句证据尾注、状态/置信度标注、漂移登记。详见 `references/L5L6写作指南.md`。

**核心业务链路定义（决策风险轴）**：**判定试金石**——「不写下来的话，一个有能力的 AI 在施工时，会不会做出一个看起来合理、但和团队已拍板结果不同的选择？」会 → 进 L5；只有一种合理写法（纯 CRUD/透传/字段映射/标准操作）→ 不进，代码自由。两种形态：① **决策点**（前端如：状态管理粒度、缓存一致性策略、并发更新处理、错误重试/降级策略、乐观更新与否）；② **复杂业务编排**（多步交互流程：步骤顺序 + 每步为什么 + 关键取舍）。

**L5 管辖范围（文档 > 代码）vs 代码自由范围**：
- 管辖：架构骨架与分层方向（脚手架/目录/分层/禁止模式）；跨模块红线/禁忌清单；**全部核心业务链路**（决策点 + 复杂编排，无数量上限）；技术选型
- 代码自由：纯实现细节——函数/方法内部逻辑；CSS/样式细节；第三方库具体用法；性能微调；只有一种合理写法的标准操作

**文档路径模板**：
```
通用模板：{docs_root}/{NN}-前端技术/
多端项目：{docs_root}/{NN}-前端技术/{platform}/
示例（MyApp）：docs/03-技术设计/前端/{platform}/
```

L5a/L6a 全局一份文件（改动少）；L5b/L6b 按域/功能域分文件（随功能演进）。

**建议文件拆分方式**（规模较大时）：
```
{platform}/
  L5-架构规范.md   ← 脚手架 + 框架分层 + 编码规范（全局，改动少）
  L5-业务链路.md   ← 各功能域主要业务链路（按功能域分节）
  L5-技术选型.md   ← 技术选型决策记录（变化少）
```

**审核强度**：
- **L5a 架构治理类**（脚手架/目录/分层/命名/禁止模式）：🔴 diff 逐字审。变更频率低但影响全局，每次改动必须仔细审。
- **L5b 实现方案类**（主要业务链路/状态管理/外部依赖/技术选型）：🟠 关键面抽查。随功能演进，审关键路径和选型决策是否记录完整。

**裁决位置**：第五层，与 L6 同级独立（通过 L3 接口层对话）。向 L1/L2/L3 负责。任何冲突 → 人工裁决。

**变更触发**：L1 业务链路变化；L2 交互变化影响前端状态管理；L3 接口变化影响前端调用链路；技术选型决策变更；架构规范调整。不触发：代码内部实现细节调整（主要链路走向未变）；CSS 细节调整；L3 接口字段新增但 L5 描述链路步骤未变。

**下游联动**：前端代码（架构规范或主要链路变更）；L7（主要业务链路新增/修改）。发现不一致 → 人工裁决。

**与代码的关系**：**设计型**。在架构规范、主要业务链路、技术选型范围内文档 > 代码；其余代码自由实现；发现不一致 → 人工裁决。

---

### 5.6 L6 服务端实现规约层（后端技术层）

**层定位**：与 L5 客户端实现规约层完全对称，面向服务端/后端代码库。**同时承担两个等重职责，缺一不可**：

1. **防腐约束**：记录后端架构宪法——包结构规范、框架分层（Controller → Service → Repository）、类命名规范、禁止模式。跨会话长期有效，防止越层调用、业务逻辑下沉等架构漂移。
2. **技术实现方案的唯一用户审核层**：记录主要业务链路的后端实现方案、关键状态机、定时任务、外部依赖、关键技术选型。用户无需读代码，在 L6 层面与开发方形成共识并作为验收基准。

**L6 是设计型层，不是代码镜像层**。在 L6 管辖范围内，文档 > 代码；私有方法、DTO 转换、SQL 细节自由实现；**L6 不腐烂**，因为不追代码细节。

**L6 是重大决策的锁定层**：所有需人拍板的后端业务/技术裁决在此审核、锁定；AI 后续施工只能在框架内执行，**不得自行重裁、不得违反已锁定的链路思维**。人据此验收，AI 据此施工——人和 AI 都看得懂是硬要求。

**核心问题**：后端用什么技术、走什么主要业务链路、遵守什么架构规范。

**职责边界**：

L6 管：包结构与目录规范（到模块/域级）；框架分层设计（Controller→Service→Repository，各层职责/层间单向依赖约束/禁止反向调用禁止越层）；模块/域划分；类命名规范（Controller/Service/Repository/DTO/VO/Entity 等）；编码规范与禁止模式；主要业务链路（Controller→Service→Repository 关键路径，步骤级）；关键状态机（状态枚举/合法转换路径/触发条件）；定时任务（名称/调度频率/业务意图）；外部依赖（依赖服务/交互模式/集成点/失败处理策略）；事务边界；关键技术选型。

L6 不管：私有 helper 方法实现；DTO/VO/Entity 字段转换细节；标准 CRUD Repository 操作；配置类/常量类的具体代码；与 L3 重复的接口字段定义；与 L4 重复的表结构详情；前端链路细节（归 L5）；进度状态词。

**应包含**（拆为两类，可合并为单文件）：
- 架构治理类（防腐约束）：包结构说明（精确到模块/域级，每包标注职责与允许包含的类型）；框架分层设计（分层名称/各层职责/禁止越层方向需明确标注）；模块/域划分；类命名规范；编码规范清单（命名约定/代码风格/明令禁止的反模式）
- 核心业务链路清单（用户审核层）：**本层级/域/模块的全部核心业务链路**——按决策风险轴判定（见下方「核心业务链路定义」），**不设数量上限**，有多少需人拍板的决策点/复杂编排就逐条写多少（步骤级，非代码级）；**完整领域状态机**（含内部子态/超时态/补偿态 + 对外投影映射表）；定时任务清单；外部依赖说明；事务边界说明；关键技术选型决策记录。纯实现细节（私有方法、SQL、DTO/VO 转换、标准 CRUD）不进入 L6；实现手段自由，但必须满足冻结规格与验证条件。
- 表达形式（强制）：核心链路/决策点用**精炼语言 / 表格 / 图**说明，每条至多附**一个轻量代码锚点**（类名/模块名）供定位。**禁止**：代码、伪代码、逐方法实录（"A 类调 B 类"式的代码复述）、逐句证据尾注、状态/置信度标注、漂移登记。反推中发现的漂移/缺口/技术债**不进 L6 正文**，去独立技术债登记文档。详见 `references/L5L6写作指南.md`。

**核心业务链路定义（决策风险轴）**：**判定试金石**——「不写下来的话，一个有能力的 AI 在施工时，会不会做出一个看起来合理、但和团队已拍板结果不同的选择？」会 → 进 L6；只有一种合理写法（纯 CRUD/透传/字段转换/标准操作）→ 不进，代码自由。两种形态：① **决策点**（后端如：批量查 vs 循环查库、要不要做缓存及缓存边界、事务边界放哪、同步 vs 异步执行、幂等如何保证、并发如何处理）；② **复杂业务编排**（多步业务流程：步骤顺序 + 每步为什么 + 关键取舍）。

**L6 状态机与 L3 的关系**：L6 持有**完整领域状态机定义**，包括内部子态、超时态、补偿态、重试机制。其中「对外可观察的状态投影」必须与 L3 声明的对外状态枚举存在明确映射表（格式：`领域内部状态 → L3 对外枚举值`），且不得与 L3 枚举值相矛盾。L6 不负责定义 L3 枚举，只负责说明内部状态如何映射到 L3 枚举。（见 §5.3 L3 不单独维护状态流图）

**L6 管辖范围（文档 > 代码）vs 代码自由范围**：
- 管辖：架构骨架与分层方向（包结构/分层设计/模块划分/类命名/禁止模式）；跨模块红线/禁忌清单；**全部核心业务链路**（决策点 + 复杂编排，无数量上限）；完整领域状态机；定时任务；外部依赖；技术选型
- 代码自由：纯实现细节——方法内部逻辑；DTO/VO 转换细节；SQL 实现；配置代码；性能微调；只有一种合理写法的标准 CRUD 操作

**文档路径模板**：
```
业务域文档：{docs_root}/{NN}-后端技术/{domain_name}/L6-{domain_name}.md
架构规范：  {docs_root}/{NN}-后端技术/L6-架构规范.md
示例（MyApp）：docs/03-技术设计/后端/{domain}/（业务域）
              docs/03-技术设计/L6-架构规范.md（全局架构规范）
```

L5a/L6a 全局一份文件（改动少）；L5b/L6b 按域/功能域分文件（随功能演进）。

**审核强度**：
- **L6a 架构治理类**（包结构/分层/命名/禁止模式）：🔴 diff 逐字审。变更频率低但影响全局，每次改动必须仔细审。
- **L6b 实现方案类**（主要业务链路/关键状态机/定时任务/外部依赖/技术选型）：🟠 关键面抽查。随功能演进，审关键路径和选型决策是否记录完整。

**裁决位置**：第六层，与 L5 同级独立。向 L1/L3/L4 负责。任何冲突 → 人工裁决。

**变更触发**：L1 业务链路变化；L3 接口变化影响后端处理链路；L4 数据库变化影响 Service/Dao 操作模式；技术选型变更；架构规范调整；新增定时任务或外部依赖。不触发：私有方法重构（业务逻辑不变）；DTO/VO 转换方式调整；SQL 优化（主要链路走向未变）；新增标准 CRUD 操作。

**下游联动**：后端代码（架构规范或主要链路变更）；L7（主要业务链路新增/修改、关键状态机变更）。发现不一致 → 人工裁决。

**与代码的关系**：**设计型**。在架构规范、主要业务链路、关键状态机、定时任务、外部依赖、技术选型范围内文档 > 代码；其余代码自由实现；发现不一致 → 人工裁决。

---

### 5.7 L7 测试用例层

**层定位**：最底层，被 L1~L6 共同驱动。**L7 是规格层，不是执行层**：描述"测什么、用什么场景、期望什么结果"；测试脚本是执行产物，不属于 L7 文档范畴。L7 通过了 = 代码正确实现了上游各层设计；L7 未通过 = 触发向上溯源诊断链。

**核心问题**：怎样验证 L1~L6 各层的设计意图是否被正确实现。

**测试专项路由**：

- 判断本次改动要测哪些类型、测到什么深度：使用 `test-standards`。
- 编写 L7 用例规格、白盒链路用例、黑盒业务用例和冻结留痕：使用 `test-case-design`。
- 把冻结用例路由到执行资产、收集证据、处理失败分类：使用 `test-execution-router` + 项目执行 skill。
- L7 文档只承载用例规格与追溯关系；执行命令、凭据、截图判读和环境细节不得写回 L7 规格层。

**四类测试用例资产**：

| 类型 | 验证对象 | 典型形态 | 可否删除 |
|---|---|---|---|
| 契约测试用例 | L3 契约层（接口签名/字段/错误码/状态流） | API 集成测试、mock 测试 | 契约废弃后可删 |
| 持久化不变量测试用例 | L4 持久化规格层（表/字段/索引语义/唯一约束） | DAO/Repository 测试 | 表/字段废弃后可删 |
| 端到端业务测试用例（含金标准） | L1 业务不变量与跨层流程 | E2E 测试、Service 集成测试 | 金标准**不可删除**；其余随功能废弃可删 |
| 手工验证场景用例 | L1/L3 中无法全自动化的场景（真机/三方回调/人工环境） | 手工执行 runbook | 场景废弃时可删 |

**用例通用格式**（每条用例须包含）：前置条件、操作步骤、期望结果、来源层引用（来源于哪一层的哪条规格）。

**执行绑定要求**（强制）：

- **一条 `AC-x` 只允许一个可独立证伪的结果**；一个 `CASE-x` 可组合多个 AC，禁止一个 AC 捆绑多个平台、入口、分支、边界或异常结果
- 每条断言必须填写 `assertion_kind / given / when / then / boundary / required_test_shape`，使执行层不能只靠出现 `AC-x` 字面引用宣称覆盖
- 每条 L7 用例必须填写 `execution_ref` 字段，指向至少一个可执行测试资产（文件路径 + 测试名 / Case ID）
- 手工验证场景类例外，但仍需 `manual_runbook_ref` 字段指向对应手工验证手册
- 每个执行资产（测试文件）须在文件头部声明 `covers: [L7-case-id, ...]` 列出覆盖的 L7 用例
- **金标准用例若无 `execution_ref`，视为「未生效」**，必须在 PR 描述中明确标注并在合并前补全
- 项目可选实现 lint 脚本，校验 L7 规格 ↔ 执行资产双向引用完整性

**强制测试形状**：

| 语义 | `required_test_shape` 最低要求 |
|---|---|
| 并发、幂等、单次决策 | 真并发竞争，不得用串行重放代替；断言业务结果和决策/派发次数 |
| 超时、失效、时间窗口 | 固定时钟或虚拟时钟，覆盖边界前、边界点、边界后 |
| 快路径 + 回退路径 | 两条路径分别取证，并断言最终决策/派发只发生一次 |
| 批量与故障隔离 | 至少两个项目且其中一个失败；断言其余项不被污染，并证明不存在逐项跨域/数据库调用 |

**`execution_ref` 最小协议**：

合法类型仅三类（不在此三类内的引用不视为有效绑定）：
1. **测试文件路径**：仓库相对路径 + 用例锚点，格式如 `src/test/java/example/OrderTest.java#testCreateOrder`
2. **测试用例 ID**：CI/测试管理系统中可解析的唯一标识，格式由项目补丁声明
3. **runbook 路径**：仅限手工验证用例，格式如 `docs/04-测试/手工验证/{NN}-{domain}/runbook.md`

校验规则：
- `post-change-check` 脚本须能解析上述三类引用并验证目标存在
- 引用目标不存在或已移动超过 24 小时未修复，标记 `[STALE-REF]`
- `[STALE-REF]` 用例不阻断 CI，但进入 PR review 必须先解除

命名规范由项目补丁声明。

**金标准不可删除规则**：

| 情形 | 判定 |
|---|---|
| 代码重构，业务逻辑未变 | ❌ 不可无等价替代地删除 |
| 测试跑起来麻烦 | ❌ 不可删除（执行问题改工具，不改用例） |
| 存在等价替代测试集（覆盖相同不变量，且更高质量/粒度重组/平台迁移） | ✅ 可删除（须满足等价替代三条件，见下方） |
| L1 明确废弃对应功能 | ✅ 可删除（须有 L1 变更记录 + 死亡线审查人签字） |
| L1 业务规则被明确修订 | ✅ 可修改（须有 L1 变更记录，修改后更新 L1 引用） |

**等价替代三条件**（全部满足才允许替换删除金标准用例）：
1. 显式声明被保护的业务不变量（需与原金标准的「来源层引用」字段一致）
2. 新测试集合在不变量维度上提供等价或更强的覆盖证明（用例数 × 场景深度，不得缩水）
3. 替换操作在 PR 描述中由金标准副审（测试/业务 owner）签字确认

金标准测试用例须在"来源层引用"字段中标注守护的 L1 业务不变量。执行层的注释格式由项目自定义（示例（MyApp）：`.as("L1不变量：[描述]")`）。

项目级补丁挂载点：具体金标准领域清单（核心算法/积分/等级等）由各项目自定义，不进通用规则。

**不应包含**：可执行测试脚本（归执行层）；测试环境配置/测试账号（归项目级配置）；执行结果/Bug 记录（归测试报告）；业务规则决策（归 L1）；接口字段定义（归 L3）；项目具体金标准领域清单（归项目补丁）；任务批次临时文件（归任务总控）。

**文档路径模板**：
```
实现验证：{docs_root}/{NN}-测试/{NN}-实现验证测试/{NN}-{domain_name}/
金标准：  {docs_root}/{NN}-测试/{NN}-金标准测试/{domain_name}/
接口验证：{docs_root}/{NN}-测试/{NN}-接口验证测试/{domain_name}/
手工验证：{docs_root}/{NN}-测试/{NN}-手工验证场景/{NN}-{domain_name}/
示例（MyApp）：
  docs/04-测试/实现验证/{NN}-{domain_name}/
  docs/04-测试/手工验证/{NN}-{domain_name}/
```

**审核强度**：金标准用例 🟠 关键面抽查；其余三类 🟡 方向性确认。

**裁决位置**：最底层，没有下游文档层。L7 失败时触发**向上溯源诊断链**：
```
L7 用例失败
  Step 1：L7 用例本身是否已过期（上游层已变更但 L7 未同步）？
          → 过期 → 人工裁决：更新 L7，还是回滚上游层变更？
  Step 2：L7 用例有效 → L3/L4 设计是否与 L1 一致？→ 不一致 → 人工裁决
  Step 3：L3/L4 有效 → L5/L6 方案是否与 L3/L4 对齐？→ 不对齐 → 人工裁决
  Step 4：以上均一致 → 代码实现有缺陷 → 修复代码，重跑 L7
```

**变更触发**：L1 业务不变量废弃/调整（金标准）；L1 新增功能或业务规则（金标准）；L2 页面规格变更（手工验证）；L3 接口新增/修改/废弃（接口验证/实现验证）；L4 数据库变更（实现验证）；L5/L6 主要链路变更（对应类型）。不触发：后端私有方法重构（输出结果不变）；SQL 优化（查询结果不变）；前端样式微调；测试脚本重写（执行层变化，用例规格未变）。

**与代码的关系**：**验收型**（特殊类型）。金标准用例 > 代码；接口验证用例来源于 L3（L3 > L7 > 代码）；实现验证/手工验证用例失败需人工判定是代码缺陷还是 L7 过期。

**禁止行为**：❌ 因测试用例跑起来麻烦就修改/删除用例；❌ 代码重构后金标准用例要调整就直接改；❌ 把测试脚本写入 L7 文档；❌ 用"测试通过"掩盖 L7 覆盖不足。

---

### 5.8 运行与发布资产（跨层附属，非独立编号层）

**定位**：发布策略、回滚策略、灰度规则、观测指标、告警阈值、运行手册等内容不归属于任何单一层，统一作为**跨层附属的运行资产**管理。不增加 L8 编号，不破坏「七层」命名稳定性。

**归属路径**：由项目补丁声明（示例（MyApp）：`docs/06-运行资产/` 或 `docs/04-测试/04-04-运行手册/`）。

**应包含**：发布策略（触发条件/部署顺序/预检清单）；回滚策略（条件/步骤/影响范围说明）；灰度规则（分流比例/Feature Flag/上线流程）；关键观测指标（SLI/SLO/核心业务指标及告警阈值）；运行手册（runbook：告警处理流程/故障定位步骤/应急操作）。

**变更触发扫描**：发布/回滚/灰度/告警阈值变更 → 检查 §5.8 运行资产 + L7 实现验证测试。

---

### 文档粒度总则

以下原则适用于 L1~L7 所有层：

1. **按业务域拆分**：同层中同一业务域的内容集中在同一文件（或目录）内；跨域内容须有索引文档承担入口职责。域的定义由项目补丁声明。

2. **单文档软上限**：单份文档的行数软上限由项目补丁声明（建议默认 ≤ 800 行）；超出时触发 `long-doc-governance` 分拆流程。

3. **索引文档要求**：同层若有多份文档，必须有一份索引文档（通常命名 `00-README.md`）列出所有子文件及其职责。

4. **可定位性要求**：跨域聚合文档允许存在，但必须能在 30 秒内定位到具体域条目（通过目录标题/锚点实现）。

5. **与治理 skill 联动**：`post-change-check` 报 `[CRITICAL]` 长文档警告时，强制触发 `long-doc-governance` skill 治理；不得忽略。

---

## 6. 死亡线审查机制

### 6.0 通用最小兜底清单（无论项目补丁是否存在，本条即时生效）

以下区域 AI 触碰时无需项目补丁即触发死亡线流程：

- 支付 / 计费 / 退款 / 优惠权益相关代码
- 鉴权 / Token / 密码 / 密钥相关代码
- 用户数据删除 / 批量更新 / 数据迁移脚本
- 第三方平台回调（支付/认证/OAuth 等）
- 涉及金额、用户身份、隐私字段的 SQL / 批处理脚本

项目补丁可叠加本项目的核心算法（如核心算法/积分/等级等），但不能删减上述兜底清单。

### 6.1 定义

死亡线 = 项目指定的真人审查角色必须审查的代码区域。AI 不能独自决定这些区域的逻辑；该角色可以是任务发起人，也可以是独立业务/技术负责人，由项目补丁声明。

> **项目级补丁挂载点**：项目特有的死亡线区域（如核心算法区域名称、代码位置、审查要点）由各项目在项目级 skill 补丁中维护，叠加到 §6.0 通用清单之上。

### 6.2 AI 在死亡线区域的行为

当 AI 触碰死亡线区域的代码时：

1. 在提交说明中明确标记：「⚠️ 死亡线区域变更：[区域名]」
2. 要求**项目补丁声明的死亡线审查人**亲自审查：不能自行判断逻辑是否正确
3. 确认/补充 L7 对应的金标准测试用例
4. 禁止静默修改，即使是"看起来无害"的重构

> [!WARNING]
> 死亡线区域的任何变更都不能自行决定。即使 AI 有 99% 的信心逻辑是对的，仍然必须要求项目补丁声明的死亡线审查人审查。

### 6.3 死亡线最小准入清单（通过 = 全部满足）

死亡线变更**通过**的定义：以下四项全部满足，AI 才可继续后续步骤；否则保持停机状态。

1. **命名审查人**：项目补丁中声明的真实审查人已被@或通知（不允许「AI 自审」或「留待以后再审」）。
2. **列出审查对象**：具体文件 + 行号范围 + 改动 diff 已提供给审查人（不允许只说「改了死亡线区域」）。
3. **关联验证证据**：至少关联以下一项：① 相关金标准测试 ID（execution_ref）；② 本次变更新增的回归测试；③ 手工验证 runbook 执行记录。
4. **留下可追溯记录**：审查确认留存在 PR 评论、独立 review-record 文件、或项目约定的其他可追溯位置（不允许口头确认无记录）。

---

## 7. 文档同步检查清单

**每次开发任务完成时，AI 必须对照此清单自检：**

### 7.1 代码变更后

- [ ] 是否涉及版本归属调整？→ 更新项目总览和对应文档顶部版本字段
- [ ] 是否涉及接口变更？→ 更新 L3 对应域级接口文件
- [ ] 是否涉及数据库变更？→ 更新 L4 对应域级数据库文件
- [ ] 是否涉及后端主要业务链路或架构规范变化？→ 检查 L6 是否需要更新；发现不一致 → 人工裁决
- [ ] 是否涉及前端主要业务链路或架构规范变化？→ 检查 L5 是否需要更新；发现不一致 → 人工裁决
- [ ] 是否涉及页面功能/交互设计变更（设计意图变化）？→ 检查 L2 是否需要更新
- [ ] 是否涉及新业务能力？→ 确认 L1 是否已覆盖
- [ ] 是否涉及接口/鉴权/错误码/状态流（可被测试脚本覆盖的面）？→ 检查 L7 接口验证测试用例是否需要同步；没有同步则说明原因
- [ ] 是否涉及死亡线区域？→ 标记并要求项目指定的真人角色审查
- [ ] L7 测试用例是否已更新？如涉及 L1 不变量，金标准用例是否补充/确认？
- [ ] 若需要手工验证，是否有可执行的手工验证场景用例？

### 7.2 文档变更后的级联检查

- [ ] 是否补了正确的版本归属字段？有没有误写成状态词？
- [ ] L1 变更 → L2/L3/L4 是否需要更新？→ L7 金标准是否需要更新？
- [ ] L2 变更 → L5/L7 是否需要更新？
- [ ] L3 变更 → 代码是否需要修改？→ L5/L6 是否需要更新？→ L7 是否需要更新？
- [ ] L4 变更 → 代码是否需要修改？→ L6 是否需要更新？→ L7 是否需要更新？
- [ ] 新增/改变业务结果、死亡线、契约/数据语义时，是否存在上游正式来源或可审计 `DEC-x`？有没有把评审建议或任务发起行为误写成“授权角色已批准”？
- [ ] 轻量设计全部 `SD-x` 与测试全部 `AC-x` 是否逐条物化到职责正确的 L1~L7，而不是摘要式回写？
- [ ] 五项冻结闸门是否全真？评审闭环是否有 PASS 的封闭验收记录？每个 `TOPIC-x` 是否只有一个业务答案？L6/L7 要求的状态、快照和跨时点口径是否有合法 L3/L4/域内承载？
- [ ] 评审前后业务语义差异是否全部可追到上游正式真值或 `DEC-x`？

---

## 8. 速判决策树

**发现文档和代码（或两层之间）矛盾了，怎么办？**

```
唯一答案：立刻停止，向人报告具体不一致内容，等人决定。
（裁决链告诉人"理论上谁优先"，但人才是最终决策者，AI 不自动执行裁决。）
```

**刚完成一次代码修改，接下来做什么？**

```
Q: 修改涉及接口或数据库吗？
├─ 是 → 检查 L3/L4 是否已更新；发现不一致 → 人工裁决
└─ 否 → 继续

Q: 修改涉及后端主要业务链路或架构规范吗？
├─ 是 → 检查 L6 主要链路/架构规范描述是否与代码一致；发现不一致 → 人工裁决
└─ 否 → 继续

Q: 修改涉及前端主要业务链路或架构规范吗？
├─ 是 → 检查 L5 主要链路/架构规范描述是否与代码一致；发现不一致 → 人工裁决
└─ 否 → 继续

Q: 修改涉及死亡线区域吗？
├─ 是 → 标记死亡线变更，要求项目指定的真人角色审查
└─ 否 → 继续

Q: 有相关测试用例需要更新吗？
├─ 是 → 更新 L7 对应资产；如涉及 L1 不变量，检查金标准用例
└─ 否 → 继续

└─ 完成。执行评审动作（项目可自定义触发器与命名，如 /review）
```

**该把这个东西放哪一层？**

```
这是「做什么、为什么、交互形态/线框」吗？→ L1 需求层
这是「UI 颜色/字体/视觉排版/高保真设计」吗？→ L2 交互层（页面层）
这是「系统对外暴露的接口字段契约」吗？→ L3 契约层（接口层）
这是「数据如何存储（表/字段/索引/约束）」吗？→ L4 数据库层
这是「客户端/前端架构规范/主要业务链路/技术选型」吗？→ L5 客户端实现规约层（前端技术层）
这是「服务端/后端架构规范/主要业务链路/技术选型」吗？→ L6 服务端实现规约层（后端技术层）
这是「如何验证以上各层的正确性」吗？→ L7 测试用例层
```

---

## 9. 与其他 skill 的协作关系

| 场景 | 本 skill 的职责 | 协作 skill 类型 |
|------|----------------|----------------|
| 需要判断文档属于哪一层、确认放置位置 | 分层裁决与规则参考 | 项目级文档编写指南 skill |
| 新增接口 | 提供 L3 编写规范；按流程先更新 L3 | 项目级接口/后端基础构件 skill |
| 新增数据库表或字段 | 提供 L4 编写规范；按流程先更新 L4 | 项目级数据库基础构件 skill |
| 探查现有数据库结构 | 提供 L4 真值验证依据 | 项目级数据库探查 skill |
| 大型跨会话任务 | 在任务总控中标注各子任务涉及哪些层 | 任务总控 skill |
| 代码审查 | 补充七层一致性检查 | `/review` 工作流 |
| 中等任务管理 | 任务级设计文档标注本轮变更涉及哪些层 | `lightweight-design`；影响面与验收映射留在设计层，施工切片留在 goal 章程 |
| 编写测试用例 | 提供 L7 用例规格、白盒/黑盒设计与冻结规则 | `test-standards` + `test-case-design`；执行见 `test-execution-router` + 项目执行 skill |
| 设计/用例/章程的开放式评审 | 提供真值基线、`DEC-x` 裁决留痕规则与「已决策·不得重开」依据 | `adversarial-review`（单轮开放，主线程裁决） |
| 评审整改的封闭验收 | 冻结前的评审闭环证据（报告终态 = PASS）以其产出为准 | `closed-remediation-review` |
| **自主执行期的文档处置** | 规格冻结后交 goal 自主施工；§2.3 的纯实现自由 / 有界重新冻结 / 回炉分类、文档动作清单与飞行日志 | `goal-charter` |

> 以上协作 skill 中，`test-standards` / `test-case-design` / `test-execution-router` 是用户级通用测试入口；项目执行 skill 名称由项目级补丁维护。