AI コーディングエージェントが書いたコードを、本番にマージするのが怖い。

Cursor でも Claude Code でも、生成されたコードをそのまま信用してマージするのは勇気が必要です。コーディングエージェントを使ってはいるものの、なんだかんが手動で差分を確認したり、動作確認のために別のエージェントセッションでレビューさせていたりします。場合によってはClaude Codeの Pro プランが持つ5時間の枠を全部使ってリリース前チェックを行うこともありました。

このような「生成されたコード・PRをマージするための作業に時間がかかる」理由は明確です。とにもかくにも、AIが１つのPRに生成するコードが多すぎるのです。100行ちかくの変更をProプランの5時間枠だけでも３つから５つ６つと提出されることもあります。つまりハードに使う場合、1日に100行近くの変更を１０も２０もレビューしないといけないということです。テストを整備させたとしても、結局そのテストが適正かをレビューする必要があることには変わりありません。

結局、「個人開発だし、困るのは自分だから」という言い訳で祈るようにマージボタンを押すか、リリース前調査フェーズを用意して5時間の枠を割り当てるかになっていました。

継続的デリバリーが教えてくれたこと

CircleCIでの業務を進める上での知識を得るために、CI/CDやDevOps関係の書籍をいろいろ読んでいる最中です。その中で入門 継続的デリバリーから重要な考え方の間違いに気づきました。

そもそも、大きな変更を一度にマージ・リリースすること自体がCI / CDやDevOpsの観点では回避すべきアクションです。大きな変更は、それだけレビューが大変になり、見落としリスクも増加します。そしていざリリースして問題が発生した時には、「どの変更が問題を起こしているか」の特定が大変になります。結果「問題なくリリースできる」と言い切れなくなり、リリースとデプロイが怖くなる・・・ということでした。裏返すと、「怖くない粒度のPRになるように、問題を分割」すべきなのです。

小さく分割すると、開発の流れも変わります。型定義を1つ追加したら、マージする。関数を1つ実装したら、マージする。コンポーネントを1つ作ったら、すぐ production ブランチへ統合する。小さなサイズ（Small Batch Size）でできるだけ早くマージします。それによって問題が起きた場合のロールバックの影響も小さくなり、問題の特定もより早くなります。

この開発スタイルをAI駆動開発にも持ち込むことで、レビューの手間やリリースの恐怖を軽減できる・・・はずです。ただしここで問題になるのは、「自律的に行動できるエージェントのメリットや速度を大幅に損なってしまうやり方にならないか？」ということでした。

原理原則は理解したものの、それを今のコーディングエージェントが持つ良さを壊さずに使うやり方を探す必要がありました。

Claude Code Agent Team に git worktree と GitHub CLIを組み合わせる

ここで注目したのがClaude Code の Agent Team 機能です。Agent Team は複数の Claude Code セッションを並列で動かし、互いにメッセージをやり取りさせることができます。1つのセッションが team-lead として全体を調整し、他のセッションが teammate として個別のタスクを実行する形で開発が進みます。ここに git worktree と GitHub CLI を組み合わせることにしました。

各エージェントが git worktree で独立したブランチを作り、実装を終えたら gh pr create で PR を作成する。それぞれのコーディングエージェントが独立して作業できる形を保つことで速度を殺さず、しかし成果物は small batch の PR として分割される形をめざします。

機能開発を３並列でsmall batch sizeに進めさせる

今回は実験として、ブログサイトへの検索機能の追加を依頼しました。Claude Codeに次のような指示を出します。

## 要件
ユーザーが求める情報に素早くアクセスできるよう、ブログページに検索機能を実装します。

## 検索対象
記事タイトル
記事抜粋

## 検索方法
WP APIのSearch機能を活用する

## 開発の進め方

AI駆動開発のリスクを軽減するため、以下の開発フローを採用します。

```
タスクを細かく分解してイテレーティブに進める（Iterative Decomposition）

大きなタスクを一気に任せず、計画を立ててサブタスクに分解し、Devinに順番に実行させる。Devinが1つのサブタスクを終えたら、人間がレビュー・承認してから次へ進む。これで巨大PRを防ぎ、小さなコミットを積み重ねる。
なぜCDフレンドリーか：変更が小さく、頻繁に統合・テスト可能。失敗したら即時停止・修正しやすい。
実践例：Devin公式ベストプラクティス：タスクを「小さく詳細に分解」し、明確な成功基準（テストで検証）を設ける。大きなタスクは避け、<30分のタスクに最適化。 
開発者共有（X/ブログ）：モジュール単位でデザイン→実施→レビューを繰り返す。例: 1人のエンジニアが複数エージェントを並行制御し、20k行以上のコミットを細かく管理。 
詳細計画プロンプト：ファイルツリーで変更を事前可视化し、ファイルごとの変更を計画。 
```

これを実現させるため、Agent Teamを利用して並列開発しなさい。

- まず、要件から実装プランを「先述の進め方を実現する形」で作成します
- API側の型定義や検索処理・UI側のコンポーネントの準備など、小さなコミット・小さなPRで並列実行できる形とする
- 並列実行は４つまでとする
- 各々がgit worktreeを使って（git worktree add ../worktree-auth-1 feature/auth-1 など）
- 作業が完了したものからgithub cliを使ってPull Requestを作成する
- 全てのpull requestが作成されたことをもってタスクを完了とする
- 各PRは小さく、1機能単位に

Agent Teamを有効化している場合、指示を理解して開発タスクを並列可能な形に分割してくれます。

⏺ ブログページに検索機能を実装するプランを作成し、Agent Teamで並列開発を進めます。

  実装プラン                                                                                 
   
  並列実行可能な4つのタスク                                                                  
                                                                                           
  1. WordPress API検索機能の基盤実装                                                         
    - lib/wordpress.tsに検索関数追加
    - types/index.tsに検索関連の型定義追加
    - 影響範囲：2ファイル、既存API層の拡張
  2. 検索入力UIコンポーネント作成
    - components/BlogSearchBox.tsxを新規作成
    - クライアントコンポーネント（入力状態管理）
    - 影響範囲：新規ファイル1つ
  3. 検索結果表示コンポーネント作成
    - components/BlogSearchResults.tsxを新規作成
    - 検索結果のリスト表示ロジック
    - 影響範囲：新規ファイル1つ
  4. ブログページ統合とテスト
    - app/blogs/page.tsxとapp/en/blogs/page.tsxに検索機能統合
    - lib/wordpress.test.tsにテスト追加
    - 影響範囲：既存ページ2つ、テストファイル1つ

  各タスクは独立しており、git
  worktreeで並列作業可能です。では、Teamを作成して実装を開始します。

そして開発エージェントが3つ起動し、並列で作業が始まりました。

⏺ 3つの開発エージェントを並列で起動しました：

  1. api-developer - WordPress API検索機能の実装
  2. ui-input-developer - 検索入力UIコンポーネントの作成
  3. ui-results-developer - 検索結果表示UIコンポーネントの作成

  各エージェントはgit worktreeで独立したブランチを作成し、小さなPRとして完成させます。3つのタ
  スクが完了次第、タスク4（ブログページ統合とテスト）を開始します。

  進捗状況を監視し、各エージェントからの報告をお待ちしています。


@ui-input-developer❯ Task #2 完了: BlogSearchBox実装完了

  4 tasks (1 done, 2 in progress, 1 open)                                                    
  ✔ 検索入力UIコンポーネント作成 (@ui-input-developer)   
  ◼ WordPress API検索機能の基盤実装 (@api-developer)   
    Running Run code quality checks…                                                 
  ◼ 検索結果表示コンポーネント作成 (@ui-results-developer)                         
    Running Wait for build to complete…                      
  ◻ ブログページ統合とテスト追加 › blocked by #1, #3   
 

作業が終わり次第、それぞれがGitHub CLIをつかってPull Requestを作ります。

@ui-input-developer❯ Task #2 完了: BlogSearchBox実装完了

⏺ 素晴らしい！タスク#2が完了しました。PR #225が作成されています。                            
                                                         
⏺ 進捗状況：                                                                                 
                                                                                     
  ✅ タスク#2完了 - 検索入力UIコンポーネント（PR #225）                            
  🔄 タスク#1進行中 - WordPress API検索機能                                                  
  🔄 タスク#3進行中 - 検索結果表示コンポーネント                                   
  ⏳ タスク#4待機中 - ブログページ統合（タスク1, 3の完了待ち）                               
                                                                                             
  残り2つのタスクの完了を待っています。      
                                                                                             
                                                                                             
⏺ ui-input-developerがアイドル状態になりました（正常な動作です）。引き続き、タスク#1と#3の完 
  了を待ちます。                                                                             
                                                                                             
                                                                                           
⏺ 引き続き、タスク#1（API実装）とタスク#3（検索結果UI）の完了を待っています。

しばらく待っていると、３つのPRが生まれました。

ファイル変更数も１つと非常に少ない内容です。これであればレビューエージェントも集中したレビューが行えますし、目視でのチェックも手軽です。

これで持ち込みたいと思っていたCD の原則をAI 駆動開発に持ち込むことができた。・・・と、ここまでは思いました。

統合作業の指示漏れによる破綻

問題は4つ目のタスク、統合でおきました。異様に時間がかかるので嫌な予感がしていました。提出されたPRを見ると変更がなんと764行。本来、先行のエージェントが実施した作業を統合していくのが統合タスクのはずです。しかし実際には、3つのコンポーネントすべてを一から書き直していました。

原因は明確でした。３つの先行エージェントがやった作業について何も知らなかったのです。統合エージェントは main ブランチから新しい worktree を作っていました。main にはまだ先行のPRがマージされていません。そのため、統合エージェントから見える世界には、BlogSearchBox.tsx も searchWordPressPosts 関数も存在しなかったのです。そのため、「ブログページに検索機能を統合してください」と指示されたエージェントは、統合すべきコンポーネントが見つからないので自分で作ることを決めたということです。

小さな PR に分割するところまでは成功しました。しかし「その後どうするか」を指示していなかったために、統合エージェントがそれらを無視して自前実装することになり、結果として最初から恐れていたビッグバンリリースが再現されてしましました。

進め方の指示が足りなかった

実験的な作業なので、ここで開発作業は打ち切ります。そして原因分析、つまりRCA( Route Cause Analytics )を作成させました。すると想像の通り、先行作業について何も知らなかったことがわかります。

⏺ ご指摘の通りです。PR #228には、PR #225, #226,                                              
  #227の変更がすべて含まれており、重複実装となっています。                                   
                                                                                             
  RCA (Root Cause Analysis)                                                                
                                                                                             
  問題の詳細                                                                                 

  期待される状態:
  - PR #225: 検索入力UI（52行）
  - PR #226: API実装（178行）
  - PR #227: 検索結果UI（139行）
  - PR #228: 統合のみ（既存PRの変更を使用）

  実際の状態:
  - PR #225, #226, #227: 正しく作成 ✅
  - PR #228: すべてのコンポーネントを再実装（764行追加） ❌

<中略>
 教訓

  並列開発でgit worktreeを使用する場合:
  - 統合タスクには明示的なマージ手順を含める
  - 「依存タスク完了後」だけでなく、「コードの再利用方法」を明確に指示
  - 検証ステップで重複実装を検出
  - または、並列開発には統合ブランチアプローチを採用

統合作業を見据えた指示を出す

結局のところ、チームとして開発を指示するならば、ワークフロー全体を意識したプロンプトであるべきでした。今回のプロンプトは、統合前の作業だけであれば機能した・・・ということです。そのため、「統合作業は別のセッションでやります」のような指示に変更し、マージ後に統合のためのプロンプトを出せば良かったと言えそうです。

AIにSmall Batch Sizeのマージも指示する

自動テストなどが整備されていれば、いっそ先行作業はリリースさせてもいいかもしれません。UIやAPIに統合していない作業ばかりなので、「単体テストが整備されており、それがGreenであるならば」や「CodeRabbit / Gemini Code AssistなどがOKと言えば」などの条件をつけた上で、マージを許可することもできそうです。参考までにRCAを出させたClaude Codeが提案したプロンプトはこちらです。

 ## 要件                                                                                    
  ブログページに検索機能を実装します（記事タイトル・抜粋を対象、WP API Search機能を活用）。

  ## 開発の進め方（継続的デリバリー実践）

  Agent Teamで並列開発し、**完成したPRから順次マージ・デプロイ**します。

  ### Phase 1: 並列実装（3エージェント）
  以下を並列実行（各30分以内、<200行/PR）：
  1. **api-developer**: WordPress Search API実装（lib/wordpress.ts, types/index.ts）
  2. **ui-input-developer**: 検索入力UIコンポーネント（components/BlogSearchBox.tsx）
  3. **ui-results-developer**: 検索結果UIコンポーネント（components/BlogSearchResults.tsx）

  **各エージェントの必須タスク:**
  - 実装・テスト・PR作成
  - **CI/CD完全パスまで監視**（`gh pr checks`で30秒毎確認、失敗時は修正）
  - **CI全通過後、team-leadに完了報告**（PR番号含む）

  ### Phase 2: 段階的マージ（team-leadが調整）
  **team-leadの役割:**
  1. 各エージェントからCI完了報告を受信
  2. `AskUserQuestion`で人間にPRマージを依頼
  3. `gh pr view --json state`でマージ完了を確認
  4. **3つのPRすべてマージ後、Phase 3開始**

  ### Phase 3: 統合（新チーム起動）
  **integration-leadのタスク:**
  - mainブランチから`feature/blog-search-integration`作成
  - 既存コンポーネント（Phase 1でマージ済み）をimportして接続のみ（<100行）
  - **新規コンポーネント作成は絶対禁止**
  - 統合テスト追加、PR作成、CI監視、完了報告

  ## 成功基準
  - 4つの独立したPR（各<200行）
  - すべてCI通過
  - Phase 1の3つはmainにマージ済み
  - Phase 3の統合PRがレビュー待ち

どちらを選ぶかは、タスク間の依存関係次第かなと思います。今回のように独立したコンポーネントであれば、どんどんマージしてもビルドやデプロイがこけないのであればOKかなと思います。一方でDBやAWS CDKスタックの変更などが含まれる場合は、もうすこしDevOps的な要素を取り込んでから自動化したほうが良いかなと思いました。

自信を持ってリリースできるAI駆動開発を目指して

実験的な作業ゆえに、完全にはうまくいきませんでした。しかし先行PRで作られた３つのコードはどれも有用であり、これらをマージした上で統合作業から再開することができます。小さな変更の集合であるため、AIがハルシネーションによって問題のあるコードを混入させたとしても、そのPRを破棄する心理コストや浪費したトークンについて考える必要もかなり減らせそうです。

CD の原則はシンプルです。小さく作り、すぐマージし、頻繁にデプロイする。Agent Team と git worktree と GitHub CLI の組み合わせは、この原則を AI 駆動開発で実践する手段になりえるなと思いました。

エージェントに「この機能を作って」と丸投げするのではなく、「この型定義を作って」「この関数を作って」「この PR を出して」と、CD の考え方を取り入れる開発手法はエージェントの速度を大きく損なわずに人間の不安を軽減できます。

エージェントの開発速度は、人間の想像を大きく超えてきます。しかし早く走れる車だろうとも、運転するのが人間であるように、ソフトウェア開発についても人間の手や目が入る以上、人間が制御できる範囲の速度にする必要があります。「小さく、頻繁に、安全に」走るエージェントを整えて人間が制御できる形を保つか、高速道路や新幹線のように高速で走っても問題がない環境自体を整備するか、この先の開発スタイルはどちらか２つに分岐していくのではないかと思いました。

追記

おいClaude Code。git worktree使ってねぇのかよ・・・

drwxr-xr-x@  36 okamotohidetaka  staff  1152  2 14 23:30 worktree-search-api
drwxr-xr-x@  36 okamotohidetaka  staff  1152  2 14 23:29 worktree-search-input
drwxr-xr-x@  37 okamotohidetaka  staff  1184  2 14 23:37 worktree-search-integration
drwxr-xr-x@  38 okamotohidetaka  staff  1216  2 14 23:30 worktree-search-results