--- name: GudaSpec: Implementation description: Execute approved plan phase by phase with TDD cycle and multi-model collaboration. category: GudaSpec tags: [gudaspec, implementation, tdd, multi-model, codex, gemini] argument-hint: [plan.md path] [optional: Phase N] --- ## Purpose 基于已批准的计划,逐Phase执行TDD循环(Red-Green-Refactor),利用多模型协作实现并审查代码。 ## Core Principles 1. **Plan is Law** — 严格按照计划规格实现,不擅自扩展范围 2. **Test First** — Level 1-2时先写测试,确认RED状态后再实现 3. **AI Assists, Human Decides** — AI生成原型,人工确认关键决策 4. **Dual Model LGTM** — 重要代码需Codex+Gemini双重审查 5. **Phase Isolation** — 每Phase完成后/clear,保持上下文干净 6. **Fail Fast, Recover Easy** — 问题早发现,支持从任意Phase恢复 ## Guardrails - **MUST** read plan.md completely before starting. - **MUST** follow TDD cycle if test_level >= 1. - **MUST** pause for human confirmation after each Phase. - **MUST** stop and report if plan doesn't match reality. - **NEVER** apply AI-generated code directly without review. - **NEVER** skip tests to "save time". - **NEVER** expand scope beyond what's specified in plan. --- ## Steps ### Step 0: Load Plan and Determine Starting Point **With full path:** ``` /gudaspec:implementation gudaspec/plans//plan.md ``` **With Phase specified (for recovery):** ``` /gudaspec:implementation gudaspec/plans//plan.md Phase 2 ``` **If no parameter:** ``` 请提供计划文档路径: /gudaspec:implementation gudaspec/plans//plan.md 如需从特定Phase继续: /gudaspec:implementation gudaspec/plans//plan.md Phase N ``` ### Step 1: Plan Verification ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 实施准备: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【计划概览】 需求ID: 测试策略: Level 计划状态: 批准时间: 【Phase结构】 ┌─────────────────────────────────────────────┐ │ Phase 1: [ ] │ │ Phase 2: [ ] │ │ Phase 3: [ ] │ └─────────────────────────────────────────────┘ 【起始点】 从 Phase 开始执行 【前置检查】 • 代码库状态: • 分支: • 上次commit: ``` **Pre-flight checks:** ```bash # 检查工作区状态 git status # 检查是否在正确分支 git branch --show-current ``` Use `AskUserQuestions`: ``` question: "准备开始实施?" options: [ "开始 Phase ", "需要先处理未提交的变更", "需要切换分支", "查看Plan详情" ] ``` --- ### Step 2: Phase Execution Loop **For each Phase, execute the following sub-steps:** --- #### Step 2.1: Phase Overview ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚀 Phase : ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【目标】 【变更范围】 • 【测试范围】 • 【执行流程】 1. 编写测试 (RED) 2. 实现代码 (GREEN) 3. 审查优化 (REFACTOR) 4. 验证确认 (VERIFY) 开始执行... ``` --- #### Step 2.2: RED — Write Tests First (Level 1-2) **Skip this step if test_level == 0** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔴 RED: 编写测试 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【测试规格】(来自Plan) Test 1: • 场景: • 输入: • 期望: Test 2: • 场景: • 输入: • 期望: 【生成测试代码】 ``` **Claude writes test code based on test specifications:** ```python # tests/test_.py import pytest from src.auth.service import AuthService from src.auth.exceptions import UserNotFoundError, TwoFactorNotEnabledError class TestVerify2FA: """Phase 1: 双因素认证验证测试""" @pytest.fixture def auth_service(self): return AuthService() @pytest.fixture def user_with_2fa(self, db_session): """创建已启用2FA的测试用户""" user = create_test_user(email="test@example.com") user.enable_2fa(secret="TESTSECRET123456") db_session.add(user) db_session.commit() return user def test_valid_code_should_pass(self, auth_service, user_with_2fa): """ 场景: 用户输入正确的TOTP验证码 期望: 返回True """ # Arrange valid_code = generate_totp_code(user_with_2fa.totp_secret) # Act result = auth_service.verify_2fa(user_with_2fa.id, valid_code) # Assert assert result is True def test_invalid_code_should_fail(self, auth_service, user_with_2fa): """ 场景: 用户输入错误的验证码 期望: 返回False """ # Arrange invalid_code = "000000" # Act result = auth_service.verify_2fa(user_with_2fa.id, invalid_code) # Assert assert result is False def test_user_not_found_should_raise(self, auth_service): """ 场景: 用户不存在 期望: 抛出UserNotFoundError """ # Arrange non_existent_id = uuid4() # Act & Assert with pytest.raises(UserNotFoundError): auth_service.verify_2fa(non_existent_id, "123456") def test_2fa_not_enabled_should_raise(self, auth_service, user_without_2fa): """ 场景: 用户未启用2FA 期望: 抛出TwoFactorNotEnabledError """ # Act & Assert with pytest.raises(TwoFactorNotEnabledError): auth_service.verify_2fa(user_without_2fa.id, "123456") ``` **Write tests to file and run:** ```bash # 创建/更新测试文件 # ... (write to tests/test_.py) # 运行测试确认RED状态 pytest tests/test_.py -v ``` **Expected output:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔴 RED状态确认 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 测试结果: • test_valid_code_should_pass FAILED ❌ • test_invalid_code_should_fail FAILED ❌ • test_user_not_found_should_raise FAILED ❌ • test_2fa_not_enabled_should_raise FAILED ❌ 状态: 4 failed — RED确认 ✓ 原因: verify_2fa() 方法尚未实现 继续进入GREEN阶段... ``` **If tests unexpectedly pass (implementation already exists):** ``` ⚠️ 警告: 测试意外通过 这可能意味着: 1. 功能已经存在(计划过期) 2. 测试写得不正确 3. 测试在错误的条件下通过 请确认如何处理? ``` --- #### Step 2.3: GREEN — Implement Code ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🟢 GREEN: 实现代码 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【实现规格】(来自Plan) 文件: src/auth/service.py 接口: verify_2fa(user_id: UUID, code: str) -> bool 行为规格: • 用户不存在 → UserNotFoundError • 未启用2FA → TwoFactorNotEnabledError • 验证码正确 → True • 验证码错误 → False 参考: authenticate() 方法模式 ``` **Determine implementation approach based on task type:** **For Backend Logic — Use Codex:** ``` 【调用 Codex 生成实现原型】 ``` Invoke `mcp__codex__codex`: ``` Based on this specification, implement the function: File: src/auth/service.py Class: AuthService Interface: ```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 """ ``` Behavior: - User not found → raise UserNotFoundError - 2FA not enabled → raise TwoFactorNotEnabledError - Valid code → return True, reset failed attempts - Invalid code → return False, increment failed attempts - Validation window: ±1 period (30 seconds tolerance) Reference pattern: authenticate() method at line 78-95 Existing service: TotpService.verify() at src/auth/totp.py:23 Constraints: - Use existing TotpService, do not reimplement TOTP logic - Follow error handling pattern from authenticate() - Store failed attempts in user.failed_2fa_attempts Return ONLY the implementation code, no explanations. ``` **For Frontend UI — Use Gemini:** Invoke `mcp__gemini__gemini`: ``` Based on this specification, implement the component: ... ``` **Receive and Review AI Output:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📝 Codex 生成的原型 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ```python async def verify_2fa(self, user_id: UUID, code: str) -> bool: # Get user user = await self.user_repository.get_by_id(user_id) if not user: raise UserNotFoundError(f"User {user_id} not found") # Check if 2FA is enabled if not user.is_2fa_enabled: raise TwoFactorNotEnabledError( f"2FA is not enabled for user {user_id}" ) # Verify TOTP code totp_service = TotpService() is_valid = totp_service.verify( secret=user.totp_secret, code=code, valid_window=1 # ±30 seconds ) # Update attempt counters if is_valid: await self._reset_failed_2fa_attempts(user_id) return True else: await self._increment_failed_2fa_attempts(user_id) return False ``` ``` **Claude Reviews and Refines:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 Claude 审查与改写 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【审查结果】 ✅ 接口签名正确 ✅ 异常处理符合规格 ⚠️ TotpService应复用实例,非每次创建 ⚠️ 缺少日志记录(参考authenticate模式) ✅ 失败计数逻辑正确 【改写后的代码】 ```python async def verify_2fa(self, user_id: UUID, code: str) -> bool: """验证用户的双因素认证码""" logger.debug(f"Verifying 2FA for user {user_id}") # Get user user = await self.user_repository.get_by_id(user_id) if not user: logger.warning(f"2FA verification failed: user {user_id} not found") raise UserNotFoundError(f"User {user_id} not found") # Check if 2FA is enabled if not user.is_2fa_enabled: logger.warning(f"2FA verification failed: not enabled for {user_id}") raise TwoFactorNotEnabledError( f"2FA is not enabled for user {user_id}" ) # Verify TOTP code using existing service is_valid = self.totp_service.verify( secret=user.totp_secret, code=code, valid_window=1 ) # Update attempt counters if is_valid: logger.info(f"2FA verification successful for user {user_id}") await self._reset_failed_2fa_attempts(user_id) return True else: logger.warning(f"2FA verification failed: invalid code for {user_id}") await self._increment_failed_2fa_attempts(user_id) return False ``` 【变更说明】 1. 添加日志记录(符合authenticate模式) 2. 复用self.totp_service而非创建新实例 3. 保持其他逻辑不变 ``` **Apply code and run tests:** ```bash # 应用代码变更 # ... (write to src/auth/service.py) # 运行测试 pytest tests/test_.py -v ``` **Check GREEN status:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🟢 GREEN状态检查 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 测试结果: • test_valid_code_should_pass PASSED ✅ • test_invalid_code_should_fail PASSED ✅ • test_user_not_found_should_raise PASSED ✅ • test_2fa_not_enabled_should_raise PASSED ✅ 状态: 4 passed — GREEN确认 ✓ 继续进入REFACTOR阶段... ``` **If tests fail:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ❌ 测试失败 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 失败测试: • test_valid_code_should_pass — AssertionError: expected True, got None 【请求 Codex 分析修复】 ``` Invoke `mcp__codex__codex`: ``` This test is failing: Test: ```python def test_valid_code_should_pass(...): ... ``` Error: ``` AssertionError: expected True, got None ``` Implementation: ```python async def verify_2fa(...): ... ``` Analyze the issue and provide a fix. ``` **Loop until GREEN.** --- #### Step 2.4: REFACTOR — Multi-Model Review ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔄 REFACTOR: 多模型审查 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 测试已通过,现在进行代码质量审查。 ``` **Cross-Model Review:** **Gemini reviews backend code (different perspective):** Invoke `mcp__gemini__gemini`: ``` Review this implementation for code quality issues: ```python async def verify_2fa(self, user_id: UUID, code: str) -> bool: ... ``` Check for: 1. Error handling completeness 2. Edge cases not covered 3. Security concerns 4. Code readability 5. Naming clarity Format: [ISSUE] → [SUGGESTION] If no issues: [LGTM] ``` **Codex reviews for logic issues:** Invoke `mcp__codex__codex`: ``` Review this implementation for logic issues: ```python async def verify_2fa(self, user_id: UUID, code: str) -> bool: ... ``` Check for: 1. Race conditions 2. Missing validation 3. Performance concerns 4. Consistency with codebase patterns Format: [ISSUE] → [SUGGESTION] If no issues: [LGTM] ``` **Review Results:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 审查结果 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【Gemini 审查】 [LGTM] 代码清晰,错误处理完整,日志记录规范。 【Codex 审查】 [ISSUE] 未检查code参数格式(应为6位数字) → [SUGGESTION] 添加输入验证: if not code or not code.isdigit() or len(code) != 6: raise InvalidCodeFormatError("Code must be 6 digits") 【审查总结】 • Gemini: LGTM ✅ • Codex: 1个建议 是否采纳Codex的建议? ``` Use `AskUserQuestions`: ``` question: "Codex建议添加code格式验证,是否采纳?" options: [ "采纳,添加验证", "跳过,TotpService已有验证", "采纳,但调整实现方式" ] ``` **If adopting suggestions:** 1. Apply the fix 2. Run tests again 3. Confirm still GREEN ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ REFACTOR 完成 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 代码审查: 双模型LGTM ✅ 测试状态: 4 passed ✅ 代码质量: 已优化 继续进入VERIFY阶段... ``` --- #### Step 2.5: VERIFY — Automated + Manual Verification ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ VERIFY: 验证阶段 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【自动化验证】 ``` **Run all automated checks from plan:** ```bash # 单元测试 pytest tests/test_auth.py -v # 期望: All passed # 类型检查 mypy src/auth/service.py # 期望: Success # Lint检查 ruff check src/auth/ # 期望: No issues # 完整测试套件(检查回归) pytest tests/ -v --tb=short # 期望: No regressions ``` ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 自动化验证结果 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 检查项 | 状态 | 详情 | |--------|------|------| | 单元测试 | ✅ PASS | 4/4 passed | | 类型检查 | ✅ PASS | No errors | | Lint检查 | ✅ PASS | No issues | | 回归测试 | ✅ PASS | 26/26 passed | 自动化验证: 全部通过 ✅ ``` **Manual Verification Checklist:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 👤 手动验证清单 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 请手动验证以下项目: [ ] 1. 启动应用,使用测试账户登录 [ ] 2. 启用2FA,扫描二维码 [ ] 3. 输入正确验证码,确认登录成功 [ ] 4. 输入错误验证码,确认被拒绝 [ ] 5. 连续输入5次错误,确认账户锁定 [ ] 6. 检查日志输出格式正确 完成后请确认。 ``` Use `AskUserQuestions`: ``` question: "手动验证结果?" options: [ "全部通过,继续下一Phase", "发现问题,需要修复", "需要跳过某些验证项(请说明原因)" ] ``` --- #### Step 2.6: Phase Completion & Pause ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Phase 完成 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【Phase总结】 ┌─────────────────────────────────────────────┐ │ 文件变更: │ │ • src/auth/service.py (修改) │ │ • tests/test_auth.py (新增) │ │ │ │ 测试: │ │ • 新增: 4个 │ │ • 通过: 4个 │ │ • 回归: 0个 │ │ │ │ 审查: │ │ • Codex: LGTM │ │ • Gemini: LGTM │ └─────────────────────────────────────────────┘ 【进度更新】 ┌─────────────────────────────────────────────┐ │ Phase 1: [✅] │ │ Phase 2: [ ] │ │ Phase 3: [ ] │ └─────────────────────────────────────────────┘ 【建议操作】 1. 提交当前变更: git add -A && git commit -m "feat(auth): implement 2FA verification - Phase 1" 2. 如果需要继续Phase 2: 输入 /clear 清空上下文 然后输入 /gudaspec:implementation gudaspec/plans//plan.md Phase 2 3. 如果需要暂停: 进度已保存,随时可以从Phase 2继续 ``` **Update plan.md with progress:** ```markdown ## Phase 1: 双因素认证核心逻辑 ✅ Completed: Commit: ``` --- ### Step 3: Handle Plan-Reality Mismatch **When implementation discovers plan doesn't match reality:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ 计划与实际不匹配 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【发现】 计划中: 修改 src/auth/service.py 的 AuthService 类 实际上: AuthService 已被重构为 AuthenticationService 【影响】 • Phase 1 的变更目标需要调整 • 接口位置变化,但功能规格不变 【选项】 ``` Use `AskUserQuestions`: ``` question: "如何处理这个不匹配?" options: [ "适配:按新结构实现相同功能", "暂停:返回Plan阶段更新计划", "询问:需要更多信息来决定" ] ``` --- ### Step 4: Final Completion **After all Phases complete:** ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎉 实施完成 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 需求ID: 【完成摘要】 ┌─────────────────────────────────────────────┐ │ Phase 1: 双因素认证核心逻辑 [✅] │ │ Phase 2: API端点实现 [✅] │ │ Phase 3: 前端集成 [✅] │ └─────────────────────────────────────────────┘ 【变更统计】 • 文件变更: 12个 • 新增代码: ~450行 • 新增测试: 18个 • 测试覆盖: 87% 【提交历史】 • feat(auth): implement 2FA verification - Phase 1 • feat(auth): add 2FA API endpoints - Phase 2 • feat(ui): integrate 2FA flow - Phase 3 【最终验证】 • 所有测试通过: ✅ • 类型检查通过: ✅ • Lint检查通过: ✅ • 双模型LGTM: ✅ 【下一步】 1. 创建Pull Request 2. 请求代码审查 3. 合并到主分支 📋 归档: 相关文档将移动到 gudaspec/archive/-/ ``` **Archive documents:** ```bash mkdir -p gudaspec/archive/$(date +%Y-%m-%d)- mv gudaspec/research/ gudaspec/archive/$(date +%Y-%m-%d)-/research mv gudaspec/plans/ gudaspec/archive/$(date +%Y-%m-%d)-/plan ``` --- ## Level 0: Standard Verification Mode **When test_level == 0, skip TDD cycle:** ``` Phase执行流程 (Level 0): 1. READ SPEC — 读取变更规格 2. IMPLEMENT — Claude直接实现(可借助Codex/Gemini) 3. MULTI-MODEL REVIEW — 双模型审查 4. VERIFY — 运行现有测试 + 手动验证 5. PAUSE — 等待人工确认 ``` --- ## Error Recovery ### Recovering from Failed Phase ``` /gudaspec:implementation gudaspec/plans//plan.md Phase 2 ``` The command will: 1. Read plan and detect Phase 1 is marked complete 2. Start from Phase 2 3. Verify Phase 1 changes are still intact ### Recovering from Test Failures ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ❌ 无法达到GREEN状态 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 经过3次尝试,测试仍然失败: • test_valid_code_should_pass — TypeError: ... 【选项】 1. 继续尝试(提供更多上下文给Codex) 2. 暂停并请求帮助 3. 跳过此测试(需说明原因) 4. 返回Plan阶段修改规格 ``` --- ## Exit Criteria - [ ] All Phases completed and marked in plan.md - [ ] All tests passing (TDD Level 1-2) or verification passing (Level 0) - [ ] Dual-model LGTM obtained for each Phase - [ ] All manual verification items confirmed - [ ] Changes committed with proper messages - [ ] Documents archived --- ## Reference - Plan document: `gudaspec/plans//plan.md` - Test specifications: `gudaspec/plans//tests/` - Backend implementation: Use `mcp__codex__codex` - Frontend implementation: Use `mcp__gemini__gemini` - Cross-review: Opposite model reviews implementation