轻量设计方案
本 skill 是一次任务里高风险大决策的「清算层」,用户级通用,可跨项目使用。
它解决的问题:大量任务是局部修改/改造,不值得每次重写整域 L5/L6;但只拿需求直接开工,AI 会在最危险的几个取舍上"看似合理地选错"。轻量设计就是补在中间的那一层——把会出事故的决策,在动工前、在人能拍板的地方,逐个清算到唯一选择。
与下游的分界线是【风险】,不是【海拔】。 做错会出事故(拆不动 / 牵一发动全身 / 漏钱 / 白送权益 / 越权 / 丢数据)→ 本层清算钉死; 做错只是返工(参数名 / 方法互调 / 字段内部实现)→ 不进任何文档,代码自由范围。
轻量设计方案 ── 高风险决策清算 + 影响面勘察 + 验收映射 ── 人工拍板闸(本 skill)
↓ 清算结论冻结为只读输入
测试用例设计 ── 完整用例直接写正式 L7 + 断言编号(待统一冻结)
↓
真值收敛与规格冻结 ── SD → 正式规格 → AC 对账全绿,七层一次冻完
↓
goal 章程 ───── 把裁决转成执行契约(目标+验证器+边界+切片) ── 接受红队评审(goal-charter)
↓
goal 执行 ───── 自主生产精确候选:代码 → 提交 → 测试 → 执行证据清单 → CANDIDATE_READY
↓ 候选 commit/tree + 真值基线 + 证据
候选终审 ──── 独立验收真实断言、边界形状与实现语义;闭环整改后才允许任务完成
本流程不再产出施工蓝图(它自己跟自己打架:同一份近千行文件前后给出相反的施工指令;
construction-blueprintskill 仅供传统人工逐工序把关的流程可选使用)。它的两个器官各有新家:影响面勘察 + 验收映射 → 本层 §7;施工切片 → goal 章程的里程碑。 而它的第三部分「逐文件施工指令书」没有新家,是被删掉的——那是全链条唯一无上游、只能靠猜的内容,必然腐烂。
⚠️ 这一层防的是"空心设计"——决策表填满了、却把最危险的取舍一句话糊过或下放给没人细看的下游。 防空心不靠更厚的模板(模板越厚越容易被"逐项 N/A 扫一遍"形式合规糊过),靠两件事: ① 事实基线(每个高风险决策必须锚定"我在真实代码/业务真值里读到了什么",而非"列了哪些文件"); ② 失败标准(自检每一项都有明确的"什么算不合格",写几个字不算过)。
0. 触发、分档与两层边界
0.1 什么时候用 / 不用
用(满足任一即考虑):局部功能开发 / 局部重构 / 单链路改造,且存在会出事故的决策点;或任务跨多文件易范围蔓延;或用户要求"先出设计再动手"。
不用:
| 场景 | 改用 |
|---|---|
| 小改动(修 bug、加字段、单文件小改,无事故级决策) | 计划模式,零文档成本 |
| 小任务(有决策点或测试义务,单会话可完成,未命中反向升级项) | plan-goal:一份全包计划 → 业务决策负责人批准 → goal 执行 |
| 整域级设计 / 新域立项 | 直接写七层正式文档 |
| 纯执行、无决策点的机械任务 | 直接做 |
| 跨会话、多 agent 超大任务 | task-control-doc 总控(标准模式七阶段,本层是其第 ③ 阶段) |
反向升级(轻量设计也不够用,必须升正式七层 / 专项):资金/权益/权限整链路重构 · 跨多业务域 · 不可逆数据迁移 · 阻塞级决策相互耦合、无法在一次拍板内独立收敛。别把这类硬塞进"轻量"假装轻量。
拆分前置闸(拆分必须早于评审,不许"先合评、评到一半再拆"):起草时若发现一份方案实为不同风险档的可分离子设计(典型:一半是跨域 / 升正式 L6 的架构地基、一半是域内可一次收敛的轻量改造),必须在进对抗评审闸之前先拆开,各子设计按自己的档位(轻量 / 正式七层)独立走流程。
为什么前置:合起来评审 N 轮后才拆,母稿那 N 轮评审随即作废,拆出的每一半都要从头重评——评审轮次直接翻倍。拆分判定属本层职责,不是评审能帮你做的事。可分离判据:两部分能各自独立拍板、各自冻结、互相只以"接口 / 引用结论"耦合而非"同一决策反复横跳"。
死亡线区域的局部改造不升出本层——仍走轻量设计,但强制升评审强度(判阻塞级 + 过双闸,不得单评审放行);只有整链路重构 / 跨多域 / 不可逆迁移才升正式七层。(区分依据 = 范围 + 不可逆程度,与项目补丁的死亡线流程对齐。)
0.2 风险三级分级(决定清算深度,也决定篇幅)
判据 = 「这条做错,是否触碰某条不变量 / 死亡线?」(不变量 / 死亡线清单由项目补丁注入;不按产物类型划——字段类型也可能是死亡线,如跨域 ID 用 VARCHAR、金额精度)。
| 级别 | 判定 | 清算深度(见 §4) |
|---|---|---|
| 阻塞级 | 触碰死亡线 / 不可逆 / 无上游真值需人拍 | 走完整六要素 |
| 重要级 | 灰区——非立即事故但非普通返工(性能退化 / 口径污染 / 历史兼容 / 上线窗口 / 监控缺口〔挂钱权数据链路的按 §4.1② 跨级别升阻塞〕) | 简化(候选 + 选定 + 理由 + 验证) |
| 低级 | 做错只是返工 | 只记归属 + 验证点;或直接交给施工时自行决定 |
二分判据会把大量真实决策卡在灰区让 agent 自由发挥——所以用三级,灰区一律落"重要级",不放过也不上满六要素。
术语锚定:全文「高风险决策」= 阻塞级 + 重要级。事实基线(§1.2)三项随级分级——阻塞级走满三项;重要级至少锚定 item1「读到的真实约束」,item2/3 视情可省。 无项目补丁时的兜底判级:以「不可逆 / 无上游真值需人拍 / 触碰钱权数据」(§8)为通用最低死亡线兜底;补丁只加严、不启用判级(裸用户并非全盲)。
0.3 篇幅预算(守住"轻量")
- 未命中的扫描项(§3)只写一句结论,不展开。
- 普通任务只展开命中的风险,不为凑格式机械填表。
- 深度随风险分级比例化——只有阻塞级才上满六要素。
- 最小执行路径(低/重要级任务起步):§1.2 事实基线 + §3 命中项 + §4.2 对应深度 + §9 对应项即可;阻塞级才追加六要素 + §4.3 + §5。轻任务不必通读全文。
0.4 两层关系与接点
- 两层关系:本层 = 人工不可逆裁决(业务取舍 + 架构归属);章程层(
goal-charter)= 把裁决转成执行契约(目标 + 验证器 + 边界 + 切片)并接受红队评审。"没人细看下游"只对人工细读为真——章程照样要过红队闸,不得因此被丢内容。 - 对抗评审接点:高风险任务在人审拍板前,必须先过一道独立对抗评审 / 机检闸(机器或独立第三方查"覆盖度真伪",人只拍"业务取舍"——人审对覆盖度结构性失明:无法判断量化是否编的、N/A 是否真 N/A、归属是否串域;人审只冻结业务裁决与 §4/§2/§5 主靶面,覆盖度真伪由本闸把关——详 §11/§12)。
- 补丁无关默认过闸线:任务含 ≥1 阻塞级决策 或 触碰钱/权/数据 → 强制过闸(补丁只能加严、不能取消)。
- 双闸分立:本层是设计层闸(查覆盖度 + 业务取舍),章程层另有章程层闸(红队四问:作弊路径 / 必卡路径 / 漏停路径 / 断点丢失),两闸焦点不同、不互相替代。口径卡见
adversarial-review的references/profiles/。 - 编排归
adversarial-reviewskill,本 skill 只声明接点,不内化其流程。 - 进闸前置条件(事实须已"核真"而非仅"已填"):进对抗评审闸前,§1.2 事实基线里承重锚点必须已被独立核验为真(可定位、可被第三方按锚点复核),不是"填了字段"就算数。事实未核真即进闸 = 评审轮次空耗——评审者与主线程会把整轮花在核"设计稿 / 对方评审者的事实真伪"上,而不是裁决业务取舍;现状代码读错一处,往往要多烧一整轮才纠回来。死亡线 / 改造模式决策,进闸前先用只读核验把承重事实钉死。
- 单次开放评审:同一阶段、同一真值基线、同一设计对象只允许一次开放式对抗评审。报告回补后调用
closed-remediation-review做封闭验收:本工具一个原生子线程只检查原采纳项与用户裁决,主线程逐条裁决。禁止自动 R2/R3;只有用户裁决、上游正式真值或设计发生根本重写时,登记旧评审失效原因后才可把新版本作为新对象评审。
- 返闸机制:写章程或施工中发现新增的高风险决策(会改变业务结果 / 不可逆归属)→ 退回本层补裁决,不许在下游自行处理或悄悄改。
- 例外(不返人审):施工中撞见未规定事项时,纯实现自由只进代码;若影响按规格重建但现有正式真值给出唯一方向,则按
doc-layer-system§2.3 自动走有界重新冻结,同步补SD-x → TOPIC-x → 正式规格 → AC-x与五项闸门覆盖报告(doc-layer-system§3.4),不打扰用户、不重开对抗评审。禁止只补 L5/L6 后继续。
- 例外(不返人审):施工中撞见未规定事项时,纯实现自由只进代码;若影响按规格重建但现有正式真值给出唯一方向,则按
1. 输入与事实基线(硬闸)
1.1 输入双轨(业务语义恒含)
| 任务类型 | 必备输入 |
|---|---|
| 改造现有代码 | 业务语义真值 + 真实代码(硬闸) |
| 从 0 新建 | 业务语义真值 |
- 业务语义两种模式都必须有;真实代码只在改造模式追加为硬闸。
- 真值与证据分离:本轮
DEC-x与既有正式 L1–L7 是可物化的规格来源;现有生产行为和代码只用于发现事实、冲突与候选规格,不取得裁决权。任一来源不一致都必须显式列出并按doc-layer-system§2 处理,禁止用“优先级链”静默选边。
1.2 事实基线(每个高风险决策必填——这是防空心的第一道闸)
校验"读到了什么 + 确认了什么",不是"列了哪些文件"——从二手报告也能抄出文件路径,列文件 ≠ 读代码。
每个高风险决策必须绑定三项:
- 读到的真实约束:我在真实代码 / 业务真值里读到的、会约束本决策的不变量 / 签名 / 现状(改造模式强制锚定真实代码,不是凭印象)。
- 未确认点(0..n):还没核实的事实 + 打算怎么处理(核实 / 假设并登记 / 升阻塞);若为 0,必须写明本决策已由哪些真值闭合——不强凑假阻塞。
- 一个不能猜的业务前提:这条若靠猜会出事的业务口径,明确它来自哪个真值源。
分级与模式 carve-out:重要级决策至少锚定 item1,item2/3 视情可省(§0.2 术语锚定)。从 0 模式 item1 改锚定业务真值 / 上游契约,三项可合并为「读到的业务约束 + 不能猜的前提」两项(与 §5 从 0 carve-out 对齐)。
1.3 授权裁决记录(业务语义来源硬闸)
凡决策会改变业务结果、命中死亡线、改变对外契约/持久化语义或决定不可逆架构归属,若答案不在上游正式真值中,必须由业务决策负责人裁决并写入任务级 _shared/用户裁决记录.md。该路径名为兼容既有工具保留,不表示任务发起人或当前交互方自动拥有裁决权:
| 字段 | 要求 |
|---|---|
decision_id |
稳定 DEC-x,冻结后不复用 |
| 裁决问题 | 一次只问一个独立业务选择,禁止把多项捆成“总体同意” |
| 用户原话或明确选项 | 原文/选项编号,不用 AI 总结替代 |
| 日期与来源 | 会话日期 + 可定位来源 |
| 适用范围 | 影响哪些 DP/SD、域、能力和版本 |
AI 可以把本切片全部真实缺口合并成一张表交业务决策负责人集中裁决;项目要求会签时按治理策略执行。回填时必须逐项生成 DEC-x。评审者建议、主线程偏好、代码现状和任务发起行为都不能伪装成授权裁决。没有有效来源时禁止写“已批准 / 已拍板”。
2. 范围与负面清单
- 本次改什么;本次明确不改什么(负面清单要硬,不许模糊)。
- 每条"不改"项标风险等级 + 接受主体——最危险的问题最容易被塞进负面清单逃掉(如"不处理历史数据""不改权限链路")。高风险不改项必须进 §4 清算或明确挂起,不许一句"本次不改"带过。
- 触碰钱 / 权 / 数据的不改项或残余风险,接受主体只能是用户或明确上游真值,不得由运营 / 技术口头接受(否则进 §4 清算或挂 §8)。
3. 扫描层(发现风险)
逐项扫下面这张非穷尽种子清单,命中就上 §4 清算。下表种子(非穷尽)之外,强制由项目补丁映射本项目死亡线,并加一条"其他本项目死亡线"兜底项——封闭全集会给"已扫全"的虚假底气。
| 种子 | 要问的 |
|---|---|
| 幂等 | 幂等键是哪几个业务字段、覆盖哪些重放、漏哪些 |
| 一致性边界 | 哪里强一致 / 哪里最终一致、可容忍窗口多大、谁对账兜底 |
| 并发竞态 | TOCTOU / 超卖 / 双写在哪、用什么守、残余窗口多大 |
| 真值源 | 同一数据真值在哪、不一致时谁说了算、失效覆盖全不全 |
| 失败与回滚 | 失败回滚到哪个状态、补偿手段、回滚本身会不会再失败 |
| 边界态口径 | 成功/失败之外的中间态(超时 / 部分成功 / 重复 / 撤销)各自处置 |
| 状态机完整性 | 谁驱动迁移、非法迁移怎么挡、触发点在哪 |
| 权限与数据访问边界 | 谁能看 / 谁能改 / 谁能触发 / 谁能追责;敏感信息、审计留痕 |
| 资金 / 精度 / 隐私 / 时区 | 金额精度与口径、隐私合规、时区时间 |
| 外部依赖 | 不可用 / 异常 / 契约变更 / 权限不足时怎么办(前置条件 + 降级策略 + 失败责任边界) |
| 迁移与上线 | 发布顺序 / 灰度 / 回滚窗口 / 双写读旧读新 / 兼容期 / 存量数据如何解释、历史异常修复或保留 |
| 其他本项目死亡线 | 由项目补丁注入 |
正向处置(关键):每个种子要么命中→进 §4,要么未命中→写一行"为何不适用"且锚定到 §1 读到的真实证据(同质未命中种子可合并为一组、给一条共同覆盖证据,但该证据必须真覆盖组内每项——颗粒度从每种子降到每组)。
无证据的 N/A 视为未扫——否则病灶只是从"跳过决策"搬家到"把藏身处标 N/A"。
4. 清算层(裁决)★核心
进入清算的每个决策点获得稳定编号 DP-x(清算表内按出现顺序赋号;定稿后不重排、不复用),供 SD-x 的 decision_refs 与 §7.4 验收映射引用。
4.1 六要素画像(阻塞级走满)
每个阻塞级决策点钉死六要素:
| 要素 | 要求 |
|---|---|
| ① 候选方案 | 默认 ≥2;只有一个合规解时允许单候选,但必须列出排除其他方案的硬约束(不变量/死亡线/上游裁决)证明唯一性——否则视为未清算(防"硬凑两个"也防"一律单候选逃避") |
| ② 残余风险刻画 | 分级 + 条件量化:有数据则量化;无数据则写"失败模式刻画 + 最坏界 + 量化所需证据/前置"。未量化分流:① 该量化是决策关键 或 触碰钱/权/数据(含资金链路监控缺口)→ 升阻塞级待确认(跨级别全局闸,不受所在级别限制,堵"压成重要级即可不量化"的逃生);② 非决策关键的观测缺口 → 记录,不阻塞。禁止编"漏 0.1%""窗口约 50ms"伪精度。架构/不可逆类用定性 + 拆改代价,不套定量界。内含 ≥1 失败反例:什么输入/状态/时序会出问题、为什么选定方案能挡住 |
| ③ 业务可接受度 | 这个残余风险业务吃不吃得下?吃不下→该方案出局。裁决主体三分:已由上游文档明确 / 需业务决策负责人裁决 / 默认不可接受——缺裁决必须进阻塞,agent 不得替业务拍板(漏钱/权益/权限/口径尤其) |
| ④ 阻碍与代价 | 各方案卡在哪(资质 / 性能 / 复杂度 / 跨域) |
| ⑤ 选定 + 为什么 | 在①~④基础上的裁决 |
| ⑥ 怎么验证它没被破坏 | 给可转译的验收条件:验收口径 + 关键样例 + 失败判定(写条件,不写测试实现)。资金/权益/数据类加一行运行期观测信号:上线后靠什么信号能发现被破坏 + 什么信号触发止损。强制带入 §7.4 验收映射(连成 DP-x → AC-x)与 §7.5 规格冻结清单,登记为点名的 L7 测试义务 |
4.2 分级深度
- 阻塞级 → 完整六要素。
- 重要级 → 简化:候选 + 选定 + 理由 + 验证(含事实基线 item1)。
- 低级 → 只记归属 + 验证点。
4.3 组合一致性检查(清算层末尾,必做)
六要素是逐点纵深,缺横向视图——单个决策都对、合在一起可能打架(一个要强一致、另一个接受异步补偿;一个要归属唯一、另一个让能力跨域复用)。 本表覆盖 §4 + §5 全部高风险决策(含 §5 架构归属)。 从维度菜单(事务边界 / 真值源 / 依赖方向 / 上线策略 / 一致性模型 / 失败口径)取本任务命中的维度,每决策声明各命中维度取值;任一维度跨决策矛盾,必须列「取舍归一」,否则自检失败。
5. 架构沉淀层(不可逆子类,纳入六要素纪律)
架构决策是清算层的不可逆特殊子类,走六要素(候选 ≥2 套架构、残余风险 = 拆不动 / 耦合代价,定性)。它最不可见、最不可逆、违规种类随 域×功能 组合爆炸——靠"预声明归属 + 不变量"让违规变成可检偏离,不靠评审逐个抓。
本 skill 本体只保留抽象槽位(具体规则下沉项目补丁,不得把单一项目的架构公理硬编进通用本体):
- 承重性约束 = 本项目承重架构不变量(项目补丁定义);抽象到两维度:责任边界 + 依赖边界。
- 产出归属 / 跨域声明表(模板占位,字段由补丁映射成域/模块/层/接口面): · 本次每个数据 / 逻辑单元归属唯一 · 每个跨域交互点走哪个对外接口面、传什么契约(承重 = 任何被非本模块现存调用方依赖的命名/契约面:HTTP/RPC/Facade/事件主题/持久化 schema/配置 key 等,具体枚举由补丁映射;仅无外部现存依赖的模块内部命名才是可松的装饰性规范) · 依赖方向(禁反向、禁环) · 职责单一检查(本次改动会不会让某现有模块变胖) · 预留缝:必须绑定已确认的上游需求 / 明确近期计划 / 用户裁决,否则默认不留(防过度设计合法化)
- 模式区分:改造模式钉死现有归属,仅作偏离检测基线——若本次需纠偏现有违规归属(如跨域直连、common 塞业务规则),把纠偏当一个高风险决策走 §4 清算(列目标归属 + 迁移裁决),不在 §5 默认照搬现状;从 0 模式只钉边界原则 + 首批不可逆选择,不凭空造一整套架构。
- 机检机制二选一写实,不留空头承诺:明确对接项目的机检钩子,或降级为"人工对照声明表复核"——但人工对照仅用于非高风险归属;触碰承重不变量 / 死亡线的高风险架构归属,机检缺位时必须由独立角色复核或经用户显式豁免(与 §0.4 独立闸一致)。
6. 关键约束链路(取代逐文件)
- 至少画清一条端到端主链路上"不能变的边界":分层走向 / 跨域点 / 事务边界 / 幂等点 / 失败点。
- 只到"落哪个域哪层 + 新建哪些结构性单元 + 边界画在哪",不下沉逐文件施工序列(那属 goal 章程的切片;但 §7.1 影响面勘察要求真读代码——勘察是"现状证据",不是"施工序列")。
- 本层与章程的分界 = 本层拥有"必须成立的不变量与边界",章程拥有"实现它们的切片编排与验证命令"。
- 本层清算结论冻结为下游的只读输入,章程与 goal 不得重开本层已清算的决策。
7. 影响面、规格物化与上游冲突
7.1 影响面勘察(本层产出,下游切片的唯一依据)
判据沿用 §1.2:勘察写的是「读到了什么」,不是「列了哪些文件」。从二手报告也能抄出一串文件路径——列文件 ≠ 读代码。
为什么它在这一层:施工切片(goal 章程的里程碑)需要文件/模块级的现状知识,而本层明确不下沉逐文件施工序列(§14)。勘察是决策级的现状证据,不是施工序列——它回答"改这里会牵动谁",不回答"第几步改哪一行"。没有它,下游就得靠猜切片。
触发式判定(机械化,不靠主观感觉)——逐条判,未触发也要写一行事实锚点,不许只写一句"不适用":
| 触发项 | 命中则必须勘察到什么 |
|---|---|
| 改了对外契约(接口签名/字段/错误码/枚举) | 全部现存消费方逐个点名 + 各自怎么用它 + 改了会怎样 |
| 改了表结构 / 数据语义 | 所有读写方 + 是否有历史数据需要迁移 + 兼容窗口 |
| 改了共享组件 / 公共方法 | 调用点清单 + 有没有依赖了当前行为的隐式假设 |
| 改了状态机 / 生命周期 | 每个已有状态的现存产生者与消费者 |
| 删除 / 重命名任何公开符号 | 引用点全清 + 是否有反射/配置/字符串引用(grep 不到的) |
| 未知消费方(搜不到、或跨仓库) | 显式登记为假设,进 §8 假设台账,不许当作"没有" |
勘察条目的最低形态(缺一即空心):
- 对象:{文件/模块/符号}
- 现状:{读到的事实——它现在怎么工作,关键行为是什么}
- 牵动:{改了之后谁会受影响,怎么受影响}
- 处置:{本次改它 / 本次不改但需兼容 / 登记为假设}
移植说明(防机械平移):本节器官来自施工蓝图(施工事实基线 + 影响面覆盖两部分;本流程已不再产出蓝图)。蓝图是文件级 + 逐条触发式,本层是决策级 + 种子清单式(§13 标题就叫「防机械平移」)。照搬蓝图的文件级粒度到这里,等于把蓝图复活在设计层——那正是要治的病。
勘察完成后必须冻结“任务真值切片”:按业务能力而非文件列表声明本任务涉及的域、平台、契约消费方、数据读写方、状态产生者/消费者及 L1~L7 候选文档。调查阶段清单只是种子,不得充当最终白名单。切片外腐烂只登记债务,不扩张本任务。
7.2 规范条目索引(零遗漏物化)
轻量设计中所有会约束施工或验收的有效语义都必须原子化为稳定编号 SD-x,不能只索引高风险 DP-x。至少覆盖:选定决策、业务规则、数值口径、状态/失败语义、负面约束、兼容/迁移策略、架构归属、跨域边界和验证义务。
| 规范条目 | 类型 | 内容摘要 | 来源决策 | 正式规格目标 | 验收覆盖 |
|---|---|---|---|---|---|
| SD-1 | 业务规则 | … | DP-1 | docs/01-…#…、docs/06-…#… |
AC-1, AC-3 |
- 写入覆盖报告 JSON 时,表中「类型 / 内容摘要 / 来源决策」分别映射为
type / statement / decision_refs;id保持SD-x。这四项构成设计哈希载荷。 - 每个
SD-x必须有至少一个formal_spec_refs;一条可物化到多层。 decision_refs继续引用来源DP-x;另设provenance_refs。改变业务结果、死亡线、契约/数据语义或不可逆归属的SD-x,其provenance_refs必须引用上游正式真值或DEC-x;不得引用评审意见代替裁决。provenance_refs不进入design_index_hash,但冻结前必须可解析。- 候选方案、放弃理由、调查证据和评审过程不进入
SD-x,留在轻量设计保存“为什么”。 - 索引定稿后记录
design_index_hash;T5 只能补正式落点和 AC 引用,不能静默删除或改写SD-x语义。 - 哈希规范固定为:按
SD-x数字顺序取id/type/statement/decision_refs四字段,组成 UTF-8 JSON(ensure_ascii=false、键排序、无多余空白)后算 SHA-256。正式落点与 AC 引用不入哈希,允许 T4/T5 补齐而不改变设计语义锚。 - 存在未物化
SD-x→ 规格冻结失败。
7.3 业务主题唯一性账(TOPIC-x)
SD-x 证明“有效设计语义没丢”,TOPIC-x 证明“同一问题在全部正式层里只有一个答案”。最终任务真值切片必须为每个会改变可观察结果、契约、持久化语义或架构边界的问题登记:
| topic_id | question | positive_rule | forbidden_outcomes | boundary | failure_closure | formal_spec_refs | provenance_refs |
|---|---|---|---|---|---|---|---|
| TOPIC-1 | … | … | […] | … | … | [docs/01-…#…, docs/07-…#…] |
[SD-1, DEC-1] |
- 每个
TOPIC-x必须列出切片内全部正式锚点,不得只挑一份“看起来最新”的文档。 positive_rule与forbidden_outcomes必须可以在每个锚点中对账;存在两个正式锚点支持相反结果,冻结失败。semantic_uniqueness_pass只能在全部 TOPIC 已完成跨锚点比对且零矛盾时为真。
7.4 验收映射(DP-x → AC-x)
每个决策点必须能连到至少一条验收条件,连不上的决策点 = 没人验 = 施工时可以偷偷不做:
| 决策点 | 验收条件 |
|---|---|
| DP-1 | AC-1, AC-3 ←(示例;编号由下游 test-case-design 分配后回填,本层产出时先留空或写验收口径) |
| DP-2 | AC-2(同上) |
- 判失败:存在 DP-x 没有任何 AC 覆盖 → 要么补验收条件,要么这个"决策"其实不是决策(降级删掉)
- 本层只声明可转译的验收条件;用例的具体断言与编号归
test-case-design(下游据此给 AC-x 分配稳定编号) - 只禁止实现文件施工序列;正式 L1~L7 的文件与小节锚点必须写,因为它们是
SD → SPEC → AC追溯链的中段,不是逐文件施工序列
7.5 规格冻结清单
本次设计要在施工前冻结哪几层、哪几份文档,逐份点名(接口→L3、表→L4、核心决策与链路→L5/L6、用例→L7);§4⑥ 的验证义务登记到 L7。L1~L7 每层必须标记 已修订 / 已核验无需改 / 不适用(附证据),不能因无改动而省略检查。
- 长期沉淀判据(连通两套试金石):本层按风险轴分级,L5/L6 按决策风险试金石(「不写下来,有能力的 AI 施工时会不会裁出与拍板不同的选择」)收录——两轴不重合。凡过该试金石的决策点(含重要级 / 低级),冻结清单必须点名落 L5/L6;仅本任务内一次性有效的结论随任务归档,不进七层。
不是"完工后回补":七层文档全部是规格层、全部先于代码存在(
doc-layer-system§5.0:把代码全删了能照文档重做)。实现细节属代码自由范围,不进任何文档,所以没有"施工后回血"这回事。
7.6 上游冲突清单
本次设计凡偏离现有需求 / 上游文档之处,必须显式标注是 "修正文档 / 临时例外 / 用户重新裁决" 之一,禁止静默覆盖上游真值(临时设计层最容易悄悄反写真值、撕裂文档体系;冲突按 doc-layer-system §2 三级分级走人工裁决,AI 不得自行选边)。
8. 假设台账与阻塞闸
本 skill 自我定位"唯一人工拍板闸",就必须定义什么送人审、什么 agent 可自行假设(否则要么什么都挂起淹没人审,要么静默假设复发空心病)。
- 假设台账:凡"若此假设错则跨过某条事故线"的未验证假设 = 强制阻塞确认;其余假设记录并推进。
- 阻塞标准:影响 钱 / 权 / 数据 / 不可逆架构 / 上线安全 / 业务口径 且无上游真值时 → 必须由业务决策负责人裁决;记录实际解除角色与依据。
- 阻塞级待确认未清零 → 整任务挂起,禁止进入规格冻结 / 章程 / 施工。
9. 自检(每项带失败标准)
自检若只问"是否扫过 / 是否声明",写几个字就能过——等于把 N/A 扫荡漏洞复制到自检。每项给明确失败标准:
| 自检项 | 判失败 |
|---|---|
| 事实基线 | 任一高风险决策未绑定真实读到的约束 → 失败 |
| 进闸前核真 | 死亡线 / 改造模式决策进对抗评审闸时,承重事实锚点未独立核真(仅"填了"未"核真",第三方按锚点复核不能) → 失败(§0.4) |
| 拆分前置 | 一份方案实为不同风险档可分离子设计却未在进闸前拆开、合起来评审 → 失败(§0.1) |
| 扫描覆盖 | 任一种子既未清算、又无带证据的"不适用"理由 → 失败 |
| 残余风险 | 阻塞级决策残余风险未刻画(或用了伪精度) → 失败 |
| 业务可接受度 | 裁决主体未明确、该送人审的没送 → 失败 |
| 候选充分性 | 单候选未列证唯一性硬约束 → 失败 |
| 负面清单 | 高风险不改项未进 §4 清算 / 未挂起,或未标风险等级 + 接受主体 → 失败 |
| 验证 | ⑥未给可转译验收条件、未登记 L7 → 失败 |
| 组合一致性 | 约束表未做 / 矛盾未解 → 失败 |
| 架构归属 | 本次单元归属未逐项声明 / 出现串域 → 失败 |
| 影响面勘察 | §7.1 触发项命中却只列了文件名没写"读到什么" → 失败;命中项未逐个点名现存消费方 → 失败;未触发项没有事实锚点、只写一句"不适用" → 失败(§7.1) |
| 未知消费方 | 搜不到 / 跨仓库的消费方**被当作"没有"**而非登记进 §8 假设台账 → 失败 |
| 规范条目物化 | 任一有效设计语义未进入 SD-x、任一 SD-x 无正式规格落点、design_index_hash 缺失或被静默改写 → 失败 |
| 主题唯一性 | 会改变可观察结果/契约/持久化语义/架构边界的问题未登记 TOPIC-x,或任一 TOPIC 未完成跨锚点比对、存在矛盾未解 → 失败(§7.3) |
| 授权裁决溯源 | 任一高风险 DP/SD 写“已批准”却无 DEC-x 原始证据和授权角色,或把多项决定捆绑成一个笼统确认 → 失败 |
| 业务语义差异 | 未对比评审前后设计并列出新增/删除/改写的业务结果,或评审建议被静默升格为正式规则 → 失败 |
| 验收映射 | 存在 DP-x 没有任何 AC 覆盖,或 AC 只引用轻量设计而没有正式规格来源 → 失败 |
| 规格冻结清单 | 未逐份点名、L1~L7 任一层无检查结论、切片内已知文档债非零、写成"完工后回补" → 失败 |
| 阻塞 | 阻塞项未清零又未挂起 → 失败 |
| 上游冲突 | 偏离上游处未标注处置方式 → 失败 |
10. 文档模板
# 轻量设计方案:{任务名}
> 状态:草稿 / 已过对抗评审闸 / 已拍板 / 已转写(非施工真值)
> 真值基线:{业务语义来源;改造任务列真实代码事实基线}
> 风险概览:阻塞级 N 个 / 重要级 M 个 / 已挂起 K 个
> design_index_hash:{SD-x 索引哈希}
## 1. 背景与意图(3 行内)
## 2. 范围与负面清单(每条不改项标风险等级 + 接受主体)
## 3. 风险扫描(种子清单逐项:命中→进 §4;未命中→一行带证据"不适用")
## 4. 高风险决策清算 ★(每个决策内含事实基线,按 §1.2 分级;阻塞级走六要素 / 重要级简化 / 低级只记归属)
## 4.x 组合一致性约束表
## 5. 架构归属 + 跨域声明表(承重不变量来自项目补丁)
## 6. 关键约束链路(不能变的边界,不下沉逐文件)
## 7. 影响面勘察 + 最终任务真值切片 + 规范条目索引(SD-x → 正式规格 → AC-x)+ 业务主题唯一性账(TOPIC-x)+ 验收映射 + 规格冻结清单 + 上游冲突清单
## 8. 授权裁决记录索引(DEC-x)+ 评审前后业务语义差异 + 假设台账 + 阻塞项
两份标定样例(1 决策极简版 + 多决策版)见
references/标定样例.md——照样例锚定深度,别锚定到最大模板把局部小改写成巨物。
11. 生命周期(六态)
拆分判定(可分离子设计先拆,§0.1)→ 起草(事实基线核真)→ 扫描+清算+影响面勘察+主题登记(TOPIC-x)+验收映射 → **一次开放式对抗评审** → 汇总真实授权裁决并生成 `DEC-x` → 回补 → `closed-remediation-review` 封闭验收 PASS → 业务决策负责人批准 → 冻结为下游只读输入 → 归档降级
- 拍板点:§4 清算表 + §2 负面清单 + §5 架构归属 是用户审核主靶面;拍板即冻结,后续施工不得自行重裁(要改走 §0.4 返闸)。
- 修订纪律:冻结的是决策语义,不是文字。返闸 / 回炉结论经拍板后必须改写正文为当前真值——禁止用「回炉标注 / "上文应理解为" / 后节覆盖前节的优先序规则」做追加式演进(那会让拍板者先做补丁合并才能读到真值);版本历史留 git 与评审报告,正文头部至多一行版本注记。
- 施工期:施工 AI 看的是已冻结的七层规格 + goal 章程,本文档是它们的上游依据。仅 §7.6 已显式列入并裁决过的冲突,施工期以本文档为准;施工中发现 §7.6 未列的新冲突,涉及新业务语义则按 §0.4 返闸重裁,纯实现自由只进代码,现有真值给出唯一方向的可重建性缺口走 §2.3 有界重新冻结。不得自动以本文档覆盖上游真值,也不得只补某一正式层。
- 归档降级:规格物化完成后在文档头标记“已转写(非施工真值)”并列出正式规格锚点;轻量设计保留决策理由,但施工只读冻结七层与 goal 章程。
12. 写作纪律
- 本层写"约束",不写"实现":禁代码 / 伪代码 / 逐方法调用链复述。注意与 §7.1 影响面勘察不冲突:勘察写的是"读到的现状事实"(这个消费方现在怎么用它、改了会怎样),不是"我要怎么实现"。
- 锚点制:标识符(类名 / 表名 / 字段名 / 接口面)仅作定位锚点,每个论点至多一个。
- 精炼 ≠ 含糊:每个裁决锁死到唯一选择,禁止"采用合适的策略"式模糊措辞。
- 一个不读代码的人能看懂并拍板业务取舍;但覆盖度真伪由 §0.4 对抗评审闸把关,不指望人审。
13. 项目补丁挂载点
以下由各项目的项目级补丁(项目七层补丁 skill 或项目 CLAUDE.md)声明:
| 挂载项 | 内容 |
|---|---|
| 死亡线清单 | §0.2 风险分级、§3 兜底项的判定依据 |
| 承重架构不变量 | §5 的"本项目承重性约束"具体规则(域 / 分层 / 依赖 / 接口面) |
| 域/模块/层/接口面映射 | §5 归属表字段映射成项目真实形态 |
| 机检钩子 | §5 机检机制对接的具体钩子;§0.4 对抗评审闸的升级规则 |
| 金标准领域 | §4⑥ 验证义务对应的金标准覆盖面 |
| 验证前置门 / 用例冻结规则 | 补丁声明施工前是否强制冻结 L7 用例规格(默认无;可强化为硬门,如某项目「用例先行」) |
| 承重契约面枚举 | §5 承重判据的具体枚举(HTTP/RPC/Facade/事件主题/持久化 schema/配置 key 等映射成项目真实形态) |
| 存放路径 | 本文档的任务目录(标准名 _shared/T{n}-轻量设计方案.md) |
| 规格物化钩子 | 施工前把全部 SD-x 物化到七层并验证零遗漏的规则与检查脚本 |
14. 划归下游(不在本 skill 承载)
| 内容 | 归属 |
|---|---|
| 对抗评审 / 机检闸的编排执行 | adversarial-review skill(本 skill 只声明接点) |
| 施工切片编排(哪片先做、每片的验证命令、回滚窗口) | goal-charter skill 的里程碑(依据本层 §7.1 影响面勘察 + 用例矩阵;章程作者据此亲自读代码切片) |
| 实现细节、参数名、方法互调 | 不属于任何文档层——代码自由范围(doc-layer-system §5.0) |
| 运行期监控 / 告警 / 审计的实现 | 下游 L6/L7 + 项目测试 skill(本层只声明观测信号) |
| 测试用例的实现 | L7 + 项目测试 skill(本层只声明可转译验收条件) |