Claude Code リファクタリング完全ガイド｜4フェーズワークフロー・Strangler Figパターン・worktree並列マイグレーション・影響範囲調査の実践手法

# Plan Modeに切り替えてから（Shift+Tab）
"Read src/components/UserDashboard.tsx and understand:
- What data does it fetch and from where?
- What child components does it render?
- Are there any performance issues?
Do NOT make any changes yet."

# 探索結果をもとに計画を立てる
"Based on your analysis, create a refactoring plan for UserDashboard.tsx.
The goal is to split it into smaller components under 200 lines each.
Include:
1. What components to extract and their boundaries
2. Props and data flow between components
3. Order of changes to minimize breaking changes
4. Tests to run at each step"

# Plan Modeを解除してから（Shift+Tab で通常モードへ）
"Implement the refactoring plan.
Start with extracting StatsSection as the first component.
After each component extraction, run npm test to verify nothing broke."

"Run the following checks and fix any failures:
1. npm test -- --coverage (all tests must pass)
2. npm run lint
3. npm run type-check
4. Start the dev server and check the dashboard renders correctly.
Do not mark as complete until all checks pass."

# 変更前に影響範囲を把握する
claude "Use subagents to investigate the impact of refactoring the AuthService class:

1. Find all files that import or instantiate AuthService
2. Find all tests that directly test AuthService
3. Check if AuthService is referenced in any documentation or config files

Report the complete impact scope with file paths before we start making changes."

# 複数箇所を並列に調査してから比較
claude "Use parallel subagents to investigate:
1. How the frontend API client handles authentication errors (src/api/)
2. How the backend generates error responses for auth failures (src/server/auth/)
3. What existing auth error tests cover (tests/)

Report where the implementations align and where they diverge."

// フェーズ1: ファサードを作成（旧実装に委譲）
// auth-facade.ts
export class AuthFacade {
  constructor(private legacy: LegacyAuthService) {}

  async login(email: string, password: string) {
    // まず旧実装に委譲
    return this.legacy.authenticate(email, password);
  }
}

// フェーズ2: 新実装を作成してファサードを切り替え
// auth-facade.ts（更新後）
export class AuthFacade {
  constructor(
    private legacy: LegacyAuthService,
    private newAuth: NewAuthService,
    private useNew = false,  // Feature Flagで制御
  ) {}

  async login(email: string, password: string) {
    if (this.useNew) {
      return this.newAuth.login(email, password);  // 新実装
    }
    return this.legacy.authenticate(email, password);  // 旧実装
  }
}

// フェーズ3: テスト通過後、旧実装を削除してファサードも廃止

# ステップ1: ファサード作成
claude "Create an AuthFacade class that wraps LegacyAuthService.
The facade should have the same interface as LegacyAuthService
but delegate all calls to it. This will be our Strangler Fig entry point."

# ステップ2: 既存の呼び出し箇所をファサードに切り替え
claude "Find all places that use LegacyAuthService directly and update them
to use AuthFacade instead. Run the tests after each file change."

# ステップ3: 1メソッドずつ新実装に切り替え
claude "Implement the login() method in NewAuthService.
Switch AuthFacade.login() to use NewAuthService.
Run the login-related tests and fix any failures before continuing."

# メインブランチからworktreeブランチを3つ作成
git worktree add ../project-ts-a -b migrate/ts-utils
git worktree add ../project-ts-b -b migrate/ts-components
git worktree add ../project-ts-c -b migrate/ts-services

# 各worktreeで別々のClaude Codeセッションを起動
# ターミナルを3つ開いて並列実行

# ターミナル1: utils/のマイグレーション
cd ../project-ts-a
claude "Migrate all JavaScript files in src/utils/ to TypeScript.
For each file:
1. Rename .js to .ts
2. Add type annotations to all functions and variables
3. Fix any TypeScript errors
4. Run tsc --noEmit to verify
Move to the next file only after each one is clean."

# ターミナル2: components/のマイグレーション
cd ../project-ts-b
claude "Migrate all JavaScript files in src/components/ to TypeScript.
[同様の指示]"

# ターミナル3: services/のマイグレーション
cd ../project-ts-c
claude "Migrate all JavaScript files in src/services/ to TypeScript.
[同様の指示]"

# 各ブランチの変換が完了したらメインブランチにマージ
git checkout main
git merge migrate/ts-utils
git merge migrate/ts-components
git merge migrate/ts-services

# worktreeの後片付け
git worktree remove ../project-ts-a
git worktree remove ../project-ts-b
git worktree remove ../project-ts-c

# Esc を2回押すか、/rewind コマンドでメニューを開く

# メニューで選択できる操作:
# 1. 会話のみを巻き戻す（コードの変更は保持）
# 2. コードの変更のみを巻き戻す（会話は保持）
# 3. 会話とコード変更の両方を巻き戻す

# コマンド:
# Esc × 2 または /rewind → チェックポイントメニューを表示

claude "Migrate files in src/utils/ one by one, in alphabetical order.
After each file migration:
1. Run: npx tsc --noEmit
2. Run: npm test -- src/utils/
3. Fix any errors before moving to the next file.
Do not proceed to the next file until all checks pass."

# 以下のシグナルが出たら /clear を検討する:
# - 同じ修正をしようとして2回以上失敗している
# - Claudeが以前と矛盾する実装方針を提案している
# - 「前回話した〇〇について」という言及が混乱している

/clear

# /clear後は具体的な状況を伝えて再開する
claude "Continuing refactoring of AuthService. So far:
- Completed: createUser(), deleteUser()
- Remaining: updateUser(), getUserById(), listUsers()
- Known issue: updateUser() has a dependency on EmailService that needs mocking

Continue with updateUser() next."

claude "src/components/UserDashboard.tsx is 600 lines long.
Refactor it by extracting:
- StatsGrid component (lines ~50-120)
- ActivityFeed component (lines ~130-280)
- DashboardSidebar component (lines ~300-450)

Rules:
- Keep all data fetching in UserDashboard and pass data as props
- Create TypeScript interfaces for all new props
- Do not change any CSS class names or behavior
- After each extraction, run npm test to verify"

claude "Find all usages of the deprecated fetchUser() API in src/.
List the files first, then replace them one by one with the new getUser() API.
The new signature is: getUser(id: string): Promise<User>
Run tests after each file change."

claude "Convert src/components/LoginForm.tsx from a class component to
a functional component with hooks.
- Replace this.state with useState
- Replace componentDidMount with useEffect
- Replace componentWillUnmount cleanup with useEffect cleanup
- Replace this.handleX methods with regular functions
Keep the same JSX structure and class names.
Run the existing tests after conversion."

claude "Add TypeScript type annotations to src/utils/formatters.js.
For each function:
1. Infer parameter types from how they are called in the codebase
2. Add explicit return types
3. Use strict types (avoid 'any')
4. Create new TypeScript interfaces if needed
Run npx tsc --noEmit after each function."