はじめに
本記事では、Claude Code の複数のセッションに、1つの機能を分けた複数の PR を並列に実装させる方法を紹介します。
従来は、1つの機能を十分に小さな PR に分け、1人の開発者がその PR を1つずつ順に実装してリリースしていました。
cross-session messaging を使うと、PR ごとに分けたセッションが互いに連絡を取り合い、PR の間の食い違いを自分たちで合わせながら、複数の PR を並列に実装できます。人間がセッション同士の連絡の仕方を指示する必要はありません。そのための前提として、人間は、AI が作業の終わりを自分で確かめられるゴールの条件（設計書とテスト）を、あらかじめ用意しておきます。
公式ドキュメントも、cross-session messaging の使いどころの1つとして、別々の worktree で同じリポジトリを扱うセッション同士の連絡を挙げています。
Coordinate parallel worktrees: when sessions work the same repository in separate worktrees, Claude can tell the other sessions what landed.
出典: Message your other Claude Code sessions — When to use cross-session messaging
機能は、小さな PR に分けてリリースする
1つの機能を開発するときは、機能を小さな PR に分けて、少しずつリリースするのがよいとされています。これは AI が普及する前からの常識で、Four Keys（デプロイの頻度、変更のリードタイムなど）の文脈でもよく言われます。
Working in small batches is an essential principle in any discipline where feedback loops are important, or you want to learn quickly from your decisions.
本記事では、ユーザーに「表示名」（ニックネーム）を加える機能を例にします。設計書の「リリースの計画」の章では、この機能を、依存する順に次の4つの PR に分けています。各 PR は、1つ前の版のブラウザ・サーバー・DB と組み合わせても動くように作り、PR ごとにリリースします。以降の章の例も、すべてこの機能で示します。
| PR | 中身 | マージの条件 |
|---|---|---|
| 1 | DB: users テーブルに display_name 列を加える（NULL を許す） | — |
| 2 | サーバー: プロフィールの API で、表示名を読み書きする | PR 1 のマイグレーションが本番に反映された後 |
| 3 | ブラウザ: プロフィールの編集画面に、表示名の入力欄を加える | PR 2 の後 |
| 4 | ブラウザ: コメントの一覧で、氏名の代わりに表示名を表示する | PR 2 の後 |
小さく分けた PR は、並列に実装しにくい
設計書をもとに PR の分け方を決めるのは、それだけで大変な作業です。本記事の例では、PR の大まかな分け方とマージの順序を、あらかじめ設計書に書いておきました。
PR を分けた後も、PR の間では、実装を進めるうちに食い違いが起きます。たとえば、後の PR は前の PR の API の形に合わせて書くので、前の PR で API の形が変わると、後の PR も直す必要があります。
1つの機能を分けた PR は、このように実装の細かい単位で互いに依存しています。そのため、機能のような大きな単位であれば開発者を分けて並列に実装しますが、1つの機能の PR は、1人の開発者が時系列の順に1つずつ実装するケースが多いです。
cross-session messaging を使うと、PR ごとのセッションが互いに連絡を取り合い、これらの食い違いを自分たちで合わせながら、並列に実装を進められます。
前提
セッションが人間の指示を待たずに作業を進められるのは、作業の終わりを自分で確かめられるゴールの条件があるからです。本記事では、ゴールの条件として次の3つを用意しています。
- 設計書を書き終えています。設計書には、何を作るかと、PR の大まかな分け方とマージの順序を書いてあります。設計書は、複数のセッションに並列に編集させて仕上げました（方法はこちらの記事で紹介しています）。
- テスト仕様書を作る skill（
/generate-testcases）と、テストケースを実行して結果を書き込む skill（/execute-testcases）があります。各セッションは、実装を終えるとこの2つを使い、テスト仕様書の作成とテストの実施を自分で進めます。不具合が見つかれば直し、全件を実行し直します。 - 型の検査・lint・単体テスト・ビルドを、1つのコマンドで実行できます。
テストの skill（/generate-testcases、/execute-testcases）の作り方は、機会があれば別の記事で紹介します。
作業の環境は、次のとおりです。
- 開発とテストは、ローカルの環境で行います。ローカルの DB と dev サーバー（ポート 3000）は1つずつしかなく、すべてのセッションが共用します。2つのセッションが同時に使うと、互いのデータとサーバーを壊してしまいます。
- git worktree を置くディレクトリ（
~/src/worktree/）を、~/.claude/CLAUDE.mdに書いてあります。各セッションは、担当する PR の worktree をこのディレクトリの下に作って作業します。
テストは、AI の作業のガードレールにもなります。あるセッションが別の PR の前提を壊すと、そのセッションのテストか、後の PR のテストが失敗するため、セッションは壊したことに自分で気づけます。
手順
人間が必ず行うことは、セッションを用意することと、まとめ役のセッションに1回指示することの2つだけです。セッション同士の連絡の仕方は、人間が指示しません。
セッションを用意する
設計書を作ったセッションに、/rename でまとめ役の名前を付けます。
/rename impl-01
新しいターミナルのタブで、まとめ役のセッションを名前で指定して分岐させます。
claude --resume impl-01 --fork-session
--fork-session は、セッションを再開するときに、元の会話を引き継いだまま新しいセッション ID で始めるオプションです。
When resuming, create a new session ID instead of reusing the original
分岐したセッションは、設計書を作ったときの議論まで知った状態で作業を始めます。そのため、人間は、分岐したセッションに背景を説明し直す必要がありません。
分岐したセッションには、impl-02、impl-03 のように、まとめ役とそろえた名前を付けます。名前をそろえておくと、人間は、まとめ役への指示の中で、兄弟のセッションを impl-xx とまとめて指せます。続けて、分岐したセッションに、まとめ役の指示を待つよう伝えます。PR を分担させたい数だけ、この手順を繰り返します。
/rename impl-02
impl-01 から指示が来るまで待ってください。
まとめ役のセッションに、1回だけ指示する
人間は、まとめ役のセッションに次のように指示します。
設計書に基づいて実装を開始してください。
設計書の PR の分け方を確かめ、それぞれの PR を兄弟のセッション（impl-xx）で分担するよう指示して進めてください。
実装が終わったら、テスト仕様書の作成・実施・不具合の修正・PR の作成まで、作業をやりきってください。
この指示だけで、すべてのセッションが動き出します。人間が1回指示するだけで済む手軽さが、この方法の最大の利点です。
途中で全員に伝えたいことは、どれか1つのセッションに頼む
指示の後も、人間はどのセッションに指示や質問をしてもかまいません。全員にさせたいことができたら、どれか1つのセッションに「全員に伝えて」と頼むだけで済みます。頼む相手はまとめ役でなくてもよく、そのとき話しているセッションでかまいません。頼まれたセッションが、ほかのすべてのセッションに伝えます。
次のメッセージは、人間が impl-03 にテストの決まりを伝えた後に、impl-03 がほかのすべてのセッションに送ったものです。
人間からの指示です。各 PR の QA に、リグレッションのケースを必ず1件入れて実行してください。
【リグレッションのケース】新しいユーザーで会員登録からログインし、プロフィールの画面とコメントの一覧を画面で開いて確かめる
...
しくみ
まとめ役のセッションに指示した後に、各セッションが行ったことを示します。次の図の例では、impl-01 が PR 1・2、impl-02 が PR 3、impl-03 が PR 4 を担当しています。
各セッションは、人間が指示しなくても、自分の判断で次の3つを行いました。これが、この方法の成果です。
- まとめ役は、作業を任せるときに、範囲・終わりの条件と API の形を伝える
- ほかのセッションの担当範囲に食い違いを見つけたら、直すよう頼む
- ローカルの環境を使うセッションは、使う前と後に知らせる
その結果、PR 3・4 のセッションは、まとめ役が分担と API の形を送った時点で、PR 1・2 の完了を待たずに実装を始められました。次の図は、課題の章の図と同じ PR を、セッションごとに並べたものです。
以降の節で、それぞれを実例とともに説明します。
まとめ役は、作業を任せるときに、範囲・終わりの条件と API の形を伝える
まとめ役のセッションは、作業を任せるメッセージに、範囲・ブランチ・終わりの条件と、その PR が使う API の形を書きました。API の形は、サーバーの PR を書き終える前に決めて送りました。次のメッセージは、impl-01 が PR 3 を impl-02 に任せたときのものです。
【作業】PR 3（ブラウザ: プロフィールの編集画面に、表示名の入力欄を加える）
- 範囲: 設計書の「リリースの計画」の PR 3
- ブランチ: PR 2 のブランチを push したら知らせる。その上に feature/display-name-3 を切り、~/src/worktree/display-name-3 に置く
- 終わりの条件: /execute-testcases でテストを全件実施するまで
- 使う API（PR 2 で作る）:
profile.get → { name: string, displayName: string | null }
profile.updateDisplayName({ displayName: string }) → { displayName: string }
ブラウザの PR のセッションは、サーバーの PR を待たずに書き始めました。サーバーの PR が push された時点で、ブラウザの PR は API に依存しない部分のテストまで通っており、push の後はマージして型エラーを直すだけで済みました。
ほかのセッションの担当範囲に食い違いを見つけたら、直すよう頼む
各セッションは、ほかの PR に食い違いを見つけると、自分では直さずに、その PR を担当するセッションに直すよう頼みました。次のメッセージは、impl-03 が、PR 3 の本文がテスト仕様書と食い違っていることに気づき、impl-02 に送ったものです。
PR 3 の本文の「手動の動作確認」の欄を直してください。
- 欄のケースの数が古いままで、テスト仕様書に足したリグレッションのケースが反映されていません。
- ケースの数を直し、リグレッションのケースを含むことを書き足してください。
- PR 1・2 と PR 4 の本文は、そのように直してあります。
ローカルの環境を使うセッションは、使う前と後に知らせる
ローカルの環境を使うセッションは、使う前にほかのすべてのセッションに知らせ、使い終わったらサーバーを止めて知らせました。知らせる内容には、DB の状態（どのマイグレーションを当てたか、テストのデータを消したか）も含まれていました。次に使うセッションは、この内容から、DB を作り直さずに使えるかを判断できます。
ローカルの環境を空けました。:3000 の dev サーバーは止め、DB は起動したままです。
DB には PR 1 のマイグレーション（display_name 列）が当たったままです。テストのデータは後始末で消しました。
ローカルの環境を使いたいセッションが重なったときは、セッション同士で使う順番を決めました（たとえば、impl-03、impl-01、impl-02 の順）。
おわりに
AI を使ううえでゴール（ガードレール）を設定することは周知のプラクティスですが、cross-session messaging による並列作業ができるようになったことで、ますますその重要性が増していると思います。