spec-critique

规范评审技能

概述

对规范文档进行批判性评审，检查其准确性、完整性和可行性。在开始实现前，使用扩展思考发现问题。

核心原则： 使用扩展思考（深入分析），在实现前发现问题。

使用时机

始终适用：

• 规范编写完成后
• 开始制定实现计划前
• 规范涉及外部集成时
• 对于包含多个组件的复杂功能

例外情况：

• 针对简单改动的简单规范
• 已由其他 Agent 评审过的规范

铁律

NO IMPLEMENTATION WITHOUT SPEC CRITIQUE FOR COMPLEX TASKS

复杂任务（外部集成、多服务改动）必须进行规范评审。

所需输入

评审前，请确保已获取：

1. spec.md - 要评审的规范
2. 需求文档 - 用户的原始需求
3. 项目上下文 - 技术栈、模式

工作流

阶段 1：加载所有上下文

# Read the spec
cat .claude/context/specs/[task-name]-spec.md

# Read original requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/tech-stack.md

了解：

• 规范声称的内容
• 用户最初提出的需求
• 代码库中已有的模式

阶段 2：深入分析（使用扩展思考）

重要： 此阶段必须使用扩展思考。深入思考以下方面：

技术准确性

根据需求和代码库检查规范：

• 包名称：规范使用的包名称是否正确？
• 导入语句：导入是否符合 API 模式？
• API 调用：函数签名是否与文档一致？
• 配置：环境变量和配置选项是否正确？

检查常见的规范错误：

• 包名称错误（例如，“react-query”与“@tanstack/react-query”）
• API 模式过时（例如，使用已弃用的函数）
• 函数签名错误（例如，参数顺序错误）
• 缺少必需配置（例如，缺少环境变量）

标记所有不匹配之处。

完整性

根据需求进行检查：

• 是否涵盖所有需求？ - 每项需求都应有对应的实现细节
• 所有验收标准是否都可测试？ - 每项标准都应可验证
• 是否处理了边缘情况？ - 错误条件、空状态、超时
• 集成点是否清晰？ - 组件之间如何连接

标记所有缺漏。

一致性

检查规范内部是否一致：

• 包名称一致 - 始终使用相同名称
• 文件路径一致 - 不存在冲突的路径
• 模式一致 - 全文采用相同风格
• 术语一致 - 同一概念使用相同术语

标记所有不一致之处。

可行性

检查方案是否切实可行：

• 依赖项是否可用？ - 所有包均存在且仍在维护
• 基础设施是否现实？ - 配置能够正常运行
• 实现顺序是否合理？ - 先处理依赖项，再处理依赖方
• 范围是否恰当？ - 不过度设计，也不过于笼统

标记所有疑虑。

需求对齐

与需求交叉核对：

• 是否使用了已验证的信息？ - 规范应采用经过调研的事实
• 是否标明了未经验证的说法？ - 应清楚标记所有假设
• 是否处理了注意事项？ - 应处理已知问题
• 是否采纳了建议？ - 应纳入需求中的建议

标记所有偏差。

阶段 3：汇总问题

列出发现的所有问题：

## Issues Found

### 1. [SEVERITY: HIGH] Package name incorrect

- **Spec says**: "[incorrect]"
- **Should be**: "[correct]"
- **Location**: Line 45, Requirements section

### 2. [SEVERITY: MEDIUM] Missing edge case

- **Requirement**: "Handle connection failures"
- **Spec**: No error handling specified
- **Location**: Implementation Notes section

### 3. [SEVERITY: LOW] Inconsistent terminology

- **Issue**: Uses both "memory" and "episode" for same concept
- **Location**: Throughout document

阶段 4：修复问题

针对发现的每个问题，直接在规范中进行修复：

对于每项修复：

1. 在规范中进行更改
2. 确认更改已应用
3. 记录更改内容

阶段 5：创建评审报告

# Spec Critique Report

**Spec**: [spec-name]
**Date**: [timestamp]

## Summary

| Category               | Status    | Issues  |
| ---------------------- | --------- | ------- |
| Technical Accuracy     | PASS/FAIL | [count] |
| Completeness           | PASS/FAIL | [count] |
| Consistency            | PASS/FAIL | [count] |
| Feasibility            | PASS/FAIL | [count] |
| Requirements Alignment | PASS/FAIL | [count] |

## Issues Found and Fixed

### High Severity

1. [Issue] - FIXED: [what was changed]

### Medium Severity

1. [Issue] - FIXED: [what was changed]

### Low Severity

1. [Issue] - FIXED: [what was changed]

## No Issues Found (if applicable)

Spec is well-written with no significant issues found.

## Confidence Level

[HIGH/MEDIUM/LOW]

## Recommendations

- [Any remaining concerns or suggestions]

阶段 6：验证修复

完成更改后：

# Verify spec is still valid markdown
head -50 .claude/context/specs/[task-name]-spec.md

# Check key sections exist
grep -E "^##? Overview" spec.md
grep -E "^##? Requirements" spec.md
grep -E "^##? Success Criteria" spec.md

严重程度指南

高 - 将导致实现失败：

• 包名称错误
• API 签名错误
• 缺少关键需求
• 配置无效

中 - 可能导致问题：

• 缺少边缘情况
• 错误处理不完整
• 集成点不明确
• 模式不一致

低 - 轻微改进：

• 术语不一致
• 文档缺漏
• 风格问题
• 轻微优化

类别定义

• 准确性：技术正确性（软件包、API、配置）
• 完整性：对需求和边界情况的覆盖
• 一致性：文档内部的连贯性
• 可行性：实际实现的可行性
• 对齐度：与原始需求的匹配程度

验证清单

完成规格说明评审前：

• 已通过扩展思考分析所有章节
• 已验证技术准确性
• 已根据需求检查完整性
• 已验证整个规格说明的一致性
• 已评估可行性
• 已按严重程度整理所有问题
• 已修复所有高优先级和中优先级问题
• 已创建评审报告
• 修复后规格说明仍然有效

扩展思考提示词

分析时，请思考：

“查看这份规格说明，我需要根据需求进行深入分析……

首先，检查所有软件包名称。需求提到了 [X]，但规格说明中写的是 [Y]。这处不匹配需要修正。

接下来，检查 API 模式。需求说明初始化需要 [步骤]，但规格说明展示了[不同步骤]。这是另一个问题。

关于完整性，需求提到了 [X、Y、Z]。规格说明涵盖了 X 和 Y，但我没有看到任何地方提及 Z。这是一个缺口。

检查一致性时，我注意到‘[术语 1]’和‘[术语 2]’被交替使用。应该统一成一个术语。

关于可行性，设置似乎正确。配置也符合要求。

总体而言，我发现 [N] 个问题，在这份规格说明可以用于实施前需要修复。”

常见错误

流于表面的评审

**为什么不对：**走马观花会漏掉关键问题。

**应该这样做：**运用扩展思考，深入分析每个章节。

只报告问题而不修复

**为什么不对：**仅仅列出问题并不能改进规格说明。

**应该这样做：**直接修复问题，让规格说明更完善。

与其他技能的集成

此技能适用于：

• 规格说明编写：提供待评审的规格说明
• 复杂度评估：帮助判断是否需要评审
• 调试：规格说明评审发现代码问题时使用

铁律

1. 绝不批准包含矛盾的规格说明，即使是轻微矛盾
2. 始终明确指出隐藏假设——它们与明示需求同样重要
3. 绝不在规格评审中放任范围蔓延
4. 始终在批准前验证边界情况和错误场景
5. 绝不评判实施方案——只关注规格说明的完整性和一致性

反模式

反模式	失败原因	正确做法
批准存在矛盾的规格说明	下游实施可能会错误地解决这些矛盾	在批准前指出所有矛盾，即使是轻微矛盾
忽略隐藏假设	实施时，假设会变成不匹配的需求	明确指出规格说明所依赖的每一项假设
跳过边界情况评审	实施过程中才发现错误场景，为时已晚	验证规格说明中的所有边界条件和错误路径
评判实施细节	这会分散对规格质量的关注；规格说明定义的是“做什么”，而非“如何做”	评审应聚焦于完整性、一致性和可测试性
接受含糊的成功标准	无法验证交付是否完成	要求每项需求都有可衡量、可测试的验收标准

记忆协议

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现的问题 -> .claude/context/memory/issues.md
• 做出的决定 -> .claude/context/memory/decisions.md

假设任务会中断：如果没有记录在记忆中，就等于没有发生。