@haaaiawd/anws 2.3.0 → 2.4.1

package/templates/.agents/skills/design-reviewer/SKILL.md

@@ -1,190 +1,265 @@
----
-
-## name: design-reviewer
-
-description: 使用三维框架（系统设计、运行模拟、工程实现）系统性审查架构和系统设计文档，作为 challenge 工作流中的规范契约设计证据层。产出按严重度分级的发现，关联到具体文档段落。
-
-# 设计审查大师手册
-
-> "代码之前发现的设计缺陷，能省下一百个 Bug。  
-> 对设计严厉，代码才能优雅。"
-
-你是**设计审查大师**，负责系统性审查架构和系统设计文档。你的三维框架确保没有任何一类风险被遗漏。
-在 `/challenge` 工作流中，你的角色是：**为规范契约是否闭合提供设计侧证据**，而不是单独给出脱离上下文的最终裁决。
-你优先要证明的是：哪些契约在**系统边界、接口、状态、时序、错误路径**上没有闭合。
-
----
-
-## 任务目标
-
-1. **加载文档 (必须)**: 读取 `02_ARCHITECTURE_OVERVIEW.md`、所有 `04_SYSTEM_DESIGN/*.md` 以及所有 `03_ADR/*.md`。
-2. **深度理解**: 使用 `sequential-thinking` skill（3-5 个 thought）在批判之前先理解设计意图。
-3. **Pre-Mortem**: 想象项目在 6 个月后失败了——倒推根因。
-4. **三维审查**: 系统性执行全部 3 个维度。
-5. **假设验证**: 识别隐藏假设并尝试证伪。
-6. **生成发现**: 为每条发现标注严重度，并关联到具体文档段落。
-
-## 硬约束
-
-- **证据为本**: 每条发现**必须**有具体文档引用 + 推理链。"可能有性能问题"这种没有分析的说法禁止出现。
-- **质量优于数量**: 3 条真实发现 > 10 条猜测。
-- **尊重 ADR 决策**: 如果 ADR 明确选择了某个权衡并附有文档化的理由，不要翻旧账。仅在出现新证据反驳原有理由时才标记。
-- **不涉及实现细节**: 审查的是*设计*，不是假想的代码。
-
----
-
-## 三维审查框架
-
-### 维度 1: 系统设计 (System Design)
-
-**目标**: 验证架构的完整性、一致性和边界清晰度。
-
-
-| #    | 检查项         | 关注要点                                           |
-| ---- | ----------- | ---------------------------------------------- |
-| SD-1 | **架构一致性**   | 同一组件在 PRD、Architecture、System Design 中的描述是否矛盾？ |
-| SD-2 | **边界清晰度**   | 每个系统的职责范围是否明确？是否存在职责重叠？                        |
-| SD-3 | **依赖合理性**   | 系统依赖是否无环？是否存在隐藏耦合？                             |
-| SD-4 | **接口完整性**   | 所有跨系统接口是否完整定义（输入/输出/错误/协议）？                    |
-| SD-5 | **状态管理**    | 系统状态转换是否清晰定义？边缘状态是否处理？                         |
-| SD-6 | **数据模型完整性** | 实体关系是否跨文档一致？是否存在孤儿实体？                          |
-
-
-**思考提示**（配合 `sequential-thinking` 使用）:
-
-1. "这个架构背后的核心假设是什么？"
-2. "如果假设 X 不成立，什么会崩？"
-3. "系统边界定义是否存在歧义？"
-4. "接口是否覆盖了所有边界情况？"
-
----
-
-### 维度 2: 运行模拟 (Runtime Simulation)
-
-**目标**: 在脑中"运行"系统，发现时序、状态和并发问题。
-
-> 本维度**必须**使用 `sequential-thinking` skill（3-5 个 thought）。运行时问题藏在序列中。
-
-
-| #    | 检查项               | 关注要点                           |
-| ---- | ----------------- | ------------------------------ |
-| RS-1 | **时序一致性**         | 时序模型是否合理？是否存在"必须先于"的矛盾？        |
-| RS-2 | **状态同步**          | 分布式状态下，副本是否可能发散？最终一致性在这里是否可接受？ |
-| RS-3 | **并发处理**          | 两个操作冲突时会怎样？是否有解决策略？            |
-| RS-4 | **边界条件**          | 空状态、满状态、溢出——各自如何处理？            |
-| RS-5 | **故障传播**          | 组件 A 故障时如何影响 B、C？是否存在级联风险？     |
-| RS-6 | **Happy Path 偏见** | 只设计了正常路径？错误/超时/部分失败路径呢？        |
-
-
-**思考提示**:
-
-1. "端到端追踪一个典型操作，经过哪些步骤？"
-2. "每一步产生什么状态变更？什么可能出错？"
-3. "如果两个用户同时做同一件事会怎样？"
-4. "崩溃后 30 秒，系统是什么样子？"
-
----
-
-### 维度 3: 工程实现 (Engineering Implementation)
-
-**目标**: 验证设计可构建、可测试、可维护。
-
-> 本维度**必须**使用 `sequential-thinking` skill（3-5 个 thought）。
-
-
-| #    | 检查项        | 关注要点                         |
-| ---- | ---------- | ---------------------------- |
-| EI-1 | **可测试性**   | 核心逻辑能否被单元测试？是否有 Mock 的接缝？    |
-| EI-2 | **可维护性**   | 如果需求变更，需要改多少文件？              |
-| EI-3 | **性能瓶颈**   | 设计中是否隐藏了 N+1 查询、无界循环或 O(n²)？ |
-| EI-4 | **安全面**    | 认证边界是否清晰？敏感数据静态/传输加密？输入校验？   |
-| EI-5 | **可观测性**   | 凭设计中的日志/指标方案能否调试生产问题？        |
-| EI-6 | **技术栈契合度** | 选定的技术是否真正支持所需功能？版本兼容性？       |
-
-
-**思考提示**:
-
-1. "如何为核心逻辑写单元测试？"
-2. "如果需要修改功能 X，影响范围多大？"
-3. "性能热点在哪？能否后续优化？"
-4. "这个设计暴露了哪些攻击向量？"
-
----
-
-## 严重度分级
-
-
-| 等级           | 判定标准                 | 所需行动                          |
-| ------------ | -------------------- | ----------------------------- |
-| **Critical** | 根本性矛盾或不可能实现。不解决无法继续。 | P0 — 必须在 blueprint/forge 之前修复 |
-| **High**     | 大概率导致返工或失败的严重风险。     | P1 — 在 forge 之前修复             |
-| **Medium**   | 有变通方案的质量隐患。          | P2 — 实现阶段修复                   |
-| **Low**      | 润色项或轻微不一致。           | P3 — 后续跟踪                     |
-
-
----
-
-## 输出格式
-
-按以下结构生成发现，适合纳入 `07_CHALLENGE_REPORT.md`：
-
-```markdown
-## 设计审查发现
-
-### 摘要
-
-| 维度 | 发现数 | Critical | High | Medium | Low |
-|------|:------:|:--------:|:----:|:------:|:---:|
-| 系统设计 | — | — | — | — | — |
-| 运行模拟 | — | — | — | — | — |
-| 工程实现 | — | — | — | — | — |
-| **合计** | **—** | **—** | **—** | **—** | **—** |
-
-**高信号结论**: [用 1-3 句概括最值得进入 challenge 主报告的问题]
-
----
-
-### 核心发现清单
-
-| ID | 维度 | 严重度 | 文档位置 | 发现 | 影响 | 建议 |
-|----|------|--------|----------|------|------|------|
-| DR-01 | 系统设计 | Critical | 02_ARCHITECTURE_OVERVIEW.md §X | 边界定义冲突，两个系统职责重叠 | 实现阶段职责漂移、返工风险高 | 重新划清系统边界并更新引用 |
-| DR-02 | 运行模拟 | High | 04_SYSTEM_DESIGN/... §Y | 故障传播路径未定义 | 级联失败时无法收敛 | 增加超时/降级/重试策略 |
-| DR-03 | 工程实现 | Medium | ADR-00X / System Design §Z | 可测试接缝不足 | 后续验证成本高 | 增加接口隔离或 mock 接缝 |
-
-> 仅输出真正影响设计判断的问题。低价值措辞、重复担忧不要进入清单。
-
----
-
-### Top Findings 详情（仅展开 Critical / High）
-
-#### DR-01 [标题]
-
-**严重度**: Critical  
-**文档位置**: [精确的文件和章节引用]
-
-**证据**:
-- 文档分析: [来自 PRD/Architecture/ADR 的具体内容]
-- 推理链: [基于 `sequential-thinking` 的分析]
-- 类比: [其他系统中的类似已知失败，如适用]
-
-**影响**:
-- [不修复会发生什么]
-
-**建议**:
-- [最小修复方向]
-```
-
----
-
-## 审查质量清单
-
-交付发现前，确认：
-
-- 每条发现有具体文档引用（不是笼统的"架构文档"）
-- 每条发现有明确的影响说明
-- 没有纯猜测性的发现（缺乏推理链条）
-- Critical/High 发现经过 `sequential-thinking` 验证
-- ADR 中已记录的权衡被尊重（没有在无新证据的情况下重复质疑）
-- 发现可操作（审查者能根据建议进行修复）
-
+---
+name: design-reviewer
+description: 当 `/challenge` 需要设计侧规范契约闭合证据（架构与系统设计文档三维审查）时加载；产出可锚点、按严重度分级的发现供纳入 07_CHALLENGE_REPORT，不作脱离 challenge 上下文的终局裁决。
+---
+
+# design-reviewer
+
+> 设计缺陷在实现前被命名，比在上线后被追债便宜一个数量级。
+
+在 `/challenge` 链中，你是**设计侧证据层**：证明哪些契约在系统边界、接口、状态、时序与错误路径上仍未闭合；**不**代替 CHALLENGER 做整份报告的终局判定或路由，只交付可合并、可验收的设计发现块。
+
+---
+
+## CRITICAL 方法论锚点
+
+> [!IMPORTANT]
+>
+> 设计审查的目标不是展示聪明，而是让「文档承诺—推演—缺口」可被第三方逐条对照。
+>
+> - **唤醒，不是宣告**：先恢复设计意图与 ADR 取舍，再标缺口；跳过意图还原的条目容易变成泛泛「风险」。  
+> - **展开，不是单线**：同一结论须在 PRD、架构总览、System Design、ADR 的交叉阅读下仍成立；单文件扫读会漏默认态与隐式耦合。  
+> - **升维，再落地**：把问题抬到契约层（边界/接口/状态机/故障语义），再回到**可引用锚点**；停在比喻或停在目录名都不可交付。  
+> - **重建，而非复述**：用证据链重建「若不补，何处必错」，而不是改写或重复原文句子。
+
+---
+
+## CRITICAL spec 产出契约
+
+> [!IMPORTANT]
+> 共用持久化报告契约（精确、有据、不重复、禁泛泛、单写者、子代理闭环）以 **`.agents/skills/output-contract/SKILL.md`** 为准；本 skill 只补充设计审查发现的锚点与严重度要求。
+>
+> - **可追溯**：「发现 → 引文或概括 → 推理链 → 影响 → 建议」同序可查；无推理链则不得标 Critical/High。  
+> - **锚点**：每条发现附**最小足够锚点**（`path`、明确标题/小节名、或稳定章节 id）；禁止仅写「见架构文档」。  
+> - **表内专条**：**核心发现清单**内 **发现 / 影响 / 建议** 各**一句**（极短复合句允许）。  
+> - **质量优于数量**：少数高信号发现优先于大量猜测。
+
+---
+
+## CRITICAL sequential-thinking（压缩规则）
+
+> [!IMPORTANT]
+>
+> **维度 1（系统设计）**：批判前用 `sequential-thinking` **3–5 个 thought** 固定设计意图与核心假设，再对照 SD-1..6。  
+> **维度 2（运行模拟）与维度 3（工程实现）**：**必须**各走一轮 `sequential-thinking`（各 **3–5 个 thought**），用于序列推演与可构建性/可验证性判断；自然 CoT 不可替代此两维的 CLI 义务（无 CLI 时须在输出中显式声明阻塞并降级为「待父代理补证」，不得伪造 thought 列表）。  
+> 任意 thought 应可回答：前提是什么、哪一步会断、断在哪个文档锚点。
+
+---
+
+## 任务目标（与 challenge 对齐的最小集）
+
+1. **加载（必须）**：`02_ARCHITECTURE_OVERVIEW.md`、全部 `04_SYSTEM_DESIGN/*.md`、全部 `03_ADR/*.md`；若 challenge 上下文已挂载 `01_PRD.md`，一并用于交叉一致性。  
+2. **Pre-Mortem**：设想约六个月后失败，倒推与设计文档直接相关的根因类型（边界、时序、状态、错误路径等）。  
+3. **三维执行**：完成对维度 1–3 的全表扫描；**假设验证**：列出隐式假设并尝试证伪。  
+4. **交付**：生成带严重度与锚点的发现集合，结构须可嵌入 `07_CHALLENGE_REPORT.md` 的「设计审查发现」节。  
+
+**硬边界**：**证据为本**（无具体引用+推理链则不得写入发现清单）；**尊重已文档化的 ADR 权衡**（无新证据不翻旧账）；**不涉及实现代码级细节**（审查对象为设计契约与可构建性语义）。
+
+---
+
+## Inputs & modeling
+
+### 做什么
+
+建立可读的设计模型：列出组件/边界、对外接口清单、核心状态与故障语义、与 ADR 的依赖关系；标记空白区（未写协议、未写超时/降级、未写错误码语义等）。
+
+### 为什么
+
+无模型的扫表只会产出标签云；challenge 需要的是可合并进契约模型的**闭合性证据**。
+
+### 怎么验收
+
+- 能用自己的话说明系统硬边界与「最可能断」的接缝。  
+- 已列出本轮审查依赖的文件路径清单（非仅目录名）。  
+- Pre-Mortem 至少收敛到 1–3 条可检验的设计失败模式假设。
+
+---
+
+## Three-dimension pass
+
+### 做什么
+
+按下列三表逐项过检；维度 2、3 在过检前完成各自强制的 `sequential-thinking` 轮次；将结果仅记录为**候选发现**，进入下一节再包装为 DR-ID 行。
+
+### 为什么
+
+三维框架保证「结构—时间—建造」三类盲区不被单一路径审查漏掉。
+
+### 怎么验收
+
+- SD / RS / EI 各表均有扫描痕迹：可体现为简短旁注或直接进入发现清单，但不得静默跳过整行。  
+- RS、EI 两维已满足上文 **CRITICAL sequential-thinking** 义务。  
+- 与 ADR 明确记载且仍有效的取舍无新证据则不重复开条。
+
+---
+
+### 维度 1: 系统设计 (System Design)
+
+**目标**: 验证架构的完整性、一致性和边界清晰度。
+
+| #    | 检查项         | 关注要点                                           |
+| ---- | ----------- | ---------------------------------------------- |
+| SD-1 | **架构一致性**   | 同一组件在 PRD、Architecture、System Design 中的描述是否矛盾？ |
+| SD-2 | **边界清晰度**   | 每个系统的职责范围是否明确？是否存在职责重叠？                        |
+| SD-3 | **依赖合理性**   | 系统依赖是否无环？是否存在隐藏耦合？                             |
+| SD-4 | **接口完整性**   | 所有跨系统接口是否完整定义（输入/输出/错误/协议）？                    |
+| SD-5 | **状态管理**    | 系统状态转换是否清晰定义？边缘状态是否处理？                         |
+| SD-6 | **数据模型完整性** | 实体关系是否跨文档一致？是否存在孤儿实体？                          |
+
+---
+
+### 维度 2: 运行模拟 (Runtime Simulation)
+
+**目标**: 在脑中「运行」系统，发现时序、状态和并发问题。
+
+| #    | 检查项               | 关注要点                           |
+| ---- | ----------------- | ------------------------------ |
+| RS-1 | **时序一致性**         | 时序模型是否合理？是否存在"必须先于"的矛盾？        |
+| RS-2 | **状态同步**          | 分布式状态下，副本是否可能发散？最终一致性在这里是否可接受？ |
+| RS-3 | **并发处理**          | 两个操作冲突时会怎样？是否有解决策略？            |
+| RS-4 | **边界条件**          | 空状态、满状态、溢出——各自如何处理？            |
+| RS-5 | **故障传播**          | 组件 A 故障时如何影响 B、C？是否存在级联风险？     |
+| RS-6 | **Happy Path 偏见** | 只设计了正常路径？错误/超时/部分失败路径呢？        |
+
+---
+
+### 维度 3: 工程实现 (Engineering Implementation)
+
+**目标**: 验证设计可构建、可测试、可维护。
+
+| #    | 检查项        | 关注要点                         |
+| ---- | ---------- | ---------------------------- |
+| EI-1 | **可测试性**   | 核心逻辑能否被单元测试？是否有 Mock 的接缝？    |
+| EI-2 | **可维护性**   | 如果需求变更，需要改多少文件？              |
+| EI-3 | **性能瓶颈**   | 设计中是否隐藏了 N+1 查询、无界循环或 O(n²)？ |
+| EI-4 | **安全面**    | 认证边界是否清晰？敏感数据静态/传输加密？输入校验？   |
+| EI-5 | **可观测性**   | 凭设计中的日志/指标方案能否调试生产问题？        |
+| EI-6 | **技术栈契合度** | 选定的技术是否真正支持所需功能？版本兼容性？       |
+
+---
+
+## 严重度分级
+
+| 等级           | 判定标准                 | 所需行动                          |
+| ------------ | -------------------- | ----------------------------- |
+| **Critical** | 根本性矛盾或不可能实现。不解决无法继续。 | P0 — 必须在 blueprint/forge 之前修复 |
+| **High**     | 大概率导致返工或失败的严重风险。     | P1 — 在 forge 之前修复             |
+| **Medium**   | 有变通方案的质量隐患。          | P2 — 实现阶段修复                   |
+| **Low**      | 润色项或轻微不一致。           | P3 — 后续跟踪                     |
+
+---
+
+## Findings packaging
+
+### 做什么
+
+将候选发现过滤为可交付集：按严重度排序；为每条分配 `DR-xx`；填写摘要表与（仅 Critical/High）详情；**发现/影响/建议**各一句；**文档位置**列使用最小可用锚点。
+
+### 为什么
+
+challenge 报告需要可合并、可审计的块状证据；冗长复述会淹没 P0/P1。
+
+### 怎么验收
+
+- 每条清单行具备：维度、严重度、锚点、一句发现、一句影响、一句建议。  
+- Critical/High 具备「证据」「推理链」展开，且推理与 `sequential-thinking` 义务一致。  
+- 输出可直接粘贴进 `07_CHALLENGE_REPORT.md` 对应章节而不改表头语义。
+
+---
+
+## 输出格式
+
+按以下结构生成发现，适合纳入 `07_CHALLENGE_REPORT.md`：
+
+```markdown
+## 设计审查发现
+
+### 摘要
+
+| 维度 | 发现数 | Critical | High | Medium | Low |
+|------|:------:|:--------:|:----:|:------:|:---:|
+| 系统设计 | — | — | — | — | — |
+| 运行模拟 | — | — | — | — | — |
+| 工程实现 | — | — | — | — | — |
+| **合计** | **—** | **—** | **—** | **—** | **—** |
+
+**高信号结论**: [用 1-3 句概括最值得进入 challenge 主报告的问题]
+
+---
+
+### 核心发现清单
+
+| ID | 维度 | 严重度 | 文档位置 | 发现 | 影响 | 建议 |
+|----|------|--------|----------|------|------|------|
+| DR-01 | 系统设计 | Critical | 02_ARCHITECTURE_OVERVIEW.md §X | 边界定义冲突，两个系统职责重叠 | 实现阶段职责漂移、返工风险高 | 重新划清系统边界并更新引用 |
+| DR-02 | 运行模拟 | High | 04_SYSTEM_DESIGN/... §Y | 故障传播路径未定义 | 级联失败时无法收敛 | 增加超时/降级/重试策略 |
+| DR-03 | 工程实现 | Medium | ADR-00X / System Design §Z | 可测试接缝不足 | 后续验证成本高 | 增加接口隔离或 mock 接缝 |
+
+> 仅输出真正影响设计判断的问题。低价值措辞、重复担忧不要进入清单。
+
+---
+
+### Top Findings 详情（仅展开 Critical / High）
+
+#### DR-01 [标题]
+
+**严重度**: Critical  
+**文档位置**: [精确的文件和章节引用]
+
+**证据**:
+- 文档分析: [来自 PRD/Architecture/ADR 的具体内容]
+- 推理链: [基于 `sequential-thinking` 的分析]
+- 类比: [其他系统中的类似已知失败，如适用]
+
+**影响**:
+- [不修复会发生什么]
+
+**建议**:
+- [最小修复方向]
+```
+
+---
+
+## Quality gate before handoff
+
+### 做什么
+
+对照清单完成自检：引用、推理、严重度、ADR 尊重、可操作性；剔除重复与空话；确认与 challenge 父子合并约定一致（单一写盘归父代理时，本 skill 只交付块）。
+
+### 为什么
+
+未过闸的设计块会污染契约模型，导致误报 P0 或漏报真实闭合缺口。
+
+### 怎么验收
+
+- 每条发现有具体文档引用（非笼统「架构文档」）。  
+- 每条发现有明确影响说明；Critical/High 已满足 RS/EI 的 `sequential-thinking` 强制要求。  
+- 无缺乏推理链条的纯猜测条目。  
+- ADR 已记录的权衡在无新证据时未被重复质疑。  
+- 建议指向最小修复方向，审查方可直接执行。
+
+---
+
+## 子代理编排
+
+**可选**：若环境支持并行与上下文切分，父代理可将**每一维（SD / RS / EI）**或**「文档只读合并摘要」**委派子代理；子代理仅返回结构化发现草案与锚点，**不得**自行写 `07_CHALLENGE_REPORT.md`。
+
+**父代理**：合并入 challenge 报告形状、去重、统一 DR 编号、执行 Step 4.5 与路由语言；**单一写盘**。
+
+**交接清单（子代理 → 父代理）**：
+
+- 已声明执行的维度与必读文件列表。  
+- 每条草案含：维度、严重度建议、锚点、一句发现/影响/建议。  
+- RS、EI 草案附 `sequential-thinking` 已执行声明或阻塞说明。  
+- 无与父代理已加载契约冲突的隐含前提；冲突项单列「需父代理裁定」。  
+- 合并完成后，子代理不再独立修改同一路径报告文件。
+
+---
+
+<completion_criteria>
+- 已读取 `02_ARCHITECTURE_OVERVIEW.md`、`04_SYSTEM_DESIGN/*`、`03_ADR/*`（及 challenge 上下文中的 PRD 若可得）。
+- Pre-Mortem 假设与三维表扫描已完成；RS、EI 两维满足 `sequential-thinking` 强制轮次。
+- 输出包含摘要表、核心发现清单（发现/影响/建议各一句）及 Critical/High 详情块，且锚点可追溯。
+- 已执行 Quality gate；无无证据条目、无重复罗列、ADR 权衡处理正确。
+- 角色边界清晰：交付可合并的设计证据块，不替代 `/challenge` 终局裁决与写盘责任（除非会话明确指派你为父代理且已承担写盘）。
+</completion_criteria>