GitHub連携で最初につまずいた話
シリーズ1本目。前回「何はともあれGitHub」と書きましたが、実際に繋ぐ段階では、かなりつまずきました。ここでは具体的な連携方法と、ハマったポイント、そして連携の経路をComposioに変えるまでの経緯を書きます。
最初は、チャット上ですべて完結していた
スペース☆タワーの初期は、AIとの会話の中でコードを丸ごとやり取りしていました。1枚のHTMLにゲーム全体が入っているので、修正のたびにファイルを貼り、直したものを貼り返してもらう。ファイルが数百KBを超えたあたりから、これが破綻します。
- 貼るたびにAIがどこかを微妙に変える。気づかないうちに壊れる
- 「前回の続き」がAIの中に残っていない。毎回説明し直し
- どれが最新版か、自分でもわからなくなる
GitHubを介せば、この3つが全部解決します。最新はmainにある。差分はPRで見える。経緯はIssueに残る。当たり前の話なんですが、「AIと会話する」感覚で始めてしまうと、後回しにしがちです。
連携の方法（いまの形）
いま使っている構成は3つの経路の組み合わせです。
1. Issueを起点にAIに実装させる
流れはこうです。まず私がチャットで「何をしてほしいか」を伝える。AIがそれを目的・変更箇所・完了条件に整理して、GitHubのIssueに起票する。そのIssueにAI宛てのメンションが付いていると、別のAIがブランチを切ってコードを直し、PRを作ります。私はPRの差分とプレビューを見て、OKなら「マージGO」と言う。マージの操作自体はAIがやります。
つまり私が書くのは、Issueではなくチャットの指示です。Issueの文面はAIが論理的にまとめます。「ふわっとした要望を、実装できる形に翻訳する」のがAIの仕事で、私はその翻訳が合っているかを見ます。
これの良いところは、大きいファイルをチャットに貼らなくていいこと。AIはリポジトリの中で直接作業します。
2. チャット側からGitHubのAPIを叩く
Issueの起票、PRの状態確認、小さいファイルの読み書き、ワークフローの再実行など、軽い操作はチャットから直接行います。後述しますが、ここが一番苦労した部分です。
3. マージの判断は私、操作はAI
本番反映は必ず私の「マージGO」を待ってから。判断は私、マージとデプロイの操作はAI、という分担です。AIが指示なしにマージしないことは、ルール化して文書に書いてあります。
連携時の注意点
- 大きいファイルは普通の方法で読めない。私の環境では、ゲーム本体（約1MB）をチャット側の連携で読もうとするとタイムアウトしました。500KBを超えるファイルはIssue経由でAIに直接触らせる、というルールにしています
- APIで取ると中身が切れることがある。GitHubのファイル取得APIは、サイズが大きいと内容を省略して返します。ファイル一覧からSHAを取り、blob取得の別APIで読む、という二段構えが必要でした
- ワークフローファイルは特別扱い。GitHub Actionsの設定ファイル（
.github/workflows/）は権限の関係でAIから書けない時期がありました。いまは書けるようになっていますが、CI/CDの根幹なので他のファイルより慎重に扱っています。とはいえ流れは同じで、私がチャットで指示し、AIが内容をまとめて更新します - プロジェクトの現在地は、すべてGitHubで把握できるようにする。最新のコード、開いているIssue/PR、ルール文書。どれもGitHubを見れば最新の状態が分かる、という状態を保ちます。チャットの履歴やAIのメモリーを頼りにしない。これは次の記事で詳しく書きます
- ボットが作ったPRは、Actionsの実行に承認が要る。AIが作ったPRのプレビューデプロイが動かない、と思ったら承認待ちだった、ということが何度もありました
- 1つのIssueに詰め込まない。変更箇所が多いとAIの処理が途中で途切れます。目安は1 Issueあたり3箇所まで
Composioに移行するまでの苦労
チャットからGitHubを操作する経路は、何度も作り直しました。順に書きます。
最初: Docker経由のGitHub連携
最初に使ったのは、Claudeのデスクトップアプリに GitHub連携（MCP）を繋ぐ方法でした。この連携はDockerというコンテナ環境の上で動く仕組みで、使うにはまずDocker Desktopを起動しておく必要があります。
これが地味に面倒でした。
- Dockerを起動し忘れると「Dockerが見つからない」で止まる。AIは原因を教えてくれないので、しばらく悩む
- 動いていても、大きいファイル（ゲーム本体）の取得はタイムアウトする
- 接続が古くなると応答が返らなくなる。直すにはアプリを完全に終了して再起動
- 会話の途中で接続が死ぬと、その会話では復帰しない。新しい会話を開くしかない
当時のトラブルシューティング表がそのまま残っています。「Dockerが見つからない → Docker Desktop起動を確認」「MCP接続エラー → 完全Quit→再起動」「既存チャットでMCP応答なし → 新規チャットで続ける」。連携を動かすための作業で、開発の時間が削られていました。
次: Composioに切り替え
数ヶ月後、ClaudeがComposioという汎用のツール連携サービスを使えるようになりました。
きっかけは単純で、Docker経由の連携で不具合が頻発していたこと、そしてDocker経由は起動しているPCでしか使えないことです。外出先のスマホからは何もできない。そこでClaudeに「なんか他に良いのないの？」と聞いたところ、Composio経由でGitHubのAPIを直接叩く方法を提案されました。
切り替えてみると、Dockerは不要。PCを立ち上げていなくてもスマホから作業できる。接続の生死をAI側で確認できる。ファイルのSHA取得やワークフローの再実行など、細かい操作が全部できるようになりました。
反面、覚えることが増えました。APIの呼び方、レスポンスの形、失敗したときの再試行。AIが毎回ゼロから思い出すのは非効率なので、「この操作はこのAPIをこう叩く」という手順をリポジトリ内の文書に書いておき、AIにそれを読ませる運用にしました。
移行の判断基準
シンプルで、「壊れたときに自分で原因がわかるか」です。Docker経由の連携は、動いている間は楽ですが、止まったときにAIも自分も何が起きているか分からない。しかもPCの前にいないと使えない。多少手間でも、中身が見える経路のほうが長く使えます。
最初から知っていたら
- 最初の1日でGitHubリポジトリを作り、AIとの作業は全部そこを通す
- 「大きいファイルは直接読めない」前提で、AIをリポジトリ内で作業させる経路を用意する
- 「確認と指示は私、操作はAI」を最初にルール化する
- プロジェクトの現在地は全部GitHubに。チャットやメモリーを頼りにしない
- 連携が切れているかどうかを、AIではなく自分で確認できる経路を選ぶ（Docker経由は分かりにくかった）