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、纯透传/字段映射）以代码为准、不视为冲突；核心决策不许落到"以代码为准"这一档。表达形式与禁列见 §5.5/§5.6。

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

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

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

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

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

生命周期状态字段（必填，记录文档自身的当前状态）：

状态值	含义
草稿	尚未经过正式审核
已审核	已经过主审角色确认，当前为真值
已废弃	对应功能已下线/移除，文档保留供参考
过时待修订	功能仍在，但文档与现状已有已知偏差，待修订

生命周期状态与版本归属组合使用：> 版本归属：V2 | 生命周期状态：已审核

1.3 文档元数据要求

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

字段	说明
版本归属	见 §1.2 规则
生命周期状态	见 §1.2 规则

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

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

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

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

---

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. 询问而非判断（四选一）：「请裁决：(a) 以 [来源 A] 为准，修订 [来源 B]；(b) 以 [来源 B] 为准，修订 [来源 A]；(c) 两边都不完整，需要在 [层] 补写新规则；(d) 无法当下判断，挂起任务。」
4. 等待人的决定，不允许 AI 用裁决链"猜"哪个对
5. 人做出决定后，AI 按人的指示统一更新所有相关层

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

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

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

---

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）：.claude/hooks/post-change-check.sh）
3. 评审拦截层：评审工作流中作为强制检查项（项目可自定义触发器与命名，如 /review）

---

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.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 文档是「表结构是什么」的规格描述。若 migration 与 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 各层的设计意图是否被正确实现。

四类测试用例资产：

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

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

执行绑定要求（强制）：

• 每条 L7 用例必须填写 execution_ref 字段，指向至少一个可执行测试资产（文件路径 + 测试名 / Case ID）
• 手工验证场景类例外，但仍需 manual_runbook_ref 字段指向对应手工验证手册
• 每个执行资产（测试文件）须在文件头部声明 covers: [L7-case-id, ...] 列出覆盖的 L7 用例
• 金标准用例若无 execution_ref，视为「未生效」，必须在 PR 描述中明确标注并在合并前补全
• 项目可选实现 lint 脚本，校验 L7 规格 ↔ 执行资产双向引用完整性

execution_ref 最小协议：

合法类型仅三类（不在此三类内的引用不视为有效绑定）：

1. 测试文件路径：仓库相对路径 + 用例锚点，格式如 src/test/java/example/ActivityTest.java#testCreateActivity
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 是否需要更新？

---

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 工作流
中等任务管理	任务级设计文档标注本轮变更涉及哪些层	轻量设计方案 / 施工蓝图 skill
编写测试用例	提供 L7 四类用例规格与金标准规则	项目级测试与金标准 skill

以上协作 skill 均为类型描述，具体 skill 名称由项目在项目级 skill 补丁中维护。本 skill 不引用任何具体项目的 skill 名称。