workflow-test-fix-cycle

ワークフローテスト・修正サイクル

エンドツーエンドのテスト・修正ワークフローパイプラインです。段階的なレイヤー（L0～L3）でテストセッションを生成し、AI によるコード検証とタスク生成を行うフェーズ 1、その後、適応型戦略エンジンを使用して、合格率が 95% 以上になるまで反復的な修正サイクルを実行するフェーズ 2 で構成されます。

アーキテクチャの概要

┌────────────────────────────────────────────────────────────────────────────┐
│  Workflow Test-Fix Cycle Orchestrator (SKILL.md)                            │
│  → Full pipeline: Test generation + Iterative execution                     │
│  → Phase dispatch: Read phase docs, execute, pass context                   │
└───────────────┬────────────────────────────────────────────────────────────┘
                │
   ┌────────────┴────────────────────────┐
   ↓                                     ↓
┌─────────────────────────┐   ┌─────────────────────────────┐
│ Phase 1: Test-Fix Gen   │   │ Phase 2: Test-Cycle Execute  │
│ phases/01-test-fix-gen  │   │ phases/02-test-cycle-execute │
│ 5 sub-phases:           │   │ 3 stages:                    │
│ ① Create Session        │   │ ① Discovery                  │
│ ② Gather Context        │   │ ② Main Loop (iterate)        │
│ ③ Test Analysis (Gemini)│   │ ③ Completion                 │
│ ④ Generate Tasks        │   │                              │
│ ⑤ Summary               │   │ Agents (via spawn_agent):    │
│                         │   │ @cli-planning-agent           │
│ Agents (via spawn_agent)│   │ @test-fix-agent               │
│ @test-context-search    │   │                              │
│ @context-search         │   │ Strategy: conservative →      │
│ @cli-execution          │   │ aggressive → surgical          │
│ @action-planning        │   │                              │
└────────┬────────────────┘   └────────────┬──────────────────┘
         ↓                                 ↓
   IMPL-001..002.json              Pass Rate >= 95%
   TEST_ANALYSIS_RESULTS.md        Auto-complete session

Task Pipeline:
┌──────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐
│  IMPL-001    │───→│  IMPL-001.3     │───→│  IMPL-001.5     │───→│  IMPL-002    │
│  Test Gen    │    │  Code Validate  │    │  Quality Gate   │    │  Test & Fix  │
│  L1-L3       │    │  L0 + AI Issues │    │  Coverage 80%+  │    │  Max 10 iter │
│@code-developer│   │ @test-fix-agent │    │ @test-fix-agent │    │@test-fix-agent│
└──────────────┘    └─────────────────┘    └─────────────────┘    └──────────────┘
                                                                        │
                                                              Fix Loop: │
                                                    ┌──────────────────┘
                                                    ↓
                                              ┌──────────┐
                                              │ @cli-plan│───→ IMPL-fix-N.json
                                              │  agent   │
                                              ├──────────┤
                                              │@test-fix │───→ Apply & re-test
                                              │  agent   │
                                              └──────────┘

主な設計原則

1. 2 フェーズパイプライン：生成（フェーズ 1）でセッションとタスクを作成し、実行（フェーズ 2）で反復的な修正サイクルを実施します
2. 純粋なオーケストレーター：フェーズのドキュメントへディスパッチし、出力を解析して、フェーズ間でコンテキストを受け渡します
3. フェーズ 1 の自動継続：フェーズ 1 内のサブフェーズは自律的に実行されます
4. サブエージェントのライフサイクル：spawn_agent → wait_agent → close_agent による明示的なライフサイクル管理
5. 段階的なテストレイヤー：L0（静的）→ L1（単体）→ L2（統合）→ L3（E2E）
6. AI コード問題の検出：AI 生成コードによくある問題に照らして検証します
7. インテリジェントな戦略エンジン：反復の状況に応じて、保守的 → 積極的 → 外科的な戦略を選択します
8. CLI フォールバックチェーン：分析の堅牢性を確保するため、Gemini → Qwen → Codex の順に使用します
9. 段階的なテスト：反復中は影響を受けるテストを実行し、最終検証では完全なテストスイートを実行します
10. ロールパスの読み込み：MANDATORY FIRST STEPS でパス参照を介してサブエージェントのロールを読み込みます

自動モード

フェーズ 1 でテストセッションとタスクを生成します。フェーズ 2 では、合格率が 95% 以上になるか、最大反復回数に達するまで、反復的な修正サイクルを実行します。**フェーズ 1 とフェーズ 2 の間では、実行に進む前に必ず停止して、ユーザーの確認を待ってください。**承認後、フェーズ 2 は自律的に実行されます。

サブエージェント API リファレンス

spawn_agent

タスクを割り当てて、新しいサブエージェントを作成します。

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Run: `ccw spec load --category "planning execution"`

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait_agent

サブエージェントから結果を取得します（結果を取得する唯一の方法です）。

const result = wait_agent({
  timeout_ms: 1800000  // 30 minutes
})

if (result.timed_out) {
  followup_task({ target: agentId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
  const status = wait_agent({ timeout_ms: 180000 })  // 3 min
  if (status.timed_out) {
    followup_task({ target: agentId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
    const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
    if (forced.timed_out) {
      close_agent({ target: agentId })
    }
  }
}

followup_task

アクティブなサブエージェントに新しい作業を割り当てます（明確化やフォローアップ用）。

followup_task({
  target: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

サブエージェントのリソースをクリーンアップします（取り消しできません）。

close_agent({ target: agentId })

使用方法

workflow-test-fix-cycle <input> [options]

# Input (Phase 1 - Test Generation)
source-session-id    WFS-* session ID (Session Mode - test validation for completed implementation)
feature description  Text description of what to test (Prompt Mode)
/path/to/file.md     Path to requirements file (Prompt Mode)

# Options (Phase 2 - Cycle Execution)
--max-iterations=N   Custom iteration limit (default: 10)

# Examples
workflow-test-fix-cycle WFS-user-auth-v2                                              # Session Mode
workflow-test-fix-cycle "Test the user authentication API endpoints in src/auth/api.ts" # Prompt Mode - text
workflow-test-fix-cycle ./docs/api-requirements.md                                     # Prompt Mode - file
workflow-test-fix-cycle "Test user registration" --max-iterations=15                    # With custom iterations

# Resume (Phase 2 only - session already created)
workflow-test-fix-cycle --resume-session="WFS-test-user-auth"                          # Resume interrupted session

品質ゲート：テスト合格率 95% 以上（重要度を考慮）または 100% 最大反復回数：10（デフォルト、変更可能） CLI ツール：Gemini → Qwen → Codex（フォールバックチェーン）

テスト戦略の概要

段階的なテストレイヤー（L0～L3）：

レイヤー	名称	対象
L0	静的解析	コンパイル、インポート、型、AI コードの問題
L1	単体テスト	関数／クラスの動作（正常系／異常系／境界ケース）
L2	統合テスト	コンポーネント間の連携、API コントラクト、障害モード
L3	E2E テスト	ユーザージャーニー、重要な経路（任意）

主な機能：

• AI コード問題の検出 - AI 生成コードによくある問題（実在しないインポート、プレースホルダーコード、モックの混入など）に照らして検証します
• プロジェクトタイプの検出 - 適切なテストテンプレート（React、Node API、CLI、ライブラリなど）を適用します
• 品質ゲート - IMPL-001.3（コード検証）と IMPL-001.5（テスト品質）によって高い基準を確保します

詳細な仕様：L0～L3 の要件と品質しきい値の全容については、test-task-generate ワークフローツールを参照してください。

実行フロー

Input → Detect Mode (session | prompt | resume)
  │
  ├─ resume mode → Skip to Phase 2
  │
  └─ session/prompt mode → Phase 1
       │
Phase 1: Test-Fix Generation (phases/01-test-fix-gen.md)
  ├─ Sub-phase 1.1: Create Test Session → testSessionId
  ├─ Sub-phase 1.2: Gather Test Context (spawn_agent) → contextPath
  ├─ Sub-phase 1.3: Test Generation Analysis (spawn_agent → Gemini) → TEST_ANALYSIS_RESULTS.md
  ├─ Sub-phase 1.4: Generate Test Tasks (spawn_agent) → IMPL-*.json, IMPL_PLAN.md, TODO_LIST.md
  └─ Sub-phase 1.5: Phase 1 Summary
       │
  ⛔ MANDATORY CONFIRMATION GATE
  │   Present plan summary → request_user_input → User approves/cancels
  │   NEVER auto-proceed to Phase 2
       │
Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
  ├─ Discovery: Load session, tasks, iteration state
  ├─ Main Loop (for each task):
  │   ├─ Execute → Test → Calculate pass_rate
  │   ├─ 100% → SUCCESS: Next task
  │   ├─ 95-99% + low criticality → PARTIAL SUCCESS: Approve
  │   └─ <95% → Fix Loop:
  │       ├─ Select strategy: conservative/aggressive/surgical
  │       ├─ spawn_agent(@cli-planning-agent) → IMPL-fix-N.json
  │       ├─ spawn_agent(@test-fix-agent) → Apply fix & re-test
  │       └─ Re-test → Back to decision
  └─ Completion: Final validation → Summary → Sync session state → Auto-complete session

コアルール

1. 直ちに開始：最初のアクションとして functions.update_plan を初期化します
2. 事前分析は禁止：Phase 1 の前にファイルを読まないでください
3. すべての出力を解析：各フェーズ／サブフェーズからデータを抽出し、次の処理に渡します
4. フェーズ内で自動継続：フェーズ内のサブフェーズは自動的に実行されます。Phase 2 の反復も、開始後は自動的に実行されます
5. フェーズの読み込み：フェーズのドキュメントを必要に応じて読み込みます（phases/01-*.md、phases/02-*.md）
6. タスクのアタッチモデル：サブタスクを ATTACH → 実行 → COLLAPSE します
7. 必須の確認ゲート：Phase 1 の完了後、必ず停止して生成した計画をユーザーに提示してください。Phase 2 を開始する前に、request_user_input によるユーザーの明示的な承認を待ちます。Phase 1 から Phase 2 へ自動的に進んではいけません
8. Phase 2 の継続実行：ユーザーが承認したら、合格率が 95% 以上になるか、最大反復回数に達するまで Phase 2 を継続して実行します
9. 明示的なライフサイクル管理：wait_agent の完了後は、リソースを解放するため、必ず close_agent を実行してください

フェーズの実行

Phase 1：テスト修正の生成

読み込み：phases/01-test-fix-gen.md

テストセッションを作成し、タスク JSON を生成する 5 つのサブフェーズ：

1. テストセッションの作成 → testSessionId
2. テストコンテキストの収集（spawn_agent → wait_agent → close_agent）→ contextPath
3. テスト生成の分析（spawn_agent → wait_agent → close_agent）→ TEST_ANALYSIS_RESULTS.md
4. テストタスクの生成（spawn_agent → wait_agent → close_agent）→ IMPL-001.json、IMPL-001.3.json、IMPL-001.5.json、IMPL-002.json、IMPL_PLAN.md、TODO_LIST.md
5. Phase 1 の概要 → ⛔ 必須：計画を提示し、Phase 2 の前にユーザーの確認を待ちます

使用するエージェント（spawn_agent 経由）：

• test_context_search_agent（agent_type: test_context_search_agent）- コンテキストの収集（セッションモード）
• context_search_agent（agent_type: context_search_agent）- コンテキストの収集（プロンプトモード）
• cli_execution_agent（agent_type: cli_execution_agent）- Gemini によるテスト分析
• action_planning_agent（agent_type: action_planning_agent）- タスク JSON の生成

Phase 2：テストサイクルの実行

読み込み：phases/02-test-cycle-execute.md

適応型戦略による 3 段階の反復実行：

1. 検出 - セッション、タスク、反復状態を読み込みます
2. メインループ - タスクを実行 → テスト → 失敗を分析 → 修正 → 再テスト
3. 完了 - 最終検証 → 概要 → セッションを自動完了

使用するエージェント（spawn_agent 経由）：

• cli_planning_agent（agent_type: cli_planning_agent）- 失敗の分析、根本原因の抽出、修正タスクの生成
• test_fix_agent（agent_type: test_fix_agent）- テストの実行、コードの修正、重要度の割り当て

戦略エンジン：保守的（反復 1～2）→ 積極的（合格率 >80%）→ 外科的（リグレッション）

出力成果物

ディレクトリ構造

{projectRoot}/.workflow/active/WFS-test-[session]/
├── workflow-session.json              # Session metadata
├── IMPL_PLAN.md                       # Test generation and execution strategy
├── TODO_LIST.md                       # Task checklist
├── .task/
│   ├── IMPL-001.json                  # Test understanding & generation
│   ├── IMPL-001.3-validation.json     # Code validation gate
│   ├── IMPL-001.5-review.json         # Test quality gate
│   ├── IMPL-002.json                  # Test execution & fix cycle
│   └── IMPL-fix-{N}.json             # Generated fix tasks (Phase 2)
├── .process/
│   ├── [test-]context-package.json    # Context and coverage analysis
│   ├── TEST_ANALYSIS_RESULTS.md       # Test requirements and strategy (L0-L3)
│   ├── iteration-state.json           # Current iteration + strategy + stuck tests
│   ├── test-results.json              # Latest results (pass_rate, criticality)
│   ├── test-output.log                # Full test output
│   ├── fix-history.json               # All fix attempts
│   ├── iteration-{N}-analysis.md      # CLI analysis report
│   └── iteration-{N}-cli-output.txt
└── .summaries/iteration-summaries/

進捗の追跡

初期化（必須）

// Initialize progress tracking after input parsing
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "pending" }
])

フェーズの移行

// After Phase 1 completes (before mandatory confirmation gate)
functions.update_plan([
  { id: "phase-1", status: "completed" },
  { id: "phase-2", status: "in_progress" }
])

// After Phase 2 completes (pass rate >= 95% or max iterations)
functions.update_plan([{ id: "phase-2", status: "completed" }])

再開モード

// When --resume-session skips Phase 1
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "completed" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "in_progress" }
])

エラー処理

フェーズ	シナリオ	アクション
1.1	ソースセッションが見つからない（セッションモード）	セッション ID とともにエラーを返します
1.1	完了済みの IMPL タスクがない（セッションモード）	エラーを返します。ソースは未完了です
1.2	コンテキストの収集に失敗	エラーを返し、ソース成果物を確認します
1.2	エージェントのタイムアウト	タイムアウトを延長して再試行し、close_agent を実行してからエラーを返します
1.3	Gemini による分析に失敗	エラーを返し、コンテキストパッケージを確認します
1.4	タスクの生成に失敗	1 回再試行してから、エラーを返します
2	テストの実行エラー	ログに記録し、エラーのコンテキストを添えて再試行します
2	CLI 分析の失敗	フォールバック：Gemini → Qwen → Codex → 手動
2	エージェントの実行エラー	状態を保存し、close_agent を実行してから、簡略化したコンテキストで再試行します
2	最大反復回数に到達	失敗レポートを生成し、ブロック済みとしてマークします
2	リグレッションを検出	直近の修正をロールバックし、外科的戦略に切り替えます
2	停滞したテストを検出	別の戦略で続行し、失敗レポートに記録します

ライフサイクルのエラー処理：

try {
  const agentId = spawn_agent({ message: "..." });
  const result = wait_agent({ timeout_ms: 1800000 });  // 30 minutes
  // ... process result ...
  close_agent({ target: agentId });
} catch (error) {
  if (agentId) close_agent({ target: agentId });
  throw error;
}

コーディネーターチェックリスト

フェーズ 1（生成）：

• 入力タイプを検出します（セッション ID／説明／ファイルパス／再開）
• 2 つのトップレベルフェーズで functions.update_plan を初期化します
• 詳細なサブフェーズの実行手順については phases/01-test-fix-gen.md を読み込みます
• spawn_agent → wait_agent → close_agent のライフサイクルで 5 つのサブフェーズを実行します
• フェーズ 1 のすべての出力（4 件以上のタスク JSON、IMPL_PLAN.md、TODO_LIST.md）を検証します
• 各サブフェーズの完了後、すべてのエージェントが終了していることを確認します
• ⛔ 必須：計画の概要を提示し、確認のため request_user_input を求めます
  • 表示する情報：セッション ID、タスク数、テストレイヤー、品質ゲート
  • 選択肢：「実行に進む」／「計画を確認」／「キャンセル」
  • 「キャンセル」の場合 → 戻り、フェーズ 2 を開始しないでください
  • 「計画を確認」の場合 → IMPL_PLAN.md を表示してから戻ります
  • ユーザーが「実行に進む」を選択した場合にのみ、フェーズ 2 に進みます

フェーズ 2（実行）：

• 詳細な実行ロジックについては phases/02-test-cycle-execute.md を読み込みます
• セッション状態とタスクキューを読み込みます
• spawn_agent → wait_agent → close_agent で反復的なテスト・修正サイクルを実行します
• functions.update_plan で反復回数を追跡します
• 成功時（合格率 >= 95%）にセッションを自動完了します
• 各反復の後、すべてのエージェントが終了していることを確認します

再開モード：

• --resume-session が指定されている場合、フェーズ 1 をスキップします
• 既存のセッションを直接フェーズ 2 に読み込みます

関連スキル

前提スキル：

• workflow-plan または workflow-execute - 実装を完了します（セッションモード）
• プロンプトモードでは不要です

フェーズ 1 のエージェント（phases/01-test-fix-gen.md が spawn_agent を介して使用）：

• test_context_search_agent（agent_type: test_context_search_agent）- テストカバレッジの分析（セッションモード）
• context_search_agent（agent_type: context_search_agent）- コードベースの分析（プロンプトモード）
• cli_execution_agent（agent_type: cli_execution_agent）- Gemini を使用したテスト要件の確認
• action_planning_agent（agent_type: action_planning_agent）- タスク JSON の生成

フェーズ 2 のエージェント（phases/02-test-cycle-execute.md が spawn_agent を介して使用）：

• cli_planning_agent（agent_type: cli_planning_agent）- CLI の分析、根本原因の抽出、タスクの生成
• test_fix_agent（agent_type: test_fix_agent）- テストの実行、コードの修正、重大度の割り当て

フォローアップ：

• セッションの同期：$session-sync -y "Test-fix cycle complete: {pass_rate}% pass rate"
• 成功時にセッションを自動完了します
• フォローアップ作業のためにイシューを作成します（完了後の拡張）