Doc Layer System

七层文档体系

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

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

0. 适用范围与形态映射

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

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

0.1 审核能力矩阵

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

0.2 项目形态与层裁剪

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

说明：

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

0.3 业务域与功能模块

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

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

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

1. 七层定义速查

审核强度说明：

• 🔴 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 版本归属与生命周期状态

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

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

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

1.3 文档元数据要求

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

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

项目补丁可声明推断脚本，将 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 三级冲突分级

判断分级的辅助输入：变更面（是否涉及契约面）+ 死亡线标记（死亡线区域的任何语义冲突自动升级到 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 每撞一次文档不一致就要停机，结果管控当场退化回过程管控——这正是要治的病。

禁止只补 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 改动扫描矩阵

代码变更扫描展开表：

3.2 钩子实现三层联动

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

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

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

任一要求只有 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.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：

没有"实录层"这种东西。 七层里不存在"施工后按代码回写"的层——那是代码镜像层的定义，而 §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 持有，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 规格层。

四类测试用例资产：

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

执行绑定要求（强制）：

• 一条 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 规格 ↔ 执行资产双向引用完整性

强制测试形状：

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 必须先解除

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

金标准不可删除规则：

等价替代三条件（全部满足才允许替换删除金标准用例）：

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 中，test-standards / test-case-design / test-execution-router 是用户级通用测试入口；项目执行 skill 名称由项目级补丁维护。