commands/gudaspec/implementation.md

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/<requirement-id>/plan.md

With Phase specified (for recovery):

/gudaspec:implementation gudaspec/plans/<requirement-id>/plan.md Phase 2

If no parameter:

请提供计划文档路径:
/gudaspec:implementation gudaspec/plans/<requirement-id>/plan.md

如需从特定Phase继续:
/gudaspec:implementation gudaspec/plans/<requirement-id>/plan.md Phase N

Step 1: Plan Verification

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 实施准备: <Requirement Title>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【计划概览】
需求ID: <requirement-id>
测试策略: Level <X>
计划状态: <approved>
批准时间: <timestamp>

【Phase结构】
┌─────────────────────────────────────────────┐
│ Phase 1: <name>                    [ ]      │
│ Phase 2: <name>                    [ ]      │
│ Phase 3: <name>                    [ ]      │
└─────────────────────────────────────────────┘

【起始点】
从 Phase <N> 开始执行

【前置检查】
• 代码库状态: <clean/有未提交变更>
• 分支: <current branch>
• 上次commit: <hash>

Pre-flight checks:

# 检查工作区状态
git status

# 检查是否在正确分支
git branch --show-current

Use AskUserQuestions:

question: "准备开始实施？"
options: [
  "开始 Phase <N>",
  "需要先处理未提交的变更",
  "需要切换分支",
  "查看Plan详情"
]

---

Step 2: Phase Execution Loop

For each Phase, execute the following sub-steps:

---

Step 2.1: Phase Overview

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 Phase <N>: <Phase Name>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【目标】
<Phase goal from plan>

【变更范围】
• <file1.py> — <change type>
• <file2.py> — <change type>

【测试范围】
• <test1> — <scenario>
• <test2> — <scenario>

【执行流程】
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_name>
• 场景: <scenario>
• 输入: <input>  
• 期望: <expected>

Test 2: <test_name>
• 场景: <edge case>
• 输入: <input>
• 期望: <expected>

【生成测试代码】

Claude writes test code based on test specifications:

# tests/test_<module>.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:

# 创建/更新测试文件
# ... (write to tests/test_<module>.py)

# 运行测试确认RED状态
pytest tests/test_<module>.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 生成的原型 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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模式） ✅ 失败计数逻辑正确

【改写后的代码】

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_<module>.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:

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:

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:

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 <N> 完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

【Phase总结】
┌─────────────────────────────────────────────┐
│ 文件变更:                                   │
│ • src/auth/service.py (修改)               │
│ • tests/test_auth.py (新增)                │
│                                             │
│ 测试:                                       │
│ • 新增: 4个                                 │
│ • 通过: 4个                                 │
│ • 回归: 0个                                 │
│                                             │
│ 审查:                                       │
│ • Codex: LGTM                              │
│ • Gemini: LGTM                             │
└─────────────────────────────────────────────┘

【进度更新】
┌─────────────────────────────────────────────┐
│ Phase 1: <name>                    [✅]     │
│ Phase 2: <name>                    [ ]      │
│ Phase 3: <name>                    [ ]      │
└─────────────────────────────────────────────┘

【建议操作】
1. 提交当前变更:
   git add -A && git commit -m "feat(auth): implement 2FA verification - Phase 1"

2. 如果需要继续Phase 2:
   输入 /clear 清空上下文
   然后输入 /gudaspec:implementation gudaspec/plans/<id>/plan.md Phase 2

3. 如果需要暂停:
   进度已保存，随时可以从Phase 2继续

Update plan.md with progress:

## Phase 1: 双因素认证核心逻辑 ✅
Completed: <timestamp>
Commit: <hash>

---

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: <requirement-id>

【完成摘要】
┌─────────────────────────────────────────────┐
│ Phase 1: 双因素认证核心逻辑        [✅]     │
│ Phase 2: API端点实现              [✅]     │
│ Phase 3: 前端集成                 [✅]     │
└─────────────────────────────────────────────┘

【变更统计】
• 文件变更: 12个
• 新增代码: ~450行
• 新增测试: 18个
• 测试覆盖: 87%

【提交历史】
• <hash1> feat(auth): implement 2FA verification - Phase 1
• <hash2> feat(auth): add 2FA API endpoints - Phase 2
• <hash3> feat(ui): integrate 2FA flow - Phase 3

【最终验证】
• 所有测试通过: ✅
• 类型检查通过: ✅
• Lint检查通过: ✅
• 双模型LGTM: ✅

【下一步】
1. 创建Pull Request
2. 请求代码审查
3. 合并到主分支

📋 归档:
相关文档将移动到 gudaspec/archive/<date>-<requirement-id>/

Archive documents:

mkdir -p gudaspec/archive/$(date +%Y-%m-%d)-<requirement-id>
mv gudaspec/research/<requirement-id> gudaspec/archive/$(date +%Y-%m-%d)-<requirement-id>/research
mv gudaspec/plans/<requirement-id> gudaspec/archive/$(date +%Y-%m-%d)-<requirement-id>/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/<id>/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/<requirement-id>/plan.md
• Test specifications: gudaspec/plans/<requirement-id>/tests/
• Backend implementation: Use mcp__codex__codex
• Frontend implementation: Use mcp__gemini__gemini
• Cross-review: Opposite model reviews implementation