GitHub AgentOps 実践ガイド

第6章：GitHub Agents 運用（Issue→PR→反復→マージ）

この章で扱うこと

  • 標準フロー（Issue→PR→レビュー→反復→マージ）
  • 失敗パターン（仕様不足、差分肥大、テスト不足）と対処

標準フロー（最小）

GitHub 上でのエージェント運用は、次のループを「短く回す」ことが要点です。

  1. Issue（実行仕様）：目的/スコープ/受入基準/制約/検証を固定
  2. エージェント実行：調査→実装→テスト→ドキュメント→自己検証
  3. PR 作成：変更意図、検証結果、リスク、ロールバックを記録
  4. レビュー：仕様差分（決定事項）をコメントで残す
  5. 反復：指摘→最小修正→再検証（CI を起点にする）
  6. マージ：人間が最終責任を持つ

ステアリング（仕様差分を「決定」として残す）

エージェント運用で重要なのは、途中で仕様が変わること自体ではなく、変更理由が残らない ことです。 ステアリングでは、次の粒度でコメントを残します。

  • 何を変える決定をしたか（受入基準の追加/緩和、非スコープ化など）
  • なぜそうしたか（背景、制約、リスク）
  • 影響範囲（誰に/どこに影響するか）

これにより、後から「なぜこの実装になったか」を追跡できます。

ミニ例：ステアリングコメント（決定ログ）

Issue/PR コメントとして残す最小形です。未確定事項は推測で断定せず、追跡できる形で分離します。

[Decision] 受入基準を追加: 「PR 本文にロールバック手順を必須とする」
理由: 変更影響の説明責任を担保し、緊急時に切り戻せる状態を維持するため
影響: PR テンプレ更新が必要（適用は次PRから）
未確定: 既存PRへの遡及適用は要議論（運用負荷の評価が必要）

ミニ例：PR 本文（運用ログ）

PR 本文に「意図/検証/リスク/ロールバック」を固定します。テンプレは一例です。

## 変更内容
- （何を変えたか）

## 検証
- `npm test`: OK

## リスク
- （影響範囲、想定される副作用）

## ロールバック
- revert するコミット/手順（または機能フラグで無効化）

失敗パターンと対処（最小）

仕様不足（曖昧な Issue）

  • 症状：成果がブレる、手戻りが増える、レビューで揉める
  • 対処：不足情報を質問として返す／選択肢（案A/案B）と判断材料を提示する

差分肥大（1PR が大きい）

  • 症状：レビュー不能、リスク評価不能、ロールバックが難しい
  • 対処：PR を分割（1PR=1意図）／先に安全柵（テスト/型/静的解析）を置く

テスト不足（検証が弱い）

  • 症状：CI は通るが品質が担保できない、回帰が起きる
  • 対処：受入基準→テスト観点→粒度選定の順に整理し、必要ならテストを先に追加する

ミニ例：CI 失敗時の反復（Runbook 断片）

CI を起点に「短いループ」で収束させます。

  1. 失敗ジョブのログから、失敗コマンドとエラー箇所を特定する
  2. ローカルで同じコマンドを実行し、再現性を確認する（環境差分があれば記録する）
  3. 最小修正→再実行を繰り返し、原因と対処を PR に残す

Companion 資産（参照先）

Companion repo: itdojp/GitHub-AgentOps-companion

  • Issue 実行仕様テンプレ: .github/ISSUE_TEMPLATE/agent-task.yml
  • PR テンプレ: .github/PULL_REQUEST_TEMPLATE.md

章末チェックリスト（ドラフト）

  • 反復のログが GitHub 上に残る（Issue コメント / PR コメント）
  • 仕様差分が「決定」として追跡できる
Edit this page on GitHub