Claude Code でリファクタリング：計画、小さなステップ、通るテスト

リファクタリングで Claude Code ができること

• リファクタリングのバックログを、1 ステップずつ別々のプルリクエストにして、小さく進めます。
• 各ステップの前後でテストを実行し、失敗したら止まります。
• 移行の機械的な部分を引き受けます：コードベース全体での名前の変更、API のアップグレード、新しいライブラリへの移行。
• 使われていないコードや重複したロジックを削除し、削除のたびに理由を説明します。

リファクタリングに使える Claude Code の機能

リファクタリング向けに Claude Code を設定する方法

1. ツールをつなぐ

   つなぐものはありません。リファクタリングを安全にするのは、Claude が実行できるテストコマンドと、各ステップの大きさの上限です。どちらも CLAUDE.md に書き、worktree で始めましょう。

   # 専用の worktree でリファクタリングを始める
   claude --worktree billing-async
   
   # 編集の前に計画を合意する
   /plan Move the billing module from callbacks to async/await

2. CLAUDE.md にルールを書く

   Claude Code は、claude -p での実行も含め、すべてのセッションの開始時に CLAUDE.md を読みます。仕事のルールはそこに書くか、長くなるなら .claude/skills/ 以下のスキルにします。CLAUDE.md ガイドをご覧ください。

   ## リファクタリングのルール
   - 振る舞いは変えない。テストを変える必要があれば、止まって確認する。
   - 始める前と各ステップの後に `npm test` を実行する。
   - 1 つのプルリクエストに 1 ステップ、変更は 400 行未満。
   - REFACTOR.md を最新に保つ：終わったものにチェックを付け、
     見つけたものを追加する。
   - 確認なしに migrations/、生成されたファイル、公開 API に
     触れない。

3. 対話型の画面なしで実行する

   claude -p は 1 つのタスクを実行して終了するので、cron や CI、ほかのツールから起動できます。確認なしで何をしてよいかは --allowedTools か --permission-mode で決めます。--output-format json を付けると、結果がコストと一緒に返ります。

   # REFACTOR.md のバックログから 1 日 1 ステップ
   claude -p "REFACTOR.md で次の未チェックの項目をこなし、テストを通したままにして" \
     --allowedTools "Bash(npm test),Read,Edit"

4. スケジュールに載せる

   /schedule でクラウドのスケジュールタスクにするか（Pro、Max、Ultra、Team、Enterprise）、デスクトップのスケジュールタスクを使うか、セッションを開いている間は /loop を使います。Claude Code を自律的に動かす方法をご覧ください。

出典：Claude Code のドキュメント

限界と安全性

• テストがなければ、リファクタリングと振る舞いの変更を見分けられません。まずその領域にテストを追加しましょう。
• 大きな書き直しを一度に行うと、レビューが難しくなります。1 つずつマージできる小さなステップのほうが安全で、結局は速く進みます。
• どの奇妙なコードが意図的なものかは知りません。そうした箇所には、コメントかルールで印を付けておきましょう。
• Claude Code v2.1.302 以降、claude -p は Manual モードで始まります。承認が必要な操作は、ルールで許可されていない限り拒否されます。許可するツールは、その仕事に必要なものだけにしましょう。

リファクタリングに使うなら Claude Code と Codex のどちら？

ルールはそのまま使い回せます。AGENTS.md に一度書き、CLAUDE.md に @AGENTS.md と書いておけば、両方のエージェントが同じファイルを読みます。

もう一方のエージェントでの手順：リファクタリングを Codex で行う方法。

リファクタリングを誰かの仕事にする

コマンドは、誰かが実行を思い出したときにしか動きません。Crewmark は、あなたの Claude Code を、職種、数字の目標、勤務時間、ハートビートを持つ AI 社員に変えます。仕事はスケジュールどおりに進み、ボードに表示されます。

1. 職種から始める

   AI ソフトウェアエンジニアを選び、ブリーフにこのページのルールを加えます。

2. 仕事をボードに載せる

   この仕事を定期 issue として追加します。社員はハートビートで起きて仕事をこなし、結果をコメントで報告します。

3. 関連ページ

   各ステップは、マージの前にコードレビューでチェックします。

よくある質問