GitHub Agent HQでClaudeとCodexを使い分ける：Issue駆動AI開発をチーム運用に落とす設計メモ

Last updated at 2026-05-12Posted at 2026-05-12

はじめに：AIエージェントは「個人の便利ツール」から「開発レーン」になり始めた

2026年の開発現場では、AIコーディングエージェントの話題がかなり実務寄りになってきました。

少し前までは、話の中心はこうでした。

Claude Codeでどこまで書けるか
Codexにどこまで任せられるか
CursorやCopilotと比べてどれが強いか
MCPサーバーをどう増やすか

もちろん、これは今でも重要です。

ただ、最近の変化はそこではありません。

AIエージェントを、GitHub Issue、Pull Request、レビュー、CIの流れにどう組み込むか が本題になってきました。

GitHubはAgent HQの文脈で、ClaudeやCodexをGitHub上のエージェントとして扱える方向へ寄せています。

OpenAI Codexも、クラウド上のサンドボックスでタスクを並列実行し、GitHubから呼び出せるワークフローを前提にしています。

Claude Codeは、MCP、Hooks、Subagentsのような拡張ポイントを持ち、ローカルやチームの開発環境に深く入り込めます。

つまり、これからの論点はこうです。

どのAIが一番賢いか
  ↓
どの作業を、どのエージェントに、どの責任境界で渡すか

この記事では、GitHub Agent HQ / Codex / Claude Code / MCPを前提に、Issue駆動でAIエージェントを安全に使う設計 をまとめます。

この記事で扱うこと

この記事は「ツール紹介」ではなく、運用設計のメモです。

扱うのは以下です。

GitHub IssueをAIタスク仕様書として使う
ClaudeとCodexを役割で分ける
AGENTS.md / CLAUDE.md / Issueテンプレートで指示を標準化する
MCPを便利な接続口ではなく、権限境界として扱う
AI PRをレビュー可能な粒度に保つ
人間が最後に見るべきチェックポイントを決める

前提として、各ツールの現在位置は以下のように見ています。

ツール	得意な役割	向いているタスク
GitHub Agent HQ	エージェント作業の入口	Issue / PR / VS Codeからタスクを渡す
Codex	クラウド上での並列タスク実行	バグ修正、テスト追加、PR下書き
Claude Code	ローカル文脈の深い実装	大きめの設計変更、既存コード理解、調査
MCP	外部ツール接続	GitHub、DB、Sentry、Slack、Figmaなど
Hooks	強制ルール	format、test、禁止ファイル検知、ログ

なぜIssue駆動にするのか

AIエージェントに作業を渡す時、雑にプロンプトを投げると失敗します。

たとえば、こういう指示です。

管理画面をいい感じに改善して

人間同士でも危ない指示ですが、AI相手だとさらに危険です。

なぜならAIは、足りない前提をそれっぽく補完して作業を進めるからです。

結果として、以下が起きます。

UIだけ変わってデータ構造が追従していない
テストを追加したが実行されていない
既存の設計思想と違う抽象化が入る
触ってほしくないファイルまで変更する
PRが大きすぎてレビューできない

ここでGitHub Issueを使います。

Issueは、人間向けのタスク管理だけではなく、AIエージェント向けの作業仕様書になります。

AIに渡すIssueには、最低限これを書きます。

## Goal
何を達成したいか。

## Scope
触ってよい範囲。

## Non-goals
今回はやらないこと。

## Acceptance Criteria
完了条件。

## Verification
実行してほしい確認コマンド。

## Risk
壊れやすい箇所、注意点。

ポイントは、実装方法を細かく縛りすぎないが、完了条件と禁止範囲は明確にする ことです。

AIに自由度を渡すなら、同時に失敗条件も渡す必要があります。

まず作るべきIssueテンプレート

GitHubに以下のようなIssueテンプレートを用意します。

---
name: AI Agent Task
about: Claude / Codex / Copilot agentに渡す実装タスク
title: "[AI Task] "
labels: ["ai-agent"]
---

## Goal

<!-- 1文で目的を書く -->

## Context

<!-- 背景、関連PR、関連Issue、仕様メモ -->

## Target files

<!-- 触ってよいファイルやディレクトリ -->

- `src/...`
- `tests/...`

## Do not touch

<!-- 触ってほしくない範囲 -->

- `.env*`
- `package-lock.json` unless dependency changes are required
- database migrations unless explicitly requested

## Acceptance Criteria

- [ ] ...
- [ ] ...
- [ ] ...

## Verification

Run:

```bash
npm run lint
npm run test
npm run build
```

## Notes for agent

<!-- 実装方針、既存パターン、避けたい実装など -->

このテンプレートの狙いは、AIに「頑張って」ではなく、レビュー可能なPRを作ること を求める点です。

特に Do not touch は重要です。

AIエージェントは、問題を解くために周辺ファイルへ広がりがちです。

その広がりが価値になることもありますが、チーム運用ではレビューコストが跳ねます。

最初は狭く渡した方が、成功率が上がります。

AGENTS.mdでチームの標準ルールを書く

Issueテンプレートだけでは、毎回同じことを書くことになります。

そこで、リポジトリ直下に AGENTS.md を置きます。

Claude Codeなら CLAUDE.md、Codexならエージェント向けのプロジェクト指示ファイルとして扱える形にしておくと便利です。

例です。

# Agent Instructions

## Project

This repository is a production web application.
Prefer small, reviewable changes.

## Default workflow

1. Read the related issue and existing code before editing.
2. Keep changes inside the requested scope.
3. Reuse existing components and helpers.
4. Add or update tests when behavior changes.
5. Run the verification commands listed in the issue.
6. Summarize changed files and remaining risks.

## Coding rules

- Do not introduce a new UI library.
- Do not change public routes unless the issue says so.
- Do not modify environment files.
- Do not commit generated secrets, tokens, or local logs.
- Prefer existing patterns over new abstractions.

## PR summary format

Use this format:

### Summary
- ...

### Verification
- ...

### Risk
- ...

ここに書くべきなのは、抽象的な思想ではありません。

AIが毎回間違えやすい、具体的なルールです。

たとえば、以下は効果があります。

使ってよいパッケージ
使ってはいけないパッケージ
テストコマンド
ルーティングの制約
デザインシステムの入口
DBマイグレーションの扱い
PR本文のフォーマット

逆に、以下はあまり効きません。

高品質なコードを書いてください。
保守性を高くしてください。
バグを出さないでください。

人間にもAIにも、曖昧すぎます。

ClaudeとCodexをどう使い分けるか

個人的には、ClaudeとCodexを「どちらが上か」で見ない方が運用しやすいです。

役割で分けます。

Codexに渡しやすいタスク

Codexは、クラウド上で独立したタスクを並列に投げやすいのが強みです。

向いているのは、完了条件が明確な作業です。

failing testの修正
小さなバグ修正
テスト追加
型エラーの修正
PR差分レビュー
既存実装の説明
セキュリティ観点の確認

Issue例です。

## Goal

Fix the bug where the invoice total is rounded incorrectly when tax is included.

## Target files

- `src/domain/invoice.ts`
- `src/domain/invoice.test.ts`

## Acceptance Criteria

- [ ] Tax-included total uses floor rounding only at the final display step.
- [ ] Existing tax-exclusive behavior does not change.
- [ ] Regression tests cover both paths.

## Verification

```bash
npm run test -- invoice
```

この粒度なら、Codexにそのまま渡しやすいです。

Claude Codeに渡しやすいタスク

Claude Codeは、既存コードの文脈を深く読ませたい時に強いです。

向いているのは、調査と設計判断を含む作業です。

複数モジュールにまたがる設計変更
既存コードの責務整理
画面フローの改善
MCP経由の外部ツール連携
ローカルでの再現確認
Subagentを分けた調査

Issue例です。

## Goal

Refactor the onboarding flow so that account creation and workspace creation are separate steps.

## Context

The current flow mixes user creation, workspace creation, and billing setup.
This makes retry behavior hard to reason about.

## Target files

- `src/app/onboarding/**`
- `src/server/onboarding/**`
- `tests/onboarding/**`

## Non-goals

- Do not change billing provider integration.
- Do not redesign the visual layout.

## Acceptance Criteria

- [ ] User creation can succeed even if workspace creation fails.
- [ ] Workspace creation can be retried.
- [ ] Billing setup remains untouched.
- [ ] Tests cover the retry path.

こういう作業は、最初にClaude Codeへ「調査だけ」させるのも有効です。

このIssueを実装する前に、影響範囲、既存の責務分離、壊れやすいテストを調べてください。
まだ編集しないでください。

調査結果を見てから実装に進めると、PRが荒れにくくなります。

MCPは「便利機能」ではなく「権限境界」

MCPは、AIエージェントが外部ツールへ接続するための強力な仕組みです。

GitHub、Slack、Figma、Sentry、Postgresなどにつなぐと、AIがかなり実務に近い動きをできます。

ただし、MCPは便利なだけではありません。

権限境界そのもの です。

たとえば、Postgres MCPをつなぐ場合、AIにどこまで許すかを分ける必要があります。

MCP権限	許可する例	危険な例
read-only	スキーマ確認、SELECT	個人情報の広範囲取得
write-limited	seed追加、検証用insert	本番テーブル更新
admin	migration実行	DROP / TRUNCATE

最初はread-onlyで十分です。

AIにDBを読ませたい時も、以下のようにIssue側で目的を狭めます。

## MCP access

Postgres MCP may be used only for:

- Reading table names
- Reading column names
- Checking indexes

Do not query user rows or production personal data.

これを書かないと、AIは「調査に必要」と判断して広く見に行く可能性があります。

MCPは「できることを増やす」前に、「してよいことを狭く定義する」方が大事です。

HooksでAIの作業を強制的に整える

Claude CodeのHooksのような仕組みは、AI運用ではかなり重要です。

LLMへのお願いだけでは、毎回同じ行動を保証できません。

Hooksを使うと、以下を機械的に挟めます。

ファイル編集後にformatterを走らせる
.env や秘密鍵の編集をブロックする
package.json 変更時に確認を要求する
テスト未実行のまま終了しそうなら止める
MCP write操作をログに残す

たとえば、疑似コードではこういう考え方です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/scripts/agent-post-edit-check.sh"
          }
        ]
      }
    ]
  }
}

agent-post-edit-check.sh では、プロジェクトごとに最低限のチェックをします。

#!/usr/bin/env bash
set -euo pipefail

if git diff --name-only | grep -E '(^|/)\.env'; then
  echo "Do not edit environment files." >&2
  exit 1
fi

if git diff --name-only | grep -E 'package(-lock)?\.json'; then
  echo "Dependency files changed. Explain why in the PR summary." >&2
fi

これはAIを疑うためではありません。

人間のレビュー前に、毎回同じ最低ラインを通すためです。

AI PRは「小さく、失敗理由が読める」ことが大事

AIに任せると、PRが大きくなりがちです。

大きなPRは、人間がレビューできません。

人間がレビューできないPRは、AIを使って速く作った意味が薄れます。

目安として、最初の運用ではこれくらいに制限すると安定します。

項目	目安
変更ファイル	10ファイル以内
PRの目的	1つ
UI変更	1画面または1コンポーネント単位
DB変更	1 migrationまで
外部API変更	1 providerまで

Issueにも書いておきます。

## PR size limit

Keep the PR reviewable.

- Prefer fewer than 10 changed files.
- If the task requires more, stop and explain the split plan.

AIが作業中に「これは分割した方がよい」と判断できるようにするのがポイントです。

実務フロー案：人間1人 + AI複数体

実際の運用は、以下の流れが扱いやすいです。

重要なのは、AIを一発で正解させようとしないことです。

AIエージェントは、実装者としては速いです。

しかし、プロダクト判断者ではありません。

人間は以下を見るべきです。

その変更は本当に必要か
仕様の解釈は合っているか
レビュー可能な粒度か
本番データや顧客影響はないか
失敗時に戻せるか

AIに任せるほど、人間はコードを書く時間より、責任境界を決める時間が増えます。

エージェントに投げるプロンプト例

GitHub IssueからCodexやClaudeへ渡す時は、以下のように短くします。

Please work on this GitHub issue.

Follow the repository AGENTS.md.
Keep changes scoped to the issue.
Do not touch files listed in "Do not touch".
After changes, run the verification commands in the issue.
Open a draft PR with Summary, Verification, and Risk sections.

Claude Codeで最初に調査だけさせるなら、こうです。

Investigate this issue first.

Do not edit files yet.
Return:

1. Relevant files
2. Current behavior
3. Proposed implementation plan
4. Risks
5. Suggested split if this is too large

CodexにPRレビューをさせるなら、こうです。

Review this PR diff.

Focus on:

- behavioral regressions
- missing tests
- security risks
- over-broad changes
- unclear migration or deployment risk

Return only actionable findings with file and line references when possible.

AIに「自由に考えて」と投げるより、出力形式を固定した方がレビューしやすいです。

失敗パターンと対策

失敗1：Issueが抽象的すぎる

UXを改善して

これは危険です。

少なくとも以下に分解します。

ユーザー登録フォームで、メールアドレスの入力エラーが送信後にしか表示されない。
入力中またはblur時にエラーを表示し、既存の送信時バリデーションは残す。

失敗2：AIが勝手に依存関係を増やす

IssueかAGENTS.mdに書きます。

Do not add dependencies unless the issue explicitly allows it.
If a dependency seems necessary, stop and explain why.

失敗3：PRが巨大化する

AIに中断条件を渡します。

If the change exceeds 10 files or needs schema changes, stop and propose a split.

失敗4：MCPが強すぎる

最初はread-onlyにします。

DB、Slack、GitHub write系は、用途ごとに分けます。

github-read
github-write-pr-only
postgres-read-schema
postgres-read-anonymized
slack-read-channel

「1個の強いMCP」より「用途別の弱いMCP」を増やす方が安全です。

失敗5：CIを見ずに完了扱いにする

Issueテンプレートに必ずVerificationを書きます。

AIが実行できない場合も、PR本文に明記させます。

### Verification

- [x] npm run lint
- [ ] npm run test
  - Not run: local database is not available in the agent environment.

未実行を隠されるより、未実行だと分かる方がレビューできます。

小さく始めるなら、この3点だけでいい

いきなりAgent HQ、Codex、Claude Code、MCP、Hooksを全部整える必要はありません。

最初はこれだけで十分です。

1. AI用Issueテンプレートを作る

Goal、Scope、Non-goals、Acceptance Criteria、Verificationを書けるようにします。

2. AGENTS.mdを置く

テストコマンド、触ってはいけないファイル、PR本文形式を書きます。

3. AI PRを小さく制限する

10ファイル以内、目的1つ、テスト結果必須。

これだけでも、AIエージェントの出力はかなりレビューしやすくなります。

まとめ：AIエージェント運用の本質は「指示」ではなく「設計」

Claude、Codex、Copilot、CursorのようなAIコーディングツールは、今後も速くなります。

しかし、チームで使う時に差が出るのは、モデル性能だけではありません。

差が出るのは、以下です。

Issueが仕様書になっているか
エージェントごとの役割が決まっているか
MCPの権限が狭く定義されているか
PRがレビュー可能な粒度か
CIと人間レビューが最後に残っているか

AIエージェントに任せるほど、人間の仕事は「コードを書く」から「作業単位と責任境界を設計する」へ寄っていきます。

これは、エンジニアの仕事がなくなるという話ではありません。

むしろ逆です。

AIが速く動けるようになった分、人間側のIssue設計、レビュー設計、権限設計の質が、そのまま開発速度と事故率に出ます。

2026年のAI開発で本当に効くのは、強いプロンプト1本ではなく、エージェントが迷わず小さく安全に動ける開発レーン だと思っています。

参考

この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表 / AIアーキテクト
Next.js / TypeScript / n8nを活用した自律型アーキテクチャ設計を専門としています。
日々の自動化の検証結果や、ビジネス側の視点（ROI等）に関するより深い考察は、以下の公式サイトおよびnoteで発信しています。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up