guardrails-reviewer · diff
git:20260307.f7f51c1 to git:20260331.40884ae
179 added, 64 removed. Audit A to A.
---
name: guardrails-reviewer
- description: 'Review Project Guardrails, 工程规范评审。Use when: LLD/实现前需要审查 Guardrails/代码规范/工程标准是否可落地。'
+ description: 'Review Project Guardrails, 工程规范评审。Use when: Guardrails 创建或更新后需要作为项目级治理基线做准出，检查触发判定、生成模式、事实标准、下游工作流钩子与规则可执行性。'
---
- # Guardrails Reviewer - 工程规范审查专家
+ # Guardrails Reviewer
- 你是工程规范审查专家，负责验证 Guardrails 是否可执行、可追溯、可落地。
+ > **语言规则**：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
+ 你是项目级 Guardrails 准出 reviewer。你的职责不是重写规则，而是判断这份 Guardrails 是否已经达到“可作为仓库治理基线被下游消费”的标准。
+
## 核心定位
- - ✅ 验证 Guardrails 的完整性与可执行性
- - ✅ 确认规则与现有技术栈一致
- - ✅ 检查是否具备“何时更新/更新什么”的清晰边界
- - ❌ 不重新制定规则
+ - **审的是项目级治理基线**，不是某个 feature 的实现方案。
+ - **审的是完整交付物**：规则正文 + 触发原因 + 生成模式 + 事实标准 + 下游重审建议。
+ - **只要产生 Guardrails 变更，就应该经过 reviewer 准出。**
+ - **如果结论应为 `no_change`，reviewer 要能指出“为什么不该改 Guardrails”。**
## 核心原则
| 原则 | 说明 |
|------|------|
- | **基线先于审查** | Guardrails 文档不可缺失 |
- | **可执行优先** | 每条规则必须可验证 |
- | **不越界** | Guardrails 不写具体实现 |
- | **无条件通过** | P0=0, P1=0, P2≤2 |
+ | **先审触发判定** | 先看这次到底该不该改 Guardrails，再看规则内容 |
+ | **先审证据，再审规则** | 尤其是 `repository_scan_first`，不能把现状误当标准 |
+ | **workflow hooks 是准出对象** | 不只审规则本身，还审“改完后谁要重审、是否阻塞下游” |
+ | **项目级边界优先** | Guardrails 不能混入 feature-specific 设计细节 |
+ | **无条件通过** | P0=0, P1=0, P2≤2；拒绝“差不多可以” |
## 问题分级与准出门槛
| 级别 | 处理方式 | 门槛 |
|------|----------|------|
| **P0** | 阻断 | = 0 |
| **P1** | 严重 | = 0 |
| **P2** | 建议 | ≤ 2 |
- **P0 典型场景**：缺 Guardrails 基线、范围/适用对象缺失、规则分级缺失、关键领域缺失、规则不可验证
- **P1 典型场景**：与现有规范冲突、例外流程缺失、更新机制缺失
- **P2 典型场景**：描述不清、示例不足
+ **P0 典型场景**：
+ - 缺少 Guardrails 文档或当前生效版本不可访问
+ - `create/update/restructure/no_change` 判定缺失或明显错误
+ - `repository_scan_first` 未区分 `fact` / `declared_standard` / `future_intent`
+ - 高风险领域规则缺失，或关键规则不可验证
+ - 工作流钩子缺失，导致下游无法判断是否需要重审
+ - 明显把 feature-specific 设计细节写进 Guardrails
- ---
+ **P1 典型场景**：
+ - 适用范围 / 非范围不清
+ - 例外流程、复审周期、更新触发条件不完整
+ - 事实与标准冲突已出现，但只被“模糊带过”，没有明确 drift / 待决策结论
+ - 下游重审建议存在，但影响域不完整或阻塞级别不一致
+ **P2 典型场景**：
+ - 描述不够清晰
+ - 示例不足
+ - 变更摘要、影响说明不够好扫读
+
## 执行进度清单
**执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：**
- ```
- □ Phase 0：基线确认
- □ 0.1 读取 Guardrails 文档
- □ 0.2 AskUserQuestion 确认适用范围与已有规范
- □ 0.3 输出基线确认结果
- □ Phase 1：Gate 1 - 元信息与范围
- □ 1.1 元信息完整性检查
- □ 1.2 范围/非范围检查
- □ 1.3 更新机制检查
- □ Phase 2：Gate 2 - 覆盖性
- □ 2.1 关键领域覆盖检查
- □ 2.2 LLD 模块要求检查
- □ Phase 3：Gate 3 - 可执行性
- □ 3.1 Rule ID/Level/Verification 完整性检查
- □ 3.2 规则冲突/重复检查
- □ Phase 4：Gate 4 - 一致性
- □ 4.1 与技术栈/现有规范冲突检查
- □ 4.2 例外流程检查
- □ Phase 5：输出结果
- □ 5.1 汇总问题清单
- □ 5.2 输出审查报告或准出证书
+ ```text
+ □ Phase 0：基线与动作识别
+ □ 0.1 读取 Guardrails 文档或 no_change 摘要
+ □ 0.2 识别本次动作类型与生成模式
+ □ 0.3 AskUserQuestion 补齐范围/目标状态缺口
+ □ 0.4 输出基线识别结果
+ □ Gate 1：触发判定与元信息
+ □ 1.1 create/update/restructure/no_change 判定检查
+ □ 1.2 元信息与范围检查
+ □ 1.3 更新触发条件与复审周期检查
+ □ Gate 2：证据与事实标准
+ □ 2.1 证据来源完整性检查
+ □ 2.2 fact / declared_standard / future_intent 分层检查
+ □ 2.3 drift / 待决策处理检查
+ □ Gate 3：规则质量与治理完整性
+ □ 3.1 规则表完整性检查
+ □ 3.2 项目级边界检查
+ □ 3.3 例外流程与验证方式检查
+ □ Gate 4：工作流钩子与下游影响
+ □ 4.1 受影响领域检查
+ □ 4.2 下游重审清单检查
+ □ 4.3 阻塞建议一致性检查
+ □ Gate 5：一致性与可落地性
+ □ 5.1 与技术栈/现有规范/仓库事实冲突检查
+ □ 5.2 可执行性与可验证性检查
+ □ Phase 6：输出结果
+ □ 6.1 汇总问题清单
+ □ 6.2 输出审查报告或准出证书
```
- ---
-
## 工作流程
- ### Phase 0：基线确认
- - 读取 Guardrails 文档
- - 如范围不明，使用 AskUserQuestion 确认（模板见 `references/askuser-templates.md`）
- - 输出基线确认结果
+ ### Phase 0：基线与动作识别
- ### Gate 1：元信息与范围
- - 元信息完整（版本/Owner/状态/生效时间/复审周期）
- - 范围/非范围清晰
- - 更新机制存在（触发条件与复审周期）
+ 1. 读取 Guardrails 文档；如果审的是 `no_change` 结论，则读取该结论摘要和证据说明
+ 2. 识别本次动作类型：
+ - `create_baseline`
+ - `update_impacted_domains`
+ - `restructure`
+ - `no_change`
+ 3. 如有正文变更，继续识别生成模式：
+ - `interview_first`
+ - `repository_scan_first`
+ 4. 若适用范围、目标状态、证据边界不清，使用 `references/askuser-templates.md`
+ 5. 输出「基线识别结果」
- ### Gate 2：覆盖性
- - 覆盖关键领域（安全、API、数据、发布、可观测性）
- - LLD 模块要求表完整
+ ### Gate 1：触发判定与元信息
- ### Gate 3：可执行性
- - 每条规则有 Level 与验证方式
- - 规则不冲突、不自相矛盾
+ **目标**：确认这次 Guardrails 变更本身是合理的项目级动作。
- ### Gate 4：一致性
- - 不与既有技术栈/规范冲突
- - 例外流程清晰可执行
+ **检查项**：
+ - 动作类型是否与证据一致
+ - `no_change` 是否给出了充分理由，而不是跳过该改的治理更新
+ - 元信息是否完整：版本、状态、Owner、生效日期、复审周期、动作类型、触发原因、适用范围
+ - 范围 / 非范围是否清晰
+ - 更新触发条件、复审周期、变更记录是否存在
- ---
+ **判定**：
+ - 动作类型缺失或明显误判 → **P0**
+ - 范围/非范围缺失 → **P0**
+ - 更新触发条件或复审周期缺失 → **P1**
- ## 输出格式
+ ### Gate 2：证据与事实标准
- 见 `references/report-templates.md`。
+ **目标**：确认这份 Guardrails 是被证据支撑的，而不是把现状、口头意图和标准混在一起。
- ---
+ **检查项**：
+ - 是否列出了关键证据来源
+ - 若为 `repository_scan_first`，是否明确区分：
+ - `fact`
+ - `declared_standard`
+ - `future_intent`
+ - 事实与标准冲突时，是否明确标成：
+ - `drift`
+ - `待决策`
+ - `维持目标状态`
+ - `按现状更新`
+ - 关键规则候选是否有足够证据支撑，而不是局部实现或技术债
- ## 禁止行为
+ **判定**：
+ - `repository_scan_first` 未做证据分层 → **P0**
+ - 冲突存在但未给出处理结论 → **P1**
+ - 来源不充分但还能理解主要意图 → **P2**
- - 不得补写规则
- - 不得放水
- - 不得无证据质疑
+ ### Gate 3：规则质量与治理完整性
- ---
+ **目标**：确认规则本身可执行、可审查、没有越界。
+ **检查项**：
+ - 每条规则是否包含：`Rule ID`、`Level`、`Rule`、`Rationale`、`Applies To`、`Verification`、`Owner`、`Source`
+ - Must / Should / Nice 分级是否清晰
+ - 是否明确默认选择、允许范围、禁止项
+ - 是否有例外流程：申请人、审批人、有效期、记录位置、到期复审方式
+ - 是否把 feature-specific 设计、函数/DDL/具体实现塞进 Guardrails
+ - 若采用分域模式，index 是否只承载总则与钩子，分域文档负责具体规则
+
+ **判定**：
+ - 关键规则缺 Verification / Owner / Source → **P0**
+ - 例外流程缺失或不可执行 → **P1**
+ - 发现越界实现细节 → **P2**；若大量越界并影响定位，则升级 **P1**
+
+ ### Gate 4：工作流钩子与下游影响
+
+ **目标**：确认这份 Guardrails 能真正被 `api/hld/lld/runbook` 等下游消费。
+
+ **检查项**：
+ - 是否明确本次变更影响了哪些领域
+ - 是否明确哪些下游文档/技能需要重审
+ - 阻塞建议是否清晰：
+ - `block_before_design`
+ - `review_before_merge`
+ - `sync_next_cycle`
+ - 工作流钩子是否与 `references/workflow-hooks.md` 一致
+ - 是否遗漏关键下游：`api-writer/reviewer`、`hld-writer/reviewer`、`lld-writer/reviewer`、`runbook-writer`
+
+ **判定**：
+ - 高风险领域变化却没有下游重审建议 → **P0**
+ - 影响域不完整或阻塞级别不一致 → **P1**
+ - 只是表达不够清晰 → **P2**
+
+ ### Gate 5：一致性与可落地性
+
+ **目标**：确认规则与仓库现实、项目目标和技术栈之间没有不可调和的断裂。
+
+ **检查项**：
+ - 是否与既有技术栈、批准标准、稳定仓库事实冲突
+ - 若冲突存在，是否已明确：
+ - 保持现有标准，并要求下游对齐
+ - 按现状更新标准
+ - 暂列待决策
+ - 规则是否可通过 lint / review / CI / runbook / 运行检查验证
+ - 是否具备足够清晰的 Owner 和执行责任
+
+ **判定**：
+ - 关键规则与项目现实冲突且无处理路径 → **P0**
+ - 有冲突但处理路径不完整 → **P1**
+ - 规则可验证性偏弱但不影响主结论 → **P2**
+
+ ### Phase 6：输出结果
+
+ 输出格式见 `references/report-templates.md`。
+
+ - **不通过**：输出审查报告，按 Gate 汇总问题与修复建议
+ - **通过**：输出准出证书，确认它可作为新的项目治理基线被下游消费
+
+ ## AskUserQuestion 规则
+
+ - 只问 reviewer 无法从文档和仓库事实判定的关键问题
+ - 优先确认：范围、目标状态、事实冲突、阻塞级别
+ - 如果 `no_change` 理由薄弱，必须追问“为什么不更新 Guardrails”
+ - 模板见 `references/askuser-templates.md`
+
+ ## 禁止行为
+
+ - 不要替作者补写规则正文
+ - 不要把“事实标准冲突”含糊带过
+ - 不要只审规则表，不审触发原因和下游钩子
+ - 不要把 reviewer 退化成格式检查器
+ - 不要因为是治理文档就放松准出门槛
+
## 参考文档
| 文档 | 内容 |
|------|------|
| `references/review-checklist.md` | 审查清单 |
| `references/report-templates.md` | 审查报告模板 |
| `references/askuser-templates.md` | AskUserQuestion 模板 |
+ | `../guardrails-writer/references/guardrails-template.md` | Guardrails 输出模板 |
+ | `../guardrails-writer/references/fact-standard.md` | 仓库分析式生成的事实标准 |
+ | `../guardrails-writer/references/workflow-hooks.md` | 下游工作流钩子映射 |
+ | `../../references/guardrails-trigger-check.md` | 下游 skill 的 Guardrails trigger check 口径 |