mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
v1.0：gudaspec正式版，不再依赖于openspec
This commit is contained in:
GuDaStudio
405
gudaspec/plan-review.md
Normal file
405
gudaspec/plan-review.md
Normal file
@@ -0,0 +1,405 @@
|
||||
---
|
||||
name: GudaSpec: Plan Review
|
||||
description: Review plan structure, write detailed implementation plan with test specifications, and approve.
|
||||
category: GudaSpec
|
||||
tags: [gudaspec, plan, review, detail, tdd, approval]
|
||||
argument-hint: [requirement-id]
|
||||
---
|
||||
|
||||
<!-- GUDASPEC:PLAN-REVIEW:START -->
|
||||
|
||||
## Purpose
|
||||
|
||||
基于已确认的计划结构，编写详细实施计划，生成测试规格（如适用），多模型审查，最终用户批准。
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Structure First** — 结构已在plan阶段确认，本阶段聚焦细节
|
||||
2. **Test-First When TDD** — Level 1-2时，测试规格先于实现细节
|
||||
3. **Interactive Review** — 逐Phase与用户确认，非一次性输出
|
||||
4. **Multi-Model Verification** — 多模型审查计划完整性
|
||||
5. **Explicit Approval** — 必须获得用户明确批准
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **MUST** load both structure.md and requirement.md first.
|
||||
- **MUST** confirm each Phase with user before moving to next.
|
||||
- **MUST** generate test specifications if test_level >= 1.
|
||||
- **MUST** run multi-model review before final approval.
|
||||
- **NEVER** finalize plan with open questions.
|
||||
- Keep context under 60K tokens.
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### Step 0: Load Documents
|
||||
|
||||
```bash
|
||||
cat gudaspec/plans/<requirement-id>/structure.md
|
||||
cat gudaspec/research/<requirement-id>/requirement.md
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Phase结构
|
||||
- 测试策略Level
|
||||
- 约束集
|
||||
- 技术决策
|
||||
|
||||
### Step 1: Structure Confirmation
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📋 计划详细化: <Requirement Title>
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
需求ID: <requirement-id>
|
||||
测试策略: Level <X>
|
||||
|
||||
【计划结构回顾】
|
||||
Phase 1: <name> — <goal>
|
||||
Phase 2: <name> — <goal>
|
||||
Phase 3: <name> — <goal>
|
||||
|
||||
接下来我将逐Phase编写详细内容。
|
||||
每个Phase完成后会请您确认。
|
||||
|
||||
准备开始？
|
||||
```
|
||||
|
||||
### Step 2: Detail Each Phase (Interactive Loop)
|
||||
|
||||
**For each Phase:**
|
||||
|
||||
#### 2.1 Generate Test Specifications (if Level >= 1)
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🧪 Phase 1 测试规格
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【测试目标】
|
||||
验证: <what this phase should achieve>
|
||||
|
||||
【测试用例】
|
||||
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Test 1: <test_name> │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 场景: <scenario description> │
|
||||
│ 输入: <input> │
|
||||
│ 期望: <expected output> │
|
||||
│ 验证: <how to verify> │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Test 2: <test_name> │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 场景: <edge case> │
|
||||
│ 输入: <input> │
|
||||
│ 期望: <expected output> │
|
||||
│ 验证: <how to verify> │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
【测试代码骨架】
|
||||
```python
|
||||
# tests/test_<module>.py
|
||||
|
||||
class TestPhase1<Feature>:
|
||||
"""Phase 1: <name> 测试"""
|
||||
|
||||
def test_<scenario_1>(self):
|
||||
"""
|
||||
场景: <description>
|
||||
期望: <expected>
|
||||
"""
|
||||
# Arrange
|
||||
<setup code hint>
|
||||
|
||||
# Act
|
||||
<action code hint>
|
||||
|
||||
# Assert
|
||||
assert <condition>, "<failure message>"
|
||||
|
||||
def test_<scenario_2>(self):
|
||||
"""边界情况: <description>"""
|
||||
# TODO: Implement
|
||||
pass
|
||||
```
|
||||
|
||||
【Property Tests】(if Level 2)
|
||||
```python
|
||||
from hypothesis import given, strategies as st
|
||||
|
||||
@given(st.text(min_size=1, max_size=100))
|
||||
def test_<property_name>(input_value):
|
||||
"""
|
||||
Property: <invariant description>
|
||||
"""
|
||||
result = <function>(input_value)
|
||||
assert <property_condition>
|
||||
```
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "Phase 1 测试规格是否完整？"
|
||||
options: [
|
||||
"完整，继续编写实现细节",
|
||||
"需要添加更多测试场景",
|
||||
"需要修改某个测试",
|
||||
"测试粒度不合适"
|
||||
]
|
||||
```
|
||||
|
||||
### Step 2.2: Write Implementation Details
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📝 Phase 1 变更规格
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【变更清单】
|
||||
|
||||
1️⃣ 认证服务扩展
|
||||
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 文件: `src/auth/service.py` │
|
||||
│ 类型: 修改现有类 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 【接口定义】 │
|
||||
│ ```python │
|
||||
│ async def verify_2fa( │
|
||||
│ self, │
|
||||
│ user_id: UUID, │
|
||||
│ code: str │
|
||||
│ ) -> bool: │
|
||||
│ """ │
|
||||
│ 验证用户的双因素认证码 │
|
||||
│ │
|
||||
│ Args: │
|
||||
│ user_id: 用户唯一标识 │
|
||||
│ code: 6位TOTP验证码 │
|
||||
│ │
|
||||
│ Returns: │
|
||||
│ 验证成功True，失败False │
|
||||
│ │
|
||||
│ Raises: │
|
||||
│ UserNotFoundError: 用户不存在 │
|
||||
│ TwoFactorNotEnabledError: 用户未启用2FA │
|
||||
│ """ │
|
||||
│ ``` │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 【行为规格】 │
|
||||
│ • 用户不存在 → 抛出 UserNotFoundError │
|
||||
│ • 用户未启用2FA → 抛出 TwoFactorNotEnabledError │
|
||||
│ • 验证码正确 → 返回 True，重置失败计数 │
|
||||
│ • 验证码错误 → 返回 False，增加失败计数 │
|
||||
│ • 验证窗口 → ±1周期（允许30秒误差） │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 【实现要点】 │
|
||||
│ • 使用现有 TotpService.verify() 方法 │
|
||||
│ • 遵循 authenticate() 的错误处理模式 │
|
||||
│ • 失败计数存储于 user.failed_2fa_attempts │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 【参考模式】 │
|
||||
│ • src/auth/service.py:78-95 authenticate() 方法 │
|
||||
│ • src/auth/totp.py:23 TotpService.verify() 方法 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 关联约束: HC-I-1（复用TotpService）, SC-I-2（错误处理模式） │
|
||||
│ 关联测试: test_valid_code_passes, test_invalid_code_fails │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
【注意】: 以上是规格说明，非完整实现代码。
|
||||
Implementation阶段将基于此规格编写实际代码。
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "Phase 1 实现细节是否清晰完整？"
|
||||
options: [
|
||||
"清晰，继续Phase 2",
|
||||
"代码变更需要调整",
|
||||
"执行顺序需要修改",
|
||||
"Success Criteria需要补充"
|
||||
]
|
||||
```
|
||||
|
||||
#### 2.3 Repeat for Each Phase
|
||||
|
||||
Continue until all Phases are detailed.
|
||||
|
||||
### Step 3: Multi-Model Review
|
||||
|
||||
**Invoke `mcp__codex__codex`:**
|
||||
```
|
||||
Review this implementation plan:
|
||||
[paste complete plan]
|
||||
|
||||
Check for:
|
||||
1. Missing files that should be modified
|
||||
2. Incorrect dependency order
|
||||
3. Incomplete success criteria
|
||||
4. Edge cases not covered by tests
|
||||
|
||||
Format: [ISSUE] <description> → [SUGGESTION] <fix>
|
||||
```
|
||||
|
||||
**Invoke `mcp__gemini__gemini`:**
|
||||
```
|
||||
Review this implementation plan:
|
||||
[paste complete plan]
|
||||
|
||||
Check for:
|
||||
1. UI/UX gaps
|
||||
2. Accessibility issues
|
||||
3. Component interaction problems
|
||||
4. Missing manual verification steps
|
||||
|
||||
Format: [ISSUE] <description> → [SUGGESTION] <fix>
|
||||
```
|
||||
|
||||
**Present review findings:**
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔍 多模型审查结果
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【Codex 发现】
|
||||
• ⚠️ <issue 1> → 建议: <fix>
|
||||
• ✅ 依赖顺序正确
|
||||
• ✅ 测试覆盖完整
|
||||
|
||||
【Gemini 发现】
|
||||
• ⚠️ <issue 2> → 建议: <fix>
|
||||
• ✅ UI变更合理
|
||||
|
||||
【已自动修正】
|
||||
• <auto-fixed issue>
|
||||
|
||||
【需要您确认】
|
||||
• <issue requiring user decision>
|
||||
```
|
||||
|
||||
### Step 4: Final Summary & Approval
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📋 计划总结
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【计划概览】
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 需求: <requirement title> │
|
||||
│ ID: <requirement-id> │
|
||||
│ 测试策略: Level <X> │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Phase 1: <name> │
|
||||
│ ├─ 文件变更: <N>个 │
|
||||
│ ├─ 测试用例: <M>个 │
|
||||
│ └─ 验证点: 自动<A>个 + 手动<B>个 │
|
||||
│ │
|
||||
│ Phase 2: <name> │
|
||||
│ ├─ 文件变更: <N>个 │
|
||||
│ ├─ 测试用例: <M>个 │
|
||||
│ └─ 验证点: 自动<A>个 + 手动<B>个 │
|
||||
│ │
|
||||
│ Phase 3: <name> │
|
||||
│ ├─ 文件变更: <N>个 │
|
||||
│ ├─ 测试用例: <M>个 │
|
||||
│ └─ 验证点: 自动<A>个 + 手动<B>个 │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 总计: │
|
||||
│ • 文件变更: <total>个 │
|
||||
│ • 测试用例: <total>个 │
|
||||
│ • 自动验证: <total>个 │
|
||||
│ • 手动验证: <total>个 │
|
||||
│ • 风险等级: 中 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
【执行流程预览】
|
||||
Phase 1 → 自动验证 → ⏸️手动确认 → Phase 2 → 自动验证 → ⏸️手动确认 → ...
|
||||
|
||||
【回滚计划】
|
||||
如果任何Phase失败: <rollback strategy>
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "是否批准此计划？"
|
||||
options: [
|
||||
"批准，保存完整计划",
|
||||
"需要修改某个Phase",
|
||||
"需要调整整体结构",
|
||||
"有问题需要讨论"
|
||||
]
|
||||
```
|
||||
|
||||
### Step 5: Save Complete Plan
|
||||
|
||||
Save to: `gudaspec/plans/<requirement-id>/plan.md`
|
||||
|
||||
Also save test skeletons (if Level >= 1):
|
||||
```
|
||||
gudaspec/plans/<requirement-id>/tests/
|
||||
├── test_spec.md
|
||||
└── skeletons/
|
||||
├── test_phase1.py
|
||||
├── test_phase2.py
|
||||
└── ...
|
||||
```
|
||||
|
||||
Update structure.md status: `status: plan-approved`
|
||||
|
||||
### Step 6: Completion Output
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ 计划已批准
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
需求ID: <requirement-id>
|
||||
|
||||
📁 生成的文件:
|
||||
gudaspec/plans/<requirement-id>/
|
||||
├── structure.md (已更新状态)
|
||||
├── plan.md (完整计划) ⭐
|
||||
└── tests/
|
||||
├── test_spec.md (测试规格)
|
||||
└── skeletons/ (测试骨架代码)
|
||||
|
||||
📊 计划摘要:
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Phases: [N] │
|
||||
│ 文件变更: [X] │
|
||||
│ 测试用例: [Y] │
|
||||
│ 测试策略: Level [Z] │
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
📋 下一步操作:
|
||||
1. 输入 /clear 清空当前上下文
|
||||
2. 输入 /gudaspec:implementation gudaspec/plans/<requirement-id>/plan.md
|
||||
|
||||
⚠️ 实施阶段提示:
|
||||
• 将逐Phase执行，每Phase有明确的停止点
|
||||
• 测试将在实现前/后运行（取决于TDD Level）
|
||||
• 每个Phase自动验证通过后等待您的手动确认
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- [ ] Structure document loaded and confirmed
|
||||
- [ ] All Phases detailed with implementation steps
|
||||
- [ ] Test specifications generated (if Level >= 1)
|
||||
- [ ] Multi-model review completed and issues addressed
|
||||
- [ ] User explicitly approved the plan
|
||||
- [ ] plan.md saved with all details
|
||||
- [ ] Test skeletons saved (if applicable)
|
||||
- [ ] User directed to /gudaspec:implementation
|
||||
|
||||
<!-- GUDASPEC:PLAN-REVIEW:END -->
|
||||
Reference in New Issue
Block a user