agentsclimarketplace

Doc layer system

Skill BackToCimaCoppi/Praxis/skills/doc-layer-system

给「AI 驱动开发」立规矩的 Claude Code skill 方法论库：七层文档治理 · 对抗评审 · 任务总控三驾马车，外加老代码考古、施工蓝图等共 16 个 skill —— 让 AI 写代码又快又不失控。

Install
npx -y skills add BackToCimaCoppi/Praxis --skill doc-layer-system

Assembled 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

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

SKILL.md

73.9 KB, as published. Nobody here has run it

七层文档体系

本 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 / L7L2（无 UI）/ L5（无客户端）
纯前端（对接外部 API）L1 / L2 / L3 / L5 / L7L4（无自有持久化）/ L6（无自有服务端）
纯前端（离线 / 无后端）L1 / L2 / L5 / L7L3 / 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 之外产出并已过评审 ③ 存在飞行决策日志，每条自愈留痕，用户事后逐条追认

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

情况goal 内动作
代码 ≠ 本次冻结的规格按规格改代码，记飞行日志，不停机
未规定事项属于纯实现自由：任一选择都不改变可观察结果、契约、数据语义、架构边界，也不影响按规格重建在代码中选取合规实现并记日志；不写 L1–L7，避免把代码细节污染成规格
规格有洞但不需要新业务裁决：影响可重建的 L5/L6 选择，且现有正式真值给出唯一合法方向暂停当前施工切片，走“有界重新冻结”：补轻量设计 SD-x → 职责正确的正式层 → 对应 AC-x，更新哈希、主题唯一性账、业务语义差异表与覆盖报告，五项冻结闸门重跑全绿后继续；不问用户、不重开对抗评审
goal 中意外发现的存量陈旧描述，且最新冻结真值已给出唯一答案同样走有界重新冻结，保证轻量设计、正式规格、L7 与覆盖报告同步；若开工前已知，则说明原冻结无效，必须退回冻结阶段
规格错了 / 洞会改变业务结果 / 命中死亡线 / 两份都已冻结的真值真矛盾例外不覆盖，照 §2.2 停机（或走回炉出口——回炉 = 终止本 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）：.claude/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，正文至多一行版本注记。正文亦不得引用任务过程产物（任务总控工作包 / 蓝图 / 评审报告）作为效力依据——效力依据是裁决本身，至多留一行「日期 + 决策号」出处。

实测教训：一份 938 行的施工蓝图之所以自己跟自己打架（同一文件相隔 264 行给出相反的施工指令），根因就是它承载了"施工指令书"这种无上游、只能靠猜的内容。把同类内容塞进 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；仍按人逐工序把关的流程可继续用 construction-blueprint 出施工图纸
编写测试用例提供 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 名称由项目级补丁维护。

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.