v1.0：gudaspec正式版，不再依赖于openspec

2026-03-22 19:18:52 +08:00 · 2026-02-06 11:11:39 +08:00
parent 32d5902088
commit 34b2c931b6
8 changed files with 3669 additions and 196 deletions
--- a/gudaspec/plan.md
+++ b/gudaspec/plan.md
@@ -1,61 +1,351 @@
 ---
 name: GudaSpec: Plan
-description: Refine proposals into zero-decision executable task flows via multi-model analysis.
+description: Analyze requirements and design implementation plan structure with test strategy selection.
 category: GudaSpec
-tags: [gudaspec, plan, multi-model, pbt]
-allowed-tools: Bash(openspec:*), mcp__codex__codex, mcp__gemini__gemini
-argument-hint: [proposal_id]
+tags: [gudaspec, plan, structure, multi-model, tdd]
+argument-hint: [requirement.md path]
 ---
-<!-- GUDASPEC:START -->
-**Guardrails**
- If the project is detected to lack `./openspec/` dir, prompt the user to initialize the project using `/gudaspec:init`.
- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**.
- The goal of this phase is to eliminate ALL decision points from the task flow—implementation should be pure mechanical execution.
- Do not proceed to implementation until every ambiguity is resolved and every constraint is explicitly documented.
- Multi-model collaboration is mandatory: use both `mcp__codex__codex` and `mcp__gemini__gemini` to surface blind spots and conflicting assumptions.
- Every requirement must have Property-Based Testing (PBT) properties defined—focus on invariants, not just example-based tests.
- If constraints cannot be fully specified, escalate back to the user rather than making assumptions.

-**Steps**
-1. Run `openspec view` to display all **Active Changes**, then confirm with the user which proposal ID (`<proposal_id>`) they wish to refine into a zero-decision plan.
+<!-- GUDASPEC:PLAN:START -->

-2. Run `/opsx:continue <proposal_id>` then follow it to review the current specs and improve quality of specs.
+## Purpose

-3. During the review progress, invoke both MCP tools to detect remaining ambiguities:
-   - Use `mcp__codex__codex` tool, e.g. "Review proposal <proposal_id> for decision points that remain unspecified. List each as: [AMBIGUITY] <description> → [REQUIRED CONSTRAINT] <what must be decided>."
-   - Use `mcp__gemini__gemini` tool, e.g. "Identify implicit assumptions in proposal <proposal_id>. For each assumption, specify: [ASSUMPTION] <description> → [EXPLICIT CONSTRAINT NEEDED] <concrete specification>."
-   - **Anti-Pattern Detection** (flag and reject):
-     - Information collection without decision boundaries (e.g., "JWT vs OAuth2 vs session—all viable")
-     - Technical comparisons without selection criteria
-     - Deferred decisions marked as "to be determined during implementation"
-   - **Target Pattern** (required for approval):
-     - Explicit technology choices with parameters (e.g., "JWT with accessToken TTL=15min, refreshToken TTL=7days")
-     - Concrete algorithm selections with configurations (e.g., "bcrypt with cost factor=12")
-     - Precise behavioral rules (e.g., "Lock account for 30min after 5 failed login attempts")
-   - Use `AskUserQuestions` tool for ANY ambiguity, NEVER assume or guess.
-   - **Iterate** with user until ALL ambiguities are resolved into explicit constraints.
+分析需求文档，设计计划结构，选择测试策略。产出计划结构草案供review阶段确认和细化。

-4. After clarifying requirements, modify the spec documents. For each change, you MUST run the command `openspec validate <proposal_id> --strict` to ensure the correct format.
+## Core Principles

-5. When backend logic modification requirements are identified, Invoke both MCP tools to derive testable invariants:
-   - Use `mcp__codex__codex` tool, e.g. "Extract Property-Based Testing properties from proposal <proposal_id>. For each requirement, identify: [INVARIANT] <mathematical property that must always hold> → [FALSIFICATION STRATEGY] <how to generate test cases that attempt to break it>."
-   - Use `mcp__codex__codex` tool, e.g. "Analyze proposal <proposal_id> for system properties. Define: [PROPERTY] <name> | [DEFINITION] <formal description> | [BOUNDARY CONDITIONS] <edge cases to test> | [COUNTEREXAMPLE GENERATION] <approach>."
-   - **PBT Property Categories to Extract**:
-     - **Commutativity/Associativity**: Order-independent operations
-     - **Idempotency**: Repeated operations yield same result
-     - **Round-trip**: Encode→Decode returns original
-     - **Invariant Preservation**: State constraints maintained across operations
-     - **Monotonicity**: Ordering guarantees (e.g., timestamps always increase)
-     - **Bounds**: Value ranges, size limits, rate constraints
-   - After modify the spec documents with the PBT, MUST run the command `openspec validate <proposal_id> --strict` to ensure the correct format.
+1. **Read Everything First** — 完整读取所有引用文件后再分析
+2. **Verify Before Plan** — 验证约束仍然有效
+3. **Structure Before Detail** — 先确认结构，再写细节
+4. **Test Strategy Early** — 在结构阶段就决定测试策略

-6. For complex proposals, consider running steps 2-4 iteratively on sub-components and remind the user rather than the entire proposal at once.
+## Guardrails

-**Exit Criteria**
-A proposal is ready to exit the Plan phase only when:
- [ ] All multi-model analyses completed and synthesized
- [ ] Zero ambiguities remain (verified by step 3 audit)
- [ ] All PBT properties documented with falsification strategies
- [ ] `openspec validate <id> --strict` returns zero issues
- [ ] User has explicitly approved all constraint decisions
-<!-- GUDASPEC:END -->
+- 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 -->