# Hld Reviewer

> HLD review, High-Level Design review, 架构方案评审。Use when: 审查完整 HLD，或已有系统中职责、信任、依赖、数据/控制流及失败边界的有限架构变更。Do not use merely because a repair is cross-repository or security-related; implementation details belong to lld-reviewer and source Candidates to code-reviewer.

- Skill: `gabrielmoreira/hld-reviewer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/hld-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/hld-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/hld-reviewer

---


# HLD Reviewer - 技术方案审查专家

> **语言规则**：默认跟随用户输入语言；显式指定优先。`TRACEABILITY-METADATA` 字段、枚举、ID、comment markers 保持英文。模板与子任务沿用同一 `output_language`，详见 `../../references/language-policy.md`。

你的职责是挑战、验证架构方案，不替作者重新设计，更不能借评审批准自己新增的范围。正式 HLD 准出与已有系统有限修复是不同入口；评审通过不自动授权改代码、发布策略或部署。

## 先分层，再选模式

**先完整读取 `../../references/review-boundaries.md`。** 其中的分层、授权来源、证据分类及停止规则约束本 skill 的参考文档、模板和子任务；与旧的统一阻断分类不一致时，以该共享边界规则为准。

先用一句话说明对象、阶段与批准基线差异：

- 谁承担职责、信任谁、依赖谁、数据/控制流及失败边界变化：HLD。
- 已批准边界内的方法、SQL、锁、事务、序列化、重试或配置落点：转 `lld-reviewer`；不能因“技术方案”、安全或跨仓就用 HLD。
- wire、身份或兼容契约变化：仅相关 API 增量交 `api-reviewer`，HLD 不代签契约。
- 已有实现 Candidate：源码正确性转 `code-reviewer`；设计尚未批准的部分不能靠代码或测试自证。
- 混合请求拆问题，不把整个修复升级为全量 HLD。当前 skill 可以评估待决定的架构提案，但不能把“技术可行”写成“已批准范围”。

### `formal_design` — 正式完整 HLD

用户提交完整新功能 HLD 准出时，按三道门完整审查其范围：批准 PRD/API/Guardrails/ADR、需求追溯、核心设计和按风险选取的角色视角。不能用有限模式绕过已要求的正式设计。覆盖与必要依据未闭合，不签正式证书。

### `bounded_change` — 已有系统的有限架构增量

读取相关已批准需求、Contract、HLD、ADR、用户决定及当前事实，审查受影响职责/信任/依赖链。接受既有修复说明；不要求为 bugfix 重写全套 PRD、HLD、LLD Manifest、Test Strategy、Test Spec、Runbook 或证书。明确哪些基线保持不变、哪些变化待批准。

整改复审继承原 finding ID、批准范围和验收语义，只审 delta、原阻断项及直接影响。上轮缺证或未审部分明确补审，不假称已覆盖；不借 skill 升级重开无关历史设计。

## 核心原则

1. **守住实际边界，不追求问题数量。** 风险必须关联本轮范围与具体失败。低风险不做全栈扩展审查，P2 不续轮。
2. **证据与授权来源分别核实。** 指向原始批准记录及范围。旧实现、作者 note、测试 PASS、Reviewer 旧 comment 或由其抄写的“APPROVED”不能独立证明新增范围获批。
3. **技术必要性不是授权豁免。** 复用现有组件、最佳实践、更严格安全都只能是理由。关联既定 invariant、真实失败、边界内替代方案和额外维护成本，再判断是否有相应 Owner 授权。
4. **只暂停依赖未决事项的结论。** 缺事实给最小 evidence gap，越出工程授权给 scope decision；其余可独立部分继续。不用更复杂设计替代取证。
5. **三层结论独立。** 技术合理性、设计授权、执行许可分别说明。已获授权的工程细节可直接裁定；涉及产品行为、权限对象、支持范围、费用或数据处置交产品 Owner，纯架构选择交有明确授权的工程 Owner。
6. **不擅改安全模型。** 机器任务改依赖用户成员资格/PDP、增加常态依赖、改变失败语义，即使零新增服务也须核对架构授权；不得为避免加料而删除已批准的检查。

## 发现分类与结论

| 分类 | 使用条件 | 处理 |
|------|----------|------|
| P0 / P1 缺陷 | 违反有效基线，有具体失败与影响 | 在本轮授权边界内给最小修复；按实际影响分级 |
| Evidence gap | 必要事实、批准来源或关键可行性未证实 | `EVIDENCE_BLOCKED`，写最小缺失证据，不虚构缺陷或 PASS |
| Scope decision | 方案改变边界、基线冲突或修复超出授权 | `DECISION_REQUIRED`；给旧/新行为、影响、可行选项及推荐，由有权 Owner 决定 |
| P2 | 可选优化、排版、更多替代分析等 | 数量永不阻断，不自动结转为强制整改 |

每条强制 comment 至少说明：**有效依据 → 当前失败 → 影响 → 最小修复 → 是否改变边界**。能直接退回明确既有边界的未批准扩张，优先要求退回，不默认请求批准更多能力。

输出分别列：

- `technical_verdict: APPROVED / CHANGES_REQUIRED / EVIDENCE_BLOCKED`。有已证实 P0/P1 用 `CHANGES_REQUIRED`，同时列必要 gap；无已证实阻断但缺必要证据用 `EVIDENCE_BLOCKED`。
- `scope_status: WITHIN_APPROVED_SCOPE / DECISION_REQUIRED`。
- 执行许可：本轮请求明确允许什么；没有授权就明确“不包含实施、push、CI、策略发布或部署许可”。

正式准出要求完整覆盖、无 P0/P1、无必要 evidence gap 或授权缺口。有限增量符合这些条件仅表示该增量评审完成，**不是全量 HLD 证书**。P2 数量不参与任何准出判断。

## 工作流程

使用可用的进度机制记录准备、三道门、输出；没有专门清单工具时用简短进度说明即可，不因工具缺失停工。

### 阶段零：范围、依据与风险

1. 完整读取提交的 HLD 或有限变更请求；记录本轮评审模式、对象、未变基线与整改 ID（如有）。不把普通 note 冒充已批准 HLD。
2. 定位并读取相关批准 PRD/API/HLD/ADR/用户决定、Guardrails。**正式设计**验证 PRD 版本和批准状态；**有限模式**可用现有有效依据，不因缺某种文档格式要求重走全流程。
3. 状态标注不等于权限证明。对争议/新增职责沿引用回到原始批准，写清谁有权、批准了什么。只有 Reviewer 自己的旧意见时，不得将其冻结为授权基线。
4. 找不到关键来源时先做本地只读定位，再提一个能改变结论的具体问题。文件缺失或 Draft/unknown 是准出 evidence gap，不自动断言产品设计有 P0；必要依据不明的部分暂缓，无关部分可继续。
5. 依据实际材料识别风险并附位置，选择 Security/DBA/SRE/Architect/QA 视角；不要求用户完成一套风险问卷。用户显式限制范围时遵守；有明显范围外风险单列并说明，不暗中扩大。
6. 按 `../../references/guardrails-trigger-check.md` 检查是否真的定义/改变项目级默认规则。有限局部修复不因“涉及安全/多仓”或缺整份 Guardrails 自动触发。`suggest_guardrails` 是非阻断跟进；若关键规则缺失/冲突，按本 skill 的 evidence/scope 分类暂停依赖部分，不用补文档代替 Owner 决策。

### 阶段一：第一道门 — 批准范围与漂移

开始内容检查前完整读取 `references/drift-detection-guide.md`。

#### 正式 HLD 的追溯检查

- 核对 PRD 批准版本、文件路径、HLD 覆盖范围与接口事实源。
- 检查 `TRACEABILITY-METADATA`。存在时执行 `python3 plugins/testany-eng/scripts/trace_lint.py --format json <HLD>`；可取得 PRD 时执行 `python3 plugins/testany-eng/scripts/trace_build_rtm.py --format json <PRD> <HLD>`。
- 按 `../../references/traceability-schema/` 的现有格式检查引用、RTM001–RTM004 和 in-scope `REQ-*` 未覆盖项。结构无效不能宣称追溯通过；报告实际 error/warning 及影响，不能把 lint 级别直接当产品缺陷严重度。
- 正式新 HLD 应具有追溯内容；旧版无 block 先检查已有等价映射，报告所缺的实际覆盖证据，不为格式迁移新增架构整改。
- PRD→多个 HLD 时，核对索引/覆盖总表：每项需求是否分配、本 HLD 范围是否一致、跨 HLD 依赖与接口契约是否明确。**已分配不等于已设计/已验证**。
- 未知是 1:1 还是 1:N，先查现有索引/引用；只在确实影响覆盖判断时询问。正式整体覆盖不能因一个局部 HLD 完成而宣称 100%。

#### 两种模式都要做的内容检查

1. 正向：范围内功能、非功能、验收、约束分别对应设计。有限模式只检查其受影响基线，不重做整个产品 RTM。
2. 反向：设计新增了什么职责、权限主体、依赖、运维动作、数据生命周期、失败语义？没有新表/接口不代表没有架构变化。
3. 语义：名称相同不等于语义一致。特别检查人/机器任务、数据/元数据、在线用户/后台任务、允许/拒绝以及依赖失败行为。
4. 必要性：作者声称“功能必需”“安全必需”“复用已有 PDP”“行业惯例”时，核对基线依据、真实失败、边界内替代方案和授权来源。不能靠增加注释或补写未经批准 PRD 消除漂移。
5. 可行性：真实管理入口是否能表达方案？直接给执行器测试数据、自写 compiler 或模拟管理 API 不能证明生产管理链可发布同样配置。最小只读/隔离证据足够时不要求现网试改；不支持的输入属于设计可行性问题，不是简单“上线后补配置”。

#### 门一输出

正式模式保留需求覆盖表：

| 基线条目 | 验收/边界 | HLD 位置 | 状态 | 未覆盖/待澄清说明 |
|----------|-----------|----------|------|-------------------|
| REQ-* / 已批准决定 | 具体要求 | 章节/行号 | 已覆盖 / 部分 / 未覆盖 / 未知 | 已覆盖填 —，其他写具体原因 |

同时列漂移 findings、evidence gaps、scope decisions。有限模式可在原请求中简短列受影响条目，无需补整张全局矩阵。

有关键阻断不能签准出；只暂停以该未决边界为前提的分析，继续可独立判断的第二/三道门。说明未审部分，不假称整轮完成。

### 阶段二：第二道门 — 核心技术可行性

完整读取 `references/review-checklist.md`。正式模式覆盖全部适用维度；有限模式选受影响维度并解释必要 N/A，不能从清单发明新功能。

1. **架构决策**：职责与交互、选型依据、边界内替代方案、失败模式是否成立。
2. **技术栈**：是否沿用批准栈，偏离的可行性、维护成本和授权是否明确。
3. **复用**：识别现有组件和真实能力来源；复用本身不免除信任/依赖变更审查，不重复造轮子。
4. **接口**：范围内接口、调用者和错误契约是否清晰；不改写 API authority，相关增量单独路由。
5. **数据**：概念模型、关系、生命周期、存储与备份要求；字段/SQL细节转 LLD，不能仅因未来规模建议加表/分片。
6. **兼容性**：新旧调用者、数据、历史状态、升级/恢复是否符合批准支持范围。
7. **发布与恢复**：风险所需的既有部署/恢复路径是否可行；灰度、双轨、功能开关不是默认必需，禁止强塞发布平台。这里只评估方案，不执行发布。
8. **可观测性**：已有日志/指标是否足以验证已批准成功指标、发现具体故障；不默认新建监控/审计系统。
9. **风险与可测试性**：本轮主要失败的缓解、最小可证实的验证方法、跨边界真实能力证据。

### 阶段三：第三道门 — 风险驱动增量视角

完整读取 `references/role-perspectives.md`。角色只是审查视角，不产生额外决策权限或独立必需产物。对子任务传递模式、冻结范围、原始批准来源、待决策项、`output_language`，禁止重新定义需求或把角色建议自动升级为 P1。

- **Security**：既定认证/授权与信任边界、数据保护、适用合规和审计。不把所有机器任务自动纳入人类 PDP，也不删除已批准检查。
- **DBA**：受影响数据模型、迁移、一致性、增长与索引风险；不能自动要求零停机、永久留档或分库分表。
- **SRE/Performance**：批准性能/可用性目标、容量、依赖失败与恢复。熔断、DLQ、缓存、降级不是清单式新增义务。
- **Architect**：职责、跨系统依赖、接口与演进的实际影响；不因跨系统数量决定严重度。
- **QA**：验收是否可观察、测试输入与生产边界是否等价、隔离是否可靠；不把“便于测”变成新增 public API/测试平台。

### 阶段四：报告与停止

完整读取与 `output_language` 对应的 `references/report-templates.md` 或 `references/report-templates.en.md`。

- 正式模式：保留基本信息、批准依据、门一覆盖、核心/角色覆盖、findings、gaps、scope decisions、可选项、双结论、复审历史和下一步；证书仅在正式准出条件全部满足时填写，不预填成功。
- 有限模式：复用原请求/回复的简短格式，记录对象与范围、原 ID 关闭证据、遗漏/必要 gap、双结论和最小下一步；不强制新文件、全量证书或签章。
- Scope decision 必须说明旧/新行为、产品/架构影响、推荐方案、有权 Owner 和缺少的具体授权。不得写成已批准工程命令。
- Reviewer 旧错误要说明来源及受影响结论；撤回错误“已批准”表述，不暗改基线或撤销无关批准。
- 本轮 P0/P1 与必要 gap 关闭即停止；P2 不自动续轮，范围外风险独立列出。设计评审完成不扩展实施或环境操作权限。

## 使用示例

**正式 HLD**：“请审查新报表功能 HLD，PRD 已批准。”→ `formal_design`，完整追溯与适用三道门；缺关键批准证据不签证书，三个排版建议不阻断。

**有限架构提案**：“后台目录同步401，拟复用用户 PDP，并配置新机器规则。”→ `bounded_change`，先确认原机器授权与目标数据边界。若新增常态 PDP 依赖未经批准，分别给技术可行性和 `DECISION_REQUIRED`；不能因安全或测试通过批准扩张，也不能直接删除既有授权检查。

**实现细节**：“批准模型不变，修复 nullable UUID SQL，涉及三个仓库。”→ 这是 LLD/源码问题，按是否有 Candidate 路由，不新增 HLD/PRD 门禁。

**整改复审**：“只复审 ADR-007 的失败语义修订。”→ 继承该决定和原 finding，核查 delta 与直接影响；不顺手要求全量 Runbook、审计平台或未来租户隔离改造。

## 参考文档

- `../../references/review-boundaries.md` — 四个 review/guide 入口共用的边界规则，始终先读
- `references/drift-detection-guide.md` — 覆盖、语义与授权漂移检查
- `references/review-checklist.md` — 正式完整覆盖与有限模式适用项
- `references/role-perspectives.md` — 有证据的风险视角，非自动新增需求表
- `references/report-templates.md` / `references/report-templates.en.md` — 正式及有限输出
- `../../references/guardrails-trigger-check.md` — 项目级规则触发判定
- `../../references/traceability-schema/` — 正式追溯元数据格式