doc-layer-systemlisted

# 七层文档体系 本 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 /