実装者
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.md、AGENTS.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_request と pull_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 状態を、日付なしで断定すること
受入基準
補足
差分最小化より、本としての完成度を優先してよいです。
現行の章番号を維持すること自体は目的ではありません。必要なら章名・節構成・導入順序を大胆に見直してください。
ただし、読者が「いま何を、なぜ、どの順で導入すべきか」を理解できる構成にしてください。
実装者
codex cli gpt-5.4 xhigh
目的
本書を 2026-04 時点の GitHub / GitHub Copilot / OpenAI Codex の公式仕様と実運用に合わせて全面リライトする。
狙いは、「入門的な運用ガイド」から「企業導入・統制・監査・セキュリティ・コスト管理まで扱う商用レベルの実務書」へ引き上げること。
背景
現行本の骨格は良いが、現時点では次が弱い。
AGENTS.md中心で、repo-wide / path-specific / agent-specific instruction の役割分担が薄いリポジトリ運用ルール
src/配下を編集する。docs/は生成物なので手編集しないnpm testを実行し、lint/build/link-check を通す編集方針
GitHub AgentOps 実践ガイドは原則維持してよいが、副題・章名・小見出しは現在の実運用に合わせて刷新してよい推奨する再構成(11章は維持してよいが、中身は刷新すること)
第1章:2026年の GitHub AgentOps 概観と責任分界
第2章:Agent-ready repo の成熟度モデル
第3章:Instruction hierarchy と context 設計
AGENTS.md単独の章ではなく、.github/copilot-instructions.md、.github/instructions/**/*.instructions.md、AGENTS.mdの役割分担に再構成する第4章:再利用レイヤー(Skills / custom agents / hooks)
第5章:Policy と control surface 設計
第6章:GitHub ネイティブな実行フロー
第7章:MCP と tool exposure 設計
第8章:コスト・予算・利用ガバナンス
第9章:継続的 AI の実装パターン
openai/codex-action@v1を残す場合も、中心ではなく比較対象の一つとして位置づける第10章:セキュリティ・秘密情報・供給網
pull_requestとpull_request_target、最小権限、Secrets、OIDC、action pinning、push protection、artifact attestations、secret scanning、dependency/supply chain の話を実務線でまとめる第11章:メトリクス・運用レビュー・展開ロードマップ
付録の改稿方針
AGENTS.md.github/copilot-instructions.md.github/instructions/**/*.instructions.md.github/agents/*.agent.md.github/hooks/*.jsonSKILL.md)を追加・更新する
必ず入れる表・図・チェックリスト
明確に更新してほしいポイント
AGENTS.mdを唯一の正解として書かないAGENTS.md、.codex/config.toml、approval/sandbox/network controls、skills の使い分けを明示する非目標
受入基準
src/配下の主要ページ(導入、各章、付録)が一通り改稿されているpull_request_target/ least privilege / OIDC / push protection / artifact attestations / supply chain まで含むnpm testが通る補足
差分最小化より、本としての完成度を優先してよいです。
現行の章番号を維持すること自体は目的ではありません。必要なら章名・節構成・導入順序を大胆に見直してください。
ただし、読者が「いま何を、なぜ、どの順で導入すべきか」を理解できる構成にしてください。