GitHub Agent HQ使い方 Claude/Codex自動ルーティング

「Issueは増えるのに、ClaudeとCodexのどっちに投げるか毎回迷う…」という状態、めっちゃ起きやすいですよね。特にMac miniでself-hosted runnerを回していると、せっかく高速な実行基盤があるのに、入口の振り分けが手作業だと一気に詰まります。この記事では、GitHub Agent HQの使い方として、Issueタイプ別にClaude/Codexを自動ルーティングする実装を、今日から動かせる粒度でまとめます。

GitHub Agent HQ実践編とは？使い方の全体像

GitHub Agent HQは、ざっくり言うと「Issueの受付窓口」と「AIエージェント実行基盤」をつなぐ運用レイヤーです。ポイントは、AIを直接呼ぶことよりも先に、Issueを構造化することです。ここが曖昧だと、ClaudeにもCodexにも同じ粒度の依頼が飛んでしまって、品質も速度も安定しません。

僕が実務で意識しているのは、次の3段階です。イメージとしては、物流センターと同じで、仕分け・配送・追跡の順番です。

1. 分類 — Issueテンプレートとラベルで「何の仕事か」を確定する
2. 実行 — ラベルに応じてClaudeかCodexへ自動ルーティングする
3. 評価 — 完了時間・差し戻し率・再オープン率を毎週見る

この3段階を分けると、非エンジニアのメンバーでも「このIssueはspec系だからClaude」「このIssueは実装系だからCodex」と会話できます。GitHub Agent HQ 使い方の本質は、モデル選定ではなく運用設計を分離することです。ここができると、チーム全体の判断コストが一気に下がります。

ちなみに、僕の技術ブログ運用でも手順型の記事が強くて、週次データで主力記事が386PV/81eng（上位20ページPVの57.2%）を占めています。再現性の高い型は、開発運用でもコンテンツ運用でも同じく強いです。

Claude Codex 使い分け設計：Issueタイプで分ける

ClaudeとCodexの使い分けは、モデル性能の優劣で決めるより、Issueの性質で決める方がブレません。僕は最初に「思考中心か、編集中心か」で2分割し、運用が回り始めてから細分化しています。

まずは次の比較で決めるのがシンプルです。

最初から5分類にしなくても大丈夫です。最初の2週間は「spec系=Claude」「code系=Codex」だけで十分回せます。分類を増やすのは、差し戻し理由が偏ってからでOKです。

注意点として、緊急障害対応を完全自動にするのはおすすめしません。P1/P0は必ず人間レビューを挟むルールにしておくと、事故率が下がります。つまり、使い分けの目的は「人をなくす」ではなく「人の判断を必要な場所に集中させること」です。

Mac mini self-hosted runner構成と初期セットアップ

Mac mini self-hosted runnerは、低消費電力で24時間回しやすいのが強みです。僕は常時稼働ノードを1台、メンテ用の予備ノードを1台の2台構成にしています。最初の1台を作るなら、Mac miniの最新モデル（紹介リンク）を基準に、メモリは最低16GBから始めると運用が安定しやすいです。

セットアップは次の順で進めると詰まりにくいです。

1. Runner専用ユーザー作成 — 管理者アカウントとは分離
2. GitHub Runner登録 — リポジトリ単位ではなくOrganization単位を優先
3. ラベル設計 — self-hosted macOS mac-mini agenthq を付与
4. サービス常駐化 — 再起動後も自動復帰するように設定
5. 監視追加 — ディスク残量とジョブ失敗通知をSlack連携

# 例: runner導入の最小コマンド
mkdir actions-runner && cd actions-runner
curl -o actions-runner-osx-arm64.tar.gz -L https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64.tar.gz
tar xzf ./actions-runner-osx-arm64.tar.gz
./config.sh --url https://github.com/your-org --token YOUR_TOKEN --labels self-hosted,macOS,mac-mini,agenthq
sudo ./svc.sh install
sudo ./svc.sh start

「速いマシン」より「止まらない運用」の方が、最終的な開発速度は上がります。ここは地味ですが、長期では差が大きいです。

GitHub Agent HQで自動ルーティングを実装する手順

ここから実装です。流れはシンプルで、Issue作成時にラベルを付け、Actionsでラベルを読んでClaude/Codexを切り替えます。まずIssueテンプレート側で、最低限の分類ラベルを強制します。

1. Issueラベルを固定化する

• spec — 仕様・要件・設計相談
• bug — 不具合修正
• refactor — 既存実装の改善
• docs — ドキュメントのみ

次に、GitHub Actionsでラベルに応じて実行先を決めます。Claude実行側はClaude Code公式ページ（紹介リンク）の設定に合わせてスクリプト化しておくと、差し替えが楽です。

2. ルーティングWorkflowを作る

name: issue-agent-router

on:
  issues:
    types: [opened, edited, labeled]

jobs:
  route:
    runs-on: ubuntu-latest
    outputs:
      agent: ${{ steps.pick.outputs.agent }}
    steps:
      - id: pick
        uses: actions/github-script@v7
        with:
          script: |
            const labels = context.payload.issue.labels.map(l => l.name)
            let agent = "claude"
            if (labels.includes("bug") || labels.includes("refactor")) agent = "codex"
            if (labels.includes("spec") || labels.includes("docs")) agent = "claude"
            core.setOutput("agent", agent)

  execute:
    needs: route
    runs-on: [self-hosted, macOS, mac-mini, agenthq]
    steps:
      - uses: actions/checkout@v4
      - name: Run selected agent
        run: |
          if [ "${{ needs.route.outputs.agent }}" = "codex" ]; then
            ./scripts/run-codex.sh "${{ github.event.issue.number }}"
          else
            ./scripts/run-claude.sh "${{ github.event.issue.number }}"
          fi

この形のメリットは、エージェント実装を差し替えてもWorkflow本体をほぼ触らなくていいことです。つまり、判断ロジック（ラベル）と実行ロジック（スクリプト）を分けられます。GitHub Agent HQの実践では、この分離が保守性の生命線です。

運用初期は「自動実行+人間承認コメント」を入れるのがおすすめです。完全自動にいきなり振り切らず、2週間だけ半自動にすると精度が安定しやすいです。

運用KPIと改善サイクル：回しながら精度を上げる

自動化は作って終わりじゃなく、数字で回して初めて価値になります。僕は週次で3つだけ見ます。初回レスポンス時間、差し戻し率、再オープン率です。KPIを増やしすぎると、見るだけで疲れて続きません。

この運用は、僕が業務効率化ツールで月80時間削減したときの進め方と同じです。最初に完璧な設計を狙うより、週単位でボトルネックを1つずつ潰す方が結果が出ます。「分類ミスが多い週はラベル定義を見直す」みたいに、改善点を1つだけ決めるのが継続のコツです。

自動ルーティングを放置した先に待つ現実

ここを後回しにすると、じわじわコストが積み上がります。ラベルなしIssueが増えると、毎回の判断が属人化して、担当者不在の日に止まります。さらに、ClaudeとCodexの使い分け基準が人によってズレると、レビュー観点もバラバラになります。この状態を知らないままだと、処理速度より先にチームの心理的コストが上がる可能性があります。結果として、自動化したはずなのに「前より管理が大変」という逆転現象が起きやすいです。

この記事を書いている理由

僕はSESで実装現場を経験したあと、人材開発で550名以上のキャリア面談をしてきました。その中でずっと感じていたのは、「技術そのもの」より「伝わる設計」の方が組織成果に直結するということです。今は福祉領域のITを担当していて、非ITメンバーと一緒に運用設計する機会が多いです。だからこそ、AIエージェント運用も、専門家だけが扱える形じゃなく、現場の言葉で回る形にしたいんです。僕自身がITと非ITの間を行き来してきたからこそ、この橋渡しを具体的に届けたいと思っています。

次のアクション

まずは今週、Issueラベルを4種類に固定して、1本だけルーティングWorkflowを動かしてみてください。詰まったらコメントで状況を投げてもらえたら、次に直すポイントを一緒に言語化します。導入時の確認用に、GitHub Actionsの公式ページ（紹介リンク）も貼っておきます。