工程コンテキストをGitHubに残す：AIコーディングのツール間引き継ぎと並列ブランチ開発
AI コーディングツールを切り替えるとき、一番面倒なのはコード生成の精度よりも、プロジェクトの事情を最初から説明し直すことだったりします。なぜ前のセッションでその設計に決めたのか。どのブランチで作業しているのか。どのテストが通り、どの PR がまだレビュー待ちなのか。前の Agent に許されていた操作は何だったのか。
私はこうした情報をチャットだけに置かず、GitHub で読める形に残すようにしました。Codex、Claude Code、Cursor、ブラウザー版 ChatGPT のどれを使っても、最初に Issue、ブランチ、PR の現在地を確認する。書き込み権限があれば自分のブランチでコミットし、読み取りだけならレビューに回る。
これが私のいう GitHub-first です。AI ツールは替えても、エンジニアリングの状態までチャットと一緒に消してはいけない。 進捗を覚えておく専用の常駐 Bot は必須ではなく、外出先のスマートフォンから次の作業を引き継ぐこともできます。
会話の記憶とエンジニアリングの文脈は別物
何日も続くプロジェクトでは、A が却下した設計上の理由を B は知らず、古いコミットの緑色の CI を見て現在の HEAD も成功したと思い込むことがあります。複数の人が同じファイルを編集して、それぞれ自分が担当者だと思っている場合もあります。過去の会話を大量に貼り直せば一時的には改善しますが、特定のチャット履歴への依存は深まります。
GitHub に保存できるのはモデルの「記憶」そのものではなく、あとから読み返して検証できる工程上の事実です。私は次の四層に分けています。
- プロジェクトのルール：
AGENTS.md、README、必要なアーキテクチャ文書。AGENTS.mdを自動で読むかどうかはツール次第です。 - タスクの識別：Issue、タスク ID、計画、担当者、checkpoint、完了事項と未検証事項。
- コードのバージョン：
main、各 feature branch、commit／Git Blob SHA。どのブランチで作業しているかが重要です。 - レビューと受け入れ：PR の差分、コメント、ACK、その HEAD に対応する CI、マージやデプロイの記録。
巨大な JSON データベースを新設する必要はありません。Git はコードの履歴、Issue と PR は議論、必要に応じて checkpoint が「次の一手」を記録する。機密情報や一時的なモデルキャッシュ、頻繁に更新されるロックはリポジトリに入れません。
新しいセッションには、長い会話ログより先に次の短い復帰プロンプトを渡しています。コード例は他のツールにも貼れるよう英語のまま載せます。
You are the developer for this task. Recover project state read-only first.
Repository: OWNER/REPO
Task: Issue #N, linked PR #M, task ID TASK_ID
Read repository rules, the plan, checkpoint, current feature-branch HEAD,
PR diff, the latest applicable review comments, and checks for that HEAD.
Explain the authorized actions, verified work, and remaining gates.
Stop and report if the branch moved, permissions differ, or orders conflict.
Do not merge, deploy, or change production settings without separate approval.個人開発なら軽く始めれば十分です。README／AGENTS.md、Issue または PR、直近のコミットを確認するだけでも、一度ツールを切り替えて作業を再開できます。複数セッションや複数担当者、独立したレビューが必要になってから checkpoint や Order／ACK を追加すればよいのです。
GitHub を共通の状態基盤にして、複数の AI とブランチをつなぐ
役割を図にすると、次のような流れです。記事冒頭のアニメーション SVG も同じ構造を表しています。
Phone / browser / local IDE / cloud coding agent
|
Read GitHub task facts
|
AGENTS.md · Issue · plan · checkpoint
branch · PR
|
Check permission scope
|
Feature branch A Fix branch B
| |
commit commit
| |
PR A PR B
\ /
review + CI per HEAD
|
Human approval to merge
|
mainすべての入り口が同じ GitHub 権限を持つわけではありません。検索や読み取りだけできる連携もあれば、実行環境を持ち、ファイル変更や PR 作成ができる Coding Agent もあります。2026 年 10 月時点の説明であり、名前を挙げた各製品の最新権限を一通り実測したものではありません。 実際に使うアカウントと連携設定で read、write、comment、merge、deploy を確認する必要があります。
複数の Agent は同じルールを読む一方、それぞれ feature/A、docs/B、fix/C のように別ブランチで変更します。成果は PR で合流させます。ただしブランチが違っても論理的な競合は起こります。同じ API や依存関係を触ることはあるので、一つの作業ブランチには原則一人の書き手を割り当て、マージ前には共通の基点、差分、最新 CI、統合テストを見ます。
GitHub の Pull Request ドキュメントにはレビューやチェックの仕組みがあり、保護ブランチでは必須レビューなども設定できます。ローカルの作業ディレクトリを分離する方法はGit Worktree の記事で紹介しています。ここでの主題は異なる AI が同じ GitHub タスクをどう引き継ぎ、PR に戻すかです。
ツール間の引き継ぎ：Issue・ブランチ・PR を先に確認する
復帰プロンプトだけでは不十分です。現在の HEAD、前担当者の成果物、誰が書き込みを許されているかを、新しいツールが事実に基づいて答えられる必要があります。
最初はルートに短い AGENTS.md を置きます。プロジェクト全体の説明を重複させるのではなく、既存ドキュメントやテスト手順への道案内にするのが便利です。
# AGENTS.md
- Stack and architecture: see README.md and docs/architecture.md
- Install and test: follow the current commands in README.md
- Task entry points: GitHub Issue and linked PR
- Optional state: tasks/<TASK_ID>/checkpoint.json
- Before editing: verify task ID, branch, and live HEAD
- Prefer one writer for each feature branch
- Merges and deployments need separate approval長期タスクでは追加で checkpoint.json を残します。次のキーは私の実際の checkpoint にあるものですが、ID や SHA は公開用のプレースホルダーに置き換えています。
{
"task_id": "TASK_ID",
"phase": "P2",
"status": "IN_PROGRESS",
"branch": "feat/TASK_ID",
"commit_sha": "REPLACE_WITH_LAST_VERIFIED_40_HEX_SHA",
"pr": "https://github.com/OWNER/REPO/pull/N",
"verification": { "merge": { "status": "NOT_AUTHORIZED" } },
"next_action": "Read current HEAD and review comments before resuming"
}これは私有ファイルのコピーでも、どんなプロジェクトでも使える完全な Schema でもありません。コミットするたびに checkpoint を更新する必要もありません。 私は節目の引き継ぎ、検証、ブロッカー発生時だけ更新します。小さなタスクなら Issue／PR コメントで足ります。
注意したいのは commit_sha の自己参照です。checkpoint.commit_sha は最後に検証されたコードのコミットであって、必ずしも checkpoint を含むコミットでも、今の HEAD でもありません。 コードをコミット A で確認し、あとで checkpoint をコミット B に保存したなら、ファイルには A を書けます。しかし B がまだ存在しないうちに B 自身の SHA を予測することはできません。「常に一コミットずれる」という固定的な関係でもありません。
したがって、新しいセッションは必ず GitHub からライブの HEAD を読み、記録された基準点とその後の変更を突き合わせます。ACK の observed_head_sha と new_head_sha はレビュー対象の旧版と修正後の新版です。SHA が一致しないことと、Order が古くて拒否されることは別の判定です。
AGENTS.md はルール、Issue／PR は議論とレビュー、checkpoint は必要な進捗を担当します。自動で AGENTS.md を読まないクライアントには、明示的に読み込ませます。
このより厳密な引き継ぎプロトコルはオープンソースにしました。軽量な運用には不要ですが、Order／ACK が HEAD にどう紐付き、古い指示をどう拒否し、オフラインでどう検査するかをコードで確認できます。
このリポジトリにはプロトコル、バリデーター、例があります。プロジェクトの状態を外部サービスに複製したり、別の AI チャットを自動起動したりする常駐 Bot ではありません。タスクと PR は各自の GitHub に残ります。
実際の PR：FIX_REQUIRED → ACK → 独立した再レビュー
アーキテクチャ図を作ると、AI が二つとも「了解」と答えただけで引き継ぎが成功した気になりがちです。私は実際のドキュメントだけを直す PRを読み直しました。レビュー役 B が二つの問題を指摘し、開発役 A が修正して新 HEAD を書き戻し、B がその新しい版を確認しました。最後のマージ判断は別途人が行いました。
FIX_REQUIRED、ACK、ADVANCE は私のプロジェクト固有のコメント上の約束で、GitHub 標準の PR ステータスではありません。修正要求、開発側の受領と新版の報告、レビュー側の再確認を意味します。後述の STALE_ORDER は古い HEAD に結びついた指示を止める状態です。
重要だった F-001 は GitHub Actions のイベント監査に関する問題でした。監査計画では issue_comment のようなトリガーを確かめたいのに、コマンドは workflow のファイル名だけを取得していました。
# Original plan: names only; the YAML triggers remain invisible.
gh api "repos/OWNER/REPO/contents/.github/workflows" --jq '.[].name'ファイル名が分かっても YAML トップレベルの on: に issue_comment があるかは分かりません。F-002 は文書の章参照の誤りでした。修正版は監査する SHA を固定し、YAML の実際のイベント設定を読んで、最後に HEAD が移動していないか再確認します。私は変更前後の文書を比較しました。Actions イベントの公式資料も参照できます。
A は元の PR に ACK と新 HEAD をコメントし、B は修正二件を新 HEAD で検証した後に ADVANCE を返しました。これは人が二つの AI 会話を進めた運用で、チャットを自動的に目覚めさせる仕組みでも、GitHub Actions やローカル Git hook に組み込まれた門番でもありません。普通の PR コメントと正確な HEAD だけでも簡易運用は可能です。
次は実際の ACK コメントから重要なフィールドを抜き出したものです。私有 ID と SHA は置き換えています。
{
"protocol": "ai-supervisor/ack/v1",
"task_id": "TASK_ID",
"order_id": "REPLACE_WITH_ORDER_ID",
"decision_received": "FIX_REQUIRED",
"observed_head_sha": "REPLACE_WITH_OLD_HEAD",
"new_head_sha": "REPLACE_WITH_NEW_HEAD",
"executed": [
"F-001: Inspect workflow triggers at a pinned SHA",
"F-002: Correct the audit plan's section reference"
]
}実際のプロトコルには追加フィールドと整合性チェックがあります。ここで重要なのは、A が B のどの旧 HEAD に対する指摘を受け、どの新 HEAD を返したかを明確に残せる点です。B は「直しました」という言葉だけを信じずに、新しい版を見て再審査できます。
対象は監査計画の文書変更だけでした。対応 HEAD での成功 CI や本番 VPS 監査の実行記録はありません。確認できるのは追跡できるレビューの受け渡しであって、システム全体の自動運転ではありません。
STALE_ORDER：古い HEAD に紐付く指示を止める
Order とは、B が Issue／PR コメントに残す構造化された指示です。タスク ID、対象ブランチ、観測した observed_head_sha、指摘事項、許可・禁止した操作を結び付けます。ACK の order_id はこの指示を参照します。
別のネガティブテストでは、Order が古い main HEAD に固定され、後からリポジトリの HEAD が進みました。A が古い Order を読んだ場合は STALE_ORDER として停止し、旧版の指示で勝手に書き込んではいけません。
私は保存された Order、新しい HEAD、ソース中の decideResume() の古さ判定を直接確認しました。当時 A は停止したと報告しましたが、その結果は人が転記したもので、A 自身が GitHub に独立した ACK を書いたわけではありません。有用な負の試験ですが、全クライアントでエンドツーエンド検証済みとは言えません。
ルールは簡単です。B はタスク・ブランチ・HEAD・許可操作を指示に固定し、A は実行前に最新 HEAD を取得する。変わっていたら停止して B に再確認してもらう。かつて正しかった指示でも、別のコードバージョンには当てはまらない可能性があります。
独立レビューを残す理由も同じです。「もっともらしい diff を生成した」ことと、別セッションが実際の新 HEAD 上で修正を検証したことは別の事実です。一般的な owner や状態の設計はAI Agent オーケストレーションの記事で扱っています。
スマホで協業できても、GitHub が無料の実行環境になるわけではない
この構成でありがたいのは、進捗を追うためだけに一台の Mac を常時起動したり、専用の常駐調整 Bot を運用したりしなくてよい点です。スマホから PR の状態やコメントを確認し、次のタスクを渡せます。一方、実際のコード変更、ビルド、テストには権限を持つクラウド Agent、Runner またはローカル環境が必要です。
コストも分けて考える必要があります。長い会話の繰り返しや専用サービスの保守は減らせるかもしれませんが、モデル推論、Chat／Codex／API の利用枠、CI はそれぞれ別の費用です。同じ作業を比較した Token 測定はしていないので、何％節約したなどとは書きません。
私のブログには GitHub Actions → Self-hosted Runner のデプロイ経路もあります。複数デバイスからの開発とデプロイの記事は、その後の公開工程についてです。この記事が答えたいのはその前段階、ツールや担当者が変わっても、本当に同じタスクを引き継いでいるとどう確認するかという問題です。
小さな単一ファイル変更なら、一つの AI と一つのブランチで十分でしょう。タスクが数日間にまたがり、複数ツールや人に引き継がれるとき、checkpoint、ブランチ所有者、独立レビュー、操作許可が効いてきます。GitHub-first の魅力は AI が記憶を共有する魔法ではなく、工程上の事実を同じ場所に残して、次の担当者が再開できることです。