mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
406 lines
17 KiB
Markdown
406 lines
17 KiB
Markdown
---
|
||
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 -->
|