【勉強】生成 AI 協働者編②GitHub を介してエージェントに任せる

生成 AI は毎日使っているのに、知識そのものは数年前で止まっている自覚がありました。Gemini や Claude を私生活で触っているのですが、どちらも「だいたい分かっている」つもりになっていて、実際には用語の意味も課金の仕組みも説明できない、という状態です。そこで、キャッチアップすべき項目を洗い出したラーニングパスを自分用に作り、端から潰していくことにしました。

構成は 4 レイヤー・15 ステップで、項目数は 80 ほどです。利用者編から始めて、協働者編・開発者編・運用者編へ進みます。進め方は「まず自分で手を動かして調べる・検証する」「詰まったところや調べきれなかったところを AI に補ってもらう」「ワークログに残す」の 3 つを項目ごとに繰り返します。

前回の協働者編①では、手元の開発環境にコーディングエージェントを入れ、エージェントに渡す設定を整えました。今回の協働者編②では、GitHub の Issue を入口、プルリクエスト（PR）を出口にして、エージェントに作業を任せるところを扱います。練習用のリポジトリを 1 つ作り、5 つの項目すべてで使い回しました。題材は前回と同じく Claude Code です。この記事は、そのワークログを清書したものです。個人的に勉強して、個人的にまとめただけのものなので、網羅的な解説になっていない可能性が大いにあります。また、生成 AI まわりは動きが速いので、記載の内容はすべて 2026-10 時点のものになります。

協働者編では、次のことができる前提で進めます。どれも生成 AI とは関係のない知識なので、ラーニングパスの項目には含めていません。

• ターミナルでコマンドを実行し、ファイルやディレクトリを操作できる
• Git で branch・commit・merge を自分で実行できる（Pro Git の最初の 3 章程度）
• GitHub でリポジトリを作り、プルリクエストを作ってマージしたことがある（GitHub の Hello World 程度）
• Python などで書かれたコードを読み、テストを実行できる

下の表が今回のやることリストです。私と同じような状況にある人は、ぜひこの順番で自分でもタスクをこなしてみることをオススメします。

GitHub 連携

• 【調べる】エージェントを GitHub につなぐ方法と、それぞれの権限の違いを説明できるようにする
• 【動かす】練習用のリポジトリを作り、エージェントに Issue を立てさせる

AI と一緒に開発を進めるには、まずバージョン管理を AI から触れるようにする必要があると思い、Claude Code を GitHub につなぐ方法から調べました。

3 つの接続方式

Claude Code から GitHub を扱う方法は、大きく 3 つあります。

GitHub Actions 版で使う Claude GitHub App は、Code Review などほかの Claude の機能と共有されているため、Actions では使わない権限も含めて付与されます（GitHub App 権限）。一部の権限だけを受け入れることはできないので、権限を絞りたい場合は、セットアップガイドに従って自分用の GitHub App を作ることになります。

どの方式でも、エージェントには GitHub の認証情報を持たせることになります。たとえば gh のトークンが repo スコープなら、エージェントは練習用のリポジトリだけでなく、自分のすべてのリポジトリに手が届きます。これが問題になる例として、Claude Code を -p フラグで非対話的に実行すると、初回のフォルダで出る信頼の確認が行われません（セキュリティ）。他人のリポジトリを clone して claude -p を実行すると、そのリポジトリに置かれた hooks のコマンドが確認なしに走り、そこから自分のトークンも使えてしまいます。トークンの権限が広いと、悪意のある hooks で自分の GitHub アカウントごと乗っ取られる恐れがあるということで、どの方式を選ぶ場合でも、エージェントに渡す認証情報の権限の広さは意識しておく必要があります。

今回は個人の練習なので、手元の gh を使う方式にしました。

練習用のリポジトリを作る

題材は趣味である麻雀の点数計算にしました。点数の計算だけを返す小さな Web API で、構成は FastAPI と pytest です。点数計算には早見表があり、その値をそのままテストの正解（期待値）にできるので、自分で計算しなくても AI の実装が正しいかを判定できます。

リポジトリの作成はエージェントに任せ、初期設定は自分で行いました。CLAUDE.md には、まずは確認しながら進めたいので「役割はアシスタント」「ファイルの編集は指示されたときだけ」「GitHub の操作は gh で行う」と書きました。

動作確認を兼ねて、「最初のテストを追加する Issue を立ててください」と頼むと、次のような Issue が立ちました。

概要
app/main.py の GET / に対する最初の API テストを tests/test_api.py に追加する。

やること
fastapi.testclient.TestClient を使って GET / を呼び出すテストを書く
次の 2 点を確認する
ステータスコードが 200 であること
レスポンスの JSON が {"message": "Hello World!"} であること

完了条件
uv run pytest でテストが 1 件以上実行され、すべて成功する

無事にエージェントに GitHub の操作を任せることができました。

テストの作成と実行

• 【調べる】エージェントにテストを書かせるときの注意点を調べる
• 【動かす】テストが自動で実行される hook を置く

コーディングを本格的に任せる前に、品質を担保するためのテストを用意しておきたいと考えました。

テスト駆動開発と、エージェントの落とし穴

今回は、テスト駆動開発（TDD）の作法に則って開発を進めることにしました。この開発手法では、テストリストを作り、テストを 1 つ書き、それを成功させ、リファクタリングする、をリストが空になるまで繰り返します（【翻訳】テスト駆動開発の定義）。

エージェントにテストを書かせるときの注意点は、Claude Code テスト駆動開発 完全ガイド に 6 つ挙がっていました。実装に合わせてテストを書いてしまう、テストと実装が同じ会話にあるとテストが実装に迎合する、要求されていない機能まで作り込む、といったものです。すべての対応を一度にしようとすると大変なので、注意点は項目ごとに 1 つずつ扱うことにしました。この項目で扱うのは「実装に合わせたテスト」です。

期待値は早見表から取る

「実装に合わせたテスト」は、実装を先に作り、その出力をそのまま期待値にしてしまうことで起きます。点数計算では早見表という外部の正解があるので、CLAUDE.md に「期待値は早見表から取る。実装の出力をそのまま期待値にしない」と書きました。あわせて、テストを書いて失敗させた段階（Red）で一度止まり、私がテスト内容や期待値を確認してから実装に進む運用にしてみました。当面の作業の流れは、私がやりたいことをエージェントに相談して、そのうちのいくつかを Issue にしてもらい、各 Issue に対してエージェントがブランチを作ってテストを書き、私が確認してから実装して PR まで出し、最後に私が手動で確認してマージする、という形です。

テストを毎ターン実行する hook

テストを用意しても実行しなければ意味がありません。テストの自動実行は、前回記事（協働者編①）の hooks の節で扱った仕組みを使い、Claude の応答が終わるたびに走る Stop の hook に置きました。これで、「この Issue の『やること』を検証するテストを書いて」や「『やること』を実現するコードを書いて」のような依頼が完了するたびにテストが強制的に実行されるようになります（強制できる点が CLAUDE.md や Skill と比較した hooks の利点でした）。なお、他にテストを実行する hooks の候補には PostToolUse がありましたが、こちらだとファイルを編集するたびにテストが走るので、全テストのような重い検査には向かないと判断しました。

hooks 自体は、やりたいことを伝えてエージェントに書いてもらいました。動作確認として、前の項目で立てた Issue に実際に取り組んでもらい、会話が自分に返ってくるたびにテストが実行されることを確認しました。

ループエンジニアリング

• 【調べる】/goal と hooks の使い分けを説明できるようにする
• 【動かす】テストが通るまでエージェントに作業を続けさせる

前の項目で「指示して、コーディングしてもらう」の往復は経験したので、これを「テストに合格するまでコーディングを続けてもらう」に広げたいと考えました。前回記事で、プロンプト → コンテキスト → ハーネス → ループと段階を分けたうちの、ループにあたる部分です。

/goal の仕組み

Claude Code では /goal がこの役割を担います。/goal <条件> を実行すると、条件を満たすまで Claude が作業を続けます。仕組みは、セッションの間だけ有効な、プロンプトで判定する Stop hook です。Claude がターンを終えるたびに、判定役のモデル（デフォルトは Haiku）が条件と会話を読み、「未達成」「達成」「不可能」のいずれかを返します（評価の仕組み）。なお、名前の似ている /loop は、決めた時間の間隔でプロンプトを繰り返し実行する別の機能です（/loop で定期的にプロンプトを実行する）。

注意点は、判定役のモデルはコマンドを実行せず、ファイルも読まず、Claude が会話の中で見せた内容だけで判定することです。そのため「テストが本当に通ったか」を機械的に保証する用途には向きません。そこで、次のように使い分けることにしました。

• テストが通るか、テストが書き換えられていないかといった決定的なチェックは、hooks（将来的には CI）が担う
• どこまでやれば終わりかの判定は、/goal で依頼ごとに指定する

条件文は、公式の効果的な条件を書くにある、測れる終了状態・それをどう示すか・変えてはいけないもの、の 3 つを入れ、ターン数の上限も添えました。最終的に使った形は次のとおりです。

/goal Issue #NN の完了条件をすべて満たし、PR を作成した。`uv run pytest` の全件成功を出力で示し、`git diff main -- tests/` の出力で既存のテストの行を削除していないことを示す。20 ターンで止める

あわせて CLAUDE.md を書き換え、前の項目で指定していた Red 後に一度止まる運用をやめて、1 つの Issue につき PR を 1 つ出すところまでは任せるようにしました。ただしこの運用だと、せっかく前の項目で作った Stop hook は PR の作成後に実行されるのでゲートの役割は果たさなくなります。とはいえ、このゲートはいずれ CI に担わせるつもりなので、気にしないことにしました。PR を確認するときに、ターミナル上に出力された Stop hook の結果も確認できるので、全くの無駄というわけでもありません。

テストを緩めさせない仕組み

前の項目で確認した AI にテストを任せる注意点のうち、この項目では「テストを緩めて通す」を対策することにしました。仕組みを 2 つ入れ、どちらも /goal で回して作ってもらいました。

1 つ目は予防的な統制で、PreToolUse の hook で、テストのファイルに skip や xfail など（無条件でテストをパスしようとする試み）を書き込もうとしたら拒否します。拒否の理由はエージェントに返るので、エージェントはそれを読んで別の方法を探します。ただし、Bash でファイルを書き換えたりした場合にはこの hook では検出できないので、これで完璧というわけではありません。

2 つ目は発見的な統制で、Stop hook でテストと実装を同じコミットで変えていたら、実装の都合でテストに手を加えたと判断して警告を出します。こちらもコミットを分ければすり抜けられるので、気休め程度です。

たまたま、2 つ目を作っている途中で、実装後のテストが一度失敗し、エージェントが実装をやり直す場面に出会いました。原因は、Stop hook の実行により生じたキャッシュのファイルを、hook 自身が「テストのフォルダに変更がある」と判定していたことでした。これにより判定に失敗してループを抜けられず、エージェントはテスト側の修正ではなく hook 側の中身を改良して作業を完了させました。テストを緩めずに実装を直すという、今回やりたかった対策を、実際に確認することができました。

こうして、テストに合格するまでエージェントに作業を続けさせることはできました。ただ、任せてみると、自分でコードを書く必要はなくなる一方で、コードが妥当なのか、そもそも Issue の内容や方針が妥当なのかは自分で判断する必要があり、それはそれで疲れるということもわかりました。

Issue から PR までを任せる

• 【調べる】エージェントが迷う点と、それを Issue にどう書くかを説明できるようにする
• 【動かす】Issue から PR までをエージェントに任せる

テストで品質を担保しながら PR を出してもらうことはできたので、Issue を何本も続けて任せたときに、エージェントがどこで迷うのかを見たいと考えました。

エージェント向けの Issue の書き方

GitHub の Copilot のドキュメントでは、エージェントに任せるタスクには、解決すべき問題の明確な説明、完全な受け入れ基準、変更すべきファイルの指示を含めるよう勧めています（GitHub Copilot を使用してタスクに取り組むためのベスト プラクティス）。Claude Code のベストプラクティスも、最初の節で「Claude に自分の作業を検証する方法を与える」を挙げています（Claude Code のベストプラクティス）。/goal の条件文に「どう示すか」を書いたのと同じ考え方です。練習用リポジトリの Issue は、この時点で「背景・動機」「やること」「注意点」「完了条件」の形になっていたので、これらは満たしていました。

点数計算を 4 本任せる

点数計算の本体を、子のロン・子のツモ・親のロン・親のツモの 4 つの Issue に分け、それぞれ前の項目の /goal の条件文で回しました。1 本目では、テストを書いて失敗させ（Red）、実装して通し（Green）、後の Issue で使い回せるように共通の計算を関数に切り出す（Refactor）、という 3 つのコミットが PR に並びました。2 本目以降はその関数を使うので、実装の追加は数行で済んでいます。軽微な Issue も 2 本任せ、合わせて 6 本の PR を出してもらいました。

エージェントが迷った点

任せた PR の内容と、エージェントが PR に書いてきた「気づいたこと」を振り返り、Issue に書いておけばよかったことを表にまとめました。

いちばん効いたのは、期待値の表を Issue に書き写したことです。PR ではテストのケースを表で書いてもらう運用にしたので、Issue の表と PR の表、テストを見比べるだけで確認できるようになりました。その過程で、参照していた早見表の 1 マスが計算式と合わないことにも気づきました。表だけを見ていると気づけない誤りで、出典をそのまま正解にするなら、Issue を立てる前に一度確かめる必要があります。

まとめた内容は、次回以降に活かせるように、Issue テンプレートと CLAUDE.md に反映してもらいました。このように、エージェントに渡す設定（ハーネス）は必要に応じて更新を続けることで、価値のある財産となっていきます。なお、同じ GitHub のページでは、開発者が理解を深めるための学習目的のタスクはエージェントに任せないほうがよいとされています（与えるタスクの適切な種類の選択）。今回はまさに学習目的なので、エージェントの作業内容を追いやすくするため、CLAUDE.md で PR に「初めて使った機能」の解説を書くよう指示し、毎回そこを読んで理解を補っています。

条件文の貼り付けを Skill にまとめる

6 本の Issue で、同じ /goal の条件文を毎回貼っていたので、その後、Issue 番号を渡すだけで済むように Skill とサブエージェントにまとめました。組み込みの /goal は Skill からは呼べないので、同じ判定を hooks で組んでいます。ところが、最初に動かしたときは、完了条件の判定が期待どおりに働いていませんでした。この原因の調査もエージェントに Issue として任せたところ、確認用のサブエージェントを作ってログを取り、サブエージェントの報告の仕方によっては hook の差し戻しが効かなくなることを突き止めてきました。原因の特定も検証も、人間よりはるかに速く進みます。人間に必要なのは方向性を示すことだと実感しました。

AI コードレビュー

• 【調べる】AI にコードレビューを頼む方法を調べる
• 【動かす】2 つのエージェントに同じ PR をレビューさせて比べる

適切な Issue を立ててエージェントに作業を依頼すると、かなり頻繁に PR を出してもらえるようになりますが、今度は PR を読む手間が残ります。そこで、レビューも AI に支援してもらうことにしました。

レビューの頼み方

AI にレビューを頼む方法は、大きく 4 つあります。

• Web チャット：git diff の結果などを貼り付けて頼む
• AI エディタ：エディタ上で「未コミットの差分をレビューして」などと頼む
• ターミナル：コーディングエージェントを起動して「main ブランチとの差分をレビューして」などと頼む
• GitHub 連携：GitHub Actions などで PR のイベントを拾い、自動でレビューさせる

今回はターミナルで頼みました。Claude には、GitHub 上で PR を自動レビューする Code Review という機能もありますが、Team / Enterprise プラン向けのリサーチプレビューなので、個人のプランでは使えません。個人のプランで使えるのは、手元で差分をレビューする /code-review コマンドです。引数なしならブランチのアップストリームより先のコミットと未コミットの変更を、PR 番号などを渡せばそれをレビューし、--comment を付けると結果を PR にコメントします。なお、GitHub Actions 版の Claude Code は、Pro や Max のサブスクリプションのトークンでも動かせるので（手動セットアップ）、GitHub 上での自動レビューは後の項目で試すつもりです。

2 つのエージェントで比べる

点数計算を API から呼べるようにした PR に、Claude Code の /code-review --comment を掛けました。結果は指摘 0 件で、GitHub には何も投稿されませんでした。報告では、確かめた点として次のようなものが挙がっていました。

- 親子・ツモ／ロンの 4 通りの組み合わせが、それぞれ正しい関数とレスポンスの形につながっています
- 不正な入力のときに 422 を返します。Issue の指定どおりです
- テストの期待値は 4 件とも Issue の表と一致しています
- ありえない組み合わせは Issue の「やらないこと」に入っているので、指摘の対象から外しています

比較用に、Antigravity CLI（モデルは Gemini 3.8 Flash）にも「PR のコードレビューをお願い」とだけ頼みました。Claude Code のようなレビュー用のコマンドは見当たらなかったので、依頼文は一言です。結果は「LGTM（Approve）」で、FastAPI の機能を活かした入力チェック、TDD の手順がコミット履歴に残っていること、関心の分離が守られていること、の 3 つを良い点として挙げ、今後の検討事項としてレスポンスの型を定義する案を添えていました。

Claude Code のほうは淡白で、仕様に沿っているかのチェックという印象です。Antigravity のほうは全体を見たうえで、今後の参考情報まで載せています。一見すると後者のほうが親切ですが、関心が発散しているとも言えるので、Issue の内容に絞った前者のほうが、長く付き合うにはよさそうです。/code-review は、正確性のバグと、再利用・簡素化・効率化の改善を報告するように作られていて、effort が low や medium なら確信の高い指摘だけを残します（努力とアーギュメントを調整する）。差の多くは、モデルよりも、レビュー用の手順が組み込まれているかどうかから来ていそうです。いずれにしても、レビューは将来 CI で自動化するつもりなので、依頼文の作り込みはそのときに考えることにしました。

テストの作成と実行の項目で確認した AI にテストを任せる注意点のうち、この項目は「テストの甘さの見落とし」に関連します。具体的には、別のエージェントにテストをレビューさせることがその対策です。ただ、今回の PR はシンプルな更新にとどまっていたので、実装とレビューでエージェントを変えることによる効果は実感できませんでした。

おわりに

GitHub につなぎ、テストを用意し、テストが通るまで回し、Issue から PR までを任せ、最後にレビューも任せる、と人が手を離す範囲を 1 つずつ広げてきました。そのたびに、CLAUDE.md・Issue テンプレート・hooks・Skill が、失敗を見て 1 つずつ増えていきました。こうしたルールを作り込んでいくことが、ハーネスを作り込んでいくことなのだと実感しています。一方で、今回の設定は Claude Code 固有のものが多く、別のベンダーのモデルに乗り換えるなら、いくつかは作り直しになります。Agent Skills のような標準化が、もっと進んでほしいところです。もしくは、Cursor や Kiro のような、複数のベンダーのモデルを呼べる AI エディタに乗り換えるというのも、必要になってきたのかもしれません。

ここまでは、自分が見ている前でエージェントに任せる段階です。次は協働者編③として、CI 上でエージェントを動かすなど、自分の手を離れて回すところへ進む予定です。