mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
352 lines
14 KiB
Markdown
352 lines
14 KiB
Markdown
---
|
||
name: GudaSpec: Plan
|
||
description: Analyze requirements and design implementation plan structure with test strategy selection.
|
||
category: GudaSpec
|
||
tags: [gudaspec, plan, structure, multi-model, tdd]
|
||
argument-hint: [requirement.md path]
|
||
---
|
||
|
||
<!-- GUDASPEC:PLAN:START -->
|
||
|
||
## Purpose
|
||
|
||
分析需求文档，设计计划结构，选择测试策略。产出计划结构草案供review阶段确认和细化。
|
||
|
||
## Core Principles
|
||
|
||
1. **Read Everything First** — 完整读取所有引用文件后再分析
|
||
2. **Verify Before Plan** — 验证约束仍然有效
|
||
3. **Structure Before Detail** — 先确认结构，再写细节
|
||
4. **Test Strategy Early** — 在结构阶段就决定测试策略
|
||
|
||
## Guardrails
|
||
|
||
- If project lacks `gudaspec/` directory, prompt user to run `/gudaspec:init`.
|
||
- **MUST** read requirement.md and ALL referenced files completely.
|
||
- **MUST** verify constraints against current codebase.
|
||
- **MUST** get user confirmation on plan structure before proceeding.
|
||
- **NEVER** write detailed implementation steps in this phase.
|
||
- Keep context under 50K tokens.
|
||
|
||
---
|
||
|
||
## Steps
|
||
|
||
### Step 0: Load Requirement Document
|
||
|
||
**With parameter:**
|
||
```
|
||
/gudaspec:plan gudaspec/research/<requirement-id>/requirement.md
|
||
```
|
||
Read the file and all files mentioned in it.
|
||
|
||
**Without parameter:**
|
||
```
|
||
请提供需求文档路径:
|
||
/gudaspec:plan gudaspec/research/<requirement-id>/requirement.md
|
||
```
|
||
|
||
### Step 1: Context Gathering & Verification
|
||
|
||
1. **Extract from requirement.md:**
|
||
- 约束集（硬约束 + 软约束）
|
||
- 技术决策
|
||
- 集成点
|
||
- 成功标准
|
||
- 实施边界
|
||
|
||
2. **Read all referenced source files**
|
||
|
||
3. **Verify constraints still valid:**
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
🔍 约束验证
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
| 约束ID | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| HC-I-1 | ✅ 有效 | 代码未变更 |
|
||
| HC-I-2 | ⚠️ 变化 | 文件已移动到新位置 |
|
||
| SC-E-1 | ✅ 有效 | 外部API仍适用 |
|
||
```
|
||
|
||
4. **Present understanding for confirmation**
|
||
|
||
Use `AskUserQuestions` to confirm understanding.
|
||
|
||
### Step 2: Multi-Model Analysis
|
||
|
||
**Invoke `mcp__codex__codex`:**
|
||
```
|
||
Analyze this requirement for implementation planning:
|
||
[paste key constraints and decisions]
|
||
|
||
Identify:
|
||
1. Implementation risks
|
||
2. Dependency order between components
|
||
3. Edge cases to address
|
||
4. Suggested phase boundaries
|
||
```
|
||
|
||
**Invoke `mcp__gemini__gemini`:**
|
||
```
|
||
Analyze this requirement for implementation planning:
|
||
[paste key constraints and decisions]
|
||
|
||
Identify:
|
||
1. UI/UX implementation considerations
|
||
2. Component structure recommendations
|
||
3. State management implications
|
||
4. Testing challenges for frontend
|
||
```
|
||
|
||
**Present synthesized findings:**
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
🔍 多模型分析结果
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
【风险识别】
|
||
• <risk 1>
|
||
• <risk 2>
|
||
|
||
【依赖顺序建议】
|
||
1. <first>
|
||
2. <second>
|
||
3. <third>
|
||
|
||
【建议的Phase边界】
|
||
• Phase 1 与 Phase 2 在 <component> 处分界
|
||
• 原因: <rationale>
|
||
```
|
||
|
||
### Step 3: Test Strategy Selection
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
🧪 测试策略选择
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
请选择本次实施的测试策略:
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Level 0: 标准验证模式 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • 使用Success Criteria命令验证 │
|
||
│ • 不生成测试代码 │
|
||
│ • 适合: 简单修复、配置变更、原型探索 │
|
||
│ • 验证方式: 运行现有测试 + 手动检查 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Level 1: TDD模式 ⭐推荐 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • 先写测试，再写实现 (Red-Green-Refactor) │
|
||
│ • 生成测试骨架代码 │
|
||
│ • 适合: 标准功能开发、API开发、业务逻辑 │
|
||
│ • 验证方式: 测试从红变绿 + 手动检查 │
|
||
│ │
|
||
│ 【TDD如何帮助AI开发】 │
|
||
│ • 失败测试为AI提供精确的任务定义 │
|
||
│ • 防止AI"幻觉"——测试会立即暴露错误 │
|
||
│ • 每个小步骤都有验证，错误不会累积 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Level 2: TDD + Property Testing │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ • 包含Level 1全部内容 │
|
||
│ • 额外定义Property不变量 │
|
||
│ • 随机输入发现边界情况 │
|
||
│ • 适合: 关键业务逻辑、安全功能、数据处理 │
|
||
│ • 验证方式: 测试通过 + Property验证 + 手动检查 │
|
||
│ │
|
||
│ 【Property Testing示例】 │
|
||
│ • "密码永不出现在日志中" — 随机测试1000种输入 │
|
||
│ • "加密后解密等于原文" — 验证往返一致性 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
基于您的需求特点，我建议: Level <X>
|
||
原因: <rationale>
|
||
```
|
||
|
||
Use `AskUserQuestions`:
|
||
```
|
||
question: "选择测试策略Level"
|
||
options: [
|
||
"Level 0: 标准验证（简单任务）",
|
||
"Level 1: TDD模式（推荐）",
|
||
"Level 2: TDD + Property Testing（关键逻辑）",
|
||
"不确定，请解释更多"
|
||
]
|
||
```
|
||
|
||
### Step 4: Design Plan Structure
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
📐 计划结构设计
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
【实施策略概述】
|
||
<1-2句话描述整体策略>
|
||
|
||
【Phase划分】
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Phase 1: <名称> │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 目标: <完成什么> │
|
||
│ 涉及: <模块/文件范围> │
|
||
│ 依赖: 无 │
|
||
│ 预计: ~<N>个文件变更 │
|
||
│ 测试: <Level对应的验证方式> │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ 完成 + 验证通过
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Phase 2: <名称> │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 目标: <完成什么> │
|
||
│ 涉及: <模块/文件范围> │
|
||
│ 依赖: Phase 1 │
|
||
│ 预计: ~<N>个文件变更 │
|
||
│ 测试: <Level对应的验证方式> │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ 完成 + 验证通过
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Phase 3: <名称> │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 目标: <完成什么> │
|
||
│ 涉及: <模块/文件范围> │
|
||
│ 依赖: Phase 2 │
|
||
│ 预计: ~<N>个文件变更 │
|
||
│ 测试: <Level对应的验证方式> │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
【明确不包含】
|
||
• ❌ <排除项1> — 原因: <reason>
|
||
• ❌ <排除项2> — 原因: <reason>
|
||
|
||
【风险预判】
|
||
| 风险 | 严重度 | 缓解策略 |
|
||
|------|--------|----------|
|
||
| <risk> | 高/中/低 | <mitigation> |
|
||
```
|
||
|
||
Use `AskUserQuestions`:
|
||
```
|
||
question: "计划结构是否合适？"
|
||
options: [
|
||
"合适，保存并继续",
|
||
"需要调整Phase划分",
|
||
"需要调整范围边界",
|
||
"风险评估需要修改"
|
||
]
|
||
```
|
||
|
||
### Step 5: Save Structure Document
|
||
|
||
Save to: `gudaspec/plans/<requirement-id>/structure.md`
|
||
|
||
```markdown
|
||
---
|
||
requirement_id: <requirement-id>
|
||
created: <ISO timestamp>
|
||
planner: claude
|
||
status: structure-approved
|
||
test_level: <0|1|2>
|
||
requirement_ref: gudaspec/research/<requirement-id>/requirement.md
|
||
git_commit: <current commit>
|
||
branch: <current branch>
|
||
---
|
||
|
||
# Plan Structure: <Requirement Title>
|
||
|
||
## 实施策略
|
||
<strategy overview>
|
||
|
||
## 约束验证结果
|
||
| 约束ID | 状态 | 说明 |
|
||
|--------|------|------|
|
||
...
|
||
|
||
## 多模型分析摘要
|
||
### 风险
|
||
...
|
||
### 依赖顺序
|
||
...
|
||
|
||
## 测试策略
|
||
Level: <0|1|2>
|
||
原因: <rationale>
|
||
|
||
## Phase结构
|
||
|
||
### Phase 1: <name>
|
||
- 目标:
|
||
- 涉及:
|
||
- 依赖:
|
||
- 预计变更:
|
||
|
||
### Phase 2: <name>
|
||
...
|
||
|
||
## 不包含
|
||
- ❌ ...
|
||
|
||
## 风险预判
|
||
| 风险 | 严重度 | 缓解策略 |
|
||
...
|
||
|
||
## 下一步
|
||
/clear → /gudaspec:plan-review <requirement-id>
|
||
```
|
||
|
||
### Step 6: Completion Output
|
||
|
||
```
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
✅ 计划结构已保存
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
需求ID: <requirement-id>
|
||
结构文档: gudaspec/plans/<requirement-id>/structure.md
|
||
|
||
结构摘要:
|
||
┌─────────────────────────────────────────┐
|
||
│ Phase数量: [N] │
|
||
│ 测试策略: Level [X] │
|
||
│ 预计文件变更: [Y] 个 │
|
||
│ 风险等级: 高/中/低 │
|
||
└─────────────────────────────────────────┘
|
||
|
||
📋 下一步操作:
|
||
1. 输入 /clear 清空当前上下文
|
||
2. 输入 /gudaspec:plan-review <requirement-id>
|
||
|
||
plan-review阶段将:
|
||
• 确认每个Phase的详细内容
|
||
• 生成具体的代码变更说明
|
||
• 生成测试规格（Level 1-2）
|
||
• 最终批准计划
|
||
```
|
||
|
||
---
|
||
|
||
## Exit Criteria
|
||
|
||
- [ ] Requirement document fully read and understood
|
||
- [ ] All referenced files read
|
||
- [ ] Constraints verified against current code
|
||
- [ ] Multi-model analysis completed
|
||
- [ ] Test strategy level selected
|
||
- [ ] Plan structure designed and approved
|
||
- [ ] Structure document saved
|
||
- [ ] User directed to /gudaspec:plan-review
|
||
|
||
<!-- GUDASPEC:PLAN:END -->
|