get-shit-done 的 /gsd:eval-review：AI 阶段评估覆盖度的事后审计与 EVAL-REVIEW 修复计划

get-shit-done 的 /gsd:eval-review：AI 阶段评估覆盖度的事后审计与 EVAL-REVIEW 修复计划

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

导读

/gsd:eval-review是 get-shit-done（GSD）为 Claude Code 提供的 AI 阶段评估审计命令：在/gsd:execute-phase完成某个 AI 阶段的实现之后，它会对该阶段的**评估覆盖度（evaluation coverage）**进行回溯式审计，核对AI-SPEC.md中规划的评估策略是否真正落地，并产出一份带评分、判定结论、差距清单与修复计划的EVAL-REVIEW.md。读完本文，你将掌握该命令的输入状态判定逻辑、审计 Agent 的评分模型（维度覆盖 × 基础设施加权公式）、四档判定标准，以及如何基于审计结果驱动下一阶段的迭代。

一、命令概览：它解决什么问题

/gsd:eval-review的定位在 commands/gsd/eval-review.md 中定义得很明确：对已执行的 AI 阶段（completed AI phase）进行回溯式评估覆盖度审计，检查AI-SPEC.md中的评估策略是否真的被实现了，最终产出EVAL-REVIEW.md修复计划。它由命令入口的allowed-tools约束为 Read、Write、Bash、Glob、Grep、Agent 与 AskUserQuestion，且声明requires: [phase]，即只能在阶段执行之后使用，接受可选参数[phase number]，缺省时作用于最近一个已完成阶段。

该命令与/gsd:ui-review、/gsd:validate-phase遵循同一模式（workflow 的 purpose 部分明确说明 "Mirrors the pattern of /gsd:ui-review and /gsd:validate-phase"），是 GSD 阶段门禁体系的一部分：实现 → 审计 → 修复 → 再验证。核心工作流文件为 get-shit-done/workflows/eval-review.md，评分框架依赖 get-shit-done/references/ai-evals.md，实际执行审计的则是子 Agentgsd-eval-auditor（agents/gsd-eval-auditor.md）。

二、执行上下文与前置产物

命令 frontmatter 通过execution_context声明其依赖：

• 工作流 get-shit-done/workflows/eval-review.md —— 编排整个审计流程；
• 参考文档 get-shit-done/references/ai-evals.md —— 提供评分框架（评估维度、测量方式、护栏与飞轮决策等）。

这套审计体系与上游的/gsd:ai-integration-phase（commands/gsd/ai-integration-phase.md）形成闭环：该命令编排gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner的流水线，其中gsd-eval-planner（agents/gsd-eval-planner.md）负责把评估策略写入AI-SPEC.md的 Section 5（Evaluation Strategy）、Section 6（Guardrails）、Section 7（Production Monitoring）。eval-review审计的正是这些规划是否被后续的 execute 阶段真正实现。

三、工作流逐步拆解

3.1 Step 0：初始化与 Banner

流程首先通过 GSD SDK 查询阶段信息：

INIT=$(gsd-sdk query init.phase-op "${PHASE_ARG}") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

解析出phase_dir、phase_number、phase_name、phase_slug、padded_phase、commit_docs等字段，再解析审计模型：

AUDITOR_MODEL=$(gsd-sdk query resolve-model gsd-eval-auditor 2>/dev/null | jq -r '.model' 2>/dev/null || true)

随后显示审计横幅，标识当前阶段号与名称。

3.2 Step 1：输入状态检测（三种状态）

工作流根据阶段目录中的文件判断审计起点：

SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null) AI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-AI-SPEC.md 2>/dev/null | head -1) EVAL_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-EVAL-REVIEW.md 2>/dev/null | head -1)

• State A—— 同时存在AI-SPEC.md与SUMMARY.md：执行对照规格的全量审计（audit against spec）；
• State B—— 只有SUMMARY.md、没有AI-SPEC.md：退化为对照通用 AI 评估最佳实践的审计，并给出非阻塞性警告，提示下次实现前应先运行/gsd:ai-integration-phase；
• State C—— 没有SUMMARY.md：直接退出，提示"Phase {N} not executed. Run /gsd:execute-phase {N} first."。

此外，若EVAL-REVIEW.md已存在，会通过 AskUserQuestion 询问用户是"Re-audit（重新审计）"还是"View（展示现有报告并退出）"。

3.3 Step 2：收集审计上下文

构建交给 auditor 的文件清单：

• AI-SPEC.md（若存在，即规划中的评估策略）；
• 阶段目录下全部SUMMARY.md；
• 阶段目录下全部PLAN.md。

3.4 Step 3：孵化 gsd-eval-auditor

流程以 Task 方式孵化 auditor，携带的 prompt 包含 objective（State A 则"Audit against AI-SPEC.md evaluation plan"，State B 则"Audit against general AI eval best practices"）、files_to_read清单，以及结构化 input：ai_spec_path、phase_dir、phase_number、phase_name、padded_phase、state。模型取上一步解析出的AUDITOR_MODEL。

3.5 Step 4：解析审计结果

读取 auditor 写出的EVAL-REVIEW.md，提取三个关键字段：overall_score、verdict（PRODUCTION READY | NEEDS WORK | SIGNIFICANT GAPS | NOT IMPLEMENTED）、critical_gap_count。

3.6 Step 5：展示摘要与下一步

终端输出审计完成摘要（分数、判定、关键差距数、报告路径），并按判定分支给出后续动作：

• PRODUCTION READY→ 进入/gsd:plan-phase（下一阶段）或部署；
• NEEDS WORK→ 先处理EVAL-REVIEW.md中的关键差距，再重跑/gsd:eval-review {N}；
• SIGNIFICANT GAPS / NOT IMPLEMENTED→ 回看AI-SPEC.md的评估计划，关键评估维度未实现，禁止部署。

3.7 Step 6：提交（可选）

当commit_docs为 true 时，自动将报告纳入版本控制：

git add "${EVAL_REVIEW_FILE}" git commit -m "docs({phase_slug}): add EVAL-REVIEW.md — score {overall_score}/100 ({verdict})"

四、文本模式：非 Claude 运行时的兼容开关

工作流明确支持workflow.text_mode: true（配置）或--text标志：一旦激活TEXT_MODE，所有AskUserQuestion交互都会被替换为纯文本编号列表，由用户输入选项编号。这是为 OpenAI Codex、Gemini CLI 等不具备AskUserQuestion能力的运行时准备的必需路径，保证审计命令在多 AI 运行时下可用。

五、审计 Agent 的评分模型

5.1 对抗式立场

gsd-eval-auditor的核心立场是FORCE stance（对抗式假设）：默认认为评估策略没有被实现，直到代码库证据证明相反。其角色定义明确要求回答"实现的系统是否真的交付了规划的评估策略"，而非"看起来像实现了"。Agent 指令还显式列出了审计者常见的"变软"失败模式，用于自我纠偏：

• 因为"有一些测试"就把 MISSING 标成 PARTIAL——关键评估维度的部分覆盖在缺口未被量化前应视为 MISSING；
• 把指标日志当作评估已实现的证据，而忽略日志指标是否真正驱动决策；
• 把AI-SPEC.md的文档本身当作实现证据；
• 只验证测试文件存在，而不验证评估维度是否对照 rubric 评分；
• 为了软化报告而把 MISSING 降级为 PARTIAL。

差距分级为两种：BLOCKER（评估维度 MISSING 或护栏未实现，AI 系统不得上生产）与WARNING（评估维度 PARTIAL，覆盖不足但并非缺失）。每个规划维度必须归入 COVERED、PARTIAL（WARNING）或 MISSING（BLOCKER）之一。

5.2 执行流程与代码扫描

auditor 的执行流包含五步：读阶段产物（AI-SPEC.md 的 Section 5/6/7、SUMMARY.md、PLAN.md）→ 扫描代码库 → 逐维度评分 → 基础设施审计 → 计算分数并写报告。代码扫描覆盖五个类别（见 agents/gsd-eval-auditor.md 中的scan_codebase步骤），典型的探测命令包括：

# 评估/测试文件 find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "eval_*" \) \ -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -40 # 追踪/可观测性配置 grep -r "langfuse\|langsmith\|arize\|phoenix\|braintrust\|promptfoo" \ --include="*.py" --include="*.ts" --include="*.js" -l 2>/dev/null | head -20 # 护栏实现 grep -r "guardrail\|safety_check\|moderation\|content_filter" \ --include="*.py" --include="*.ts" --include="*.js" -l 2>/dev/null | head -20

5.3 维度评分标准

对 PARTIAL 与 MISSING，需要记录"规划了什么 / 实际发现了什么 / 达到 COVERED 的具体补救步骤"。

5.4 基础设施审计与加权打分

基础设施审计对 5 个组件分别评 ok / partial / missing：评估工具链（已安装且真实被调用，而非仅列在依赖里）、参考数据集（文件存在且满足规模/构成规格）、CI/CD 集成（Makefile、GitHub Actions 中存在评估命令）、在线护栏（每个规划的护栏真实进入请求路径，而非桩实现）、追踪（工具已配置并包裹真实 AI 调用）。

最终三档分数按固定公式计算：

coverage_score = covered_count / total_dimensions × 100 infra_score = (tooling + dataset + cicd + guardrails + tracing) / 5 × 100 overall_score = (coverage_score × 0.6) + (infra_score × 0.4)

判定阈值：80–100 →PRODUCTION READY（带监控部署）；60–79 →NEEDS WORK（上线前处理关键差距）；40–59 →SIGNIFICANT GAPS（禁止部署）；0–39 →NOT IMPLEMENTED（回看 AI-SPEC.md 并补实现）。

5.5 EVAL-REVIEW.md 输出结构

auditor 必须使用 Write 工具（而非 heredoc）写入{phase_dir}/{padded_phase}-EVAL-REVIEW.md，标准结构包含：审计日期与 AI-SPEC 是否存在、总分与判定、Dimension Coverage 表（维度/状态/测量方式/发现）、Infrastructure Audit 表（五组件状态与发现）、Critical Gaps（仅列 Critical 严重度的 MISSING 项）、分层的Remediation Plan（Must fix before production / Should fix soon / Nice to have），以及扫描中发现的评估相关文件清单（Files Found）。

六、评分框架参考：ai-evals.md 提供的底层逻辑

eval-review的评分不是凭空打分，而是建立在 get-shit-done/references/ai-evals.md 的评估方法论之上，该文档也是gsd-eval-planner与gsd-eval-auditor共用的框架：

• 为什么需要评估：AI 系统具有非确定性，单靠单元测试与集成测试不够；
• 模型评估 vs 产品评估：MMLU/HumanEval 等模型评估只作初筛，80% 的评估精力应投入产品评估（你的数据、用户与领域规则）；
• 每次评估的三要素：Input（查询、历史、检索文档、系统提示、配置）、Expected（通过 rubric 定义的好行为）、Actual（实际产出，含中间步骤、工具调用与推理轨迹）；
• 三种测量方式：代码化指标（确定性、快、便宜，先用）、LLM 裁判（主观质量，需先与人工校准）、人工评估（黄金标准但不可规模化，用于校准/边界/高价值决策）；
• 护栏 vs 飞轮决策：若行为出错对业务是灾难性的 → 在线实时护栏（有延迟成本，要克制）；否则 → 离线批量分析飞轮；
• Rubric 设计：必须定义维度、1/3/5 分档（5 分制）或 pass/fail 标准、领域内可接受/不可接受行为的示例，否则 LLM 裁判产出的是噪声而非信号；
• 参考数据集：起步 10–20 条高质量样例，覆盖关键成功场景、常见用户流、已知边界与历史失败模式，由领域专家标注；
• 评估工具选型：RAGAS（RAG 评估）、Langfuse / Arize Phoenix（平台化、可自托管）、LangSmith（LangChain 生态）、Braintrust（模型无关）、Promptfoo（CLI 优先、CI/CD）等。

七、闭环关系：planner 规划 → auditor 审计

要真正用好eval-review，需要理解它与上游gsd-eval-planner的契约关系。planner 在实现前就把评估策略写入AI-SPEC.md：按系统类型（RAG / Multi-Agent / Conversational / Extraction / Autonomous / Content / Code / Hybrid）映射必需维度（如 RAG 需 context faithfulness、hallucination、answer relevance、retrieval precision、source citation；Autonomous 需 safety guardrails、tool use correctness、cost/token adherence、task completion），并始终包含 safety 与 task completion 两个通用维度；每个 rubric 用 PASS/FAIL 加测量方式（Code / LLM Judge / Human）格式化，标记优先级（Critical/High/Medium），并规划工具链、参考数据集规格与在线护栏。审计时 auditor 逐条核对"规划 vs 实际"，若只有通用实践而无阶段专属计划（State B），审计强度自然下降——这正是工作流会警告用户"下次先跑 /gsd:ai-integration-phase"的原因。

八、实现佐证：仓库测试如何保障该体系

仓库中的 tests/ai-evals.test.cjs 覆盖了这套评估体系的契约完整性，包括：workflow.ai_integration_phase配置键的默认值（默认为 true）与 config-set/config-get 往返持久化、validate-health在缺少该配置时给出 W016 警告、addAiIntegrationPhaseKey修复动作、AI-SPEC.md 模板的 Section 完整性、plan-phase 的 AI 关键词提示块、ai-integration-phase 与 eval-review 两个命令的 frontmatter，以及 ai-evals.md / ai-frameworks.md 参考文件存在且非空。这从侧面印证了eval-review不是孤立命令，而是与配置、健康检查、模板和参考文档一起被持续验证的系统能力。

九、使用要点与最佳实践

1. 顺序正确：先/gsd:execute-phase {N}完成实现，再/gsd:eval-review {N}做回溯审计；缺省参数时自动选择最近完成的阶段。
2. 先有规划：实现 AI 阶段前优先运行/gsd:ai-integration-phase生成AI-SPEC.md，否则审计降级为对照通用实践（State B），且会收到非阻塞警告。
3. 按判定行动：NEEDS WORK 时先消化EVAL-REVIEW.md的 Critical Gaps 再重跑审计；SIGNIFICANT GAPS 与 NOT IMPLEMENTED 阶段禁止进入部署。
4. 多运行时兼容：在 Codex、Gemini CLI 等环境使用--text标志或配置workflow.text_mode: true，交互会切换为纯文本编号列表。
5. 重复审计：报告已存在时选择 "Re-audit" 可重新生成，配合commit_docs自动提交，形成可追溯的评估记录链。

十、局限说明

eval-review是评估覆盖度审计而非功能正确性审计——它回答"规划的评估体系是否落地"，不直接替代码质量把关；其评分依赖 auditor 对代码库的扫描深度与AI-SPEC.md中规划维度的质量（规划本身越粗糙，审计上限越低）。此外，文本模式与模型解析（AUDITOR_MODEL）依赖 GSD SDK 与gsd-sdk query resolve-model的可用性，这些属于运行时的前提条件。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done