AIコーディングアシスタントを戦わせて最強のリファクタリングPlaybookを作った話

この記事は 「カンリー Advent Calendar 2025」 の15日目の記事です。

https://adventar.org/calendars/11622

こんにちは、株式会社カンリーのエンジニアの桑野です！
12月といえば大掃除の季節ですね。皆さんは大掃除していますか？エンジニアにとっての大掃除といえば、そう、リファクタリングです。

今回は、フロントエンドのリファクタリングを進める中で、DevinとClaude Codeという2つのAIコーディングアシスタントを活用し、最終的に「誰が使っても同じ品質のコードが出力される」Playbookを作り上げた話をお届けします。

背景：技術的負債の蓄積

私たちのプロジェクトの初期では、細かい仕様変更が頻繁にあり、開発スピードを優先してきました。その結果、以下のような課題が発生していました。

• コンポーネント化の不足：急ぎの開発でロジック分離やコンポーネント化を後回しにしていた
• テストの欠如：単体テストがなく、バージョンアップ時のデグレチェックが大変

まずはテスト可能な状態にするため、Container/Presentationalパターンを適用し、ロジックをカスタムフックで定義することにしました。

第一の試み：Devinでのリファクタリング

最初はDevinを使って複数の機能をリファクタリングしました。しかし、いくつかの課題が判明しました。

• カスタムフックの粒度が粗い：APIコール、状態管理、フォーム管理を分離してほしいのに、大きな1つのファイルになってしまう
• テストが作られない：単体テストの生成が不十分
• 出力のバラつき：指示の仕方によって異なる構成になり、レビューコストが高い

Claude Codeでリファクタリングを試してみたところ、こちらの方が精度が高いことがわかりました。しかし、このままでは各エンジニアのローカルで実行されるため「対応者ごとにバラつきがある」という根本的な問題は解決しません。

解決策：詳細なPlaybookの作成

そこで、誰が実行しても同じ品質のコードが生成されるようにするため、詳細なPlaybookを作成することにしました。

また今回はそのPlaybookすらAIに作らせてみました。

ステップ1: これまでのタスクからPlaybookのベースを作成

これまでのリファクタリングタスクをインプットとしてPlaybookのベースを作成します。

@Devin
フロントエンドのリファクタリング用Playbookを作ってください。

要件
- .ai-knowledgeの実装方針を守ること
- コンポーネントの構成はContainer/Presentationalパターンを採用しロジックはhooksベースで定義すること
- Unit Testが無ければ追加すること
- 以下の対応時のコメントを参考に実装方針を追加すること
  - https://app.devin.ai/sessions/xxx  //Devinでのリファクタ
  - https://github.com/xxx/pull/xxx    //ClaudeCodeでのリファクタ

※この後調整していくのでMarkdownファイルをPRに残しておく

# 必要に応じて調整
ユニットテストはjestではなくvitestを利用してください
処理はカスタムフックとして切り出してください

補足：.ai-knowledgeディレクトリについて

.ai-knowledgeディレクトリは、私たちのプロジェクトにおけるAI用のナレッジファイル置き場です。

プロジェクト固有の実装方針やコーディング規約、アーキテクチャの決定事項などが記載されており、AIコーディングアシスタントがこれらのファイルを参照させて、プロジェクトの文脈に沿ったコード生成を行うことを目的にしています。

ステップ2: 同じ機能を2つの方法でリファクタリング

Playbookの精度を検証するため、1つの機能に対して以下の2つのアプローチでリファクタリングを実施します。

• Claude Codeでのリファクタリング：ローカル環境で詳細な指示を出しながら対話的に実施
• Devin Playbookでのリファクタリング：初期バージョンのPlaybookを使用してDevinに実行させる

ステップ3: 2つのPRを比較分析

Playbookの改善点を見つけるため、Devinに2つのPullRequestを比較分析させ、良いところを抽出します。

@Devin
以下のPRを比較して
- https://app.devin.ai/sessions/xxx  //Devinでのリファクタ
- https://github.com/xxx/pull/xxx    //ClaudeCodeでのリファクタ

ステップ4: Playbookを改善して再実行

分析結果を反映してPlaybookを更新し、再びDevin Playbookで同じ機能に対してリファクタリングを新しいタスクとして再実行します。

比較結果を元にDevin Playbookの改善を行ってください。

Playbook PR
https://github.com/xxx/pull/xxx    // ステップ1のPR

自分の納得がいくまでステップ3と4を数回繰り返し、最終的に「誰が使っても同じ品質のコードが出力される」Playbookが完成しました。

出来上がったPlaybook（イメージ）

実際の使い方

以下のように指示を出せばPlaybookにすべての詳細が記載されているため、AIは迷うことなく一貫した品質のコードを生成できます。

@Devin
!refactoringをsrc/app/(features)/storesに実行して

得られた効果

この取り組みによって、以下の効果が得られました：

1. レビュースピードの向上：誰がリファクタを実施しても同じ構成なので、レビュアーが構造を理解しやすい
2. 生産性の向上：一気に複数画面をリファクタリングできる
3. 品質の保証：ロジック部分に包括的な単体テストを拡充
4. 保守性の向上：関心の分離により、変更が容易に
5. 再利用性の向上：分離されたフックにより、部分的な再利用が可能

まとめ

複数のAIツールでマルチエージェントのように同一のタスクを実施し評価させることで、品質を担保しつつ画一的なリファクタリングを実現することができました。

ClaudeCodeやCursorのカスタムスラッシュコマンドでも同様のことができると思うので、リファクタリングに悩んでいる方、AIを活用して開発生産性を上げたい方の参考になれば幸いです。

明日のAdvent Calendarもお楽しみに！