195個のGraphQLエンドポイントをリファクタリング - Claude Code並列リファクタの作法-

今回のAKARI Tech Blogは、AI SaaS事業本部の渡邊が担当します。

私たちが開発・提供している Digital Builder は、建設業界における「請求・発注・見積・経費精算・原価管理」といった一連の業務をクラウドで一元管理できる Web アプリケーションです。

私が直近で取り組んだのは、デジタルビルダーのアプリケーション上に存在した計195個のGraphQLエンドポイント(Query 99個 + Mutation 96個)を、別の実装方式に画一的に置き換えるリファクタリング作業です。Claude Codeの並列エージェント戦略により、人間の実質的な作業時間は 約3〜4時間 で完了させることができました。この記事では、Claude Codeに大量タスクを丸投げするのではなく「1件分の成功の型を先に固めることでスケールさせる」ための4手順と、その具体的な実施方法について紹介します。

はじめに
実施した具体的施策
- 特定した4手順と解決策
得られた成果
- 定量的成果
- 定性的成果
最後に
We're Hiring!

はじめに

Claude Codeのような並列エージェントを業務で活用しようとする際、本当にスケールするのかどうかを、まず疑うと思います。「結局、人間がレビューと修正に追われて、トータルでは大して速くならないのでは」と感じた方も多いのではないでしょうか。

確かに、エージェントに丸投げすると失敗します。しかし、「1件分の成功の手本」を先に人の手を加えて確立し、エージェントはそれを複製する役割に徹するように設計を変えることを意識し、このスケールを成功させました。

実施した具体的施策

私が設定した目標は「最初の1件をお手本として完走させ、残り194件を並列エージェントが自走できる状態を作る」ことでした。

Claude Codeなどのエージェントは、参照できる完成例があるかどうかで出力品質が大きく変わります。お手本のないまま大量タスクを投げると、出力にばらつきが生じ、それをレビュー・調整する業務が発生します。エージェントに渡す入力品質を最大化することに人間の工数を集中させる ことが、並列化の鍵です。

特定した4手順と解決策

並列リファクタリングを成立させた要素を、4つの手順として整理しました。

手順1: 最初の1件は人間が完走する

エージェントは賢いですが、プロジェクト固有の暗黙知を読み取るのは下手です。そこで、まずは1件のお手本を、人間が伴走して完走させます。これにより、ディレクトリ規約・触らないファイル等を指示し、ファイルをどのディレクトリに置くか、どのファイルは触ってはいけないか(自動生成・スコープ外)を明確化します。

手順2: 過去コミットを「仕様書」として渡す

「このGraphQLエンドポイントを新しい実装方式に書き換えてください」と自然言語で説明するアプローチには、以下のような問題点があります:

ファイルパス・import順・型の対応まではカバーされない
後続のエージェントごとに微妙に違う仕上がりになる
レビュー時に「型のズレ」を毎回直すコストが累積する

そこで解決策として、既に成功している類似コミットのハッシュをそのまま渡し、「これと同じことをやってください」と指示する方法に切り替えました。これにより変更すべきファイルパス・import順・型の対応・テスト/lint対応範囲の指示を明確化しました。

手順3: PRはレビューできる粒度で割る

195件を1PRに詰めると人間がレビューできず、CIが落ちたとき原因の切り分けが地獄になります。今回はドメイン単位で9PRに分割しました。

PR1: 手動完走分
PR2: ユーザー・組織
PR3: 決済・取引先
...(以下略、計9PR)

各PRが独立しているので、個別にCI確認し・個別にマージができます。問題が出ても切り戻しの粒度が小さく、影響範囲が読みやすくなり、レビューしやすくなり結果として品質が向上します。

手順4: 繰り返す定型手順はスキル化しておく

スキル化により、人間の作業をよりなくすことでさらに速度を上げることができます。具体的には、resolver追加 → スキーマ更新 → メタデータ反映のような定型手順をCustom Skillとして事前に登録し、人間の作業としては「指示」ではなく「最終確認」だけに集中できるようにしました。

得られた成果

定量的成果

対象は195本のGraphQLエンドポイント(Query 99本、Mutation 96本)。これを最大8並列でエージェントに任せ、9本のPRに分けて独立にマージしました。実質的な作業時間は 約3〜4時間 です。同じ作業を従来手順で進めれば人手換算で 約15人日 かかる規模だったので、削減率95%を達成しました。

定性的成果

今回4手順として手順を汎用化できたので、別の領域でリファクタリングが必要になったときに、他のメンバーがそのままなぞれる状態になりました。型4で書き出した定型スキルは新しく入ったメンバーのオンボーディングにも転用できます。そして個人的に一番大きかったのは、工数削減で生まれた時間を、設計や仕様定義、検証といった上流の工程に回せたことです。

一方で、進めるなかで見えてきた課題もありました。

エージェント権限の事前整備不足: 8並列で立ち上げたエージェントのうち複数が、ファイル書き込みやコマンド実行の権限不足で実行途中に停止しました。その都度、許可ダイアログに人間が応答してから再開する必要があり、3回のリトライでトータル30分ほど失っています。本来は .claude/settings.json のallow listに、対象リファクタで必要なコマンド・ツールを並列起動の前に追加しておくだけで防げたはずです。事前整備をしておけば、ダイアログ応答にかかる時間も、中断したエージェントが再生成する分のトークンも、丸ごと節約できたはずです。
スキーマ同期工程が直列のまま残った: GraphQLサーバーを実際に起動してスキーマを再生成する工程は、複数のエージェントが同じポートやファイル出力先を取り合うため並列化できず、ここで2時間使いました。具体的には、各worktreeで起動する GraphQLサーバー / Postgres / Hasura などのポートが固定値で重複してしまい、同時に立ち上げられないという問題です。これを解消するには、worktreeごとに docker compose のポート番号をオフセットして起動できる仕組み(例: ベースポート + worktreeインデックスで自動採番)を用意し、各worktreeが独立してスキーマ生成と検証を完結できる状態にする必要があります。