Skip to content

全面リライト: GitHub AgentOps 実践ガイドを 2026 年時点の商用レベル実務書に再構成する #37

Description

@ootakazuhiko

実装者

codex cli gpt-5.4 xhigh

目的

本書を 2026-04 時点の GitHub / GitHub Copilot / OpenAI Codex の公式仕様と実運用に合わせて全面リライトする。
狙いは、「入門的な運用ガイド」から「企業導入・統制・監査・セキュリティ・コスト管理まで扱う商用レベルの実務書」へ引き上げること。

背景

現行本の骨格は良いが、現時点では次が弱い。

  • instruction 層の説明が AGENTS.md 中心で、repo-wide / path-specific / agent-specific instruction の役割分担が薄い
  • GitHub ネイティブな運用面が、cloud agent / code review / custom agents / hooks / MCP / rulesets / required workflows / merge queue 前提に再構成されていない
  • 第9章が Codex Action 中心で、現在の実装選択肢比較としては狭い
  • 商用レベルに必要な「導入判断」「統制設計」「例外運用」「予算管理」「運用レビュー指標」「展開ロードマップ」が弱い

リポジトリ運用ルール

  • src/ 配下を編集する。docs/ は生成物なので手編集しない
  • 変更後は npm test を実行し、lint/build/link-check を通す
  • PR ではこの Issue を参照する
  • 文章は日本語。ビジネス用途に耐える、断定しすぎない、過度に煽らない文体にする
  • 一次情報優先。古い二次情報やブログ断片で本文を組まない
  • 変化しやすい数値や preview 状態は、本文で断定しすぎず、必要なら「2026-04 時点」と明記する

編集方針

  • 部分修正ではなく、章立て・見出し・導入・まとめ・付録まで含めて再設計する
  • 書名 GitHub AgentOps 実践ガイド は原則維持してよいが、副題・章名・小見出しは現在の実運用に合わせて刷新してよい
  • 本全体の重心を「GitHub ネイティブな AgentOps の設計と統制」に置き、その中で OpenAI Codex を重要な実装パスとして扱う
  • 単なる機能紹介ではなく、「どの制御面をどう組み合わせるか」「何を人間に残すか」「どの方式をどの条件で選ぶか」が判断できる本にする
  • 初学者向けの GitHub 基本説明に紙幅を使いすぎない。読者は開発リーダー、テックリード、Platform/DevEx、SRE、セキュリティ担当、メンテナーを想定する
  • 例は toy project ではなく、商用/組織運用を意識した前提で書く
  • 各章に、判断基準、比較表、アンチパターン、導入順序、チェックリストの少なくともどれかを入れる
  • preview / public preview の機能は、便利機能として扱ってよいが、本文の基幹前提にしすぎない
  • Companion repo の既存リンクを壊さない。新しい companion asset が必要でも、存在しないファイルへのリンクは貼らない。必要なら PR 本文でギャップを明示する

推奨する再構成(11章は維持してよいが、中身は刷新すること)

第1章:2026年の GitHub AgentOps 概観と責任分界

  • Human / Agent / CI の責任分界を維持しつつ、GitHub 上での research / plan / branch / PR / review / merge まで含めた運用モデルに更新する
  • 「人間が判断する境界」「AI に委譲してよい境界」「CI で担保する境界」を、実務の責任線として書き直す
  • 章冒頭で、本書が扱う control plane 一覧を見せる

第2章:Agent-ready repo の成熟度モデル

  • 現行の最小要件を、導入レベル別の maturity model に拡張する
  • Issue / PR テンプレ、DoD、CODEOWNERS、required checks、environments、auditability を、最小/標準/高度 の3段階程度で整理する
  • 「最初に整えるもの」と「後から強化するもの」を分ける

第3章:Instruction hierarchy と context 設計

  • AGENTS.md 単独の章ではなく、.github/copilot-instructions.md.github/instructions/**/*.instructions.mdAGENTS.md の役割分担に再構成する
  • repo-wide / path-specific / agent-specific context をどう分けるか、何をどこに書くか、競合時の考え方、メンテナンス方針を整理する
  • 「長い AGENTS.md 1 枚に寄せる」以外の設計を示す

第4章:再利用レイヤー(Skills / custom agents / hooks)

  • Skills は再利用可能なワークフローとして整理し直す
  • custom agents は役割固定の専門エージェントとして整理する
  • hooks は実行前後の制御・監査・禁止・検証レイヤーとして位置づける
  • instruction / skill / custom agent / hook の違いを、用途ベースで比較する

第5章:Policy と control surface 設計

  • 現行の allow / prompt / forbidden を抽象概念で終わらせず、どの制御面で実装するかに落とし込む
  • 例: approvals、hooks、rulesets、Actions policy、required workflows、CODEOWNERS、environments、manual gates
  • 「ルールを書く」ではなく「執行可能な形でルールを置く」章にする

第6章:GitHub ネイティブな実行フロー

  • Issue → research/plan → branch → PR → code review → merge の流れを、GitHub 上の agent 運用として再設計する
  • Copilot cloud agent(初出で旧称は一度だけ注記可)、Copilot code review、GitHub 上の third-party agents をこの章で整理する
  • 人間による steering comment / review / accept / reject のログ設計を強化する
  • 「小さい Issue」「PR を小さく保つ理由」「差し戻し時の再委譲」まで書く

第7章:MCP と tool exposure 設計

  • MCP を「便利な拡張」ではなく、tool exposure / authority boundary / secret boundary の設計問題として扱う
  • read-only / mutating / external side effect の区分、公開範囲、最小公開、危険な接続の避け方を書く
  • org / enterprise policy、registry / allowlist 的な観点、autonomous tool use のリスクを明示する

第8章:コスト・予算・利用ガバナンス

  • premium requests / Actions minutes / overage / budget / policy / analytics を前提に書き直す
  • 「どこで金がかかるか」だけでなく、「誰の quota に載るか」「自動実行と手動実行をどう使い分けるか」「コスト最適化の優先順位」を整理する
  • 読者が予算会議や運用レビューで説明できる内容にする

第9章:継続的 AI の実装パターン

  • 現行の Codex Action 中心の章を刷新し、以下を比較する章にする
    • PR 要約 / リスク抽出
    • Copilot code review
    • GitHub 上の cloud agent / third-party agents
    • ローカル/ターミナルでの OpenAI Codex CLI
    • 必要なら Codex Action を「1 つの選択肢」として扱う
  • この章は「何を CI に入れるか」「何を GitHub 上で回すか」「何をローカルで回すか」の選択基準を示すこと
  • openai/codex-action@v1 を残す場合も、中心ではなく比較対象の一つとして位置づける

第10章:セキュリティ・秘密情報・供給網

  • fork PR、pull_requestpull_request_target、最小権限、Secrets、OIDC、action pinning、push protection、artifact attestations、secret scanning、dependency/supply chain の話を実務線でまとめる
  • 「危ないからやめる」ではなく、「どこまでなら許容できるか」「何を承認必須にするか」「どのログを残すか」を書く
  • content exclusions 的な例外や、agent が見てしまう/触れてしまう前提の注意点も明示する

第11章:メトリクス・運用レビュー・展開ロードマップ

  • 現行の lead time / review time / 差し戻し率 だけでなく、adoption、merged PR outcome、rework、human override、security exception、cost efficiency などの運用指標に拡張する
  • 「何を毎週/毎月見るか」「導入初期と定着期でどの指標を重視するか」を整理する
  • 最後に rollout roadmap / maturity roadmap を入れて、導入順序で閉じる

付録の改稿方針

  • 付録A:テンプレ集
    • AGENTS.md
    • .github/copilot-instructions.md
    • .github/instructions/**/*.instructions.md
    • .github/agents/*.agent.md
    • .github/hooks/*.json
    • Skills (SKILL.md)
    • Issue / PR / review / risk log のテンプレ
  • 付録B:プレイブック集
    • バグ修正
    • 依存更新
    • テスト追加
    • ドキュメント保守
    • security fix / review assist / rollout review など、商用運用で使うプレイブックを追加
  • 付録C:トラブルシュート
    • ambiguity
    • oversized PR
    • flaky checks
    • ruleset / required workflow / merge queue 由来の詰まり
    • permission / secret / fork PR 問題
    • MCP / hook / custom agent 由来の運用事故
      を追加・更新する

必ず入れる表・図・チェックリスト

  • instruction layer 比較表
  • execution path 比較表(cloud agent / code review / third-party agent / Codex CLI / Codex Action)
  • control surface 対応表(allow/prompt/forbidden をどこで執行するか)
  • trust boundary / secret boundary の表
  • rollout maturity matrix
  • 月次運用レビューの観点表
  • 主要なアンチパターン一覧

明確に更新してほしいポイント

  • AGENTS.md を唯一の正解として書かない
  • GitHub 上の agent 運用を、cloud agent / code review / custom agents / hooks / MCP / rulesets まで含めて説明する
  • OpenAI Codex は、GitHub 上の third-party agent と、ローカル実行の Codex CLI の両方を視野に入れて書く
  • Codex CLI の文脈では、AGENTS.md.codex/config.toml、approval/sandbox/network controls、skills の使い分けを明示する
  • volatile な plan / quota / pricing は、一覧暗記型ではなく「どう読むか」「どこを確認すべきか」を中心に書く
  • 現在の製品名称に合わせて用語を正規化する
  • preview 機能は、初出でその旨を明記し、本文全体の根幹前提にしすぎない

非目標

  • GitHub の基本操作を一から教える入門書化
  • AI 一般論や未来予測の水増し
  • 特定 UI のスクリーンショット依存
  • 1 つの製品や 1 つの実行方式だけを正解として押し出すこと
  • 変わりやすい料金や preview 状態を、日付なしで断定すること

受入基準

  • 本文が「更新の寄せ集め」ではなく、最初から最後まで一冊の実務書として読める
  • src/ 配下の主要ページ(導入、各章、付録)が一通り改稿されている
  • 第3章が instruction hierarchy に更新されている
  • 第4章/第5章が skills / custom agents / hooks / policy enforcement まで広がっている
  • 第6章/第7章が GitHub ネイティブな agent 運用と MCP/tool exposure を商用レベルで説明している
  • 第8章が premium requests / Actions minutes / budgets / analytics を含む
  • 第9章が Codex Action 単独中心ではなく、複数の実装パターン比較になっている
  • 第10章が fork PR / pull_request_target / least privilege / OIDC / push protection / artifact attestations / supply chain まで含む
  • 第11章が flow・quality・security・cost・adoption を横断する運用指標になっている
  • 付録A/B/C が現行 ecosystem に合わせて更新されている
  • 内部リンク・外部リンクが壊れていない
  • npm test が通る
  • PR 本文に、旧構成→新構成の対応表、主な更新理由、未解決点(あれば)が書かれている

補足

差分最小化より、本としての完成度を優先してよいです。
現行の章番号を維持すること自体は目的ではありません。必要なら章名・節構成・導入順序を大胆に見直してください。
ただし、読者が「いま何を、なぜ、どの順で導入すべきか」を理解できる構成にしてください。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions