refactor

/refactor - リファクタリングワークフロー

レビューゲートを設けた安全なリファクタリングです。

使用する場面

• 「Xをリファクタリングして」
• 「このコードを整理して」
• 「これをモジュールに切り出して」
• 「Yのアーキテクチャを改善して」
• 大規模なコードの再構築
• 技術的負債の削減

ワークフローの概要

┌──────────┐    ┌────────────┐    ┌──────────┐    ┌──────────┐    ┌───────────┐
│ phoenix  │───▶│   plan-    │───▶│  kraken  │───▶│plan-reviewer│───▶│ arbiter  │
│          │    │   agent    │    │          │    │          │    │           │
└──────────┘    └────────────┘    └──────────┘    └──────────┘    └───────────┘
  Analyze         Plan             Implement       Review          Verify
  current         changes          refactor        changes         tests pass

エージェントの順序

#	エージェント	役割	出力
1	phoenix	現在のコードを分析し、改善箇所を特定します	分析レポート
2	plan-agent	安全なリファクタリング計画を作成します	ステップごとの計画
3	kraken	リファクタリングを実装します	コードの変更
4	plan-reviewer	変更の正しさをレビューします	レビューレポート
5	arbiter	すべてのテストが引き続き成功することを確認します	テストレポート

リファクタリングの原則

1. テストを優先：リファクタリングの前に、十分なテストカバレッジを確保します
2. 小さなステップで進める：各変更を個別に検証できるようにします
3. 動作を維持する：リファクタリング中に機能を変更しません
4. レビューしやすくする：変更を簡単にレビューできるようにします

実行

フェーズ 1：分析

Task(
  subagent_type="phoenix",
  prompt="""
  Analyze for refactoring: [TARGET_CODE]

  Identify:
  - Current pain points
  - Code smells
  - Improvement opportunities
  - Risk areas
  - Test coverage gaps
  """
)

フェーズ 2：計画

Task(
  subagent_type="plan-agent",
  prompt="""
  Plan refactoring: [TARGET_CODE]

  Analysis: [from phoenix]

  Create:
  - Step-by-step refactoring plan
  - Each step should be:
    - Small and focused
    - Independently testable
    - Reversible
  - Identify files affected
  - Risk mitigation strategy
  """
)

フェーズ 3：実装

Task(
  subagent_type="kraken",
  prompt="""
  Implement refactoring: [TARGET_CODE]

  Plan: [from plan-agent]

  Requirements:
  - Follow plan exactly
  - Run tests after each step
  - Stop if tests fail
  - NO behavior changes
  """
)

フェーズ 4：レビュー

Task(
  subagent_type="plan-reviewer",
  prompt="""
  Review refactoring: [TARGET_CODE]

  Changes: [git diff from kraken]

  Check:
  - Behavior preserved
  - No unintended changes
  - Code quality improved
  - Patterns consistent
  """
)

フェーズ 5：検証

Task(
  subagent_type="arbiter",
  prompt="""
  Validate refactoring: [TARGET_CODE]

  - Run full test suite
  - Verify no regressions
  - Check type errors
  - Run linting
  """
)

リファクタリングの種類

モジュールの切り出し

phoenix → plan-agent → kraken → plan-reviewer → arbiter

名前変更／再構成

phoenix → kraken → arbiter  (simpler, skip detailed planning)

アーキテクチャの変更

phoenix → plan-agent → [kraken → plan-reviewer] × N phases → arbiter

例

User: /refactor Extract the validation logic into a separate module

Claude: Starting /refactor workflow...

Phase 1: Analyzing current structure...
[Spawns phoenix]
Found: Validation logic spread across 4 files
- form.ts (lines 45-120)
- api.ts (lines 200-280)
- user.ts (lines 15-45)
- order.ts (lines 88-130)

Phase 2: Planning extraction...
[Spawns plan-agent]
Plan:
1. Create src/validation/index.ts
2. Extract common validators
3. Update imports one file at a time
4. Run tests after each change

Phase 3: Implementing...
[Spawns kraken]
Completed all 4 steps, tests green after each

Phase 4: Reviewing changes...
[Spawns plan-reviewer]
✅ All behavior preserved
✅ DRY improved (removed 45 duplicate lines)
✅ New structure consistent

Phase 5: Final validation...
[Spawns arbiter]
✅ 312 tests passing, 0 regressions

Refactoring complete!

安全性フラグ

• --dry-run：計画のみを行い、実装しません
• --step-by-step：各変更の後に一時停止し、承認を求めます
• --coverage-check：続行前に80%を超えるカバレッジを必須とします