09-02. ケース 2: 反復的なリファクタリングの自動化

シチュエーション

コードベース内の 同じパターン(古い API 呼び出し → 新しいもの、命名規約変更、型注釈追加など)を 50 ファイル超 に渡って適用したい。

例: - from old_module import X を from new_module import X に - すべてのテスト関数に @pytest.mark.unit デコレータを追加 - print(...) を logger.info(...) に置換(ただし context 依存で残すべき箇所もある)

Before (Claude Code を使わない場合)

• sed/awk で機械置換 → エッジケースで壊れる(コメント内、文字列内、import の順序)
• 手動で 1 ファイルずつ → 集中力が持たない、ヒューマンエラー
• テストを毎回回す → サイクルが長い
• 数日かかる、レビューも疲れる

After (Claude Code を使う場合)

wzxhzdk:0

→ 30 分〜数時間で完了、テスト保証付き。

必要な道具立て

CLAUDE.md 必須セクション例

wzxhzdk:1

Hook 設定 (.claude/settings.json)

wzxhzdk:2

→ Edit のたびにテスト、失敗したら Claude に「次の編集をブロック、見直せ」と返す。

Skill .claude/skills/refactor-pattern/SKILL.md

wzxhzdk:3

ワークフロー (例: print → logger 置換)

wzxhzdk:4

注意点・限界

• テストカバレッジが低い箇所は危険(変更後テストが通っても本当に動くか分からない) → カバレッジが低い領域は別途手動確認
• 意味を変える置換(例: print でロガーが上書きする出力色を期待してた箇所)は AI には判別できない → コードレビューで人間が確認
• 大きすぎるリファクタ(1000 ファイル超)は 1 セッションでは厳しい → 章単位で分割
• コスト目安: Haiku で 50 ファイル ≈ $1〜$3、Sonnet を使うと $5〜$15

応用

• 依存パッケージのメジャーバージョンアップ (Python 3.x → 3.y で deprecated になった API の置換)
• テストデコレータの一斉追加 (新しい pytest plugin の設定)
• i18n キーの追加 (UI 文字列を gettext("...") で囲む)
• 型注釈の段階的導入 (untyped だった関数に Type hint を追加)

このケース後にできるようになること

• 機械的反復作業を半自動化 できる
• テストが品質保証になる という感覚 — テストが薄いと AI 任せもできない、と気づく
• Hook の威力を体感(失敗を即座に検知 → 暴走しない)

関連

• 08-04 Hooks — このケースで多用する技術
• 08-03 Skills — refactor-pattern Skill の作り方