From 132fa1d2d55254c5d929589d2853fd35cda4aa98 Mon Sep 17 00:00:00 2001 From: myoshizumi Date: Thu, 30 Jul 2026 03:37:16 +0900 Subject: [PATCH 01/53] refactor(docs): remove top-level guide markdown files migrated to archive --- Antigravity-cli-guide.md | 892 ------------------------ Gemini-multi-agent-best-practices.md | 973 --------------------------- Harness-engineering-google-guide.md | 523 -------------- 3 files changed, 2388 deletions(-) delete mode 100644 Antigravity-cli-guide.md delete mode 100644 Gemini-multi-agent-best-practices.md delete mode 100644 Harness-engineering-google-guide.md diff --git a/Antigravity-cli-guide.md b/Antigravity-cli-guide.md deleted file mode 100644 index 225fef03..00000000 --- a/Antigravity-cli-guide.md +++ /dev/null @@ -1,892 +0,0 @@ -# Google Antigravity CLI 完全ガイド - -### 全コマンド・設定・ベストプラクティス徹底解説(中級〜上級者向け) - -> 最終更新調査日: 2026年7月29日 (Antigravity CLI v1.1.5 以降対応)。Antigravity CLI は現在も高頻度でアップデートされているツールです。本ガイドは公式ドキュメント (`antigravity.google/docs/cli/*`)、GitHub リポジトリ、および著名な開発者による一次情報をもとに作成していますが、コマンド仕様は今後変更される可能性があります。実行前に必ず `agy --help` または CLI 内の `/help` で最新仕様を確認してください。 - ---- - -## 0. このガイドの読み方 - -Antigravity CLI (`agy`) は、Google が2026年5月に発表した Terminal UI(TUI)型のエージェント型コーディングツールです。旧 Gemini CLI の後継にあたる製品で、Go言語で実装されており、Antigravity 2.0(デスクトップGUI版)・Antigravity IDE(VS Code フォーク)・Antigravity SDK(Python)と「共有エージェントハーネス」を利用する点が最大の特徴です。 - -```mermaid -graph TD - Harness["共有エージェントハーネス
(Shared Agent Harness)"] - CLI["Antigravity CLI
ターミナルTUI・Go実装"] - GUI["Antigravity 2.0
デスクトップGUI"] - IDE["Antigravity IDE
VS Codeフォーク"] - SDK["Antigravity SDK
Python製カスタムエージェント基盤"] - - Harness --> CLI - Harness --> GUI - Harness --> IDE - Harness --> SDK - CLI <-.->|設定・権限を双方向同期| GUI - CLI -.->|/resume でスレッドを相互インポート| GUI -``` - -同じハーネスを使っているため、**推論エンジンの改善はCLIとGUI双方に自動反映**され、パーミッション設定なども共有されます(会話履歴自体は既定では共有されません)。本ガイドでは、インストールから日常運用、自動化、トラブルシューティングまでを、実務で使う順に沿って解説します。 - ---- - -## 1. インストールと認証 - -### 1-1. インストールコマンド - -| OS | コマンド | -|---|---| -| macOS / Linux | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` | -| Windows (PowerShell) | `irm https://antigravity.google/cli/install.ps1 \| iex` | -| Windows (CMD) | `curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd` | - -デフォルトのインストール先は以下の通りです。 - -- macOS / Linux: `~/.local/bin/agy` -- Windows: `C:\Users\\AppData\Local\agy\bin` - -**インストールスクリプトのフラグ** - -| フラグ | 効果 | -|---|---| -| `--skip-aliases` | 旧 `agy`/`antigravity` シェルエイリアスの整理をスキップ | -| `--skip-path` | シェルプロファイルへの `PATH` 追記をスキップ | - -> ⚠️ **ベストプラクティス**: `agy: command not found` になる場合は `~/.bashrc` または `~/.zshrc` に `export PATH="~/.local/bin:$PATH"` を追記し `source` し直してください。 - -### 1-2. 認証フロー - -```mermaid -sequenceDiagram - participant User as 開発者 - participant CLI as Antigravity CLI - participant Keyring as OSキーリング - participant Browser as ブラウザ - - User->>CLI: agy を起動 - CLI->>Keyring: 保存済みトークンを確認 - alt トークンあり - Keyring-->>CLI: トークンを返却 - CLI-->>User: サイレントログイン完了 - else トークンなし(ローカル環境) - CLI->>Browser: 既定ブラウザを自動起動 - Browser-->>User: Googleアカウントでサインイン - User-->>CLI: 認証完了・トークン保存 - else トークンなし(SSHリモート環境) - CLI-->>User: 認証用URLをターミナルに表示 - User->>Browser: URLをローカルPCで開く - Browser-->>User: 認証コードを表示 - User->>CLI: コードをターミナルに貼り付け - end -``` - -CLI は macOS の Keychain、Linux の Secret Service(D-Bus)、Windows Credential Manager などOS標準のセキュアストレージにトークンを保存します。エンタープライズ利用時はオンボーディング時にGCPプロジェクトを接続してください。 - -ログアウトする場合は CLI 内で以下を実行します。 - -``` -/logout -``` - ---- - -## 2. 初回起動とプロジェクトの基本操作 - -プロジェクトディレクトリに移動して起動するだけです。 - -```bash -cd ~/my-project -agy -``` - -初回起動時にカラースキーム・レンダリングモード(Alt-Screen / Inline)・ワークスペースの信頼設定などをウィザード形式で聞かれます。 - -**実務Tips(Google Cloud Developer Advocate による共有 Tips より)**: プロジェクトを1つの親フォルダにまとめておくと、そのフォルダ配下であれば毎回パーミッション確認なしにエージェントがアクセスできるようになり、複数プロジェクトを横断する指示("Aのこの機能をBにも適用して"等)がスムーズになります。 - -``` -~/Desktop/antigravity-projects/ -├── project-a/ -├── project-b/ -``` - ---- - -## 3. 実行モード(Execution Modes) - -Antigravity CLI には3つの実行モードがあり、**エージェントの自律性と開発者のレビュー負荷のトレードオフ**を調整します。 - -| モード | 挙動 | 向いている場面 | -|---|---|---| -| `default` | ファイル作成・変更の都度、差分プレビューで確認を求める | 標準的な開発、機微なコードの慎重なレビュー | -| `accept-edits` | ファイルの作成・編集・置換を自動承認 | 高速なプロトタイピング、信頼済みコードの反復 | -| `plan` | プロンプトに `/plan` を自動付与し、コード変更前に調査・計画を提示 | 未知のアーキテクチャの調査、複雑な複数ファイル変更の設計 | - -```mermaid -stateDiagram-v2 - [*] --> default - state "accept-edits" as accept_edits - state "plan" as plan_mode - default --> accept_edits: Shift+Tab - accept_edits --> plan_mode: Shift+Tab - plan_mode --> default: Shift+Tab -``` - -> **重要**: `command(git)` のようなシェルコマンド実行の可否は、実行モードに関係なく常に `/permissions` の設定(または `--dangerously-skip-permissions`)が優先されます。実行モードはあくまで「ファイル書き込み」の自動承認に関わる設定です。 - -### モードの起動・切り替え方法 - -```bash -# 既定モードで起動(差分レビューあり) -agy - -# 編集を自動承認するモードで起動 -agy --mode=accept-edits - -# 計画優先モードで起動 -agy --mode=plan -``` - -セッション中に切り替える場合は `Shift+Tab` を押すだけで `default → accept-edits → plan → default` と循環します。恒久的な既定値は `/config`(`/settings`)から変更するか、`settings.json` に以下を書きます。 - -```json -{ - "agentMode": "accept-edits" -} -``` - -### ⚠️ 既知の仕様変更(重要な注意) - -公式の「Choose an execution mode」ドキュメントによれば、**旧来の `/planning` と `/fast` スラッシュコマンドは v1.1.0 で廃止(vestigial)**となり、現在は `Shift+Tab` によるモード循環、または `/plan` をプロンプトの先頭に付ける方式に統一されています。一方で同時期に取得した CLI リファレンス表にはまだ `/fast` や `/planning` の記載が残っており、ドキュメント間で若干の不整合が見られました。実運用では **`/help` または `agy --help` で自分の手元のバージョンの正式な挙動を必ず確認**してください。 - -### `default` モードでの差分レビュー操作 - -| キー | 動作 | -|---|---| -| `y` | 変更を承認してディスクに保存 | -| `n` | 変更を拒否して既存ファイルを維持 | -| `f` | フルスクリーンのスクロール可能な差分ビュー(前後3行のコンテキスト付き)を開く | -| `Ctrl+G` | `$EDITOR` でファイルを開き手動編集 | -| プロンプト入力後 `Enter` | 変更を拒否しつつ、修正指示をそのままエージェントへ送信 | - ---- - -## 4. スラッシュコマンド 全リファレンス - -`/` を入力するとタイプアヘッド候補メニューが開きます。以下は公式リファレンスに掲載されている中核コマンド一覧です。 - -| コマンド | カテゴリ | エイリアス | 用途 | -|---|---|---|---| -| `/add-dir ` | ユーティリティ | — | アクティブなワークスペースにディレクトリを追加 | -| `/agents` | ツール・タスク | — | エージェントマネージャーパネル(カスタムエージェント切替・サブエージェント監視) | -| `/artifact` | ツール・タスク | — | Artifact Reviewパネル(実装計画・ウォークスルー)を開く | -| `/btw ` | ユーティリティ | — | メイン会話を中断せずバックグラウンドで別質問 | -| `/clear` | ユーティリティ | `/new` | ターミナルをクリアし会話コンテキストをリセット | -| `/config` | 設定 | `/settings` | インタラクティブな設定エディタを開く | -| `/context` | ユーティリティ | — | コンテキスト使用量の可視化パネル | -| `/copy` | ユーティリティ | — | 直近のエージェント応答をクリップボードにコピー | -| `/credits` | アカウント | — | AI Premiumクレジット残高と購入リンクを表示 | -| `/diff` | ユーティリティ | — | インタラクティブ差分ビューア(VCS/Turn/Commit) | -| `/exit` | コア | `/quit` | TUIセッションを終了 | -| `/effort [level]` | 設定 | — | 推論モデルの思考努力レベル(low, medium, high等)を設定(コマンドライン引数 `--effort` と相互同期) | -| `/fast`※ | 設定 | — | 推論プランをバイパスする高速モード(※廃止予定、下記注記参照) | -| `/feedback` | ユーティリティ | — | フィードバック送信パネル | -| `/fork` | 会話 | `/branch` | 現在の会話を新しい並行セッションに複製 | -| `/help` | ユーティリティ | — | コマンド・ショートカット一覧のヘルプパネル | -| `/hooks` | ツール・タスク | — | 実行中のpre/post-formatフックを閲覧 | -| `/keybindings` | 設定 | — | キーボードショートカットエディタ | -| `/logout` | アカウント | — | 認証情報を破棄しサインアウト | -| `/mcp` | ツール・タスク | — | MCPサーバーマネージャー | -| `/model` | 設定 | — | 使用する推論モデルを選択(セッション間で永続化) | -| `/open ` | ユーティリティ | — | 指定パスを既定エディタで開く | -| `/permissions` | 設定 | — | ツール許可ルールのインタラクティブ管理パネル | -| `/planning`※ | 設定 | — | 複数ターンの計画生成モード(※廃止予定、下記注記参照) | -| `/rename ` | 会話 | — | 現在のセッションに名前を付ける | -| `/resume` | 会話 | `/switch`, `/conversation` | 過去の会話を一覧・検索・再開 | -| `/rewind` | 会話 | `/undo` | 会話履歴を過去の状態に巻き戻す | -| `/skills` | ツール・タスク | — | ロード済みのローカル/グローバルAgent Skillsを閲覧 | -| `/statusline` | 設定 | — | ステータスバーのカスタマイズ | -| `/tasks` | ツール・タスク | — | バックグラウンドシェル実行ログのタスクマネージャー | -| `/title [on/off]` | 設定 | — | ターミナルウィンドウタイトル更新のオン・オフ | -| `/usage` | ユーティリティ | `/quota` | モデルクォータ使用量の表示 | - -### 4-1. 追加で確認されたコマンド(公式Codelab・チュートリアル由来) - -Google Codelabs(`codelabs.developers.google.com`)のハンズオン教材では、上表には無い以下のプロンプト接頭辞・コマンドが紹介されています。挙動が確認できるまでは `/help` での併用確認を推奨します。 - -| コマンド | 用途 | -|---|---| -| `/goal <指示>` | 指定したゴールが完全に達成されるまでエージェントが自律的に反復実行し続ける(テスト全通過まで自己修復するようなタスクに有効) | -| `/plan <指示>` | UIやアーキテクチャのリファクタリングなど複雑な変更の前に、まず実装計画(Implementation Plan)を提示させる | -| `/grill-me <指示>` | 実装前にインタビュー形式で要件・デザインの選択肢を1問ずつ確認してくれる、詳細な壁打ちプランニング | -| `! ` | Bashモード。`!` を先頭に付けると、エージェントを介さず直接シェルコマンドを実行(例: `! git status`) | -| `Ctrl+B` | 実行中の長時間タスクをバックグラウンドに送る | - -### 4-2. 主要コマンドの詳細ステップ - -以降は特に利用頻度の高いコマンドについて、公式ドキュメントに基づく詳細な操作手順を解説します。 - -#### `/permissions` — パーミッション管理 - -``` -/permissions -``` - -**操作フロー** - -1. **スコープピッカー**: `Project`(現在のプロジェクトのみ)/ `Shared`(全Antigravity製品共通)/ `Global`(全セッション共通)から選択(`↑/↓`、`Enter`)。 -2. **ルールビューア**: `←/→`(または`Tab`)で `allowlist` / `denylist` / `asklist` タブを切替。`a`で追加、`e`(または`Ctrl+G`)で編集、`d`(または`Backspace`)で削除。 -3. **ルール追加/編集**: `action(target)` 形式で入力(例: `command(git)`、`read_file(/path/to/dir)`、`write_file(/path/to/file)`)。`Enter`で保存。 - -**実務例**: `git` コマンド全般を自動承認したいが、`git push` は毎回確認したい場合は `command(git)` を追加後、細かい制御が必要なら denylist/asklist 側で個別に絞り込みます。 - -> 💡 **著名開発者のTips**: ワークスペース外のファイル(例: 別ディレクトリのプロジェクトや `~/.gemini/config/mcp_config.json` のような設定ファイル)にエージェントがアクセスするたびに確認を求められるのが煩わしい場合、`settings.json` に直接 `permissions.allow` を追記しておくと快適です。パスマッチングは再帰的なので、ディレクトリを1つ許可すれば配下すべてに適用されます。また `write_file` は `read_file` を包含するため、書き込みだけ許可すれば十分です。 - -```json -{ - "permissions": { - "allow": [ - "read_file(/Users/you/Desktop/projects/my-app)", - "write_file(/Users/you/.gemini/config/mcp_config.json)" - ] - } -} -``` - -#### `/diff` — インタラクティブ差分ビューア - -``` -/diff -``` - -3つのモードを `Tab`(または `←/→`)で循環します。 - -```mermaid -flowchart LR - VCS["VCSモード
未コミット・未追跡ファイル一覧
(Git/Hg/JJ対応)"] -- Tab --> Turn["Turnモード
会話ターンごとの変更差分"] - Turn -- Tab --> Commit["Commitモード
インタラクティブなコミットグラフ"] - Commit -- Tab --> VCS -``` - -| ビュー | 主なキー操作 | -|---|---| -| ファイル一覧(VCS/Turn) | `↑/↓` 移動、`Enter` 詳細表示、`Esc` 終了 | -| 詳細ビュー | `↑/↓` スクロール、`j/k` または `←/→` でファイル切替、`n/N` でハンク間ジャンプ、`c` でコメント追加、`d` でコメント削除 | -| コミットツリー | `↑/↓` コミット移動、`←/→` ブランチ移動、`Enter` で差分表示 | -| 終了確認画面 | `Shift+Y` コメントを送信して終了、`Shift+N` 破棄して終了 | - -**ステップバイステップ: 行コメントでエージェントを誘導する** - -1. 詳細ビューでコメントしたい行にカーソルを合わせる。 -2. `c` を押してコメント入力欄を開く。 -3. フィードバックを入力し `Enter` で保存(`💬`アイコンがガター表示)。 -4. `Esc` でファイル一覧に戻り、さらに `Esc` で終了。 -5. 未送信コメントがあれば確認画面が出るので `Shift+Y` で承認・送信すると、コメントが `:: ` の形式で整形されエージェントへの次の指示として送られます。 - -#### `/resume` — 会話の再開 - -``` -/resume -``` - -| 操作 | キー | -|---|---| -| 検索 | 文字入力で即時フィルタ | -| 移動 | `↑/↓` | -| ページ送り | `←/→` | -| リネーム | `F2` | -| 削除 | `Ctrl+Delete` → `Enter`/`y` で確定 | -| Antigravity 2.0からインポート | `Tab` でCLIタブ→Antigravityタブへ切替 → `Enter` → `y` | - -**コマンドラインからの直接再開** - -```bash -# 現在のワークスペースで直近の会話を再開 -agy -c -# または -agy --continue - -# 特定の会話IDを直接指定 -agy --conversation -``` - -再開キャッシュは `~/.gemini/antigravity-cli/cache/last_conversations.json` に、ワークスペースの絶対パスと会話IDのマップとして保存されています。 - -#### `/codesearch`(エイリアス: `/cs`, `/search`)— コード検索 - -``` -/codesearch UserSession -``` - -- 既定は**正規表現**・スマートケース(大文字を含めば大小区別)。 -- リテラル一致: `-F` または `--literal` -- ファイルパスで絞り込み: `f:`(`file:`/`path:`のエイリアス可)、`-` で除外 - -``` -/codesearch -F map[string]*UserSession -/codesearch f:store.go Session -/codesearch -f:*_test.go NewUserSession -``` - -結果を `Enter` で開いてファイルビューアでコードを閲覧し、`c` で行コメント、`Esc` で終了時に送信確認(`y`/`n`)が出る点は `/diff` と同様の設計です。 - -#### `/agents` — カスタムエージェント & サブエージェント管理 - -``` -/agents -``` - -**カスタムエージェントの作成**(グローバル) - -```bash -mkdir -p ~/.gemini/config/agents/code-reviewer -cat << 'EOF' > ~/.gemini/config/agents/code-reviewer/agent.md ---- -name: code-reviewer -description: エッジケースとセキュリティに重点を置くコードレビュー専門エージェント ---- -あなたは熟練のコードレビュアーです。差分を注意深く分析し、エッジケースを検証してください。 -EOF -``` - -プロジェクト単位で限定したい場合は `{workspace}/.agents/agents/{agent_name}/agent.md` に配置します。 - -**サブエージェントのライフサイクル** - -```mermaid -stateDiagram-v2 - [*] --> running - running --> done: 正常終了 - running --> error: 実行時エラー - running --> killed: ユーザーが k で強制終了 - done --> [*] - error --> [*] - killed --> [*] -``` - -| キー | 動作 | -|---|---| -| `↑/↓` | ヘッダー・サブエージェント・利用可能エージェント間を移動 | -| `Enter` | グループの展開/折りたたみ、詳細ビューを開く、エージェントを選択 | -| `k` | 実行中のサブエージェントを強制終了(完了済みには無効) | -| `a` / `d` | パネル内から承認/拒否の即時応答 | -| `Esc` | パネルを閉じ、選択したエージェント切替を適用 | - -> ⚠️ **落とし穴**: アクティブな会話中にエージェントを切り替えると、履歴の整合性を保つために**自動的に会話がフォーク**されます。新規セッションからの切替は直接反映されます。 - -#### `/statusline` — ステータスバーのカスタマイズ - -``` -/statusline # トグル(オン/オフ切替) -/statusline on # 明示的に有効化 -/statusline off # 明示的に無効化 -/statusline ~/.gemini/antigravity-cli/statusline.sh # カスタムスクリプトを設定 -/statusline delete # 既定表示に戻す(reset も可) -/statusline help # クイックリファレンス表示 -``` - -**実務例(著名なGoogle Cloud Developer Advocateの公開スクリプトより)**: モデル名・カレントディレクトリ・gitブランチ・未コミット数・同期状況・トークン使用率をカラー表示するステータスラインの例。 - -```bash -mkdir -p ~/.gemini/antigravity-cli -curl -sSL -o ~/.gemini/antigravity-cli/statusline.sh \ - https://raw.githubusercontent.com/ykdojo/antigravity-cli-tips/4a13498f354f36bc82375a1ab9a920ae364c90c8/scripts/context-bar.sh && -echo "5c5593e50a09262a80ccfae53b0167467bc7e563556a8a92543c32f796ab5e9c $HOME/.gemini/antigravity-cli/statusline.sh" | sha256sum -c - && -chmod +x ~/.gemini/antigravity-cli/statusline.sh -``` - -```json -{ - "statusLine": { - "type": "command", - "command": "~/.gemini/antigravity-cli/statusline.sh" - } -} -``` - -表示イメージ: `モデル名 | 📁プロジェクト名 | 🔀ブランチ(未コミット数, 同期状況) | トークン使用率バー` - -#### `/title` — ウィンドウタイトル - -``` -/title # トグル -/title on # 有効化 -/title off # 無効化 -``` - -有効化すると、ターミナルのタイトルバーにアクティブなモデル・ワークスペース・エージェント状態が動的に反映されます。 - -#### `/usage`(エイリアス `/quota`)・`/credits` — 使用量管理 - -``` -/usage # モデルごとのクォータ(残リクエスト/トークン数)を表示・自動リフレッシュ -/credits # AI Premiumクレジットの残高・消費履歴・購入リンクを表示 -``` - -| キー(`/usage`パネル) | 動作 | -|---|---| -| `↑/↓`(`j/k`) | 1行スクロール | -| `PgUp/PgDn` | 1ページスクロール | -| `g`/`G` | 先頭/末尾へジャンプ | -| `Esc`(`q`) | 閉じる | - ---- - -## 5. キーボードショートカット 完全リファレンス - -### グローバル(常時有効) - -| キー | 動作 | -|---|---| -| `Esc` | アクティブなパネルを閉じる/ストリームを停止/空プロンプトをクリア | -| `Ctrl+C` | セッション終了(エージェント実行中は確認あり) | -| `Ctrl+D` | セッション終了(プロンプトが空の場合のみ) | -| `Ctrl+L` | ターミナルバッファを再描画 | - -### プロンプト入力中 - -| キー | 動作 | -|---|---| -| `Enter` | プロンプト送信/メニュー選択確定 | -| `Shift+Enter` / `Ctrl+J` | 改行(送信しない) | -| `Ctrl+V` | クリップボードの画像・メディアを添付 | -| `Ctrl+O` | ツール推論の詳細トラジェクトリを展開/折りたたみ | -| `Ctrl+R` | Artifact Reviewパネルを開く | -| `Ctrl+G` | `$EDITOR` を起動してプロンプトを作成 | -| `Alt+J` | 承認待ちの次のサブエージェントへフォーカス移動 | -| `Ctrl+K` | ステータスに表示中の保留アクションを即時承認 | -| `Ctrl+A` / `Ctrl+E` | カーソルを行頭/行末へ移動 | -| `Ctrl+Z` / `Ctrl+Shift+Z` | 元に戻す/やり直す | - -### ナビゲーション・スクロール(パネル/メニュー内) - -| キー | 動作 | -|---|---| -| `↑/↓` | 選択項目を上下に移動 | -| `PgUp`/`Shift+↑` | 1ページ分上スクロール | -| `PgDn`/`Shift+↓` | 1ページ分下スクロール | -| `←/→` | ページ切替(セッションピッカー等) | -| `Tab` | オートコンプリート候補を確定 | - -### ツール確認プロンプト中 - -| キー | 動作 | -|---|---| -| `y` | 提案されたツール・コマンド・変更を承認 | -| `n` | 拒否 | -| `A`(Reviewパネル内) | 生成された全アーティファクトを一括承認 | - ---- - -## 6. 設定ファイル `settings.json` 完全リファレンス - -保存場所: `~/.gemini/antigravity-cli/settings.json`(TUI内では `/config` または `/settings` で編集可能) - -```json -{ - "colorScheme": "tokyo night", - "altScreenMode": "always", - "toolPermission": "request-review", - "notifications": true, - "enableTerminalSandbox": true -} -``` - -| キー | 型 | 既定値 | 説明 | -|---|---|---|---| -| `colorScheme` | string | `"terminal"` | `light` / `solarized light` / `colorblind-friendly light` / `dark` / `solarized dark` / `colorblind-friendly dark` / `tokyo night` / `terminal`(シェルの配色を継承) | -| `altScreenMode` | string | `"default"` | `default`(適応的)/ `always`(常にオルタネートスクリーン)/ `never`(常にインライン出力) | -| `toolPermission` | string | `"request-review"` | `request-review` / `proceed-in-sandbox` / `always-proceed` / `strict` | -| `artifactReviewPolicy` | string | `"asks-for-review"` | `asks-for-review` / `agent-decides` / `always-proceed` | -| `notifications` | boolean | `false` | タスク完了時のデスクトップ通知・ベル音 | -| `showTips` | boolean | `true` | プロンプト上部にエージェンティックなヒントを表示 | -| `showFeedbackSurvey` | boolean | `true` | 定期的な品質フィードバック調査を表示 | -| `editor` | string | `"auto"` | `auto`(`$EDITOR`参照)/ `vim` / `emacs` / カスタム文字列 | -| `allowNonWorkspaceAccess` | boolean | `false` | Git/ワークスペースルート外への読み書きを許可 | -| `enableTerminalSandbox` | boolean | `false` | ローカル実行コマンドをOSコンテインメントリング内に制限 | -| `useG1Credits` | boolean | `false` | (外部ビルドのみ)プランのクォータ超過後に個人AIクレジットを使用 | -| `enableTelemetry` | boolean | `true` | メトリクス収集・クラッシュログ送信の許可 | -| `verbosity` | string | `"high"` | `high`(思考過程・ツール出力を全表示)/ `low`(最小限のインジケータのみ) | -| `runningLightSpeed` | string | `"medium"` | 進捗アニメーション速度: `fast`/`medium`/`slow`/`off` | -| `agentMode` | string | `"default"` | 起動時の既定実行モード: `default`/`accept-edits`/`plan` | - -その他の関連ファイル: - -| ファイル | 用途 | -|---|---| -| `~/.gemini/antigravity-cli/keybindings.json` | カスタムキーバインド(`/keybindings` からも編集可) | -| `~/.gemini/antigravity-cli/cache/last_conversations.json` | `agy -c` 用のワークスペース別・直近会話キャッシュ | -| `~/.gemini/antigravity-cli/updater/update.lock` | セルフアップデーターのアドバイザリロック | -| `~/.gemini/config/agents//agent.md` | グローバルなカスタムエージェント定義 | -| `{workspace}/.agents/agents//agent.md` | プロジェクト限定のカスタムエージェント定義 | - -### コマンドラインフラグによる上書き - -`--effort`、`--sandbox`、`--dangerously-skip-permissions` のように、起動時フラグはセッション設定や `settings.json` の値を一時的に上書きできます。`--effort` は `/effort [level]` と相互同期します。設定パネルには上書き元(例: `Sandbox Mode on overridden by --sandbox`)が表示され、永続設定自体は変更されません(再起動でフラグの効果は消えます)。 - -```bash -# 推論モデルの思考努力レベルを high に設定 -agy --effort=high - -# 隔離環境(コンテナ/VM/専用テストマシン)で全承認を自動化する場合 -agy --dangerously-skip-permissions -``` - -> ⚠️ **セキュリティ注意**: `--dangerously-skip-permissions` は全てのツール承認要求を無条件で自動承認します。信頼できない入力やネットワークアクセス可能な本番環境に近い場所では使用しないでください(詳細は本ガイド末尾の「セキュリティ上の注意」を参照)。 - ---- - -## 7. パーミッション & サンドボックスモデル - -Antigravity CLI は「どこまでエージェントに自律性を与えるか」を、**Tool Permission(何を許可するか)** と **Sandbox(どこで実行するか)** の2軸で制御します。 - -```mermaid -flowchart TD - A["エージェントがツール実行を要求"] --> B{"toolPermission 設定"} - B -->|"request-review(既定)"| C["書込み・bash・ネットワーク呼び出しを都度確認"] - B -->|"proceed-in-sandbox"| D{"サンドボックス内で安全に実行可能か"} - D -->|"安全"| E["自動実行"] - D -->|"要注意"| C - B -->|"always-proceed"| F["確認なしで常に実行"] - B -->|"strict"| G["読み取り以外は全て確認"] -``` - -| 設定 | 説明 | -|---|---| -| `request-review`(既定) | 書込み・bashコマンド・リモートネットワーク呼び出しの前に必ず確認 | -| `proceed-in-sandbox` | 実行をサンドボックスに封じ込め、安全なコマンドは自動実行・危険なコマンドのみ確認 | -| `always-proceed` | 確認なし(信頼できる自動化専用) | -| `strict` | 読み取り以外の操作を逐一確認し、完全な透明性を確保 | - -サンドボックスが有効な場合、確認プロンプトには「サンドボックスなしで今回だけ実行」というオプションが、無効な場合は「今回だけサンドボックス内で実行」というオプションがそれぞれ追加表示されます(単発の例外対応)。 - -**推奨設定例(中〜高リスクなプロジェクト向け)** - -```json -{ - "toolPermission": "proceed-in-sandbox", - "enableTerminalSandbox": true -} -``` - -### パーミッションルールの書式 - -`/permissions` パネルで管理するルールは `action(target)` 形式です。 - -``` -command(git) # git コマンド全体を許可 -command(git diff) # git diff のみ許可(より限定的) -read_file(/path/to/dir) # 指定ディレクトリ配下の読み取りを許可(再帰的) -write_file(/path/to/file) # 指定ファイル/ディレクトリへの書込みを許可(read_fileを包含) -``` - -スコープは3段階です。 - -| スコープ | 適用範囲 | -|---|---| -| Project | 現在開いているプロジェクトのみ | -| Shared | Antigravity CLI / 2.0 / IDE など全製品共通 | -| Global | 全セッション共通 | - ---- - -## 8. MCP(Model Context Protocol)サーバー連携 - -Antigravity CLI は MCP を通じて Jira・Confluence・GitHub・Playwright・Snyk などの外部ツールと連携できます。 - -``` -/mcp # 設定済みMCPサーバーの一覧・状態を確認 -``` - -**設定ファイルの場所**(Google Codelabsのハンズオン教材による記載): - -- グローバル設定: `~/.gemini/config/mcp_config.json` -- ワークスペースローカル設定: `.agents/mcp_config.json`(プロジェクト直下) - -> 📝 **設定スコープの注記**: 共有(Shared)スコープの MCP 設定は `~/.gemini/config/` 配下、CLI固有の設定は `~/.gemini/antigravity-cli/` 配下に保存されます。手元の環境では `/mcp` コマンドの表示、または `agy --help` でも実際のパスを確認してください。 - -**設定例: Context7(単一サーバー、リモートURL指定)** - -```json -{ - "mcpServers": { - "context7": { - "serverUrl": "https://mcp.context7.com/mcp" - } - } -} -``` - -**設定例: 複数サーバー(Snyk / Atlassian / Playwright / GitHub)** - -```json -{ - "mcpServers": { - "Snyk Security Scanner": { - "command": "npx", - "args": ["-y", "snyk@1.1306.2", "mcp", "-t", "stdio", "--experimental"], - "env": {} - }, - "atlassian": { - "command": "npx", - "args": ["-y", "mcp-remote@0.1.38", "https://mcp.atlassian.com/v1/sse"] - }, - "playwright": { - "command": "npx", - "args": ["-y", "@playwright/mcp@0.0.78"] - }, - "github": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github@2025.4.8"], - "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "******" } - } - } -} -``` - -- **Snyk**: ワークスペースを離れずに依存関係の脆弱性スキャンをエージェントに実行させる -- **Atlassian**: Jira/Confluenceのチケット作成・検索・更新を自然言語で指示 -- **Playwright**: ブラウザ自動操作(`browser_navigate`、`browser_click`、`browser_take_screenshot` 等)によるE2Eテストや画面確認 -- **GitHub**: PR作成・Issueトリアージ・リポジトリ解析を直接連携 - ---- - -## 9. カスタムエージェント・Skills・Plugins・Hooks - -### カスタムエージェント(前述の`/agents`参照) - -`agent.md` にYAML frontmatter + システムプロンプトを記述し、グローバル(`~/.gemini/config/agents//agent.md`)またはプロジェクト限定(`{workspace}/.agents/agents//agent.md`)に配置します。 - -### Agent Skills - -Skillsは、特定タスクの手順・スクリプト・参照リソースを記述した宣言的なMarkdownファイルです。登録されると自動的にスラッシュコマンド化されます(例: `/refactor-ui`)。 - -``` -/skills # ロード済みのローカル/グローバルSkillsを一覧表示 -``` - -### Plugins - -Plugins は Skills・バックグラウンドサブエージェント・Lintルール・MCP定義・イベントフックを1つのパッケージにまとめた名前空間付きバンドルです。カスタムエージェントもPlugin経由で配布できます。 - -### Hooks - -ツール実行の直前/直後に処理を挟み込む仕組みで、pre-flightチェックやpost-formatフォーマッタ(例: ファイル書込み後の `prettier` 自動実行)に使われます。Plugin内の `hooks.json`、または `settings.json` 本体に定義します。 - -``` -/hooks # 現在アクティブなフックを一覧表示 -``` - -### プロジェクトルールファイル(`AGENTS.md` / `GEMINI.md`) - -プロジェクトルートに `AGENTS.md`(または `GEMINI.md`)を配置すると、コーディング規約・スタイル指針・テストコマンド・非推奨事項などをエージェントが起動時に自動的に読み込み、変更提案の前に参照します。 - -**実務Tips**: Claude Codeなど他ツールも併用している場合、シンボリックリンクで指示ファイルを共有すると二重管理を避けられます。 - -```bash -ln -s CLAUDE.md AGENTS.md -``` - -`AGENTS.md` にはTODOリストを書いておくのもおすすめです。 - -```markdown -## To-Do -### Done -- [x] プロジェクト初期スキャフォールド -- [x] 基本UI実装 -### Up Next -- [ ] エラーハンドリングの追加 -``` - -こうしておくと「TODOリストの状況を教えて」と聞くだけで、エージェントが正確に現在地を把握して回答してくれます。全体を通しての注記として、グローバル版のルールファイルは `~/.gemini/AGENTS.md` に置くことで全プロジェクト共通の指示にできます。 - ---- - -## 10. 自動化・スクリプティング・CI/CD連携 - -### 非対話モード(`-p` フラグ) - -```bash -agy -p "このgit diffをレビューしてConventional Commits形式のコミットメッセージを提案して" --cwd $(pwd) -``` - -Gitフックやスクリプトへの組み込み、単発クエリの自動化に有効です。 - -### Bashモード(`!` プレフィックス) - -対話中に単純なコマンドをすぐ実行したい場合、`!` を先頭に付けるとチャットを介さず直接シェルへ渡せます。 - -``` -! git status -``` - -### バックグラウンドタスク - -長時間かかるタスクは `Ctrl+B` でバックグラウンドに送れます。進行状況は `/tasks`(シェル実行系)または `/agents`(サブエージェント系)で監視できます。 - -### CI/CDパイプラインでの利用イメージ - -```mermaid -flowchart LR - Trigger["PR作成 / pushイベント"] --> Hook["CIジョブがagy -pを実行"] - Hook --> Review["diffレビュー・テスト実行"] - Review --> Comment["結果をPRコメントとして投稿"] -``` - -`AGY_CLI_DISABLE_AUTO_UPDATE=true` を環境変数に設定しておくと、CI環境でセルフアップデーターが介入するのを防げます(詳細は次章のトラブルシューティング参照)。 - ---- - -## 11. ベストプラクティス(公式ガイド + 実務Tips統合版) - -### 11-1. 検証ループを必ず組み込む - -自律型エージェントから信頼できる変更を得る最も効果的な方法は、**ローカルに検証手段(ユニットテスト・ビルドコマンド・フォーマッタ)を用意しておく**ことです。 - -```mermaid -flowchart LR - Explore["① 探索
該当箇所の調査・仕様確認"] --> Plan["② 計画
Implementation Plan artifactの生成"] - Plan --> Approve{"承認する?"} - Approve -->|No/要修正| Plan - Approve -->|Yes| Execute["③ 実行
コード変更を適用"] - Execute --> Verify["④ 検証
テスト/ビルドコマンド実行"] - Verify -->|失敗| Execute - Verify -->|成功| Done["完了"] -``` - -**手順** - -1. ワークスペースにテストスイートを用意する(無ければ先にテストを書かせる)。 -2. コード変更を依頼する際、検証コマンドまで指定する。 - -``` -Implement feature X in main.py. Run npm test afterward to verify the build. -``` - -3. エージェントがテストを実行し、失敗があれば自動的に反復修正する様子を確認する。 - -### 11-2. 「探索 → 計画 → 実行」の3段階に分ける - -複雑な変更ほど、いきなり実装させず段階を踏むことで精度が上がります。 - -``` -Explore how our router resolves `/docs/:page`. Write down an implementation plan to add `/docs/best-practices`. -``` - -- **探索**: 対象コードの解決方法・インターフェース定義をまず説明させる -- **計画**: Implementation Plan artifact(対象ファイル・依存関係・ロジック変更点を列挙)を要求 -- **実行**: 承認後にのみ編集を適用させる - -複雑なUI・アーキテクチャ変更では `/plan` コマンドや、要件を1問ずつ確認してくれる `/grill-me` の活用も有効です。 - -### 11-3. コンテキストを高精度に与える - -| 手法 | 操作 | -|---|---| -| ファイルパス補完 | プロンプト内で `@` を入力すると Interactive Path Suggestion が開き、絶対パスを挿入できる | -| 画面のスクリーンショット添付 | UI崩れ等のビジュアルバグはスクリーンショット/動画をコピーし `Ctrl+V` で貼り付け | -| Webページ・ターミナル出力の貼り付け | `Cmd+A`/`Ctrl+A` で全選択しコピーしてそのまま貼り付け(Gmailは「印刷プレビュー」、YouTubeは文字起こし表示を使うと綺麗に取得できる) | -| 絶対パスの取得 | `realpath some/relative/path` で絶対パスを取得しプロンプトに貼る | - -### 11-4. ワークスペース環境を整備する - -- `AGENTS.md`/`GEMINI.md` にディレクトリ規約・スタイル・テストコマンド・非推奨事項を明記する。 -- リスクレベルに応じて `toolPermission` を調整する(§7参照)。 - -### 11-5. セッションを能動的に管理する - -| 状況 | 対処 | -|---|---| -| 誤った検索パターン・意図とズレたコードを実行中 | `Esc` で即座に中断しクリーンなプロンプトに戻る | -| 複数回の変更でビルドエラーが蓄積した | `/rewind`(`/undo`)で会話を安定していた時点まで巻き戻す | -| 実装方針に確信が持てない | `/fork` で並行セッションを作り、試行錯誤用のブランチとして使う。失敗したら `/resume` で本線に戻る | - -### 11-6. 並列サブエージェントで作業をファンアウトする - -大規模な一括置換や複数ファイルにまたがるリファクタリングでは、メインエージェントにバックグラウンドのサブエージェントを生成させ、`/agents` パネルで監視しながら自分は別作業を継続できます。 - -### 11-7. ソフトウェア開発ライフサイクル全体でエージェントを使う - -コード生成だけに偏重せず、Issue理解・設計検討・PRレビュー・テスト作成など、SDLC全体でエージェントを活用することが推奨されています(著名なGoogle Cloud Developer Advocateによる実務記事より)。 - -### 11-8. 音声入力の活用(上級者向け実務Tips) - -タイピングより音声の方が指示速度が速いというTipsも共有されています。ローカルの音声認識モデル(例: superwhisper、MacWhisper 等)を使えば、多少の誤認識があってもLLMが文脈から意図を汲み取ってくれるため実用上問題ないケースが多いとされています。 - ---- - -## 12. トラブルシューティング - -| 症状 | 原因 | 対処 | -|---|---|---| -| `agy: command not found` | インストール先が `$PATH` に含まれていない | `~/.bashrc`/`~/.zshrc` に `export PATH="~/.local/bin:$PATH"` を追記し `source` する。Windowsは `SetEnvironmentVariable` でPATHを追記 | -| `keyring: secure lock out` | OSキーリングサービスの権限不足・ロック | macOS: Keychain Access で `agy` のアクセス許可を確認、SSH経由なら `security unlock-keychain` 実行。Linux: `export $(dbus-launch)` でD-Busセッションを起動 | -| SSH経由でのクリップボード貼付失敗 | SSH標準ストリームはグラフィカルクリップボードを転送しない | iTerm2/Ghosttyを使用し、iTerm2なら「Applications in terminal may access clipboard」を有効化(OSC 52)。tmux利用時は `set -s set-clipboard on` | -| アップデートが失敗・ハングする | セルフアップデーターのアドバイザリロックが残留 | `rm -f ~/.gemini/antigravity-cli/updater/update.lock` でロック解除。自動更新自体を止めたい場合は `export AGY_CLI_DISABLE_AUTO_UPDATE=true` | - ---- - -## 13. セキュリティ上の注意 - -Antigravity CLI の公式GitHubリポジトリでは、AIコーディングエージェント全般に共通するリスクとして以下が明記されています。 - -- 自律的なコード実行(autonomous code execution) -- データ持ち出し(data exfiltration) -- プロンプトインジェクション(prompt injection) -- サプライチェーンリスク(supply chain risks) - -エージェントが取る全てのアクションを監視・検証することが推奨されています。実務上は以下のような多層防御が現実的です。 - -1. **既定(`request-review`/`strict`)で運用**し、信頼度に応じて `proceed-in-sandbox` → `always-proceed` へ緩めていく。 -2. **サンドボックス(`enableTerminalSandbox: true`)を有効化**し、ローカル実行コマンドをOSコンテインメントリングに封じ込める。 -3. **`--dangerously-skip-permissions` はコンテナ・使い捨てVMなど隔離環境限定**で使用する。 -4. **外部ネットワーク接続を伴うMCPサーバー(GitHubトークン等)は最小権限のトークン**を発行し、`env` に直接埋め込む場合は取り扱いに注意する。 -5. Antigravity(旧Gemini CLIを含む)は米商務省の輸出規制対応等、サービス提供状況が急遽変更されることがあった実績があるため(著名なAI評論家 Simon Willison 氏のブログ・X投稿でも複数回報告)、本番CI/CDに組み込む場合は可用性リスクも考慮してください。 - ---- - -## 14. 参考文献・情報源(2026年7月29日時点で確認) - -本ガイドは以下の一次情報源(公式ドキュメント・公式リポジトリ・Google公認Developer Advocateによる技術記事・国際的に著名なAI/開発者評論家の投稿)を根拠にしています。 - -**公式ドキュメント(antigravity.google)** - -- CLI概要: https://antigravity.google/docs/cli/overview -- インストール・認証: https://antigravity.google/docs/cli/install -- 実行モード: https://antigravity.google/docs/cli/modes -- CLIリファレンス(全コマンド・キーバインド・設定キー): https://antigravity.google/docs/cli/reference -- ベストプラクティス: https://antigravity.google/docs/cli/best-practices -- トラブルシューティング: https://antigravity.google/docs/cli/troubleshooting -- 機能概要(サンドボックス・サブエージェントパネル): https://antigravity.google/docs/cli/features -- `/agents` コマンド詳細: https://antigravity.google/docs/cli/commands/agents -- `/codesearch` コマンド詳細: https://antigravity.google/docs/cli/commands/codesearch -- `/credits` コマンド詳細: https://antigravity.google/docs/cli/commands/credits -- `/diff` コマンド詳細: https://antigravity.google/docs/cli/commands/diff -- `/permissions` コマンド詳細: https://antigravity.google/docs/cli/commands/permissions -- `/resume` コマンド詳細: https://antigravity.google/docs/cli/commands/resume -- `/statusline` コマンド詳細: https://antigravity.google/docs/cli/commands/statusline -- `/title` コマンド詳細: https://antigravity.google/docs/cli/commands/title -- `/usage` コマンド詳細: https://antigravity.google/docs/cli/commands/usage -- Antigravity CLI 発表ブログ: https://antigravity.google/blog/introducing-google-antigravity-cli - -**公式リポジトリ** - -- GitHub: https://github.com/google-antigravity/antigravity-cli - -**Google公式ブログ・Developer Advocate記事** - -- Gemini CLIからの移行アナウンス: https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/ -- サーフェス選択ガイド(CLI/IDE/SDK/2.0比較): https://cloud.google.com/blog/topics/developers-practitioners/choosing-your-surface-antigravity-20-antigravity-cli-antigravity-ide-or-antigravity-sdk -- Antigravity vs Gemini CLI 比較: https://cloud.google.com/blog/topics/developers-practitioners/choosing-antigravity-or-gemini-cli -- Antigravity CLI チュートリアルシリーズ(Medium, Google Cloud Community): https://medium.com/google-cloud/antigravity-cli-tutorial-series-12b46cfe3bf2 -- Getting Started with Antigravity CLI(Medium, Google Cloud Community): https://medium.com/google-cloud/getting-started-with-antigravity-cli-26c5da90951f -- Antigravity CLIハンズオン公式Codelab: https://codelabs.developers.google.com/genai-for-dev-antigravity-cli -- Antigravity CLIハンズオン公式Codelab(別編): https://codelabs.developers.google.com/antigravity-cli-hands-on - -**著名な開発者による実務Tips・評論** - -- 「15 Antigravity CLI tips」— YK氏(Claude Code tips リポジトリ作者・9,000+スター、CS Dojo YouTubeチャンネル創設者・登録者190万人超、Eventual社 Developer Experience Manager)、Google Cloud Community寄稿: https://medium.com/google-cloud/15-antigravity-cli-tips-ddbc21c10a20 -- Simon Willison氏(国際的に著名なAI/LLM評論家)によるGoogle I/O・Antigravity関連の考察: https://simonwillison.net/2026/May/20/google-io/ - ---- - -> 📌 本ガイドの内容は2026年7月29日時点の Antigravity CLI v1.1.5 以降の公開情報に基づきます。Antigravity CLI は数週間単位でバージョンアップされており、コマンド名・設定キー・ファイルパスは変更される可能性があります。重要な自動化やCI/CD組み込みの前には、必ず `agy --help` および公式ドキュメントの最新版を確認してください。 diff --git a/Gemini-multi-agent-best-practices.md b/Gemini-multi-agent-best-practices.md deleted file mode 100644 index 09bf8883..00000000 --- a/Gemini-multi-agent-best-practices.md +++ /dev/null @@ -1,973 +0,0 @@ -# Gemini マルチエージェント開発 ベストプラクティス完全ガイド - -### GEMINI.md・AGENTS.md・agent.py・.geminiignore・settings.json・A2A・Agent Engine まで - -> 対象読者: Gemini CLI / Google Agent Development Kit (ADK) を使ってマルチエージェントシステムを構築したい初学者〜中級エンジニア -> 前提知識: Python の基礎文法、ターミナル操作、JSON/YAML の読み書き -> 情報基準日: 2026年7月26日時点でのウェブ検索結果に基づく（出典は末尾の「参考文献」を参照） - ---- - -## 0. はじめに — このガイドを読む前に知っておくべきこと - -このガイドは、Gemini エコシステムでマルチエージェント（複数の AI エージェントが協調して動くシステム）を開発するときに触れることになる、5つの設定ファイル・コードファイルと、それらをつなぐ2つのプロトコル/サービスを、初学者でも迷わないようにステップバイステップで解説します。 - -| # | ファイル/概念 | 役割を一言でいうと | -|---|---|---| -| 1 | `GEMINI.md` | エージェントに「このプロジェクトのルール」を教える指示書 | -| 2 | `AGENTS.md` | 複数のAIツール共通の「エージェント向けREADME」オープン標準 | -| 3 | `.geminiignore` | エージェントに「見せたくないファイル」を隠す除外リスト | -| 4 | `settings.json` | Gemini CLI 自体の挙動（承認モード、サブエージェント、セキュリティ等）を設定する本体設定ファイル | -| 5 | `agent.py` | ADK でエージェントのロジック・ツール・サブエージェント構成をPythonコードとして定義するファイル | -| 6 | A2A プロトコル / `agent.json`（Agent Card） | 異なるエージェント同士が「何ができるか」を名刺交換のように開示し合い、通信するための共通規格 | -| 7 | Vertex AI Agent Engine | 作ったエージェントを本番環境（クラウド）にデプロイして自動スケールさせるマネージドサービス | - -### 2026年7月時点の重要な前提（必ず先に読んでください） - -Gemini CLI を取り巻く状況は2026年に入って大きく動いています。ガイドの内容を実践する前に、以下の2点を押さえておくと迷いません。 - -1. **Gemini CLI は個人向け無償/Google One 利用枠では Antigravity CLI に統合されつつあります。** Google は2026年5月19日、Gemini CLI と Antigravity CLI を「マルチエージェント時代に向けた単一プラットフォーム」に統合する方針を発表し、2026年6月18日をもって Google AI Pro/Ultra および無償の Gemini Code Assist 個人利用枠向けの Gemini CLI へのリクエスト提供を終了しました。一方で、**Gemini Code Assist Standard/Enterprise ライセンス、または有償の Gemini / Gemini Enterprise Agent Platform API キーを利用する企業ユーザーには、これまで通り Gemini CLI へのアクセスが提供され続けます**。このガイドで解説する `GEMINI.md` / `.geminiignore` / `settings.json` / サブエージェントの仕組みは、企業向けに存続する Gemini CLI、および後継の Antigravity CLI の両方で（Agent Skills・Hooks・Subagents・拡張機能というかたちで）概ね引き継がれています。 -2. **ADK（Agent Development Kit）は 2.0 世代に入り、「決定論的ワークフロー」という新しい柱が加わりました。** 2026年7月1日に公開された Google の技術ブログによれば、ADK 2.0 では自律的なLLMエージェントに加えて、ビジネスロジックをコードで厳密に制御する `Workflow`（有向グラフ実行エンジン）が導入されています。マルチエージェント設計をする際は「LLMに任せるべき部分」と「コードで固定すべき部分」を切り分ける、という新しい設計判断が必要になります（詳細は第9章）。 - -これらの背景を踏まえたうえで、以下、各ファイル・概念を順番に見ていきます。 - ---- - -## 1. エコシステム全体像を1枚の図でつかむ - -個別のファイルに入る前に、これらがどう連携しているかを俯瞰します。 - -```mermaid -flowchart TB - subgraph LOCAL["ローカル開発環境"] - GM["GEMINI.md / AGENTS.md
（プロジェクト文脈）"] - GI[".geminiignore
（除外ファイル）"] - ST["settings.json
（CLI挙動設定）"] - AG["agent.py
（ADKでのエージェント定義）"] - end - - subgraph CLI["Gemini CLI / Antigravity CLI"] - CORE["Core: モデル呼び出し・ツール実行・ReActループ"] - SUB["ローカル サブエージェント
（.gemini/agents/*.md）"] - end - - subgraph REMOTE["リモート/他言語エージェント"] - CARD["agent.json（Agent Card）
= .well-known/agent.json"] - RAGENT["RemoteA2aAgent
（A2Aクライアント）"] - SERVER["A2Aサーバー
（Python/Go/Java等）"] - end - - subgraph CLOUD["本番環境"] - AE["Vertex AI Agent Engine
（Reasoning Engine）"] - end - - GM --> CORE - GI --> CORE - ST --> CORE - CORE --> SUB - AG --> RAGENT - RAGENT -- "Agent Card取得" --> CARD - RAGENT -- "JSON-RPC通信" --> SERVER - CARD --- SERVER - AG -- "adk deploy agent_engine" --> AE - AE -- "A2Aエンドポイント公開" --> RAGENT -``` - -読み方: `GEMINI.md` / `.geminiignore` / `settings.json` はいずれも **Gemini CLI 自体を賢く・安全にするための設定**です。一方 `agent.py` と `agent.json`（Agent Card）は **ADK で作る個々のエージェント（コード側の実体）** を定義するもので、A2Aプロトコルを介してエージェント同士、あるいは Gemini CLI のサブエージェントとして接続されます。最終的に `agent.py` は Vertex AI Agent Engine にデプロイして本番運用します。 - ---- - -## 2. GEMINI.md — プロジェクトの「文脈」を教える指示書 - -### 2.1 何をするファイルか - -`GEMINI.md` は、毎回のプロンプトで同じ指示を繰り返す代わりに、プロジェクト固有のルール（コーディング規約、対象読者、テストの実行方法など）を一度だけ書いておくファイルです。Gemini CLI はこれを自動的に読み込み、モデルへのすべてのリクエストに文脈として付加します。 - -### 2.2 3段階の階層システム（超重要） - -`GEMINI.md` は1ファイルだけではなく、以下の3段階で読み込まれ、**すべて連結されて**モデルに渡されます。 - -```mermaid -flowchart TB - A["① グローバル文脈ファイル
~/.gemini/GEMINI.md
（全プロジェクト共通のデフォルト指示）"] - B["② ワークスペース文脈ファイル
作業ディレクトリとその親ディレクトリを探索
（現在取り組んでいるプロジェクト向け）"] - C["③ Just-In-Time (JIT) 文脈ファイル
ツールがファイル/ディレクトリにアクセスした瞬間に
そのディレクトリとその祖先を自動スキャン"] - D["すべて連結してモデルへ送信
（CLIフッターに読み込み済みファイル数を表示）"] - A --> D - B --> D - C --> D -``` - -- **①グローバル**: `~/.gemini/GEMINI.md`（ホームディレクトリ）。すべてのプロジェクトに適用したいデフォルトの指示（例:「常に日本語で回答する」等）を置きます。 -- **②ワークスペース**: 作業ディレクトリとその親ディレクトリを探索して見つかった `GEMINI.md`。現在のプロジェクト向けのルールです。 -- **③JIT（Just-In-Time）**: モデルがツールで特定のディレクトリのファイルに触れた瞬間に、そのディレクトリとその祖先ディレクトリの `GEMINI.md` を都度スキャンして読み込みます。これにより、モノレポの特定コンポーネントだけに関係する詳細ルールを、必要になったときだけ読み込ませることができます（＝第4章のマルチエージェント設計で重要）。 - -### 2.3 書き方のベストプラクティス（ステップバイステップ） - -1. **`/init` コマンドで雛形を作る。** プロジェクトルートで Gemini CLI を起動し `/init` を実行すると、リポジトリを解析して `GEMINI.md` の初期版を自動生成してくれます。 -2. **簡潔に、目的ベースで書く。** 公式のベストプラクティスは「モデルがコードから推測できない情報だけ書け」「最初は50行以内に抑え、実際にギャップが出たときだけ育てる」という考え方です。冗長なドキュメントの全文コピーは避けます。 -3. **見出し構造で整理する。** `# プロジェクト概要` → `## 全般的な指示` → `## コーディングスタイル` のように、見出しでセクションを区切ります。 -4. **500行を超えたら分割する。** 巨大化してきたら `@ファイルパス` のインポート構文でモジュール化します。 - -```markdown -# Project: My TypeScript Library - -## General Instructions -- 新しいTypeScriptコードを生成する際は、既存のコーディングスタイルに従うこと。 -- 新しい関数・クラスには必ずJSDocコメントを付けること。 -- 可能な限り関数型プログラミングのパラダイムを優先すること。 - -## Coding Style -- インデントはスペース2つ。 -- インターフェース名には `I` プレフィックスを付ける（例: `IUserService`）。 -- 常に厳密等価演算子（`===` と `!==`）を使うこと。 -``` - -5. **`@file.md` 構文でインポートして分割する。** - -```markdown -# Main GEMINI.md file -これはメインの内容です。 - -@./components/instructions.md - -さらに内容が続きます。 - -@../shared/style-guide.md -``` - -6. **`/memory` コマンドで検証する。** - - `/memory show` — 現在読み込まれている連結後の文脈全文を表示（実際にモデルに渡っている内容を確認できる） - - `/memory reload` — すべての `GEMINI.md` を再スキャンして再読み込み - -### 2.4 実践チェックリスト - -- [ ] `/init` で下地を作ったか -- [ ] 「コードから読み取れないこと」だけを書いているか（重複情報を削ったか） -- [ ] セクション見出しで整理されているか -- [ ] 500行以内、または `@import` で分割されているか -- [ ] `/memory show` で意図通りの内容が読み込まれているか確認したか - ---- - -## 3. GEMINI.md と AGENTS.md — どちらを使うべきか - -### 3.1 AGENTS.md とは何か - -`AGENTS.md` は特定ベンダーに縛られない、**業界横断のオープンフォーマット**です。OpenAI Codex・Amp・Google Jules・Cursor・Factory など複数の企業が協力して策定し、現在では Codex・Cursor・GitHub Copilot・Gemini CLI・Aider・Windsurf・Zed など20を超えるツールがネイティブに読み込みます。「エージェント向けのREADME」と考えると分かりやすく、必須フィールドも決まったスキーマもない、プレーンな Markdown です。 - -### 3.2 なぜ2つ存在するのか、どう使い分けるか - -`GEMINI.md` は Gemini CLI 専用の名称・階層読み込みロジック（グローバル/ワークスペース/JIT、`@import`構文）を持つ **Gemini CLI 固有の仕組み**です。一方 `AGENTS.md` は **どのツールでも読める共通ファイル**という位置づけです。 - -| 観点 | GEMINI.md | AGENTS.md | -|---|---|---| -| 標準化団体 | Google（Gemini CLI固有） | 複数ベンダー共同策定のオープン標準 | -| 対応ツール | Gemini CLI / Antigravity CLI | Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed 等20以上 | -| 階層読み込み | グローバル→ワークスペース→JIT の3段階 | 最も近いディレクトリのファイルが優先（モノレポの各パッケージに配置可） | -| インポート構文 | `@file.md` をサポート | 仕様上の特別な構文なし（プレーンMarkdown） | -| チーム内での使い方 | Gemini CLI 中心のチームに最適 | 複数のAIツールを併用するチーム・OSSリポジトリに最適 | - -### 3.3 実は共存できる — settings.json での統合設定 - -Gemini CLI は `settings.json` の `context.fileName` プロパティで、読み込むファイル名を変更・追加できます。これを使うと、`AGENTS.md` を正としつつ Gemini CLI にも読ませる、という一石二鳥の運用が可能です。 - -```json -{ - "context": { - "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"] - } -} -``` - -この配列に指定した名前のファイルが、指定した優先順で（複数存在すれば全て連結して）読み込まれます。**複数のAIコーディングツールを併用するチームでは、`AGENTS.md` を単一の情報源にして `GEMINI.md` は作らない、という運用が2026年時点でのベストプラクティスとして定着しつつあります。** - -### 3.4 ステップバイステップ: 移行手順 - -1. リポジトリ直下に `AGENTS.md` を作成し、ビルドコマンド・テストコマンド・コーディング規約・触れてはいけないファイルなどを記述する。 -2. `.gemini/settings.json`（ワークスペース設定）に `context.fileName` を追加し、`AGENTS.md` を最優先で読み込ませる。 -3. モノレポの場合、各パッケージのルートにもその場限りの `AGENTS.md` を追加する（最も近いファイルが優先されるため、サブプロジェクトごとの独自ルールを上書き指定できる）。 -4. 既存の `GEMINI.md` の内容を `AGENTS.md` に統合し、重複を避ける。 - ---- - -## 4. マルチエージェント向け GEMINI.md / AGENTS.md 設計 - -単一エージェントのプロジェクトと違い、複数のエージェントが協調するプロジェクトでは、文脈ファイルの設計そのものが「誰にどの情報を、いつ見せるか」という設計問題になります。 - -### 4.1 モノレポ型階層設計 - -```mermaid -flowchart TB - ROOT["/AGENTS.md（ルート）
全体アーキテクチャ・共通規約・禁止事項"] - ROOT --> PY["/agents/python-extractor/AGENTS.md
Python固有: Gemini呼び出し規約・型ヒント方針"] - ROOT --> GO["/agents/go-compliance/AGENTS.md
Go固有: エラーハンドリング規約・ビルドコマンド"] - ROOT --> ORCH["/orchestrator/GEMINI.md
オーケストレーター固有: サブエージェント呼び出し順序"] -``` - -第2章で解説した JIT（Just-In-Time）読み込みの仕組みにより、モデルが `agents/go-compliance/` 配下のファイルを開いた瞬間だけ、その場所の `AGENTS.md` が自動的に追加読み込みされます。これにより、ルートの `AGENTS.md` を薄く保ちながら、各サブエージェントの専門知識を必要な時にだけ注入できます。 - -### 4.2 マルチエージェント特有の記述内容 - -単一エージェントの `GEMINI.md`／`AGENTS.md` には書かない、マルチエージェント特有の情報を追加します。 - -- **エージェント間の責務分担の一覧**（例: 「抽出は `extractor_agent`、コンプライアンス検証は Go 製のリモートエージェント `compliance_agent`、レポート生成は `report_agent` が担当」） -- **共有状態（shared state）のキー名とスキーマ**（後述する `ToolContext.state` 経由で受け渡すデータの形） -- **フェイルセーフの挙動**（あるサブエージェントが応答不能な場合、どのステートに遷移すべきか。例:「Goのコンプライアンスエージェントが3回リトライしても応答しない場合は `MANUAL_REVIEW` 状態へ遷移し、人間のレビューに回す」） -- **サブエージェントの呼び出し粒度に関する指示**（「どのタスクをメインエージェントが直接処理し、どこからサブエージェントに委譲すべきか」の判断基準） - -### 4.3 サブエージェント定義ファイルとの役割分担 - -ローカルサブエージェントは `.gemini/agents/*.md` という **別ファイル**（YAMLフロントマター付きMarkdown）で定義します（詳細は第6章）。`GEMINI.md`／`AGENTS.md` は「プロジェクト全体のルール」、サブエージェント定義ファイルは「個々のサブエージェントの人格・権限」という住み分けです。この2つを混同せず、`GEMINI.md` にサブエージェントの詳細なシステムプロンプトを書き込まないようにするのがコツです。 - ---- - -## 5. .geminiignore — 見せたくないファイルを隠す - -### 5.1 仕組み - -`.geminiignore` は Git の `.gitignore` や Gemini Code Assist の `.aiexclude` と同じ考え方の除外リストです。ここに書いたパスは、`@` コマンドでファイルを共有するときなど、この機能に対応したツールから除外されます（ただし Git など他のサービスには引き続き見える点に注意）。 - -### 5.2 構文ルール - -| ルール | 説明 | -|---|---| -| 空行・`#`で始まる行 | 無視される（コメント扱い） | -| 標準的なglobパターン | `*`, `?`, `[]` が使用可能 | -| 末尾の `/` | ディレクトリのみにマッチ | -| 先頭の `/` | `.geminiignore` があるディレクトリからの相対パスとして固定 | -| `!` | パターンを否定（除外対象から除外＝再度含める） | - -### 5.3 実践例 - -```gitignore -# /packages/ ディレクトリとそのサブディレクトリすべてを除外 -/packages/ - -# apikeys.txt ファイルを除外 -apikeys.txt - -# すべての .md ファイルを除外（ワイルドカード） -*.md - -# ただし README.md だけは除外対象から除外して見せる -*.md -!README.md -``` - -**変更を反映するには Gemini CLI セッションの再起動が必要**です。マルチエージェント開発では、各サブエージェント/リモートエージェントのシークレット（`.env`、認証キー、`agent_card_json` に埋め込みがちな認証情報）を確実に除外リストへ入れることが、次章のセキュリティ設定と合わせて重要になります。 - ---- - -## 6. settings.json — CLI 挙動の中枢設定 - -### 6.1 設定ファイルの場所と優先順位 - -| スコープ | パス | 優先順位 | -|---|---|---| -| ユーザー設定 | `~/.gemini/settings.json` | 低い（ワークスペース設定に上書きされる） | -| ワークスペース設定 | `your-project/.gemini/settings.json` | 高い（ユーザー設定を上書き） | - -`/settings` コマンドでダイアログからGUI的に編集することも、ファイルを直接編集することも可能です。 - -### 6.2 マルチエージェント開発で特に重要なカテゴリ - -全設定は10カテゴリ以上ありますが、マルチエージェント開発の文脈で押さえるべきものを抜粋します。 - -| カテゴリ | 主な設定キー | 用途 | -|---|---|---| -| Context | `context.fileName` | 読み込む文脈ファイル名（`AGENTS.md`併用など） | -| Context | `context.fileFiltering.respectGeminiIgnore` | `.geminiignore`を尊重するか（既定 `true`） | -| Agents | `agents.overrides.` | 特定サブエージェントの有効/無効・モデル・実行上限の上書き | -| General | `general.defaultApprovalMode` | ツール実行の承認モード（`default`/`auto_edit`/`plan`） | -| Security | `security.folderTrust.enabled` | 信頼済みフォルダのみで危険な操作を許可 | -| Security | `security.enableConseca` | LLMによる動的なセキュリティポリシー生成（コンテキスト対応セキュリティ） | -| Tools | `tools.sandboxAllowedPaths` / `tools.sandboxNetworkAccess` | サンドボックスの許可範囲 | -| Model | `model.compressionThreshold` | コンテキスト圧縮を発動する使用率のしきい値 | -| HooksConfig | `hooksConfig.enabled` | フックシステム全体のON/OFF | - -### 6.3 サブエージェント向け設定例 - -特定のサブエージェント（例: `codebase_investigator`）に、モデルや最大ターン数を個別指定する例です。 - -```json -{ - "agents": { - "overrides": { - "codebase_investigator": { - "modelConfig": { "model": "gemini-3-flash-preview" }, - "runConfig": { "maxTurns": 50 } - } - } - } -} -``` - -### 6.4 MCPサーバー連携の設定例 - -マルチエージェント開発では、外部ツール（GitHub等）をMCP経由で各エージェントに与えることがよくあります。 - -```json -{ - "mcpServers": { - "github": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" - } - } - } -} -``` - -`${GITHUB_TOKEN}` のような記法で、実際の値をシェル環境変数から実行時に解決させ、設定ファイル自体にシークレットを平文で書かないのがベストプラクティスです。 - -### 6.5 サブエージェントを無効化したい場合 - -```json -{ - "experimental": { "enableAgents": false } -} -``` - ---- - -## 7. サブエージェント（Subagents）の設計 - -### 7.1 サブエージェントとは - -サブエージェントは、メインの Gemini CLI セッションの中で動く「専門家」です。深いコードベース解析やドメイン固有の推論など、特定タスクをメインエージェントの文脈を汚さずに処理します。メインエージェントからは、サブエージェントは同名の**1つのツール**として見えます。呼び出されると処理を委譲し、完了すると結果だけを報告して戻ります。 - -```mermaid -flowchart LR - U["ユーザーのプロンプト"] --> MAIN["メインエージェント
（Gemini CLI Core）"] - MAIN -- "自動委譲 or @エージェント名で明示指定" --> SUB1["ローカルサブエージェント
（独立したコンテキストウィンドウ）"] - MAIN -- "A2Aプロトコル経由" --> SUB2["リモートサブエージェント
（別プロセス/別言語/別クラウド）"] - SUB1 -- "結果のみ報告" --> MAIN - SUB2 -- "結果のみ報告" --> MAIN - MAIN --> ANS["ユーザーへの応答"] -``` - -### 7.2 組み込みサブエージェント - -| 名前 | 役割 | 既定 | -|---|---|---| -| `codebase_investigator` | コードベース解析・依存関係の可視化 | 有効 | -| `cli_help` | Gemini CLI自体の使い方に関する専門知識 | 有効 | -| `generalist` | メインと同じツールを継承する汎用サブエージェント。マルチファイル改修や大量出力タスクをメインの文脈から隔離するのに使う | 有効 | -| `browser_agent` | ブラウザ操作の自動化（Chrome 144以降必須） | 無効（要有効化） | - -### 7.3 カスタムサブエージェントの作り方（ステップバイステップ） - -1. `.gemini/agents/` （プロジェクト共有）または `~/.gemini/agents/`（個人用）にMarkdownファイルを作成する。 -2. ファイル先頭にYAMLフロントマターを書く（このフォーマットは**必須**）。 -3. フロントマター以降の本文が、そのままサブエージェントの**システムプロンプト**になる。 - -```markdown ---- -name: security-auditor -description: コード内のセキュリティ脆弱性を発見することに特化。 -kind: local -tools: - - read_file - - grep_search -model: gemini-3-flash-preview -temperature: 0.2 -max_turns: 10 ---- -あなたは容赦のないセキュリティ監査官です。コードを分析し、潜在的な脆弱性を洗い出してください。 - -重点項目: -1. SQLインジェクション -2. XSS（クロスサイトスクリプティング） -3. ハードコードされた認証情報 -4. 安全でないファイル操作 - -脆弱性を発見したら明確に説明し、修正案を提示すること。ただし自分で修正はしないこと。 -``` - -### 7.4 フロントマター スキーマ一覧 - -| フィールド | 型 | 必須 | 説明 | -|---|---|---|---| -| `name` | string | ○ | 一意な識別子（小文字・数字・ハイフン・アンダースコアのみ） | -| `description` | string | ○ | どんな時に呼ぶべきかをメインエージェントが判断するための説明 | -| `kind` | string | - | `local`（既定）または `remote` | -| `tools` | array | - | 使用可能なツール一覧。ワイルドカード対応。省略時は親セッションの全ツールを継承 | -| `mcpServers` | object | - | このサブエージェント専用のインラインMCPサーバー定義 | -| `model` | string | - | 使用モデル。既定は親セッションを継承 | -| `temperature` | number | - | 0.0〜2.0、既定 `1` | -| `max_turns` | number | - | 最大ターン数、既定 `30` | -| `timeout_mins` | number | - | 最大実行時間（分）、既定 `10` | - -### 7.5 ツール分離と再帰防止 - -各サブエージェントは独立したコンテキストループで動作し、明示的に許可したツールにしかアクセスできません。**重要な安全設計として、サブエージェントは他のサブエージェントを呼び出せません**（`*` ワイルドカードを与えても他エージェントは見えない）。これにより無限再帰やトークンの爆発的消費を防いでいます。 - -### 7.6 サブエージェント単位のポリシー制御 - -ポリシーエンジンのTOML設定で、特定サブエージェントにだけ適用されるルールを書けます。 - -```toml -[[rules]] -name = "Allow pr-creator to push code" -subagent = "pr-creator" -description = "pr-creatorによる自動ブランチプッシュを許可する。" -action = "allow" -toolName = "run_shell_command" -commandPrefix = "git push" -``` - -### 7.7 説明文（description）の最適化がすべてを左右する - -メインエージェントはサブエージェントの `description` を見て「これは自分の専門家か」を判断します。呼び出し精度を上げる鉄則は、①専門分野、②いつ使うべきか、③具体的な利用シーン例、の3点を書くことです。 - -> Git操作全般（ローカル・リモート双方）に使うべきGitエキスパートエージェント。例: -> - コミットの作成 -> - `bisect`によるリグレッション調査 -> - GitHubなどのソース管理・課題管理システムとのやり取り - ---- - -## 8. リモートサブエージェントと A2A プロトコル入門 - -### 8.1 A2A（Agent-to-Agent）プロトコルとは何か - -A2A は、実装言語やフレームワークを問わずエージェント同士が相互運用できるようにするオープン標準です。「エージェント界のHTTP」と表現され、REST APIにおけるOpenAPI仕様のような役割を果たす **Agent Card** を軸に、次の3つの課題を解決します。 - -1. **発見（Discovery）**: エージェントは `/.well-known/agent.json` というJSONメタデータ（Agent Card）を通じて自身の能力を宣言する。呼び出す側は先にこのカードを取得して「相手が何をできるか」を理解する。 -2. **通信（Communication）**: すべてのデータ交換は単一エンドポイント経由の JSON-RPC 2.0 で行われる。中心となるメソッドは `message/send`（同期的な送受信）で、他に `tasks/send`・`tasks/get` などがある。データは `TextPart`（自然言語）や `DataPart`（構造化JSON）といった型付きの「Message Part」で運ばれる。 -3. **タスクのライフサイクル**: すべてのやり取りは `Task` に包まれ、`submitted → working → completed / failed` という明確な状態遷移をたどる。この仕組みにより、同期的なワークフロー（今すぐこの契約書を確認）と非同期のワークフロー（48時間かけて文書を検証）を同じプロトコルで扱える。 - -```mermaid -sequenceDiagram - participant L as ローカルエージェント
(RemoteA2aAgent) - participant R as リモートエージェント
(A2Aサーバー) - - L->>R: GET /.well-known/agent.json - R-->>L: Agent Card（名前・スキル・対応プロトコル・認証方式） - Note over L,R: カードを解析し、呼び出し可能なスキルを把握 - L->>R: POST JSON-RPC message/send（タスク送信） - R-->>L: Task状態: working - R-->>L: Task状態: completed（結果データを含む） - alt リモートが応答不能な場合 - R--xL: タイムアウト / エラー - L->>L: フェイルセーフ状態へ遷移（例: MANUAL_REVIEW） - end -``` - -### 8.2 Agent Card（`agent.json`）の主要フィールド - -```json -{ - "protocolVersion": "0.3.0", - "name": "Example Agent Name", - "description": "ドキュメント目的のサンプルエージェントの説明。", - "version": "1.0.0", - "url": "https://example.com/a2a", - "preferredTransport": "HTTP+JSON", - "capabilities": { - "streaming": true, - "extendedAgentCard": false - }, - "defaultInputModes": ["text/plain"], - "defaultOutputModes": ["application/json"], - "skills": [ - { - "id": "ExampleSkill", - "name": "Example Skill Assistant", - "description": "このスキルが行うことの説明。", - "tags": ["example-tag"], - "examples": ["ここに例を示してください。"] - } - ] -} -``` - -| フィールド | 意味 | -|---|---| -| `protocolVersion` | 準拠するA2A仕様のバージョン | -| `name` / `description` / `version` | エージェントの識別情報 | -| `url` | このエージェントのA2Aエンドポイント | -| `capabilities.streaming` | SSEによるストリーミング応答に対応しているか | -| `defaultInputModes` / `defaultOutputModes` | 受け付ける/返す既定のMIMEタイプ | -| `skills` | 提供する能力のリスト。各スキルにID・説明・タグ・利用例を持つ | - -### 8.3 Gemini CLI からリモートサブエージェントを定義する - -Gemini CLI 自体も、`.gemini/agents/*.md` で `kind: remote` を指定することで、A2A準拠の外部エージェントをサブエージェントとして直接呼び出せます。 - -```markdown ---- -kind: remote -name: my-remote-agent -agent_card_url: https://example.com/agent-card ---- -``` - -1つのMarkdownファイルに複数のリモートサブエージェントをリスト形式で定義することも可能です（ローカルとリモートの混在や複数ローカルの混在は不可、リモートの複数指定のみサポート）。 - -```markdown ---- -- kind: remote - name: remote-1 - agent_card_url: https://example.com/1 -- kind: remote - name: remote-2 - agent_card_url: https://example.com/2 ---- -``` - -Agent Card を配信するエンドポイントを持たない場合は、`agent_card_json` にJSON文字列を直接埋め込むこともできます（YAMLのブロックスカラー `|` を使うと引用符のエスケープが不要になり可読性が上がります）。 - -### 8.4 認証方式の比較 - -| 認証タイプ | 概要 | 主な用途 | -|---|---|---| -| `apiKey` | 静的なAPIキーをHTTPヘッダーで送信 | サードパーティAPI | -| `http`（Bearer/Basic/Raw） | Bearerトークン、Basic認証、その他IANA登録スキーム | 汎用HTTP認証 | -| `google-credentials` | Google Application Default Credentials（ADC）を利用。ホスト名から自動でアクセストークン/IDトークンを選択 | `*.googleapis.com`（Agent Engine, Vertex AI等）、`*.run.app`（Cloud Run） | -| `oauth` | PKCE付きOAuth 2.0 認可コードフロー。初回はブラウザでサインイン | サードパーティのOAuth対応エージェント | - -**セキュリティ上のポイント**: シークレットはエージェント定義ファイルに直書きせず、`$MY_API_KEY`（環境変数参照）や `!gcloud auth print-token`（シェルコマンド実行結果）のような動的値解決を使うことが推奨されます。特にプロジェクト共有の `.gemini/agents/*.md` はバージョン管理にコミットされる可能性が高いため注意してください。 - ---- - -## 9. agent.py — ADK でのエージェント実装パターン - -### 9.1 基本のエージェント定義 - -ADK（Agent Development Kit）は、Python・Java・Go・TypeScript・Kotlin に対応するオープンソースのマルチエージェント構築フレームワークです。もっとも基本的な `agent.py` は、ツールと指示文を持つ `Agent` オブジェクトを1つ定義するだけです。 - -```python -from google.adk.agents import Agent -from my_tools import fetch_purchase_history, get_policy, send_email, issue_refund, close_ticket - -root_agent = Agent( - name="Refund_Processor", - tools=[fetch_purchase_history, get_policy, send_email, issue_refund, close_ticket], - instruction=""" - あなたは返金処理を担当するカスタマーサービスエージェントです。 - 以下の5ステップを厳密に守ってください。 - 1. fetch_purchase_historyツールで購入履歴を確認する。 - 2. get_policyツールで返金ポリシーを確認する。 - 3. 対象であればissue_refundツールで返金処理を行う。 - 4. send_emailツールで顧客にメールを送る。 - 5. close_ticketツールで返金対応を完了とする。 - """ -) -``` - -このパターンの弱点は、ツールが10〜15個を超えると「モデルがどのツールを呼ぶべきか混乱し始める」「文脈が肥大化して指示を見落とす」といった **コンテキスト劣化（context degradation）** が起きやすくなることです。この課題を解決する2つの方向性が、次節の「マルチエージェント分割」と「ADK 2.0 Workflows」です。 - -### 9.2 マルチエージェント分割のパターン（SequentialAgent） - -1つの巨大なプロンプトに全責務を詰め込む代わりに、責務ごとにエージェントを分割し、`SequentialAgent` で順に実行させます。以下は、Python製の抽出エージェント → Go製のリモート検証エージェント（A2A経由） → レポート生成エージェント、という3段構成の実例です。 - -```python -# python-extraction-agent/app/agent.py -from google.adk.agents import Agent, SequentialAgent -from google.adk.agents.remote_a2a_agent import RemoteA2aAgent -from google.adk.models import Gemini - -# サブエージェント1: LLM推論でデータを抽出 -extractor_agent = Agent( - name="extractor_agent", - model=Gemini(model="gemini-3.5-flash"), - instruction="あなたは法務データ抽出エージェントです。契約書から金額・契約者・日付・保険条項を抽出してください。", - tools=[read_contract_text, save_extracted_fields, classify_risk_level] -) - -# サブエージェント2: Go製のA2Aコンプライアンスサービスをローカルエージェントとしてラップ -compliance_agent = RemoteA2aAgent( - name="compliance_agent", - agent_card=GO_AGENT_CARD_URL, - description="抽出された契約フィールドを企業のコンプライアンスポリシーに照らして検証する。" -) - -# サブエージェント3: 最終監査レポートを生成 -report_agent = Agent( - name="report_agent", - model=Gemini(model="gemini-3.5-flash"), - instruction="最終的なコンプライアンスレポートとMarkdown要約を生成すること。", - tools=[generate_summary_report] -) - -# コーディネーター: 上記3つを順番に連結する -root_agent = SequentialAgent( - name="contract_compliance_coordinator", - description="契約解析・A2Aコンプライアンス検証・最終レポート作成を順に実行する。", - sub_agents=[extractor_agent, compliance_agent, report_agent], -) -``` - -このパターンの利点は、**Pythonのオーケストレーターから見ると、Go製の別言語・別プロセスのサービスが、あたかもローカルのPythonクラスであるかのように呼び出せる**ことです。ADKのSDKが Agent Card の取得、パラメータのシリアライズ、JSON-RPCの通信をすべて裏側で処理してくれます。 - -### 9.3 サブエージェント間のデータ受け渡し（共有状態） - -エージェント間で関数の引数や戻り値としてデータを渡す代わりに、ADKの `ToolContext.state` が提供する共有辞書（セッションステート）を介してやり取りするのが定石です。パイプラインの各ステップを列挙型（Enum）でチェックポイント化しておくと、状態遷移が追跡しやすくなります。 - -```python -from enum import Enum - -class ComplianceStep(str, Enum): - INGESTED = "INGESTED" # 契約書アップロード、抽出待ち - EXTRACTED = "EXTRACTED" # Geminiによるフィールド抽出完了 - COMPLIANCE_PENDING = "COMPLIANCE_PENDING" # Goエージェントへ送信、結果待ち - COMPLIANCE_COMPLETE = "COMPLIANCE_COMPLETE" # Goエージェントの判定を受領 - MANUAL_REVIEW = "MANUAL_REVIEW" # タイムアウト/エラー、人間のレビューへ - REVIEW_READY = "REVIEW_READY" # 違反ありのレポート生成済み - APPROVED = "APPROVED" # 全チェック合格 -``` - -`MANUAL_REVIEW` の設計が特に重要です。リモートのコンプライアンスエージェントがクラッシュ・ネットワークタイムアウト・未起動などの理由で応答不能になっても、パイプラインは単純に失敗するのではなく、人間のレビュー担当者にケースを引き渡す状態へフェイルセーフに遷移します。**リモート依存先が断続的に利用不能になり得る本番システムでは、このフェイルセーフ設計が必須**です。 - -### 9.4 マルチエージェントパイプラインの全体像 - -```mermaid -flowchart LR - IN["契約書入力"] --> EX["extractor_agent
（Python / Gemini）"] - EX -- "共有state経由でデータ受け渡し" --> CO["compliance_agent
（RemoteA2aAgent → Go製サーバー）"] - CO -- "正常応答" --> RE["report_agent
（Python / Gemini）"] - CO -- "タイムアウト/エラー" --> MR["MANUAL_REVIEW
（人間のレビューへ）"] - RE --> OUT["最終監査レポート出力"] -``` - ---- - -## 10. RemoteA2aAgent 実装パターンの詳細 - -### 10.1 3つの指定方法 - -`RemoteA2aAgent` はリモートのA2A準拠エージェントを指し示す方法を3通りサポートします。 - -```python -from google.adk.agents.remote_a2a_agent import RemoteA2aAgent - -# 方法1: Agent CardのURLを直接指定 -remote_agent = RemoteA2aAgent( - name="image_scoring", - description="画像について興味深い事実を教えてくれるエージェント。", - agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json", - timeout=300.0, # HTTPタイムアウト（秒） - httpx_client=None, # カスタムHTTPクライアント（省略可） -) - -# 方法2: ローカルファイルパスとしてAgent Cardを指定 -remote_agent_from_file = RemoteA2aAgent( - name="illustration_agent", - description="イラストを生成するエージェント。", - agent_card="illustration-agent-card.json", -) - -# 方法3: AgentCardオブジェクトを直接構築して渡す（プログラムから動的に生成する場合） -``` - -### 10.2 サブエージェントとして組み込む - -`RemoteA2aAgent` は他の `Agent` と同じインターフェースを持つため、`sub_agents` リストにそのまま加えるだけでメインのオーケストレーターから利用できます。 - -```python -from google.adk.agents.remote_a2a_agent import RemoteA2aAgent -from google.adk import Agent - -data_analyst = RemoteA2aAgent( - name="DataAnalyst", - description="データセットを分析する。", - agent_card="https://agent-b.run.app/.well-known/agent.json" -) - -orchestrator = Agent( - name="Orchestrator", - model="gemini-2.0-flash", - instruction="データ分析タスクはDataAnalystに委譲すること。", - sub_agents=[data_analyst] -) -``` - -これだけで、カスタムのHTTP呼び出しコード、独自レスポンス形式のパース、手動の認証処理、非同期結果のポーリングといった定型作業をすべてADKが肩代わりします。ADKがAgent Cardを読み取り、DataAnalystができることを理解した上で、A2Aプロトコルによる通信をすべて処理してくれます。 - -### 10.3 逆方向: 自分のエージェントをA2A対応で公開する（`to_a2a()`） - -これまでは「他人のリモートエージェントを呼ぶ側」でしたが、逆に**自分のADKエージェントを他のエージェントから呼ばれるように公開する**には `to_a2a()` ユーティリティを使うのが最も簡単な方法です。 - -```python -# あなたの既存のエージェント定義 -root_agent = Agent( - model='gemini-flash-latest', - name='hello_world_agent', - # ...ツールや指示... -) -``` - -```python -from google.adk.a2a.utils.agent_to_a2a import to_a2a - -# エージェントをA2A対応にする -a2a_app = to_a2a(root_agent, port=8001) -``` - -```bash -# uvicornでA2Aサーバーとして起動 -uvicorn agent:a2a_app --host localhost --port 8001 -``` - -`to_a2a()` はAgent Card（`agent.json`）を、あなたのADKエージェントのコードから**自動生成**してくれます（`agent_card` 引数に自分で用意した `AgentCard` オブジェクトやJSONファイルパスを渡して上書きすることも可能）。生成されたカードは `http://localhost:8001/.well-known/agent-card.json` で確認できます。 - -内部的に `to_a2a()` は以下を自動セットアップします。 - -- **`A2aAgentExecutor`**: A2Aプロトコルとあなたの ADK エージェントを橋渡しする実行エンジン -- **`InMemoryTaskStore`** / **`InMemoryPushNotificationConfigStore`**: タスク状態とプッシュ通知の管理 -- **`DefaultRequestHandler`**: 受信したA2A HTTPリクエストを適切にルーティング -- **Starletteアプリ**: 起動時にAgent Cardを自動構築し、必要なA2A APIルートをすべてマウント - -### 10.4 もう一つの公開方法: `adk api_server --a2a` - -自前で `agent.json` を作成し、`adk api_server --a2a` でホストする方法もあります。この方式のメリットは、`adk web` と組み合わせてデバッグしやすいこと、また1つのサーバーで複数の独立したエージェントを親フォルダ配下にまとめて配信できることです。 - -```bash -# following command runs the ADK agent as a2a agent -adk api_server --a2a --port 8001 remote_a2a -``` - -### 10.5 開発時のディレクトリ構成例 - -```text -a2a_root/ -├── remote_a2a/ -│ └── hello_world/ -│ ├── __init__.py -│ └── agent.py # 公開する側（to_a2a()でa2a_appを定義） -├── README.md -└── agent.py # 呼び出す側（RemoteA2aAgentでroot_agentを定義） -``` - -```bash -# 1. リモート（公開）側を起動 -uvicorn contributing.samples.a2a_root.remote_a2a.hello_world.agent:a2a_app --host localhost --port 8001 - -# 2. 別ターミナルで、呼び出す側（コンシューマー）のadk webを起動 -adk web contributing/samples/ -``` - -`adk web` の既定ポートは `8000` なので、公開側は必ず別ポート（例では `8001`）で立てる必要があります。 - ---- - -## 11. Vertex AI Agent Engine へのデプロイ - -### 11.1 Agent Engine とは - -Vertex AI Agent Engine は、ADK・LangChain 等のフレームワークで作られたエージェントを、インフラ管理・オートスケーリング・APIサービングまで含めてマネージドで実行してくれる Google Cloud のサービスです。**2026年7月時点で、Python版ADKエージェントのみが Agent Engine の対応言語**とされています（Go/Java版ADKはCloud Run等の別ターゲットを利用）。 - -```mermaid -flowchart LR - A["ローカルのagent.py
（root_agent定義）"] --> B["adk deploy agent_engine
（CLIコマンド）"] - B --> C["コンテナビルド"] - C --> D["Vertex AI Agent Engine
（Reasoning Engine リソース）"] - D --> E["REST / A2A エンドポイント公開"] - E --> F["クライアント
（Vertex AI SDK / REST / RemoteA2aAgent）"] -``` - -### 11.2 デプロイ手順（ステップバイステップ） - -1. **前提となるIAM権限を確認する。** Agent Engineを使うには、プロジェクトに必要なIAMロールを管理者から付与してもらう必要があります。 -2. **SDKをインストールする。** - -```bash -pip install --upgrade --quiet "google-cloud-aiplatform[agent_engines,adk]>=1.112" -``` - -3. **ローカルで認証する。** - -```bash -gcloud auth application-default login -``` - -4. **`adk deploy agent_engine` コマンドでデプロイする。** このコマンドはコードのパッケージング、コンテナビルド、Agent Engineへのデプロイまでを一括で行います（数分かかります）。 - -```bash -PROJECT_ID=my-project-id -LOCATION_ID=us-central1 - -adk deploy agent_engine \ - --project=$PROJECT_ID \ - --region=$LOCATION_ID \ - --display_name="My First Agent" \ - multi_tool_agent -``` - -5. **デプロイ完了後に得られる `RESOURCE_ID` を控える。** このIDと `PROJECT_ID`・`LOCATION_ID` を組み合わせて、以降のクエリ用URLを構築します。 - -```text -https://{LOCATION_ID}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION_ID}/reasoningEngines/{RESOURCE_ID}:query -``` - -### 11.3 コードから直接デプロイする方法（in-memory object deployment） - -CLIコマンド以外に、Python から直接 `agent_engines` モジュールを使ってデプロイすることもできます。ローカルで動いているエージェントオブジェクトを `cloudpickle` でシリアライズし、Cloud Storage にアップロードしてからクラウド上で復元する流れです。 - -```python -import vertexai -from vertexai.preview import reasoning_engines - -vertexai.init( - project="your-gcp-project-id", - location="us-central1", - staging_bucket="gs://my-agent-staging-bucket", # ステージング用バケットが必須 -) - -# ローカルのadk_appオブジェクトをそのままデプロイ -remote_app = vertexai.agent_engines.create( - reasoning_engines.AdkApp(agent=root_agent, enable_tracing=True), -) -``` - -Agent Engine にデプロイすると、ADKの `InMemorySessionService`（ローカル開発用、本番運用には不向き）に代わって、Agent Engine 側のマネージドセッション管理が使われるようになります。 - -### 11.4 デプロイしたエージェントをA2A経由で呼び出す - -Agent Engine にデプロイしたエージェントは、A2Aエンドポイントとしても公開されるため、第10章の `RemoteA2aAgent` からそのまま呼び出せます。認証には `google-credentials`（Application Default Credentials）を使うのが定石です。 - -```python -import os -from google.adk.agents.remote_a2a_agent import RemoteA2aAgent - -PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT") -LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION") -REASONING_ENGINE_ID = os.getenv("REASONING_ENGINE_ID") -AGENT_ENGINE_RESOURCE = f"projects/{PROJECT_ID}/locations/{LOCATION}/reasoningEngines/{REASONING_ENGINE_ID}" -a2a_url = f"https://{LOCATION}-aiplatform.googleapis.com/v1beta1/{AGENT_ENGINE_RESOURCE}/a2a" - -time_agent = RemoteA2aAgent( - name="time_agent", - description="Agent Engine上で動くA2Aエージェント。", - agent_card=f"{a2a_url}/v1/card", -) -``` - -> **実務上の注意点**: Google Cloud の認証トークンは有効期限があるため、長時間動作するプロセスでは `httpx.Auth` を実装してトークンを自動リフレッシュする仕組みを組み込む必要があります。単純に `credentials.refresh()` を一度呼ぶだけでは、長時間セッションの途中でトークン期限切れによるエラーが発生します。 - -### 11.5 デプロイ先の比較 - -| デプロイ先 | 向いているケース | 言語対応 | -|---|---|---| -| Vertex AI Agent Engine | マネージドなセッション管理・オートスケール・ADKとの統合を重視する場合 | Python ADKのみ | -| Cloud Run | ステートレス、または外部バックエンド（Cloud SQL/GCS）を使うステートフルなWeb向けエージェント | 全言語（コンテナ化できれば何でも） | -| GKE（Google Kubernetes Engine） | 既存のKubernetes運用基盤に統合したい、より高い制御が必要な場合 | 全言語 | - ---- - -## 12. ADK 2.0: Agent と Workflow の使い分け - -### 12.1 なぜ「決定論的ワークフロー」が必要になったのか - -自律的なLLMエージェントに、手順が固定されたビジネスプロセス（「ステップAの後は必ずステップB」）を丸ごと任せると、コンテキストが混雑してきたときに手順を飛ばしたり、失敗を無視して先に進んでしまったりすることがあります。100回実行して95回は狙い通りでも、残り5回で逸脱するようでは本番システムとして不十分です。ADK 2.0 の `Workflow` は、実行ルーティングを言語モデルの推論から切り離し、コードによる有向グラフとして厳密に制御します。 - -### 12.2 使い分けの判断基準 - -| 状況 | 選ぶべきもの | -|---|---| -| ビジネスロジックや実行順序があらかじめ決まっている | Workflow | -| 決定論的な実行経路・厳格なコンプライアンス・明確な失敗状態が必要 | Workflow | -| オーケストレーションのトークン消費・レイテンシを最小化したい | Workflow | -| 自然言語・複雑なメール・画像など非構造化/曖昧な入力を処理する | Agent | -| 要約・分類・文章生成など主観的判断が要求される | Agent | -| 次のアクションが動的な推論に依存し、単純な条件分岐で表現できない | Agent | - -### 12.3 効果の実例（公開されているベンチマーク） - -Googleが公開したブログ記事によれば、返金処理という定型業務を例にした場合、LLMループにすべて任せる方式から ADK 2.0 の Workflow 方式に切り替えることで、次のような効率化が確認されています（Gemini 3.5 Flash・モックAPIによる参考値）。 - -| 指標 | 従来のLLMエージェント | ADK 2.0 Workflow | 削減率 | -|---|---|---|---| -| トークン使用量（1回あたり） | 5,152 | 2,265 | 約50% | -| レイテンシ（1回あたり） | 7.2秒 | 5.7秒 | 約20% | - -### 12.4 Workflow の考え方（概念図） - -```mermaid -flowchart TD - START(["開始"]) --> A["Node A（ツール）
購入履歴をDB/API経由で取得"] - A --> B["Node B（LLMエージェント）
非構造化のメール内容をポリシー例外と照合"] - B -->|"true"| C["Node C（ツール）
Stripe APIで返金を実行"] - B -->|"false"| E["Node E（ツール）
CRMのチケットを更新して終了"] - C --> D["Node D（LLMエージェント）
確認メールの文面をドラフト"] - D --> E -``` - -決定論的なノード（A・C・E）はコードとして高速に遷移し、曖昧な判断が必要なノード（B・D）だけをLLMエージェントに任せます。これにより、①コンテキストの肥大化（大量のAPIレスポンスをそのまま会話履歴に積み上げない）、②プロンプトインジェクションへの耐性（ワークフローのグラフ自体が「実行できる経路」を制限する境界になるため、LLMノードが操作されても未承認のアクションへの経路が存在しない）という2つの効果が得られます。 - -マルチエージェント設計においては、「サブエージェント間の受け渡しの多くをWorkflowの決定論的ノードにできないか」を検討する価値があります。 - ---- - -## 13. セキュリティ・ガバナンスのベストプラクティス - -### 13.1 チェックリスト - -- [ ] シークレット（APIキー・トークン）は `settings.json` や `.gemini/agents/*.md` に直書きせず、環境変数参照（`$ENV_VAR`）またはシェルコマンド参照（`!command`）を使っているか -- [ ] `.geminiignore` に `.env`、認証情報ファイル、シークレットを含むディレクトリを登録しているか -- [ ] リモートエージェントの認証には、可能な限り `google-credentials`（ADC）を使い、生の長期トークンをファイルに埋め込んでいないか -- [ ] サブエージェントごとにポリシーエンジン（`policy.toml`）で権限を絞っているか（特に `run_shell_command` や `write_file` を持つサブエージェント） -- [ ] リモート依存先が落ちた場合のフェイルセーフ状態（`MANUAL_REVIEW` 等）を設計しているか -- [ ] 決定論的に処理できる箇所をADK 2.0 Workflowに切り出し、LLMがアクセスできる実行経路を最小化しているか -- [ ] `security.folderTrust.enabled` を有効にし、信頼していないディレクトリでの自動承認を防いでいるか - -### 13.2 認証情報の取り扱いに関する注意 - -第8章・第11章で見た通り、A2Aプロトコルは `apiKey`・`http`(Bearer/Basic)・`google-credentials`・`oauth` という複数の認証方式をサポートしています。プロジェクト共有される設定ファイル（`.gemini/agents/*.md` や `settings.json` のワークスペーススコープ）はバージョン管理にコミットされがちなので、**シークレットの値そのものではなく、参照方法だけを記述する**ことを徹底してください。 - ---- - -## 14. 総合ステップバイステップ: ゼロからのマルチエージェント構築フロー - -最後に、ここまでの内容を1つの流れとして統合します。 - -1. **リポジトリ設計**: ルートに `AGENTS.md`（または `GEMINI.md`）を作成し、全体アーキテクチャと各サブエージェントの責務分担を書く。各サブエージェントのディレクトリにその場限りの `AGENTS.md` を追加する。 -2. **除外設定**: `.geminiignore` でシークレット・大容量データ・生成物ディレクトリを除外する。 -3. **CLI設定**: `.gemini/settings.json` で `context.fileName`、`agents.overrides`、必要なMCPサーバーを設定する。 -4. **ローカルサブエージェント定義**: `.gemini/agents/*.md` にYAMLフロントマター付きでツール・モデル・実行上限を定義する。 -5. **ADKでのエージェント実装**: `agent.py` に `Agent` / `SequentialAgent` / `Workflow` を組み合わせて実装する。決定論的な部分はWorkflowノードに、曖昧な判断はLLMエージェントに割り振る。 -6. **他言語・他チームのサービスをA2A化**: 相手チームのサービスには `to_a2a()`（または `adk api_server --a2a`）でAgent Cardを自動生成させ、公開する。 -7. **リモートエージェントの取り込み**: 自分側では `RemoteA2aAgent` でAgent Cardを指定し、`sub_agents` に加えるだけでローカルクラスのように扱う。 -8. **ローカルでの動作確認**: `uvicorn` で公開側を起動し、`adk web` で呼び出し側を起動して、別ポートで対話的にテストする。 -9. **本番デプロイ**: `adk deploy agent_engine` で Vertex AI Agent Engine にデプロイし、`google-credentials` 認証でA2Aエンドポイントを保護する。 -10. **継続的な運用**: `settings.json` のポリシーエンジンとサブエージェント別のオーバーライドで、権限とコストを継続的にチューニングする。 - ---- - -## 15. 参考文献・出典 - -本ガイドは以下の一次情報源（公式ドキュメント・Google公式ブログ・実装者による技術記事）に基づいて2026年7月時点の内容をまとめています。 - -**Gemini CLI 公式ドキュメント** -- GEMINI.mdによる文脈提供: https://geminicli.com/docs/cli/gemini-md/ -- .geminiignore（除外ファイル）: https://geminicli.com/docs/cli/gemini-ignore/ -- settings.json 設定リファレンス: https://geminicli.com/docs/cli/settings/ -- サブエージェント: https://geminicli.com/docs/core/subagents/ -- リモートサブエージェント（A2A）: https://geminicli.com/docs/core/remote-agents/ - -**Google 公式ブログ・アナウンス** -- Gemini CLIからAntigravity CLIへの移行について（2026年5月19日）: https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli -- ADK 2.0を構築した理由（2026年7月1日）: https://developers.googleblog.com/why-we-built-adk-20/ -- Google ADKとA2Aによるクロス言語マルチエージェントチーム構築（2026年6月22日、Shubham Saboo・Eric Dong）: https://developers.googleblog.com/build-cross-language-multi-agent-team-with-google-agent-development-kit-and-a2a/ - -**ADK 公式ドキュメント / GitHub** -- A2Aクイックスタート（エージェントの公開・`to_a2a()`）: https://adk.dev/a2a/quickstart-exposing/ -- RemoteA2aAgent 実装（ソースコード）: https://github.com/google/adk-python/blob/main/src/google/adk/agents/remote_a2a_agent.py -- ADKを使ったマルチエージェント構築・Agent Runtimeデプロイ・A2Aプロトコル入門codelab: https://codelabs.developers.google.com/codelabs/create-multi-agents-adk-a2a -- Vertex AI Agent EngineでのADK利用（Google Cloud公式ドキュメント）: https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/use/adk -- Google Skills: A2A SDKでリモートエージェントに接続する: https://www.skills.google/focuses/132170?parent=catalog - -**AGENTS.md オープン標準** -- AGENTS.md 公式サイト: https://agents.md/ -- AGENTS.md GitHubリポジトリ: https://github.com/agentsmd/agents.md - -**実装者・Google Developer Expertによる技術記事** -- xbill（Google Developer Expert）によるADK・A2A・Gemini CLIを用いたマルチエージェント実装シリーズ（Cloud Run編）: https://medium.com/google-cloud/multi-agent-a2a-with-the-agent-development-kitadk-cloud-run-and-gemini-cli-52f8be838ad6 -- Michaël Scherding によるADK + Agent Engineデプロイ解説: https://michael-scherding.medium.com/deploying-ai-agents-with-google-adk-and-vertex-ai-agent-engine-62a5c19396ff -- Michaël Scherding によるA2A + ADK解説: https://michael-scherding.medium.com/a2a-explained-with-google-adk-140b35ad04ad - -> 免責事項: Gemini CLI / ADK / Agent Engine はいずれも活発に開発が続いているプロダクトであり、上記の内容は情報基準日（2026年7月26日）時点のものです。特にGemini CLIとAntigravity CLIの統合方針は今後変更される可能性があるため、実装前に必ず各公式ドキュメントの最新版を確認してください。 diff --git a/Harness-engineering-google-guide.md b/Harness-engineering-google-guide.md deleted file mode 100644 index 8a9977cb..00000000 --- a/Harness-engineering-google-guide.md +++ /dev/null @@ -1,523 +0,0 @@ -# Googleにおける Harness Engineering 実践ガイド -### ― AI仕様駆動開発(Spec-Driven Development)を支える「制御層」の設計 ― - -> 対象読者：AIコーディングエージェント（Antigravity、Gemini CLI、Claude Code、Codex等）を業務で使い始めたばかりのエンジニア・QAエンジニア -> 前提知識：不要（用語はすべて本文中で定義します） - ---- - -## この記事で学べること - -- 「Harness Engineering（ハーネスエンジニアリング）」という新しい概念が、なぜ2026年に入って急速に注目されているのか -- ハーネスが具体的に何を指すのか（Guides／Sensors、Computational／Inferential） -- Harness EngineeringとSpec-Driven Development（仕様駆動開発）がどう補完し合うのか -- Googleが自社のエージェント製品（Google Antigravity／ADK／Agent Skills）でこの考え方をどう実装しているか -- 自分のプロジェクトで今日から始められる、ステップバイステップの実践手順 - ---- - -## 目次 - -1. [Harness Engineeringとは何か](#1) -2. [なぜ今ハーネスが必要なのか](#2) -3. [ハーネスの構造 ― Agent HarnessとUser Harness](#3) -4. [Feedforward（Guides）とFeedback（Sensors）](#4) -5. [ComputationalとInferential](#5) -6. [3つの統制次元](#6) -7. [Harness EngineeringとSpec-Driven Developmentの関係](#7) -8. [Googleにおける実践の全体像](#8) -9. [ステップバイステップ実践ガイド](#9) -10. [変更のライフサイクルにおける配置（Keep Quality Left）](#10) -11. [アンチパターンと落とし穴](#11) -12. [業界の広がり ― OpenAIとの比較](#12) -13. [実践チェックリスト](#13) -14. [まとめ](#14) -15. [参考文献](#15) - ---- - - -## 1. Harness Engineeringとは何か - -### 1.1 「Agent = Model + Harness」という定式 - -2026年前半、AIコーディングエージェント界隈で急速に広まった等式があります。 - -``` -Agent（エージェント） = Model（モデル） + Harness（ハーネス） -``` - -これは「エージェントの性能は、モデル単体の賢さだけでは決まらない。モデルの周りに何を組み立てるかで決まる」という考え方です。ハーネス（harness）はもともと「馬具」「安全ベルト」を意味する英単語で、ここでは「モデルを制御し、方向づけ、安全に走らせるための仕組み一式」を指す比喩として使われています。 - -具体的には、システムプロンプト、コード検索の仕組み、ツール呼び出しの設計、テストやリンター、レビューの手順、プロジェクトのルール文書など、**モデル本体を除いたエージェントを取り巻くすべて**がハーネスに含まれます。 - -### 1.2 用語の起源 - -「Harness Engineering」という言葉自体は、Terraformの生みの親として知られるMitchell Hashimotoが2026年初頭に提唱したとされています。その原則は「エージェントが同じ間違いを一度でも犯したら、二度と同じ間違いをしないよう、その場でハーネス側に修正を組み込む」というものでした。 - -この考え方はすぐにOpenAI、そしてソフトウェア工学の分野で長年発信を続けてきたMartin Fowler（Thoughtworks）のサイトへと広がります。特に、Thoughtworksのディスティングイッシュト・エンジニアであるBirgitta Böckelerが2026年4月に公開した記事「Harness engineering for coding agent users」は、この概念を体系立てて整理した基礎文献として、以後多くの実践者に引用されています。本ガイドの用語整理も、主にこの記事の枠組みに沿っています。 - -Googleの文脈では、この考え方は「Google Antigravity」というAIファーストの開発環境や、「Agent Development Kit (ADK)」、そして後述する「Agent Skills」というオープンな仕組みを通じて、非常に具体的なプロダクトの形に落とし込まれています。 - ---- - - -## 2. なぜ今ハーネスが必要なのか - -### 2.1 Vibe Codingの限界 - -「Vibe Coding（ヴァイブコーディング）」とは、仕様書を書かずに、その場の感覚（vibe）でAIに指示を出しながらコードを生成させていくスタイルを指す言葉です。プロトタイプや使い捨てスクリプトには向いていますが、次のような理由でプロダクションコードには向きません。 - -- コードベースが大きくなると、機能同士が干渉し始める -- 数週間後にコードを見返しても、「なぜこの実装にしたのか」という意思決定の記録が残っていない -- AIが生成した内容を「なんとなく動いているから」という理由で受け入れてしまう - -このように、動くけれどもチームのアーキテクチャ基準やセキュリティ要件、非機能要件を満たさないコードは、しばしば「AI Slop（AIのゴミ、无秩序に生成された低品質コード）」と呼ばれます。 - -### 2.2 信頼のギャップ - -人間のソフトウェアエンジニアがAI生成コードに対して抱く不信感には、構造的な理由があります。LLMは非決定的であり、チームやプロジェクト固有の文脈を知らず、そしてコードを「理解」しているのではなくトークンの並びとして扱っています。 - -Böckelerの整理によれば、優れたハーネスは次の2つを実現します。 - -1. エージェントが**最初の試みで**良い結果を出す確率を高める -2. 問題が人間の目に触れる前に、エージェント自身が**自己修正**できるフィードバックループを提供する - -結果として、人間によるレビューの手間が減り、システム全体の品質が上がり、無駄なトークン消費も減らせる、というのがハーネスに投資する動機です。 - ---- - - -## 3. ハーネスの構造 ― Agent HarnessとUser Harness - -「ハーネス」という言葉は、どの立場で使うかによって指すものが変わります。Böckelerはこれを3つの同心円で説明しています。 - -```mermaid -flowchart TB - subgraph outer["User Harness（ユーザーハーネス）
私たちが自分のユースケース・システム向けに構築する追加の制約"] - subgraph inner["Agent Harness（エージェントハーネス／ビルダーハーネス）
コーディングエージェント製品にあらかじめ組み込まれた基盤"] - model(("モデル（LLM）
推論そのもの")) - end - end -``` - -- **モデル**：LLM本体。推論エンジンそのもの -- **Agent Harness（ビルダーハーネス）**：Google Antigravity、Claude Code、Codexといった製品自体に組み込まれているシステムプロンプト、コード取得の仕組み、オーケストレーション機構など -- **User Harness（ユーザーハーネス）**：私たちユーザーが、自分たちのリポジトリやユースケースに合わせて追加で組み立てる仕組み（ルール文書、Skill、リンター設定、CIチェックなど） - -本ガイドで「Harness Engineering」と呼ぶ場合、主にこの一番外側の**User Harnessをどう設計するか**という実践を指しています。 - ---- - - -## 4. Feedforward（Guides）とFeedback（Sensors） - -ハーネスを構成する要素は、大きく2つの働きに分類できます。 - -- **Guides（フィードフォワード制御）**：エージェントが行動を起こす**前に**、望ましくない出力をあらかじめ予測して防ぐ仕組み。例：コーディング規約を書いたルール文書、Skill、テンプレート -- **Sensors（フィードバック制御）**：エージェントが行動を起こした**後に**観察し、自己修正を促す仕組み。例：リンターのエラーメッセージ、自動テスト、レビューエージェントの指摘 - -重要なのは、この2つはセットで機能するという点です。フィードバックだけに頼ると、エージェントは何度も同じ間違いを繰り返します。逆にフィードフォワードだけでは、そのルールが実際に守られているかどうかを確認する手段がありません。 - -```mermaid -flowchart LR - H["人間（エンジニア）"] -->|"設計・改善する"| G["Guides
(Feedforward)"] - H -->|"設計・改善する"| S["Sensors
(Feedback)"] - G -->|"事前に行動を誘導"| A["コーディングエージェント"] - A -->|"コード・PRを生成"| O["成果物"] - O --> S - S -->|"自己修正シグナルを返す"| A - S -->|"繰り返し起きる問題を報告"| H -``` - -人間の役割は、このループを**ステアリング（操縦）**することです。同じ問題が2回、3回と繰り返し発生したら、それはハーネス側（GuideかSensorのどちらか、あるいは両方）を改善すべきというサインになります。 - ---- - - -## 5. ComputationalとInferential - -Guide・Sensorには、それぞれ実行方式による違いもあります。 - -| 分類 | 特徴 | 実行主体 | 速度・コスト | 具体例 | -|---|---|---|---|---| -| **Computational（計算的）** | 決定的（deterministic）で高速 | CPU | ミリ秒〜秒単位、安価で信頼性が高い | テスト、リンター、型チェッカー、構造解析 | -| **Inferential（推論的）** | 意味的な判断、非決定的 | GPU/NPU（LLM自身） | 数秒〜数十秒、高コストで結果がばらつく | AIによるコードレビュー、"LLM as judge" | - -Computationalなセンサーは、あらゆる変更のたびに安価に実行できる一方、意味的な妥当性までは判断できません。Inferentialなセンサーはコストが高く非決定的ですが、豊かな文脈判断ができ、強力なモデルと組み合わせることで信頼性を高められます。 - -Böckelerの記事にある整理表を、日本語でまとめ直すと次のようになります。 - -| 対象 | 方向 | 種別 | 実装例 | -|---|---|---|---| -| コーディング規約 | Feedforward | Inferential | AGENTS.md、Skill | -| 新規プロジェクトの初期化手順 | Feedforward | 両方 | 手順を書いたSkill＋ブートストラップスクリプト | -| コード変換（Codemod） | Feedforward | Computational | 自動リファクタリングツール | -| 構造テスト | Feedback | Computational | モジュール境界違反を検出するアーキテクチャテスト | -| レビュー手順 | Feedback | Inferential | レビュー用Skill | - ---- - - -## 6. 3つの統制次元 - -ハーネスが「何を」規律づけようとしているのかを整理すると、次の3つのカテゴリに分けられます。難易度も大きく異なります。 - -| 統制次元 | 保証したいこと | Feedforwardの例 | Feedbackの例 | 現在の成熟度 | -|---|---|---|---|---| -| **保守性ハーネス**
(Maintainability) | コードの重複排除・複雑度・スタイルの一貫性 | AGENTS.md、Skill、Lint設定 | 静的解析、カバレッジ計測、循環的複雑度チェック | 高い（既存ツールが豊富） | -| **アーキテクチャ適合性ハーネス**
(Architecture Fitness) | 性能・可観測性など非機能要件の維持 | 性能要件を書いたSkill、ロギング規約 | 性能テスト、ログ品質のレビュー | 中程度 | -| **振る舞いハーネス**
(Behaviour) | 機能仕様どおりに動作しているか | 機能仕様（spec） | テストスイート、手動テスト、承認済みフィクスチャ | 低い（未解決の課題が多い） | - -保守性は既存の静的解析ツールが流用できるため比較的簡単ですが、「振る舞いが仕様どおりか」を機械的に判定する方法は、業界全体でまだ発展途上です。AIが生成したテストスイートが本当に正しい振る舞いを検証できているかどうかを、AI自身に評価させることには限界があるためです。 - ---- - - -## 7. Harness EngineeringとSpec-Driven Developmentの関係 - -ここまで見てきたハーネスの仕組みは、**何を規律づけるべきかという「基準」がなければ機能しません**。その基準を提供するのがSpec-Driven Development（SDD、仕様駆動開発）です。 - -SDDとは、コードを書く前に「何を作るのか」「誰のためか」「成功基準は何か」を明文化した**仕様書（spec）を主たる成果物**として扱う開発手法です。コードは、その仕様から導かれる派生物という位置づけになります。 - -- **SDDがなければ**：ハーネスが具体的に何を強制すればよいのか、参照する対象がありません -- **ハーネスがなければ**：仕様書を書いても、それが実際に守られているかを確認する手段がありません - -つまり、**SDDが「規律の対象」を用意し、ハーネスが「規律を強制する仕組み」を提供する**という、補完関係にあります。この考え方は複数の実践者が独立に強調しており、Harness EngineeringはSpec-Driven Developmentという土台があって初めて実用的になる、という指摘は業界内でも共通認識になりつつあります。 - ---- - - -## 8. Googleにおける実践の全体像 - -ここからは、Googleがこの理論をどう具体的なプロダクトに落とし込んでいるかを見ていきます。 - -### 8.1 Google Antigravity - -Google Antigravityは、Google DeepMindが手がける「エージェントファースト」の開発環境です。エディタ・ターミナル・統合ブラウザを横断してエージェントを動かし、コード変更だけでなく、タスクリストやスクリーンショット、テスト出力といった「Artifacts（証跡）」を生成することで、人間が信頼して検証できるようにする設計思想を持っています。 - -ターミナル向けの軽量版として、Go言語で書かれたTUI（Terminal User Interface）である **Antigravity CLI（`agy`コマンド）** も提供されています。これはデスクトップ版のAntigravity 2.0と同じエージェントハーネスに接続しています。 - -### 8.2 Agent Skills（google/skills、Addy Osmaniのagent-skills） - -「Skill」とは、エージェントに特定タスクの方法論やドメイン知識を教える、軽量で移植可能な仕組みです。`SKILL.md`というMarkdownファイル1枚（＋任意のスクリプトやテンプレート）で構成されており、次の3段階の「プログレッシブ・ディスクロージャー（段階的開示）」でコンテキストウィンドウを節約します。 - -1. **Discovery（発見）**：起動時、エージェントはすべてのSkillの名前と説明（メタデータ、数百トークン程度）だけを読み込む -2. **Activation（活性化）**：今のタスクがSkillの説明と一致したときだけ、`SKILL.md`本体（数千トークン程度）を読み込む -3. **Execution（実行）**：必要に応じて、Skillに同梱されたスクリプトや参考資料を読み込む - -Googleは2026年のCloud Next（Google Cloudの年次イベント）で、BigQuery・Cloud Run・Firebase・GKE・Gemini APIなどに関する公式Skill集を **`github.com/google/skills`** としてオープンソース公開しました。これにより、エージェントは古い学習データに頼るのではなく、Google製品に関する最新かつ正確な知識を都度読み込めるようになります。 - -もう一つ重要な取り組みが、Google Chromeのエンジニアリングディレクターであり、フロントエンド分野で国際的に著名な開発者でもある **Addy Osmani** が個人で公開した **`addyosmani/agent-skills`** です。これはGoogle社内のエンジニアリング文化（設計ドキュメント→レビュー→実装→可読性レビュー→リリースチェックリストという一連の流れや、「Software Engineering at Google」に登場するHyrumの法則、テストピラミッド、Beyonceルール、トランクベース開発などの考え方）を、20〜24個の構造化されたSkillとして蒸留し、一般公開したものです。 - -- `DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP` という開発ライフサイクル全体をカバー -- `/spec` `/plan` `/build` `/test` `/review` `/ship` などのスラッシュコマンドで各フェーズを起動 -- 各Skillには「アンチ合理化テーブル」が含まれ、「テストは後で書きます」のようなエージェントの言い訳を先回りして封じる設計になっている -- Claude Code、Cursor、Gemini CLI、Windsurf、GitHub Copilot、Kiroなど複数のツールで動作する - -### 8.3 Agent Development Kit（ADK） - -ADKはGoogleが提供するAIエージェント構築フレームワークです。ADK自体にもSkillの仕組み（`SkillToolset`）が組み込まれており、L1メタデータ（約100トークン）→L2命令本体（5,000トークン未満）→L3リソース、という前述と同様の段階的開示パターンを採用しています。 - ---- - - -## 9. ステップバイステップ実践ガイド - -ここからは、実際にGoogle Antigravity（またはAntigravity CLI）を題材に、ゼロからハーネスを組み立てていく手順を追っていきます。他のエージェント（Gemini CLI、Claude Code等）でも考え方はそのまま応用できます。 - -### Step 1：エージェントハーネスを選ぶ - -まず、どの製品の上に自分たちのUser Harnessを構築するかを決めます。Antigravityは「タスクのスループット（実装・テスト・検証を一気通貫でこなす力）」に強みがあり、Artifactsによる証跡管理を重視する現場に向いています。比較として、他の代表的な選択肢との違いを整理します。 - -| 製品 | 強み | 向いている場面 | -|---|---|---| -| **Google Antigravity** | エディタ・ターミナル・ブラウザ横断のオーケストレーションと検証、Artifactsによる証跡管理 | エンドツーエンドのタスク処理能力を重視したい場合 | -| **Cursor** | エディタ内での高速な反復（Tab補完、インライン編集） | エディタでの作業速度そのものを重視したい場合 | -| **Kiro** | 要件・設計・タスクを明示的に前面へ出したSpec-Driven Development、フック機構 | 最初から本番運用を見据えた仕様駆動を徹底したい場合 | - -### Step 2：プロジェクトコンテキストをブートストラップする（Rules） - -Antigravityには3階層のコンテキストがあります。 - -| 階層 | 保存場所（例） | 性質 | -|---|---|---| -| **Rules** | `.agents/rules/` | 常時有効。すべての会話で読み込まれる | -| **Skills** | `.agents/skills/` | オンデマンド。タスクが一致したときだけ読み込まれる | -| **Workflows** | `.agents/workflows/` | スラッシュコマンドで手動起動する定型プロセス | - -既存のリポジトリ（READMEが古い、ドキュメントが更新されていないなど、よくある現場の状態）を対象にする場合、最初にやるべきことは「今のコードベースを理解したコンテキスト文書」を作ることです。`repo-research`のようなSkillを使い、次のように指示します。 - -```text -このリポジトリを調査して、プロジェクトコンテキスト文書を作成してください -``` - -これにより、技術スタック・ディレクトリ構成・データモデル・外部連携などをまとめた`.agents/rules/project-context.md`が生成されます。以後のすべての会話がこの文書を自動的に参照するようになります。 - -### Step 3：プロジェクト憲法（Constitution）を定義する - -次に、「非交渉の原則（non-negotiable principles）」を定めた**プロジェクト憲法**を用意します。これは`.specify/memory/constitution.md`のようなファイルに保存され、後述するSDDサイクルの「計画」フェーズと「分析」フェーズで、この憲法に違反していないかが自動的にチェックされます。 - -```text -/speckit.constitution -このプロジェクトは1人の開発者が保守する小規模なエージェントです。 -以下の3原則を設定してください： -(1) すべてのデータベース操作はツール定義ファイル経由で行い、 - コード内に生SQLやORMを書かない -(2) セッション状態は標準の仕組みだけを使い、独自の状態管理を作らない -(3) シンプルさを最優先し、既存のファイル・命名規則を厳密に踏襲する -``` - -憲法が空のテンプレートのままだと、計画・分析フェーズのチェックには「照合する対象が何もない」状態になってしまいます。プロジェクトの規模やチーム体制に応じて、原則の数や内容は調整してください（チーム開発であれば、コードレビュー・テスト規律・可観測性・APIバージョニングなどの原則を追加するのが一般的です）。 - -### Step 4：Skillsでフィードフォワードを設計する - -Skillには大きく3つのカテゴリがあります。目的に応じて組み合わせます。 - -| カテゴリ | 役割 | 例 | -|---|---|---| -| **ドメイン知識** | 特定の技術・APIについての正確な最新知識を与える | `google/skills`（BigQuery、Cloud Run等） | -| **方法論** | 開発の進め方そのものを規律づける（Spec-Driven Developmentを強制する等） | `obra/superpowers` | -| **効率化** | トークン消費を抑え、やり取りを簡潔にする | `JuliusBrussee/caveman` | - -Skillなしでエージェントに機能追加を依頼すると、次の2つのギャップが生まれがちです。 - -1. **プロセスのギャップ**：構造がないと、エージェントはいきなりコードを書き始めてしまう。小さな修正なら問題ありませんが、複数ファイル・複数エンドポイントに影響する機能では、実装がバラバラになり、決定の記録も残りません -2. **知識のギャップ**：学習データが古く、非推奨のAPIやスキーマを使ってしまう - -方法論Skillが(1)を、ドメイン知識Skillが(2)を埋める役割を担います。 - -### Step 5：MCPで知識ギャップを埋める - -MCP（Model Context Protocol）は、エージェントが外部システムと接続するための標準プロトコルです。BigQueryを例にすると、MCPサーバーに接続することで、エージェントは学習データにある古いスキーマ情報に頼るのではなく、**実際のテーブル定義をその場で確認しながら**仕様書やコードを生成できます。 - -```json -{ - "mcpServers": { - "bigquery": { - "serverUrl": "https://bigquery.googleapis.com/mcp", - "transport": "http", - "authProviderType": "google_credentials" - } - } -} -``` - -> 注意：MCPサーバーは既定で読み取り専用とは限りません。エージェントが生成したSQLをそのまま実行できてしまう場合があるため、本番環境ではIAMによるアクセス制御（読み取り専用の強制など）を必ず設定してください。 - -### Step 6：Spec-Driven Developmentサイクルを回す - -いよいよ「仕様を書いてからコードを生成する」中心のサイクルに入ります。GoogleのAntigravity関連コードラボでは、GitHubの`spec-kit`をベースにした、次の8フェーズのパイプラインが紹介されています。 - -```mermaid -flowchart TD - C0["/speckit.constitution
プロジェクト憲法を定義"] --> C1["/speckit.specify
spec.md：何を作るか"] - C1 --> C2{"/speckit.clarify（任意）
曖昧な点を質問し反映"} - C2 --> C3["/speckit.plan
plan.md：どう作るか"] - C3 --> C4["/speckit.tasks
tasks.md：作業の分解"] - C4 --> C5{"/speckit.analyze（任意）
リスク・矛盾のチェック"} - C5 --> C6["/speckit.implement
コード生成・実装"] - C6 --> C7{"人間レビュー
仕様との整合性を確認"} - C7 -->|"差分あり・要修正"| C1 - C7 -->|"承認"| C8["マージ・完了"] -``` - -| フェーズ | コマンド | 生成物 | 目的 | -|---|---|---|---| -| 憲法策定 | `/speckit.constitution` | `constitution.md` | 非交渉の原則を定義（Step 3で実施済み） | -| 仕様化 | `/speckit.specify` | `spec.md` | 「何を作るか」をユーザー視点・技術非依存で記述 | -| 明確化（任意） | `/speckit.clarify` | 更新された`spec.md` | 仕様の曖昧な箇所を質問し、回答を仕様へ反映 | -| 計画 | `/speckit.plan` | `plan.md`、`data-model.md`、`research.md` | 「どう作るか」＝技術的アプローチ・データモデル・調査結果 | -| タスク分解 | `/speckit.tasks` | `tasks.md` | 計画を実行可能な最小単位に分割（優先度・ファイルパス付き） | -| 分析（任意） | `/speckit.analyze` | 分析レポート | タスクの抜け漏れ・矛盾・リスクを事前に検出 | -| 実装 | `/speckit.implement` | コード変更 | タスクを一つずつ実行し、チェックオフしていく | - -ポイントは、`spec.md`が「何を」「誰のために」を記述し、実装の詳細（SQLテーブル名やAPI呼び出しの中身など）にはあえて触れない、という点です。実装の詳細は次の`plan.md`フェーズに委ねられます。各成果物はリポジトリに保存され、Gitでバージョン管理されるため、会話が途中で途切れても、あるいは後から見返しても、意思決定の記録が失われません。 - -### Step 7：Subagent駆動開発で実装する - -大きめの機能では、単一のエージェントがすべてを順番にこなすのではなく、役割分担された複数のサブエージェントにタスクを委譲する「Subagent駆動開発」が推奨されています。 - -```mermaid -sequenceDiagram - participant U as 開発者 - participant M as メインエージェント - participant TI as Task Implementer - participant TR as Task Reviewer - participant FR as Final Code Reviewer - U->>M: spec / planを承認 - M->>TI: タスク1を委譲 - TI-->>M: 実装をコミット - M->>TR: 実装のレビューを依頼 - TR-->>M: 指摘、または承認 - M->>TI: タスク2を委譲（並列実行も可） - TI-->>M: 実装をコミット - M->>FR: 全体を横断した最終レビュー - FR-->>U: レビュー結果のサマリーを報告 -``` - -- **Task Implementer**：計画中の特定タスクを実装する -- **Task Reviewer**：実装をspecと照らし合わせてレビューする -- **Final Code Reviewer**：全変更を横断した最終確認を行う - -サブエージェントは個別のコンテキストウィンドウで作業するため、メインスレッドが実行ログで埋め尽くされることを防ぎ、並列実行も可能になります。 - -### Step 8：フィードバックセンサーで検証する - -実装が完了したら、Step 5で選んだComputational／Inferentialなセンサーを実際に走らせて検証します。 - -- **Computational**：型チェック、リンター、既存テストスイート、構造テスト（モジュール境界違反の検出など） -- **Inferential**：レビューエージェントによるコード品質判定、意味的な重複やオーバーエンジニアリングの検出 - -一つのコツとして、Fowlerの記事では「センサーの出力はLLMが読みやすい形にする」ことが推奨されています。たとえば、単に「エラー」とだけ表示するのではなく、「このリンタールールに違反しています。修正するには〇〇してください」という**自己修正の指示を含んだメッセージ**をエージェントに返すと、人間を介さずにその場で直させやすくなります。 - -### Step 9：ステアリングループでハーネスを継続的に改善する - -Harness Engineeringは一度設定して終わりではなく、**継続的なエンジニアリング実践**です。同じ問題が繰り返し発生したら、それはハーネス（Guide・Sensorのどちらか、あるいは両方）を改善すべきサインです。 - -- 頻発するミスに気づいたら → 新しいルールをRulesやSkillに追記する（Feedforward強化） -- センサーがすり抜けを許した問題があれば → 新しい静的解析やテストを追加する（Feedback強化） -- モデルの性能が上がり、あるルールが不要になったと感じたら → そのハーネス部品を思い切って削除する - -最後の点は見落とされがちですが重要です。ハーネスの各部品は「モデルの限界を補うため」に存在しているので、その限界がなくなればハーネスも軽くしてよい、という発想です。 - ---- - - -## 10. 変更のライフサイクルにおける配置（Keep Quality Left） - -すべてのチェックを同じタイミングで行う必要はありません。コストと速度に応じて、変更のライフサイクルに沿って配置します。 - -```mermaid -flowchart LR - subgraph Pre["コミット前"] - F1["リンター / 高速テストスイート"] - end - subgraph PR["PR作成時"] - F2["レビューエージェント / 静的解析"] - end - subgraph CI["統合パイプライン"] - F3["ミューテーションテスト / アーキテクチャレビュー"] - end - subgraph Prod["継続的モニタリング"] - F4["SLO監視 / ログ異常検知 / 依存関係スキャン"] - end - Pre --> PR --> CI --> Prod - F4 -.->|"ドリフトを検出したら差し戻す"| Pre -``` - -- **速く安いチェック**は、コミット前・統合前のできるだけ左（早い段階）で実行する -- **高価なチェック**（ミューテーションテスト、大局的なアーキテクチャレビューなど）は、統合後のパイプラインで、高速チェックの再実行と合わせて行う -- **継続的なドリフト検知**（デッドコード検出、テストカバレッジの質の分析、依存関係スキャナー）は、変更のたびにではなく、常時バックグラウンドで実行する - -問題を見つけるタイミングが早いほど、修正コストは小さくなります。 - ---- - - -## 11. アンチパターンと落とし穴 - -| アンチパターン | 何が起きるか | 対策 | -|---|---|---| -| 巨大な単一ルールファイル | すべてが「重要」だと書かれた結果、実質何も守られない。ファイルはすぐに陳腐化し、機械的な検証もできない | Rules／Skillを機能単位に分割し、常時読み込む部分は「地図」に留める | -| フィードバックのみに依存 | エージェントが同じ間違いを何度も繰り返す | 頻発する間違いはフィードフォワード（ルール）側に反映する | -| フィードフォワードのみに依存 | ルールを書いても、実際に守られているか確認できない | 対応するセンサー（テスト・リンター）を必ずセットで用意する | -| AI生成テストへの過信 | テストが「グリーン」であることと「仕様どおりの振る舞い」であることは別問題 | 承認済みフィクスチャ等のパターンを併用し、人間によるレビューを残す | -| ハーネスを一度作って放置する | モデルが進化しても、不要になった制約が残り続け、逆に足かせになる | ステアリングループを回し、定期的にハーネスを棚卸しする | -| プロジェクト憲法を空テンプレートのまま放置 | 計画・分析フェーズのチェックが「照合対象なし」で機能しなくなる | 最低限の原則（3つ程度でも可）を必ず明文化する | -| すべてを一つのエージェントに任せる | 大きなタスクで実行ログがコンテキストを埋め尽くす | Subagent駆動開発でタスクを分割・並列化する | - ---- - - -## 12. 業界の広がり ― OpenAIとの比較 - -Googleだけでなく、他社もそれぞれのやり方でハーネスの設計に取り組んでいます。比較のために、OpenAIがCodexエージェントを使い、人間がコードを一切手で書かずに約100万行規模のプロダクトを開発した事例を簡単に紹介します。 - -- 巨大な単一の指示ファイルではなく、短い案内文書（目次の役割）から、詳細なドキュメント群へのリンクをたどらせる構成にした -- レイヤードアーキテクチャを、独自のリンターと構造テストで機械的に強制した -- 「AIのゴミ（AI Slop）」を人間が毎週手作業で片付けるのは持続不可能だったため、方針をコードに落とし込み、定期的にドリフトを検出して自動でリファクタリングPRを送る仕組み（ゴミ収集になぞらえて「ガベージコレクション」と呼ばれる）を構築した - -Googleのアプローチ（Antigravity＋spec-kit＋Agent Skills）と比べると、目指す方向性（仕様を先に固定する、ルールを構造化して機械的に検証する、継続的にドリフトを検出する）には共通点が多く、Harness Engineeringが特定のベンダーに依存しない、業界横断の実践知になりつつあることがうかがえます。 - ---- - - -## 13. 実践チェックリスト - -導入時に確認したい項目をまとめました。 - -- [ ] プロジェクトコンテキスト文書（Rules）を用意したか -- [ ] プロジェクト憲法（非交渉の原則）を最低限でも明文化したか -- [ ] 方法論・ドメイン知識・効率化の3種類のSkillをそれぞれ検討したか -- [ ] MCP等で「実際のデータ・スキーマ」にエージェントがアクセスできるようにしたか -- [ ] 仕様（spec）→計画（plan）→タスク分解→実装、というサイクルを踏んでいるか -- [ ] Computationalなセンサー（リンター・テスト・構造チェック）を用意したか -- [ ] Inferentialなセンサー（レビューエージェント）を、コストに見合う範囲で導入したか -- [ ] センサーのメッセージは、エージェントが自己修正しやすい形になっているか -- [ ] 変更のライフサイクル（コミット前／PR／CI／継続監視）に応じてチェックを分散させたか -- [ ] 同じ問題が繰り返し起きていないか、定期的にハーネスを棚卸ししているか - ---- - - -## 14. まとめ - -Harness Engineeringは、「AIコーディングエージェントの性能はモデル単体では決まらず、その周りに何を構築するかで決まる」という認識から生まれた、比較的新しいエンジニアリング実践です。 - -- ハーネスは**Guides（事前の誘導）**と**Sensors（事後の自己修正）**の両輪で成り立つ -- 実行方式には**Computational（決定的）**と**Inferential（推論的）**の2種類があり、コストと信頼性のトレードオフがある -- 規律の対象は**保守性・アーキテクチャ適合性・振る舞い**の3次元に分けられ、難易度はこの順で上がっていく -- ハーネスが機能するには、規律の基準を与える**Spec-Driven Development**が土台として必要になる -- Googleは、この考え方をGoogle Antigravity、Agent Skills（`google/skills`、Addy Osmaniの`agent-skills`）、ADKといった具体的な製品・オープンソースの形に落とし込んでいる -- ハーネスは一度作って終わりではなく、**ステアリングループ**を回しながら継続的に改善し、モデルの進化に応じて不要な部分は削っていく実践である - -まずは自分のリポジトリに、小さなプロジェクトコンテキストと2〜3個の原則を書いた憲法を用意するところから始めてみてください。 - ---- - - -## 15. 参考文献 - -### Harness Engineeringの基礎理論 - -- Birgitta Böckeler（Thoughtworks）, "Harness engineering for coding agent users," martinfowler.com, 2026年4月2日 - https://martinfowler.com/articles/harness-engineering.html -- Loiane Groner, "Harness Engineering: The Missing Layer in Specs-Driven AI Development," 2026年4月14日 - https://loiane.com/2026/04/harness-engineering-missing-layer-specs-driven-ai-development/ -- Nestr Blog, "What Is Harness Engineering? How the Newest AI Agent Discipline Maps to Organisational Governance"（Mitchell Hashimotoによる用語提唱の経緯を含む） - https://nestr.io/blog/harness-engineering-ai-agents - -### Googleでの実践 - -- Addy Osmani（Google Chrome Engineering Director）, "Agent Skills" - https://addyosmani.com/blog/agent-skills/ -- addyosmani/agent-skills（GitHubリポジトリ） - https://github.com/addyosmani/agent-skills -- Google Cloud Blog, "Level Up Your Agents: Announcing Google's Official Skills Repository," 2026年4月22日 - https://cloud.google.com/blog/topics/developers-practitioners/level-up-your-agents-announcing-googles-official-skills-repository -- Google Developers Blog, "Developer's Guide to Building ADK Agents with Skills" - https://developers.googleblog.com/developers-guide-to-building-adk-agents-with-skills/ -- Google Codelabs, "Spec-Driven Development with Antigravity CLI — Structured Agent Workflows with Skills and MCP" - https://codelabs.developers.google.com/sdd-agy-cli -- Google Codelabs, "Spec-Driven ADK Agent Development with Antigravity and Spec-kit" - https://codelabs.developers.google.com/sdd-adk-antigravity -- Giovanni Galloro, "How Google Antigravity is changing spec-driven development," Google Cloud Community (Medium) - https://medium.com/google-cloud/benefits-and-challenges-of-spec-driven-development-and-how-antigravity-is-changing-the-game-3343a6942330 -- Yannipeng, "Mastering Multi-Agent Orchestration in Google Antigravity," Google Cloud Community (Medium), 2026年7月 - https://medium.com/google-cloud/mastering-multi-agent-orchestration-in-google-antigravity-2e73500d25fb -- GitHub, spec-kit（GitHub製のSpec-Driven Developmentフレームワーク） - https://github.com/github/spec-kit -- Scalable Path, "Google Antigravity Review: DeepMind's Agent-First Bet on Faster, Safer Software Development" - https://www.scalablepath.com/ai/google-antigravity-review - -### 業界の広がり（比較参考） - -- Ryan Lopopolo（OpenAI）, "Harness engineering: leveraging Codex in an agent-first world," openai.com, 2026年2月11日 - https://openai.com/index/harness-engineering/ -- Addo Zhang, "From Idea to Release: A Complete Harness Engineering Practice," Medium, 2026年5月 - https://addozhang.medium.com/from-idea-to-release-a-complete-harness-engineering-practice-b995180e63e8 - ---- - -*本ガイドは2026年7月27日時点で参照可能な一次情報・技術記事をもとに作成しています。Google Antigravity、ADK、Agent Skills等は現在も活発に更新されているプロダクトのため、実際の導入にあたっては上記リンク先の最新版ドキュメントも合わせてご確認ください。* \ No newline at end of file From b37504751e44a38b63fbf40005081c8f3c22fa69 Mon Sep 17 00:00:00 2001 From: myoshizumi Date: Thu, 30 Jul 2026 03:37:22 +0900 Subject: [PATCH 02/53] docs: add AI spec-driven development, Google sandbox, and OpenAI Codex guides --- ...n-development-markdown-best-practices.html | 2657 +++++++++++++++++ ...ven-development-markdown-best-practices.md | 393 +++ Google-sandbox-best-practices.html | 1480 +++++++++ Google-sandbox-best-practices.md | 374 +++ ...-codex-agents-multiagent-best-practices.md | 367 +++ 5 files changed, 5271 insertions(+) create mode 100644 Ai-spec-driven-development-markdown-best-practices.html create mode 100644 Ai-spec-driven-development-markdown-best-practices.md create mode 100644 Google-sandbox-best-practices.html create mode 100644 Google-sandbox-best-practices.md create mode 100644 Openai-codex-agents-multiagent-best-practices.md diff --git a/Ai-spec-driven-development-markdown-best-practices.html b/Ai-spec-driven-development-markdown-best-practices.html new file mode 100644 index 00000000..6b740933 --- /dev/null +++ b/Ai-spec-driven-development-markdown-best-practices.html @@ -0,0 +1,2657 @@ + + + + + + AI仕様駆動開発におけるMarkdown実践ガイド + + + + + + + + + +
+ + +
+ + Markdown実践ガイド / SDD +
+ + +
+ + +
+ +
+
+
+

中級〜上級エンジニア向け実践ガイド

+

+ AI仕様駆動開発における
Markdownファイル実践ガイド +

+

+ GitHub Spec Kit・AWS Kiro・Claude Code・AGENTS.md・Agent + Skillsなど、2026年時点の主要なSDDツール群が + 共通して採用する「Markdownで仕様を書き、AIエージェントに実装させる」ワークフローを、 + ステップバイステップで体系化しました。EARS記法、ファイル構成、Mermaid図解の作法まで一気通貫で扱います。 +

+
+ 14ステップ構成 + 4本のMermaid図解 + 33件の一次情報を参照 + 最終更新 2026-07-28 +
+
+ + +
+
+ + +
+ +

Chapter 01

+

SDDとは何か、なぜMarkdownなのか

+ +

Vibe Codingの限界

+

+ Andrej Karpathy氏が2025年初頭に提唱した「Vibe + Coding」という言葉は、コーディングエージェントに緩いプロンプトを + 投げて生成物をそのまま受け入れるスタイルを指し、2025年のCollins English + Dictionary「今年の言葉」にも選出される + ほど広まりました[16]。プロトタイピングや個人開発では有効ですが、数百行を超える規模になると、 + エージェントが「言語化されていない意図」を推測で埋めるようになり、その推測の積み重ねがコードベース全体の + ドリフト（意図からのズレ）を生みます[15][20]。 +

+ +
+ Simon Willison氏の視点 +

+ Datasette作者のSimon + Willison氏は、LLMが書いたコードであっても開発者がレビュー・テスト・理解を尽くしていれば、 + それはもはやVibe + Codingではなく「LLMをタイピングアシスタントとして使っている」状態だと整理しています[23]。 + この「所有できるかどうか」の境界線こそが、SDD導入の判断基準になります。 +

+
+ +

SDDの定義

+

+ 仕様駆動開発（Spec-Driven + Development）とは、コードではなくバージョン管理された仕様書そのものを + 正とし、そこから実装計画・タスク・コードを導出する開発手法です[14]。2025年に、GitHub + Spec Kit （2025年9月公開）やAWS + Kiro（2025年7月公開）といったツールがAIエージェント向けに具体化し、2026年には主要な + AIコーディングツールのほぼすべて（GitHub Spec Kit, AWS Kiro, Claude Code, Cursor, + OpenSpec, BMAD-METHOD, Tessl, Google + Antigravityなど）が何らかのSDDワークフローを実装するに至りました[16]。 +

+

+ SDDが解決しようとしている問題は明快です。AIエージェントは明示された契約（仕様）に対する実装は非常に得意ですが、 + 暗黙の意図を推測することは苦手です[16]。曖昧なプロンプトは曖昧なコードを生みますが、 + 構造化された仕様は、意図に近いコードを生みます。 +

+ +

なぜMarkdownなのか

+

SDDの実務ツールがほぼ例外なくMarkdownを採用しているのには理由があります。

+
    +
  • + 人間にもAIにも読める: + プレーンテキストであるため、人間のレビュアーとAIエージェントの + 双方が同じファイルをそのまま解釈できる[4]。 +
    • +
  • + バージョン管理と親和性が高い: + Gitでdiffが取れるため、「仕様がいつ・どう変わったか」を 追跡できる[9]。 +
    • +
  • + ツール非依存（ポータブル）: + 特定ベンダーのフォーマットに縛られず、Claude Code・Codex・ Cursor・Gemini + CLIなど複数のエージェント間で使い回せる[7]。 +
    • +
  • + 構造と自由度のバランス: + 見出し・表・コードブロックといった軽量な構造化要素を持ちながら、 + 厳密なスキーマを強制しない[26][7]。 +
    • +
+
+ + +
+ +

Chapter 02

+

成熟度モデル：Spec-first / Spec-anchored / Spec-as-source

+

+ Thoughtworks社のMartin + Fowler氏らのチームは、SDDの実践パターンを3段階の厳密度スペクトラムとして整理して + います[13]。自分たちのチームがどの段階を目指すのかを最初に決めておくことが、後述する + 「過剰形式化（Waterfall化）」を防ぐ第一歩になります。 +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
段階考え方仕様が担う役割コードの位置づけ向いているケース
Spec-first
（仕様先行）		仕様を書いてからプロンプトするAIへの高品質なコンテキスト依然として正（メンテナンス対象）ほとんどの現場のデフォルト。実務での主流[16]
Spec-anchored
（仕様係留）		仕様は実装後も「生きた契約」として残り続ける継続的なガバナンス文書正だが、仕様との乖離をCIで機械的に検知チーム開発・長期保守プロジェクト
Spec-as-source
（仕様が源泉）		仕様こそが唯一のソースで、コードは使い捨て可能な生成物実行可能な仕様そのもの生成物（規約変更時は再生成） + OpenAPIからのスタブ生成、Simulinkモデルからの組込みコード生成など、既に標準化された領域[15] +
+
+

+ 多くの現場が実際に運用しているのはSpec-anchored寄りのアプローチであり、 + 「仕様がAIの仕事を楽にし、人間レビュアーの仕事も楽にする」という位置づけです[15]。 +

+
+ + +
+ +

Chapter 03

+

全体ワークフロー：Specify → Plan → Tasks → Implement

+

+ GitHub Spec Kitに代表される主要ツール群は、ほぼ共通して「Specify → Plan → Tasks → + Implement」という + 4フェーズループを採用しています[15][16]。各フェーズの間に人間によるレビューゲートを + 置くことが、品質を保つ最大のポイントです。 +

+ +
+ 

+          

+          
+          
図1: Spec Kit / Kiro 共通の4フェーズループと人間レビューゲート

+
+          

+            GitHub Spec Kitでは、この4フェーズに加えて
+            /speckit.constitution（プロジェクトの非交渉原則を
+            定義）、/speckit.clarify（曖昧点の質問）、/speckit.analyze（spec/plan/tasks間の
+            矛盾チェック）、/speckit.checklist（仕様の抜け漏れを検査する「英語のユニットテスト」）といった
+            補助コマンドがスラッシュコマンドとして用意されています[3]。AWS
+            Kiroも同様に、要件定義→設計→実装計画
+            の3フェーズを踏み、各フェーズ間に承認ゲートを設けます[5][6]。
+          

+        

+
+        
+        

+          
+          
Chapter 04

+          
ファイル構成の全体像

+          

+            SDDのMarkdown群は役割ごとに階層化して配置するのが定石です。プロジェクト全体に効くファイルと、
+            機能単位でスコープされるファイルを混在させないことが重要です。
+          

+
+          

+            

+          

+          
+          
図2: プロジェクト全体スコープと機能スコープのファイル階層

+
+          

+            主要なツール・標準がそれぞれどのファイル名を使っているかを整理すると以下の通りです。名前は違えど、役割
+            （What/Why・How・実行単位・全体コンテキスト）はほぼ共通しています。
+          

+
+          

+            
+              
+                
+                  
+                  
+                  
+                  
+                
+              
+              
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+              
+            
ツール / 標準主なファイル提供元・管理団体位置づけ
GitHub Spec Kit
+                    constitution.md spec.md plan.md
+                    tasks.md
+                  GitHub（Microsoft傘下）OSSツールキット（MITライセンス）[1]
AWS Kirorequirements.md design.md tasks.mdAWS統合IDEに組み込み。EARS記法をネイティブ採用[5]
Claude CodeCLAUDE.mdAnthropicセッションを跨いで読み込まれる指示書[20]
AGENTS.md（オープン標準）AGENTS.md
+                    Agentic AI Foundation（Linux
+                    Foundation傘下）。OpenAI・Google（Jules）・Cursor・Factor等が策定を主導
+                  ベンダー中立、必須フィールドなしのプレーンMarkdown[32]
Cursor.cursor/rules/*.mdcCursor（Anysphere）YAML frontmatter付きMarkdown。パスごとに適用範囲を制御[22]
Agent SkillsSKILL.mdAnthropicが提唱、オープン標準化Claude Code・Codex・Cursorなど30以上のツールが対応[18][29]

+          

+
+          

+            モノレポでの配置ルール
+            

+              AGENTS.mdやCLAUDE.mdはモノレポの各パッケージ配下にも配置でき、エージェントは「編集対象ファイルに最も近い
+              ファイル」を優先して読み込みます（例:
+              OpenAIのCodexリポジトリでは88個のAGENTS.mdが階層的に配置されている）
+              [27]。Claude Codeは独自にCLAUDE.mdを読みますが、@AGENTS.md
+              のインポート記法を
+              使えばAGENTS.mdを取り込めるため、複数ツールを併用するチームは「AGENTS.mdを単一の正とし、CLAUDE.mdは1行の
+              インポート文だけにする」運用が推奨されています[26]。
+            

+          

+        

+
+        
+        

+          
+          
Chapter 05 ・ Step-by-Step

+          
spec.md / requirements.md の書き方

+
+          
Step 1: メタデータと目的を明記する

+          

+            冒頭に「何のための機能か」「誰のためか」「スコープ外は何か」を短く書きます。実装方法（How）はここに書きません。
+            GitHub Spec
+            Kitの実運用では、LLMが張り切りすぎて要素サイズや配色などの実装詳細をspecに混入させてしまう傾向が
+            報告されており、気づいた時点で技術要件をplanドキュメント側へ移動するよう指示することが推奨されています[3]。
+          

+
+          
Step 2: ユーザーストーリーを優先度付きで書く

+          

+            P1/P2/P3
+            のように優先度ラベルを振り、各ストーリーを独立してテスト可能な
+            MVPスライスとして記述するテンプレートが広く使われています[19]。
+          

+
+          

+            

+              
spec.mdmarkdown

+              
+            

+            

+          

+          
+
+          
Step 3: 受け入れ基準をEARS記法で書く

+          

+            自然文の受け入れ基準（"ユーザーはログインできる"
+            等）は曖昧で、人間にもAIにも解釈のブレを生みます。 この問題に対する業界標準の解が
+            EARS（Easy Approach to Requirements Syntax） です。
+            2009年にRolls-RoyceのAlistair
+            Mavin氏らが航空機エンジン制御の要件定義用に考案した記法で、Kiroをはじめとする
+            主要SDDツールがAIエージェント向けの受け入れ基準記法として採用しています[16][24]。EARSはベンダー
+            中立の記法であり、Kiroは採用者であって考案者ではありません[24]。
+          

+          

+            EARSは5つのパターンで構成されます。どのパターンを使うべきかは、以下のように機械的に判定できます。
+          

+
+          

+            

+          

+          
+          
図3: EARS 5パターンの判定フロー

+
+          

+            
+              
+                
+                  
+                  
+                  
+                  
+                
+              
+              
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                  
+                
+              
+            
パターン用途構文テンプレート例
Ubiquitous
（恒常要件）		常に真である基本要件THE SYSTEM SHALL <応答>THE SYSTEM SHALL 全APIレスポンスをJSON形式で返す
Event-driven
（イベント駆動）		特定のイベント発生時WHEN <トリガー> THE SYSTEM SHALL <応答>
+                    WHEN ユーザーが有効なメールアドレスを送信 THE SYSTEM SHALL
+                    15分間有効なワンタイムリンクを送付する[21]
+                  
State-driven
（状態駆動）		特定の状態が続く間WHILE <状態> THE SYSTEM SHALL <応答>WHILE メンテナンスモード中 THE SYSTEM SHALL 書き込みAPIを503で拒否する
Unwanted behavior
（望まない挙動への対応）		異常系・エラー処理IF <トリガー> THEN THE SYSTEM SHALL <応答>
+                    IF ログインリンクが2回目以降使用された THEN THE SYSTEM SHALL HTTP
+                    410で拒否する[21]
+                  
Optional feature
（オプション機能）		特定機能が有効な場合のみWHERE <機能> THE SYSTEM SHALL <応答>
+                    WHERE 多要素認証が有効化されている THE SYSTEM SHALL
+                    追加のワンタイムコード入力を要求する
+                  

+          

+          

+            EARSで書かれた受け入れ基準は、ほぼ1対1でテストケースに変換できるという実務上の利点があります[21]。
+            一方で、EARSは「表現の型」を統一するだけであり、それ自体が実行可能なテストになるわけではない点には注意が必要です[24]。
+          

+
+          
Step 4: 曖昧さを可視化するマーカーを使う

+          

+            GitHub Spec Kitの実運用では、spec.md中に
+            [NEEDS CLARIFICATION] のようなマーカーを埋め込み、
+            これが残っている間はタスクを「完了」とマークしない、という運用が確認されています[19]。曖昧な要件を
+            無理に確定させず、可視化したまま人間の判断を仰ぐ設計です。
+          

+
+          
Step 5: 実装詳細を書かない（Whatに徹する）

+          

+            spec.mdは「何を」「なぜ」に徹し、「どう作るか」はplan.mdに譲ります。良い仕様書の条件を扱った
+            Addy
+            Osmani氏（Googleの著名なエンジニア）の記事でも、仕様はAIエージェントが自己修正しつつ安全な境界内に
+            留まるための"契約"であるべきだと述べられています[10]。
+          

+        

+
+        
+        

+          
+          
Chapter 06 ・ Step-by-Step

+          
plan.md / design.md の書き方

+          
    
+            
  1. 
+              技術スタックとアーキテクチャ方針を明記する:
+              使用するフレームワーク、データストア、
+              外部API連携などをspecの要件にひもづけて記述します。
+            
    2. 
+            
  2. 
+              アーキテクチャ図・シーケンス図はMermaidで描く:
+              Kiroのdesign.mdも、技術アーキテクチャと
+              シーケンス図をこの段階で文書化する運用になっています[5]。ASCIIアートは避け、Mermaidの
+              フローチャート／シーケンス図で表現します。
+            
    3. 
+            
  3. 
+              意思決定の根拠を残す（ADR的に）:
+              なぜこの技術を選んだかを一言添えるだけで、後からの
+              手戻りやレビュー時間を大きく減らせます。
+            
    4. 
+            
  4. 
+              エラーハンドリング・テスト戦略を明記する:
+              Kiroのdesign.mdはエラーハンドリングとテスト
+              戦略を含むのが標準ですが、必要な粒度は都度調整します[32]。
+            
    5. 
+          

+
+          

+            生成物を鵜呑みにしない
+            

+              Scott Logic社の検証では、planフェーズで自動生成された406行の「research
+              doc」が、既存ページと同じ
+              ライブラリを使う理由付けなど、冗長で価値の薄い内容になっていた例が報告されています[17]。
+              生成させたら鵜呑みにせず、価値のある意思決定記録だけを残す姿勢が重要です。
+            

+          

+        

+
+        
+        

+          
+          
Chapter 07 ・ Step-by-Step

+          
tasks.md の書き方

+          
    
+            
  1. 
+              アトミックなタスクに分解する:
+              各タスクは独立してレビュー・差し戻し可能な単位にします。
+            
    2. 
+            
  2. 
+              要件へのトレーサビリティを持たせる:
+              各タスクがどのユーザーストーリー／受け入れ基準に
+              対応するかを明示し、実装が要件から逸脱していないかを追跡できるようにします[33]。
+            
    3. 
+            
  3. 
+              依存関係を明示し、並列実行可能なタスクをグルーピングする:
+              Kiroはtasks.mdから依存関係 グラフを構築し、依存のないタスクを「Wave
+              1」としてまとめて並列に扱う仕組みを持ちます[5]。
+            
    4. 
+            
  4. 
+              実装フェーズで内容を変更しない:
+              タスクはLLMが何を作るかの直接的な反映であるため、
+              この段階で不正確な内容が混入していないかの確認が特に重要だと、Spec
+              Kitの実運用知見として指摘されています[3]。
+            
    5. 
+          

+
+          

+            

+              
tasks.mdmarkdown

+              
+            

+            

+          

+          
+        

+
+        
+        

+          
+          
Chapter 08

+          
AGENTS.md / CLAUDE.md：プロジェクト全体のコンテキストファイル

+          

+            AGENTS.mdは「エージェント向けのREADME」と位置づけられる、プレーンMarkdownのオープン標準です[7]。
+            特徴は以下の通りです。
+          

+          
    
+            
  • 
+              必須フィールドなし: YAML
+              frontmatterも不要で、見出しの付け方や粒度は完全に自由です[28]。
+            
    • 
+            
  • 
+              対応ツールの広さ: 2026年前半時点でOpenAI Codex、Cursor、GitHub
+              Copilot coding agent、 Gemini CLI、Windsurf、Aider、Zed、Devin、Amazon
+              Qなど30以上のツールがネイティブまたはインポート経由で
+              読み込みます[25][26]。
+            
    • 
+            
  • 
+              ガバナンス:
+              元々OpenAI・Amp・Google（Jules）・Cursor・Factoryなどの協業から生まれ、 現在はLinux
+              Foundation傘下のAgentic AI
+              Foundationがスチュワードシップを担っています[7]。
+            
    • 
+            
  • 
+              コンフリクト解決:
+              「編集対象ファイルに最も近いAGENTS.md」が優先され、さらにユーザーの
+              チャット上の明示的な指示はすべてに優先します[7]。
+            
    • 
+          

+
+          

+            

+              
AGENTS.mdmarkdown

+              
+            

+            

+          

+          
+
+          

+            Claude CodeはAGENTS.mdではなく独自の
+            CLAUDE.md を読み込みますが、二重管理を避けるため 「CLAUDE.mdの中身は
+            @AGENTS.md の1行インポートのみにし、実体はAGENTS.mdに一本化する」という
+            移行パターンが定着しています[25]。
+          

+        

+
+        
+        

+          
+          
Chapter 09

+          
SKILL.md：段階的開示（Progressive Disclosure）

+          

+            AGENTS.mdが「プロジェクトが何であるか」を伝えるのに対し、SKILL.mdは「特定のタスクをどうこなすか」という
+            再利用可能な手順をエージェントに渡す仕組みです[27]。Anthropicが提唱し、Claude
+            Code・Codex・ Cursorなど多くのツールに広がったオープン標準です[18]。
+          

+          

+            SKILL.mdの最大の設計思想は段階的開示（Progressive Disclosure）です。コンテキストウィンドウは
+            有限であり、すべてのスキルの全文を常時ロードするとノイズが増えるため、必要になった瞬間にだけ詳細を
+            読み込む設計になっています[8]。
+          

+
+          

+            

+          

+          
+          
図4: SKILL.mdの段階的開示（Progressive Disclosure）

+
+          

+            構造は「YAML frontmatter（name と
+            description の2つが必須）＋Markdown本文の指示＋
+            任意の補助ファイル（スクリプト・テンプレート）」というシンプルな形です[27][18]。
+          

+
+          

+            

+              
SKILL.mdmarkdown

+              
+            

+            

+          

+          
+        

+
+        
+        

+          
+          
Chapter 10

+          
Markdown記法そのもののベストプラクティス

+          

+            Anthropicの公式エンジニアリングブログ「Effective context engineering for AI
+            agents」は、プロンプトや
+            コンテキストを<background_information>のようなXMLタグ、またはMarkdownの見出しで
+            明確にセクション分けすることを推奨しています。具体的な整形方法自体は今後変わっていく可能性があるが、
+            明確なセクション区切りという原則自体は重要だと位置づけられています[8]。この原則はspec.md等の
+            SDDドキュメントにもそのまま当てはまります。
+          

+
+          
10.1 見出し階層とセクション分け

+          
    
+            
  • 
+              見出し（#〜####）でセクションを明確に分離し、AIが「今どのセクションを読んで
+              いるか」を見出しテキストだけで判断できるようにする。
+            
    • 
+            
  • 1見出しに1目的。複数の関心事を1つの見出し配下に詰め込まない。
    • 
+            
  • 
+              アンカーリンク付きの目次を長いドキュメントには必ず用意し、人間のレビュー時のナビゲーションコストを下げる。
+            
    • 
+          

+
+          
10.2 表 vs 箇条書きの使い分け

+          
    
+            
  • 
+              表が向くケース:
+              複数の項目を同じ軸（列）で比較する場合。AIエージェントにとっても
+              構造化データとして解釈しやすい。
+            
    • 
+            
  • 箇条書きが向くケース: 単純な列挙、手順のステップ、条件の羅列。
    • 
+          

+
+          
10.3 Mermaidダイアグラムのルール

+          

+            ASCIIアートによる図解は保守性が低く、フォントやレンダリング環境によって崩れるため、フローチャートは必ず
+            Mermaidのコードブロックで記述します。実務での注意点は以下の通りです。
+          

+          
    
+            
  • 
+              mindmap と
+              quadrantChart は環境によって表示が崩れやすいため避け、
+              flowchart + subgraph で代替する。
+            
    • 
+            
  • 
+              サブグラフのタイトルには特殊文字を避けるか、クォートで囲んでパースエラーを防ぐ。
+            
    • 
+            
  • 
+              ノード数が多い横方向のフローチャートはビューポート幅を超えやすいため、TB（縦方向）レイアウトを
+              優先する。
+            
    • 
+            
  • 
+              ノード間に実際のエッジがない兄弟要素は横に並んで幅が広がりがちなので、意味のある接続だけを描き、
+              レイアウトを縦に収める。
+            
    • 
+          

+
+          
10.4 コードブロックとfrontmatter

+          
    
+            
  • 
+              コマンド例・設定例は必ずフェンス付きコードブロック（```）で囲み、言語識別子
+              （bash, json, markdownなど）を付与する。
+            
    • 
+            
  • 
+              SKILL.mdやCursorの.mdcファイルのように、メタデータが必要な場合はYAML
+              frontmatterを使う。 本文の指示と機械可読なメタデータを分離できる[27]。
+            
    • 
+          

+        

+
+        
+        

+          
+          
Chapter 11

+          
生きたドキュメントとしての運用

+          

+            仕様は「書いたら終わり」ではありません。SDDが従来のウォーターフォール型ドキュメントと決定的に違うのは、
+            要求が変わったらまず仕様を更新し、そこからコードを再生成・修正するという運用ループを 回す点です[16]。
+          

+          
    
+            
  • バグ修正・機能追加のリクエストが来たら、実装コードより先にspec.mdを更新する。
    • 
+            
  • 
+              仕様変更のコストが「重い」と感じ始めたら、それは過剰形式化（Waterfall化）のサインとして扱い、
+              プロセスを軽量化する[31]。
+            
    • 
+            
  • 
+              大きな機能追加のたびに1つの巨大な仕様に機能を積み増すのではなく、機能ごとに仕様を分割する。
+            
    • 
+          

+        

+
+        
+        

+          
+          
Chapter 12

+          
よくある落とし穴と対策

+
+          

+            
+              
+                
+                  
+                  
+                  
+                
+              
+              
+                
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                
+                
+                  
+                  
+                  
+                
+              
+            
落とし穴症状対策
Spec Bloat
（仕様の肥大化）		
+                    30分で実装できるはずの機能に対して800行超のMarkdownが生成される[30]
+                  テンプレートを最小構成にトリムし、「必要十分」をチーム内で明文化する
ウォーターフォール化
+                    Spec→Plan→Tasksの往復が硬直化する。Scott Logic社の実機検証では、Spec
+                    Kitのフルパイプラインが
+                    通常の反復プロンプトよりも約10倍遅く、レビューだけで3.5時間を要した例も報告されている[17]
+                  
+                    変更コストが高いと感じたら過剰形式化のサイン。小規模な変更は軽量な仕様更新に留める
+                  
Semantic Diffusion
（用語の希薄化）		
+                    「仕様駆動開発」という言葉がツールごとに異なる哲学を指すため、比較が噛み合わなくなる[24]
+                  
+                    ツール名やラベルではなく、実際のワークフロー（何がSource of Truthか）で比較する
+                  
実装詳細の混入
+                    機能仕様（spec.md）に色・サイズ・ライブラリ選定などの技術詳細が紛れ込む[3]
+                  気づいた時点でLLMに指示し、該当箇所をplan.md側へ移動する
Spec Drift
（仕様と実装の乖離）		コードだけが変更され、仕様が古いまま放置される
+                    「要求変更時は必ず仕様を先に更新する」運用をチームルール化し、CIで乖離を検知する仕組みを検討する[16]
+                  
偽の網羅感
+                    仕様を読み流し、エッジケースが書かれていると錯覚したまま実装を進めてしまう
+                  
+                    仕様は「読まれる前提」で簡潔に保ち、レビュー担当を明確に決める[30]
+                  

+          

+        

+
+        
+        

+          
+          
Chapter 13

+          
導入前チェックリスト

+          
    
+            
  • 
+              constitution.md（またはAGENTS.md冒頭）にプロジェクトの非交渉原則が明文化されている
+            
    • 
+            
  • 
+              spec.md /
+                requirements.mdが「What」「Why」に徹し、実装詳細（How）を含んでいない
+            
    • 
+            
  • 
+              受け入れ基準がEARS記法（またはGiven-When-Then）で書かれ、曖昧な自然文のままになっていない
+            
    • 
+            
  • 
+              曖昧な要件には
+                [NEEDS CLARIFICATION] 等のマーカーが付き、放置されていない
+            
    • 
+            
  • 
+              plan.md /
+                design.mdのアーキテクチャ図・シーケンス図がMermaidで記述され、ASCIIアートを含まない
+            
    • 
+            
  • 
+              tasks.mdの各タスクが要件へのトレーサビリティを持ち、独立してレビュー可能な粒度になっている
+            
    • 
+            
  • 
+              AGENTS.md（またはCLAUDE.md）にビルド／テストコマンドと「触ってはいけない領域」が明記されている
+            
    • 
+            
  • 
+              繰り返し使う手順はSKILL.mdとして切り出し、YAML
+                frontmatterのdescriptionだけで用途が判断できる
+            
    • 
+            
  • 
+              長いドキュメントにはアンカーリンク付き目次があり、見出し階層が1見出し1目的になっている
+            
    • 
+            
  • 
+              比較・列挙情報は表で、手順・条件は箇条書きで整理されている
+            
    • 
+            
  • 
+              仕様変更時は「まず仕様を更新してからコードを再生成・修正する」運用ルールがチームに共有されている
+            
    • 
+            
  • 
+              生成された仕様・計画ドキュメントの分量が肥大化していないか、レビュー時に確認している
+            
    • 
+          

+        

+
+        
+        

+          
+          
Chapter 14

+          
まとめ

+          

+            AI仕様駆動開発におけるMarkdown運用の本質は、「AIエージェントが迷わず実装でき、人間が短時間で
+              レビューできる」構造をどれだけ作れるかに尽きます。EARS記法による受け入れ基準の明確化、What/Howの
+            分離、段階的開示によるコンテキスト管理、そして「仕様は生きたドキュメントである」という運用ルールの4つが、
+            ツールを問わず共通する骨格です。同時に、Spec
+            Kitの実運用レビューが示すように、仕様が肥大化し
+            ウォーターフォール的な硬直運用に陥るリスクも実際に報告されています[17]。仕様の「厳密さ」と
+            「軽さ」のバランスは、プロジェクトの規模とチームの成熟度に応じて都度調整していく前提で運用してください。
+          

+        

+
+        
+        

+          
+          
Chapter 15

+          
参考文献

+          

+            本ガイドの記述は、2026年7月28日時点で参照可能な以下の一次情報・著名な開発者/組織の発信に基づいています。
+          

+          
    
+            
  1. 
+              
    
+                
    GitHub, "spec-kit" 公式リポジトリ
    
+                https://github.com/github/spec-kit
+              
    
+            
    2. 
+            
  2. 
+              
    
+                
    GitHub, Spec Kit 公式ドキュメントサイト
    
+                https://github.github.com/spec-kit/
+              
    
+            
    3. 
+            
  3. 
+              
    
+                
    
+                  Den Delimarsky（GitHub Principal PM）, "What's The Deal With GitHub Spec Kit"
+                
    
+                https://den.dev/blog/github-spec-kit/
+              
    
+            
    4. 
+            
  4. 
+              
    
+                
    
+                  Microsoft for Developers, "Diving Into Spec-Driven Development With GitHub Spec
+                  Kit"
+                
    
+                https://developer.microsoft.com/blog/spec-driven-development-spec-kit/
+              
    
+            
    5. 
+            
  5. 
+              
    
+                
    AWS Kiro 公式ドキュメント, "Specs"
    
+                https://kiro.dev/docs/specs/
+              
    
+            
    6. 
+            
  6. 
+              
    
+                
    AWS Kiro 公式ドキュメント, "Feature Specs"
    
+                https://kiro.dev/docs/specs/feature-specs/
+              
    
+            
    7. 
+            
  7. 
+              
    
+                
    
+                  AGENTS.md 公式サイト（Agentic AI Foundation / Linux Foundation）
+                
    
+                https://agents.md/
+              
    
+            
    8. 
+            
  8. 
+              
    
+                
    
+                  Anthropic Engineering, "Effective context engineering for AI agents"
+                
    
+                https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+              
    
+            
    9. 
+            
  9. 
+              
    
+                
    
+                  Anthropic Engineering, "Effective harnesses for long-running agents"
+                
    
+                https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+              
    
+            
    10. 
+            
  10. 
+              
    
+                
    
+                  Addy Osmani（Google, Chrome Engineering）, "How to write a good spec for AI
+                  agents"
+                
    
+                https://addyosmani.com/blog/good-spec/
+              
    
+            
    11. 
+            
  11. 
+              
    
+                
    
+                  Simon Willison（Datasette作者）, "Agentic Engineering Patterns"
+                
    
+                https://simonw.substack.com/p/agentic-engineering-patterns
+              
    
+            
    12. 
+            
  12. 
+              
    
+                
    Simon Willison, ai-assisted-programming タグ一覧
    
+                https://simonwillison.net/tags/ai-assisted-programming/
+              
    
+            
    13. 
+            
  13. 
+              
    
+                
    Martin Fowler / Thoughtworks, "Exploring Generative AI"
    
+                https://martinfowler.com/articles/exploring-gen-ai.html
+              
    
+            
    14. 
+            
  14. 
+              
    
+                
    Wikipedia, "Spec-driven development"
    
+                https://en.wikipedia.org/wiki/Spec-driven_development
+              
    
+            
    15. 
+            
  15. 
+              
    
+                
    
+                  Java Code Geeks, "Spec-Driven Development with AI: Write the Spec First, Then
+                  Prompt the Implementation"
+                
    
+                https://www.javacodegeeks.com/2026/05/spec-driven-development-with-ai-write-the-spec-first-then-prompt-the-implementation.html
+              
    
+            
    16. 
+            
  16. 
+              
    
+                
    
+                  BCMS, "Spec-Driven Development (SDD): The Definitive 2026 Guide"
+                
    
+                https://thebcms.com/blog/spec-driven-development
+              
    
+            
    17. 
+            
  17. 
+              
    
+                
    
+                  Scott Logic（Colin Eberhardt, CTO）, "Putting Spec Kit Through Its Paces: Radical
+                  Idea or Reinvented Waterfall?"
+                
    
+                https://blog.scottlogic.com/2025/11/26/putting-spec-kit-through-its-paces-radical-idea-or-reinvented-waterfall.html
+              
    
+            
    18. 
+            
  18. 
+              
    
+                
    Agentailor, "Top AI Agent Standards to Know in 2026"
    
+                https://blog.agentailor.com/posts/top-ai-agent-standards-2026
+              
    
+            
    19. 
+            
  19. 
+              
    
+                
    
+                  SSOJet, "9 PRD and Spec Templates Built for AI Coding Agents"
+                
    
+                https://ssojet.com/blog/prd-spec-templates-ai-agents
+              
    
+            
    20. 
+            
  20. 
+              
    
+                
    
+                  Joshua McDonald, "EARS, Fifteen Years On: The Requirements Format Built for the
+                  Agent Era"
+                
    
+                https://joshmcdonald.medium.com/ears-fifteen-years-on-the-requirements-format-built-for-the-agent-era-0f78f8ff35a0
+              
    
+            
    21. 
+            
  21. 
+              
    
+                
    
+                  DEV Community (krlz), "Spec-Driven Development in 2026: What It Is, the Tooling,
+                  and How Teams Actually Use It"
+                
    
+                https://dev.to/krlz/spec-driven-development-in-2026-what-it-is-the-tooling-and-how-teams-actually-use-it-2fk2
+              
    
+            
    22. 
+            
  22. 
+              
    
+                
    
+                  Augment Code, "6 Best Spec-Driven Development Tools for AI Coding in 2026"
+                
    
+                https://www.augmentcode.com/tools/best-spec-driven-development-tools
+              
    
+            
    23. 
+            
  23. 
+              
    
+                
    
+                  SoftwareSeni, "Spec-Driven Development Is Replacing Vibe Coding as the
+                  Professional Standard for AI Teams"（Simon Willison氏の見解を含む）
+                
    
+                https://www.softwareseni.com/spec-driven-development-is-replacing-vibe-coding-as-the-professional-standard-for-ai-teams/
+              
    
+            
    24. 
+            
  24. 
+              
    
+                
    
+                  CodeMySpec, "Spec-Driven Development in 2026: Guide + Tool
+                  Comparison"（EARS記法の歴史・Rolls-Royce起源の詳細）
+                
    
+                https://codemyspec.com/blog/spec-driven-development
+              
    
+            
    25. 
+            
  25. 
+              
    
+                
    CodersEra, "AGENTS.md Complete Guide 2026"
    
+                https://codersera.com/blog/agents-md-complete-guide-2026/
+              
    
+            
    26. 
+            
  26. 
+              
    
+                
    
+                  BuildBetter, "AGENTS.md Complete Guide for Engineering Teams in 2026"
+                
    
+                https://blog.buildbetter.ai/agents-md-complete-guide-for-engineering-teams-in-2026/
+              
    
+            
    27. 
+            
  27. 
+              
    
+                
    
+                  MorphLLM, "AGENTS.md Spec (2026): Recommended Sections and Comparison With
+                  CLAUDE.md / .cursorrules"
+                
    
+                https://www.morphllm.com/agents-md-guide
+              
    
+            
    28. 
+            
  28. 
+              
    
+                
    
+                  DeepWiki, "AGENTS.md Format Documentation"（openai/agents.md）
+                
    
+                https://deepwiki.com/openai/agents.md/5-agents.md-format-documentation
+              
    
+            
    29. 
+            
  29. 
+              
    
+                
    Agensi, "What Is the Agent Skills Open Standard?"
    
+                https://www.agensi.io/learn/agent-skills-open-standard
+              
    
+            
    30. 
+            
  30. 
+              
    
+                
    
+                  bitbytebit（Substack）, "Spec-Driven Development: From Vibe Coding to Structured
+                  Development"
+                
    
+                https://bitbytebit.substack.com/p/spec-driven-development-from-vibe
+              
    
+            
    31. 
+            
  31. 
+              
    
+                
    
+                  The Main Thread, "Spec-Driven Development Needs an Exit Strategy"
+                
    
+                https://www.the-main-thread.com/p/spec-driven-development-exit-strategy
+              
    
+            
    32. 
+            
  32. 
+              
    
+                
    
+                  AWS Builder Center, "Getting Started With Spec-Driven Development Using Kiro"
+                
    
+                https://builder.aws.com/content/36nn9PbSZuKJiWWoO2UWmFaaCHs/getting-started-with-spec-driven-development-using-kiro
+              
    
+            
    33. 
+            
  33. 
+              
    
+                
    
+                  Kanai Dutta（Medium）, "Experience With Kiro's Spec Driven Development
+                  Methodology"
+                
    
+                https://medium.com/@kanaiduttaiem/experience-with-kiros-spec-driven-development-methodology-1e57af895fd7
+              
    
+            
    34. 
+          

+        

+
+        

+          

+            免責事項:
+            上記は2026年7月28日時点のWeb検索結果に基づく要約であり、各ツールの仕様・対応状況は今後変更される
+            可能性があります。導入前には各公式ドキュメントの最新版を必ず確認してください。
+          

+        

+      

+    

+
+    
+    
+    
+  
+
diff --git a/Ai-spec-driven-development-markdown-best-practices.md b/Ai-spec-driven-development-markdown-best-practices.md
new file mode 100644
index 00000000..df68514a
--- /dev/null
+++ b/Ai-spec-driven-development-markdown-best-practices.md
@@ -0,0 +1,393 @@
+# AI仕様駆動開発（Spec-Driven Development）における実践的Markdown作成ガイド
+
+> 対象読者: AIコーディングエージェント（Claude Code / GitHub Copilot / Cursor / Codex CLI / Kiro など）を業務で使い、仕様駆動開発（SDD）のドキュメント運用を体系化したい中級〜上級エンジニア
+> 最終更新: 2026年7月28日時点の公開情報に基づく（出典は末尾「参考文献」参照）
+
+## 目次
+
+1. [仕様駆動開発（SDD）とは何か、なぜMarkdownなのか](#1-仕様駆動開発sddとは何かなぜmarkdownなのか)
+2. [成熟度モデル：Spec-first / Spec-anchored / Spec-as-source](#2-成熟度モデルspec-first--spec-anchored--spec-as-source)
+3. [全体ワークフロー：Specify → Plan → Tasks → Implement](#3-全体ワークフローspecify--plan--tasks--implement)
+4. [ファイル構成の全体像](#4-ファイル構成の全体像)
+5. [Step-by-Step: spec.md / requirements.md の書き方](#5-step-by-step-specmd--requirementsmd-の書き方)
+6. [Step-by-Step: plan.md / design.md の書き方](#6-step-by-step-planmd--designmd-の書き方)
+7. [Step-by-Step: tasks.md の書き方](#7-step-by-step-tasksmd-の書き方)
+8. [AGENTS.md / CLAUDE.md：プロジェクト全体のコンテキストファイル](#8-agentsmd--claudemdプロジェクト全体のコンテキストファイル)
+9. [SKILL.md：段階的開示（Progressive Disclosure）](#9-skillmd段階的開示progressive-disclosure)
+10. [Markdown記法そのもののベストプラクティス](#10-markdown記法そのもののベストプラクティス)
+11. [生きたドキュメントとしての運用](#11-生きたドキュメントとしての運用)
+12. [よくある落とし穴と対策](#12-よくある落とし穴と対策)
+13. [導入前チェックリスト](#13-導入前チェックリスト)
+14. [まとめ](#14-まとめ)
+15. [参考文献](#15-参考文献)
+
+---
+
+## 1. 仕様駆動開発（SDD）とは何か、なぜMarkdownなのか
+
+### 1.1 Vibe Codingの限界
+
+Andrej Karpathy氏が2025年初頭に提唱した「Vibe Coding」という言葉は、コーディングエージェントに緩いプロンプトを投げて生成物をそのまま受け入れるスタイルを指し、2025年のCollins English Dictionary「今年の言葉」にも選出されるほど広まりました[16]。プロトタイピングや個人開発では有効ですが、数百行を超える規模になると、エージェントが「言語化されていない意図」を推測で埋めるようになり、その推測の積み重ねがコードベース全体のドリフト（意図からのズレ）を生みます[15][20]。
+
+Simon Willison氏（Datasette作者）は、LLMが書いたコードであっても開発者がレビュー・テスト・理解を尽くしていれば、それはもはやVibe Codingではなく「LLMをタイピングアシスタントとして使っている」状態だと整理しています[23]。この「所有できるかどうか」の境界線こそが、SDD導入の判断基準になります。
+
+### 1.2 SDDの定義
+
+仕様駆動開発（Spec-Driven Development）とは、コードではなく**バージョン管理された仕様書そのもの**を正とし、そこから実装計画・タスク・コードを導出する開発手法です[14]。2025年に、GitHub Spec Kit（2025年9月公開）やAWS Kiro（2025年7月公開）といったツールがAIエージェント向けに具体化し、2026年には主要なAIコーディングツールのほぼすべて（GitHub Spec Kit, AWS Kiro, Claude Code, Cursor, OpenSpec, BMAD-METHOD, Tessl, Google Antigravityなど）が何らかのSDDワークフローを実装するに至りました[16]。
+
+SDDが解決しようとしている問題は明快です。AIエージェントは明示された契約（仕様）に対する実装は非常に得意ですが、暗黙の意図を推測することは苦手です[16]。曖昧なプロンプトは曖昧なコードを生みますが、構造化された仕様は、意図に近いコードを生みます。
+
+### 1.3 なぜMarkdownなのか
+
+SDDの実務ツールがほぼ例外なくMarkdownを採用しているのには理由があります。
+
+- **人間にもAIにも読める**: プレーンテキストであるため、人間のレビュアーとAIエージェントの双方が同じファイルをそのまま解釈できる[4]。
+- **バージョン管理と親和性が高い**: Gitでdiffが取れるため、「仕様がいつ・どう変わったか」を追跡できる[9]。
+- **ツール非依存（ポータブル）**: 特定ベンダーのフォーマットに縛られず、Claude Code・Codex・Cursor・Gemini CLIなど複数のエージェント間で使い回せる[7]。
+- **構造と自由度のバランス**: 見出し・表・コードブロックといった軽量な構造化要素を持ちながら、厳密なスキーマを強制しない[26][7]。
+
+---
+
+## 2. 成熟度モデル：Spec-first / Spec-anchored / Spec-as-source
+
+Thoughtworks社のMartin Fowler氏らのチームは、SDDの実践パターンを3段階の厳密度スペクトラムとして整理しています[13]。自分たちのチームがどの段階を目指すのかを最初に決めておくことが、後述する「過剰形式化（Waterfall化）」を防ぐ第一歩になります。
+
+| 段階 | 考え方 | 仕様が担う役割 | コードの位置づけ | 向いているケース |
+|---|---|---|---|---|
+| **Spec-first（仕様先行）** | 仕様を書いてからプロンプトする | AIへの高品質なコンテキスト | 依然として正（メンテナンス対象） | ほとんどの現場のデフォルト。実務での主流[16] |
+| **Spec-anchored（仕様係留）** | 仕様は実装後も「生きた契約」として残り続ける | 継続的なガバナンス文書 | 正だが、仕様との乖離をCIで機械的に検知 | チーム開発・長期保守プロジェクト |
+| **Spec-as-source（仕様が源泉）** | 仕様こそが唯一のソースで、コードは使い捨て可能な生成物 | 実行可能な仕様そのもの | 生成物（規約変更時は再生成） | OpenAPIからのスタブ生成、Simulinkモデルからの組込みコード生成など、narrow domainで既に標準化された領域[15] |
+
+多くの現場が実際に運用しているのは**Spec-anchored**寄りのアプローチであり、「仕様がAIの仕事を楽にし、人間レビュアーの仕事も楽にする」という位置づけです[15]。
+
+---
+
+## 3. 全体ワークフロー：Specify → Plan → Tasks → Implement
+
+GitHub Spec Kitに代表される主要ツール群は、ほぼ共通して「Specify → Plan → Tasks → Implement」という4フェーズループを採用しています[15][16]。各フェーズの間に**人間によるレビューゲート**を置くことが、品質を保つ最大のポイントです。
+
+```mermaid
+flowchart TB
+    A["constitution.md
（プロジェクトの不変原則）"] --> B["① Specify
spec.md / requirements.md"]
+    B --> C{"人間によるレビュー
曖昧さの解消（Clarify）"}
+    C -->|"要修正"| B
+    C -->|"承認"| D["② Plan
plan.md / design.md"]
+    D --> E{"技術レビュー"}
+    E -->|"要修正"| D
+    E -->|"承認"| F["③ Tasks
tasks.md"]
+    F --> G["④ Implement
AIエージェントによる実装"]
+    G --> H{"テスト・検証"}
+    H -->|"失敗"| F
+    H -->|"合格"| I["マージ"]
+    I -.->|"仕様は生きたドキュメント：
変更時はSpecを先に更新"| B
+```
+
+GitHub Spec Kitでは、この4フェーズに加えて `/speckit.constitution`（プロジェクトの非交渉原則を定義）、`/speckit.clarify`（曖昧点の質問）、`/speckit.analyze`（spec/plan/tasks間の矛盾チェック）、`/speckit.checklist`（仕様の抜け漏れを検査する「英語のユニットテスト」）といった補助コマンドがスラッシュコマンドとして用意されています[3]。AWS Kiroも同様に、要件定義→設計→実装計画の3フェーズを踏み、各フェーズ間に承認ゲートを設けます[5][6]。
+
+---
+
+## 4. ファイル構成の全体像
+
+SDDのMarkdown群は役割ごとに階層化して配置するのが定石です。プロジェクト全体に効くファイルと、機能単位でスコープされるファイルを混在させないことが重要です。
+
+```mermaid
+flowchart TB
+    subgraph Root["リポジトリルート"]
+        AGENTS["AGENTS.md
プロジェクト全体のコンテキスト"]
+        CONST["constitution.md
不変の原則"]
+    end
+    subgraph Feature["specs/001-feature/"]
+        SPEC["spec.md
What と Why"]
+        PLAN["plan.md
How"]
+        TASKS["tasks.md
実行単位"]
+    end
+    subgraph Skills["再利用可能な手順"]
+        SKILL["SKILL.md
YAML frontmatter + 手順"]
+    end
+    AGENTS --> SPEC
+    CONST --> SPEC
+    SPEC --> PLAN
+    PLAN --> TASKS
+    TASKS -.->|"必要時にオンデマンドで読込"| SKILL
+```
+
+主要なツール・標準がそれぞれどのファイル名を使っているかを整理すると以下の通りです。名前は違えど、役割（What/Why・How・実行単位・全体コンテキスト）はほぼ共通しています。
+
+| ツール / 標準 | 主なファイル | 提供元・管理団体 | 位置づけ |
+|---|---|---|---|
+| GitHub Spec Kit | `constitution.md`, `spec.md`, `plan.md`, `tasks.md` | GitHub（Microsoft傘下） | OSSツールキット（MITライセンス）[1] |
+| AWS Kiro | `requirements.md`, `design.md`, `tasks.md` | AWS | 統合IDEに組み込み。EARS記法をネイティブ採用[5] |
+| Claude Code | `CLAUDE.md` | Anthropic | セッションを跨いで読み込まれる指示書[20] |
+| AGENTS.md（オープン標準） | `AGENTS.md` | Agentic AI Foundation（Linux Foundation傘下）。OpenAI・Google（Jules）・Cursor・Factory等が策定を主導 | ベンダー中立、必須フィールドなしのプレーンMarkdown[32] |
+| Cursor | `.cursor/rules/*.mdc` | Cursor（Anysphere） | YAML frontmatter付きMarkdown。パスごとに適用範囲を制御[22] |
+| Agent Skills | `SKILL.md` | Anthropicが提唱、オープン標準化 | Claude Code・Codex・Cursorなど30以上のツールが対応[18][29] |
+
+**モノレポでの配置ルール**: AGENTS.mdやCLAUDE.mdはモノレポの各パッケージ配下にも配置でき、エージェントは「編集対象ファイルに最も近いファイル」を優先して読み込みます（例: OpenAIのCodexリポジトリでは88個のAGENTS.mdが階層的に配置されている）[27]。Claude Codeは独自にCLAUDE.mdを読みますが、`@AGENTS.md` のインポート記法を使えばAGENTS.mdを取り込めるため、複数ツールを併用するチームは「AGENTS.mdを単一の正とし、CLAUDE.mdは1行のインポート文だけにする」運用が推奨されています[26]。
+
+---
+
+## 5. Step-by-Step: spec.md / requirements.md の書き方
+
+### Step 1: メタデータと目的を明記する
+
+冒頭に「何のための機能か」「誰のためか」「スコープ外は何か」を短く書きます。実装方法（How）はここに書きません。GitHub Spec Kitの実運用では、LLMが張り切りすぎて要素サイズや配色などの実装詳細をspecに混入させてしまう傾向が報告されており、気づいた時点で技術要件をplanドキュメント側へ移動するよう指示することが推奨されています[3]。
+
+### Step 2: ユーザーストーリーを優先度付きで書く
+
+`P1`/`P2`/`P3` のように優先度ラベルを振り、各ストーリーを独立してテスト可能なMVPスライスとして記述するテンプレートが広く使われています[19]。
+
+```markdown
+### US-1（P1）: パスワードレス・ログイン
+ユーザーとして、パスワードを覚えずにメールリンクだけでログインしたい。
+これにより、パスワード忘れによる離脱を防げるため。
+```
+
+### Step 3: 受け入れ基準をEARS記法で書く
+
+自然文の受け入れ基準（"ユーザーはログインできる" 等）は曖昧で、人間にもAIにも解釈のブレを生みます。この問題に対する業界標準の解が **EARS（Easy Approach to Requirements Syntax）** です。2009年にRolls-RoyceのAlistair Mavin氏らが航空機エンジン制御の要件定義用に考案した記法で、Kiroをはじめとする主要SDDツールがAIエージェント向けの受け入れ基準記法として採用しています[16][24]。EARSはベンダー中立の記法であり、Kiroは採用者であって考案者ではありません[24]。
+
+EARSは5つのパターンで構成されます。どのパターンを使うべきかは、以下のように機械的に判定できます。
+
+```mermaid
+flowchart TD
+    Q1{"常に真であるべき要件か？"}
+    Q1 -->|"Yes"| U["Ubiquitous
THE SYSTEM SHALL ..."]
+    Q1 -->|"No"| Q2{"特定のイベントで発火するか？"}
+    Q2 -->|"Yes"| EV["Event-driven
WHEN event THE SYSTEM SHALL ..."]
+    Q2 -->|"No"| Q3{"特定の状態が続く間だけ有効か？"}
+    Q3 -->|"Yes"| ST["State-driven
WHILE state THE SYSTEM SHALL ..."]
+    Q3 -->|"No"| Q4{"望ましくない事象への対応か？"}
+    Q4 -->|"Yes"| UB["Unwanted behavior
IF trigger THEN THE SYSTEM SHALL ..."]
+    Q4 -->|"No"| OPT["Optional feature
WHERE feature THE SYSTEM SHALL ..."]
+```
+
+| パターン | 用途 | 構文テンプレート | 例 |
+|---|---|---|---|
+| Ubiquitous（恒常要件） | 常に真である基本要件 | `THE SYSTEM SHALL <応答>` | THE SYSTEM SHALL 全APIレスポンスをJSON形式で返す |
+| Event-driven（イベント駆動） | 特定のイベント発生時 | `WHEN <トリガー> THE SYSTEM SHALL <応答>` | WHEN ユーザーが有効なメールアドレスを送信 THE SYSTEM SHALL 15分間有効なワンタイムリンクを送付する[21] |
+| State-driven（状態駆動） | 特定の状態が続く間 | `WHILE <状態> THE SYSTEM SHALL <応答>` | WHILE メンテナンスモード中 THE SYSTEM SHALL 書き込みAPIを503で拒否する |
+| Unwanted behavior（望まない挙動への対応） | 異常系・エラー処理 | `IF <トリガー> THEN THE SYSTEM SHALL <応答>` | IF ログインリンクが2回目以降使用された THEN THE SYSTEM SHALL HTTP 410で拒否する[21] |
+| Optional feature（オプション機能） | 特定機能が有効な場合のみ | `WHERE <機能> THE SYSTEM SHALL <応答>` | WHERE 多要素認証が有効化されている THE SYSTEM SHALL 追加のワンタイムコード入力を要求する |
+
+EARSで書かれた受け入れ基準は、ほぼ1対1でテストケースに変換できるという実務上の利点があります[21]。一方で、EARSは「表現の型」を統一するだけであり、それ自体が実行可能なテストになるわけではない点には注意が必要です[24]。
+
+### Step 4: 曖昧さを可視化するマーカーを使う
+
+GitHub Spec Kitの実運用では、spec.md中に `[NEEDS CLARIFICATION]` のようなマーカーを埋め込み、これが残っている間はタスクを「完了」とマークしない、という運用が確認されています[19]。曖昧な要件を無理に確定させず、可視化したまま人間の判断を仰ぐ設計です。
+
+### Step 5: 実装詳細を書かない（Whatに徹する）
+
+spec.mdは「何を」「なぜ」に徹し、「どう作るか」はplan.mdに譲ります。良い仕様書の条件を扱ったAddy Osmani氏（Googleの著名なエンジニア）の記事でも、仕様はAIエージェントが自己修正しつつ安全な境界内に留まるための"契約"であるべきだと述べられています[10]。
+
+---
+
+## 6. Step-by-Step: plan.md / design.md の書き方
+
+1. **技術スタックとアーキテクチャ方針を明記する**: 使用するフレームワーク、データストア、外部API連携などをspecの要件にひもづけて記述します。
+2. **アーキテクチャ図・シーケンス図はMermaidで描く**: Kiroのdesign.mdも、技術アーキテクチャとシーケンス図をこの段階で文書化する運用になっています[5]。ASCIIアートは避け、Mermaidのフローチャート／シーケンス図で表現します。
+3. **意思決定の根拠を残す（ADR的に）**: なぜこの技術を選んだかを一言添えるだけで、後からの手戻りやレビュー時間を大きく減らせます。ただし、Scott Logic社の検証では、planフェーズで自動生成された406行の「research doc」が、既存ページと同じライブラリを使う理由付けなど、冗長で価値の薄い内容になっていた例も報告されています[17]。**生成させたら鵜呑みにせず、価値のある意思決定記録だけを残す**姿勢が重要です。
+4. **エラーハンドリング・テスト戦略を明記する**: Kiroのdesign.mdはエラーハンドリングとテスト戦略を含むのが標準ですが、これが過剰だと実装フェーズでのレビュー往復が増えるという声もあり、必要な粒度は都度調整します[32]。
+
+---
+
+## 7. Step-by-Step: tasks.md の書き方
+
+1. **アトミックなタスクに分解する**: 各タスクは独立してレビュー・差し戻し可能な単位にします。
+2. **要件へのトレーサビリティを持たせる**: 各タスクがどのユーザーストーリー／受け入れ基準に対応するかを明示し、実装が要件から逸脱していないかを追跡できるようにします[33]。
+3. **依存関係を明示し、並列実行可能なタスクをグルーピングする**: Kiroはtasks.mdから依存関係グラフを構築し、依存のないタスクを「Wave 1」としてまとめて並列に扱う仕組みを持ちます[5]。
+4. **実装フェーズで内容を変更しない**: タスクはLLMが何を作るかの直接的な反映であるため、この段階で不正確な内容が混入していないかの確認が特に重要だと、Spec Kitの実運用知見として指摘されています[3]。
+
+```markdown
+## Task 12: マジックリンク送信APIの実装
+- 対応要件: US-1 / EARS-EV-1
+- 依存: Task 03（メール送信基盤）
+- 完了条件: `POST /auth/magic-link` が15分間有効なトークンを発行し、単体テストが通ること
+```
+
+---
+
+## 8. AGENTS.md / CLAUDE.md：プロジェクト全体のコンテキストファイル
+
+AGENTS.mdは「エージェント向けのREADME」と位置づけられる、プレーンMarkdownのオープン標準です[7]。特徴は以下の通りです。
+
+- **必須フィールドなし**: YAML frontmatterも不要で、見出しの付け方や粒度は完全に自由です[28]。
+- **対応ツールの広さ**: 2026年前半時点でOpenAI Codex、Cursor、GitHub Copilot coding agent、Gemini CLI、Windsurf、Aider、Zed、Devin、Amazon Qなど30以上のツールがネイティブまたはインポート経由で読み込みます[25][26]。
+- **ガバナンス**: 元々OpenAI・Amp・Google（Jules）・Cursor・Factoryなどの協業から生まれ、現在はLinux Foundation傘下のAgentic AI Foundationがスチュワードシップを担っています[7]。
+- **コンフリクト解決**: 「編集対象ファイルに最も近いAGENTS.md」が優先され、さらにユーザーのチャット上の明示的な指示はすべてに優先します[7]。
+
+典型的に含める内容は、ビルドコマンド・テストコマンド・コーディング規約・触ってはいけない領域（境界）など、人間向けREADMEには書かないがエージェントには必要な運用情報です[26]。
+
+```markdown
+# AGENTS.md
+
+## セットアップ
+- 依存関係インストール: `pnpm install`
+- 開発サーバー起動: `pnpm dev`
+
+## テスト
+- 変更前に必ず実行: `pnpm test -- --changed`
+- E2Eは `pnpm test:e2e`（CI専用、ローカルでは実行しない）
+
+## 規約
+- 状態管理はZustandのみ使用し、Reduxを追加しない
+- APIクライアントは `src/lib/api/` 以下に集約する
+
+## 境界
+- `packages/billing/` 配下は決済監査対象。変更時は必ず人間レビューを要求すること
+```
+
+Claude CodeはAGENTS.mdではなく独自の `CLAUDE.md` を読み込みますが、二重管理を避けるため「CLAUDE.mdの中身は `@AGENTS.md` の1行インポートのみにし、実体はAGENTS.mdに一本化する」という移行パターンが定着しています[25]。
+
+---
+
+## 9. SKILL.md：段階的開示（Progressive Disclosure）
+
+AGENTS.mdが「プロジェクトが何であるか」を伝えるのに対し、SKILL.mdは「特定のタスクをどうこなすか」という再利用可能な手順をエージェントに渡す仕組みです[27]。Anthropicが提唱し、Claude Code・Codex・Cursorなど多くのツールに広がったオープン標準です[18]。
+
+SKILL.mdの最大の設計思想は**段階的開示（Progressive Disclosure）**です。コンテキストウィンドウは有限であり、すべてのスキルの全文を常時ロードするとノイズが増えるため、必要になった瞬間にだけ詳細を読み込む設計になっています[8]。
+
+```mermaid
+flowchart TB
+    S1["セッション開始
SKILL.md の name / description のみ読込"] --> S2{"タスクがスキルの
ドメインと一致するか？"}
+    S2 -->|"No"| S1
+    S2 -->|"Yes"| S3["SKILL.md 本文を読込"]
+    S3 --> S4{"補助ファイルが必要か？
（スクリプト・参考資料）"}
+    S4 -->|"Yes"| S5["補助ファイルをオンデマンドで読込"]
+    S4 -->|"No"| S6["タスクを実行"]
+    S5 --> S6
+```
+
+構造は「YAML frontmatter（`name` と `description` の2つが必須）＋Markdown本文の指示＋任意の補助ファイル（スクリプト・テンプレート）」というシンプルな形です[27][18]。
+
+```markdown
+---
+name: deploy
+description: アプリケーションを本番またはステージング環境へデプロイする
+---
+
+# Deploy
+
+## 手順
+1. テストスイートを実行: `bun run test`
+2. 本番ビルド: `bun run build`
+3. デプロイコマンドを実行し、ヘルスチェックを確認する
+```
+
+---
+
+## 10. Markdown記法そのもののベストプラクティス
+
+Anthropicの公式エンジニアリングブログ「Effective context engineering for AI agents」は、プロンプトやコンテキストを``のようなXMLタグ、または**Markdownの見出し**で明確にセクション分けすることを推奨しています。具体的な整形方法自体は今後変わっていく可能性があるが、明確なセクション区切りという原則自体は重要だと位置づけられています[8]。この原則はspec.md等のSDDドキュメントにもそのまま当てはまります。
+
+### 10.1 見出し階層とセクション分け
+
+- 見出し（`#`〜`####`）でセクションを明確に分離し、AIが「今どのセクションを読んでいるか」を見出しテキストだけで判断できるようにする。
+- 1見出しに1目的。複数の関心事を1つの見出し配下に詰め込まない。
+- アンカーリンク付きの目次（本ガイド冒頭のような）を長いドキュメントには必ず用意し、人間のレビュー時のナビゲーションコストを下げる。
+
+### 10.2 表 vs 箇条書きの使い分け
+
+- **表が向くケース**: 複数の項目を同じ軸（列）で比較する場合（本ガイドのツール比較表、EARSパターン表など）。AIエージェントにとっても構造化データとして解釈しやすい。
+- **箇条書きが向くケース**: 単純な列挙、手順のステップ、条件の羅列。
+
+### 10.3 Mermaidダイアグラムのルール
+
+ASCIIアートによる図解は保守性が低く、フォントやレンダリング環境によって崩れるため、フローチャートは必ずMermaidのコードブロックで記述します。実務での注意点は以下の通りです。
+
+- `mindmap` と `quadrantChart` は環境によって表示が崩れやすいため避け、`flowchart` + `subgraph` で代替する。
+- サブグラフのタイトルには特殊文字を避けるか、クォートで囲んでパースエラーを防ぐ。
+- ノード数が多い横方向のフローチャートはビューポート幅を超えやすいため、`TB`（縦方向）レイアウトを優先する。
+- ノード間に実際のエッジがない兄弟要素は横に並んで幅が広がりがちなので、意味のある接続だけを描き、レイアウトを縦に収める。
+
+### 10.4 コードブロックとfrontmatter
+
+- コマンド例・設定例は必ずフェンス付きコードブロック（\`\`\`）で囲み、言語識別子（`bash`, `json`, `markdown`など）を付与する。
+- SKILL.mdやCursorの`.mdc`ファイルのように、メタデータが必要な場合はYAML frontmatterを使う。本文の指示と機械可読なメタデータを分離できる[27]。
+
+---
+
+## 11. 生きたドキュメントとしての運用
+
+仕様は「書いたら終わり」ではありません。SDDが従来のウォーターフォール型ドキュメントと決定的に違うのは、**要求が変わったらまず仕様を更新し、そこからコードを再生成・修正する**という運用ループを回す点です[16]。
+
+- バグ修正・機能追加のリクエストが来たら、実装コードより先にspec.mdを更新する。
+- 仕様変更のコストが「重い」と感じ始めたら、それは過剰形式化（Waterfall化）のサインとして扱い、プロセスを軽量化する[31]。
+- 大きな機能追加のたびに1つの巨大な仕様に機能を積み増すのではなく、機能ごとに仕様を分割する。
+
+---
+
+## 12. よくある落とし穴と対策
+
+| 落とし穴 | 症状 | 対策 |
+|---|---|---|
+| **Spec Bloat（仕様の肥大化）** | 30分で実装できるはずの機能に対して800行超のMarkdownが生成される[30] | テンプレートを最小構成にトリムし、「必要十分」をチーム内で明文化する |
+| **ウォーターフォール化** | Spec→Plan→Tasksの往復が硬直化する。Scott Logic社の実機検証では、Spec Kitのフルパイプラインが通常の反復プロンプトよりも約10倍遅く、レビューだけで3.5時間を要した例も報告されている[17] | 変更コストが高いと感じたら過剰形式化のサイン。小規模な変更は軽量な仕様更新に留める |
+| **Semantic Diffusion（用語の希薄化）** | 「仕様駆動開発」という言葉がツールごとに異なる哲学を指すため、比較が噛み合わなくなる[24] | ツール名やラベルではなく、実際のワークフロー（何がSource of Truthか）で比較する |
+| **実装詳細の混入** | 機能仕様（spec.md）に色・サイズ・ライブラリ選定などの技術詳細が紛れ込む[3] | 気づいた時点でLLMに指示し、該当箇所をplan.md側へ移動する |
+| **Spec Drift（仕様と実装の乖離）** | コードだけが変更され、仕様が古いまま放置される | 「要求変更時は必ず仕様を先に更新する」運用をチームルール化し、CIで乖離を検知する仕組みを検討する[16] |
+| **偽の網羅感** | 仕様を読み流し、エッジケースが書かれていると錯覚したまま実装を進めてしまう | 仕様は「読まれる前提」で簡潔に保ち、レビュー担当を明確に決める[30] |
+
+---
+
+## 13. 導入前チェックリスト
+
+- [ ] `constitution.md`（またはAGENTS.md冒頭）にプロジェクトの非交渉原則が明文化されている
+- [ ] spec.md / requirements.mdが「What」「Why」に徹し、実装詳細（How）を含んでいない
+- [ ] 受け入れ基準がEARS記法（またはGiven-When-Then）で書かれ、曖昧な自然文のままになっていない
+- [ ] 曖昧な要件には `[NEEDS CLARIFICATION]` 等のマーカーが付き、放置されていない
+- [ ] plan.md / design.mdのアーキテクチャ図・シーケンス図がMermaidで記述され、ASCIIアートを含まない
+- [ ] tasks.mdの各タスクが要件へのトレーサビリティを持ち、独立してレビュー可能な粒度になっている
+- [ ] AGENTS.md（またはCLAUDE.md）にビルド／テストコマンドと「触ってはいけない領域」が明記されている
+- [ ] 繰り返し使う手順はSKILL.mdとして切り出し、YAML frontmatterの`description`だけで用途が判断できる
+- [ ] 長いドキュメントにはアンカーリンク付き目次があり、見出し階層が1見出し1目的になっている
+- [ ] 比較・列挙情報は表で、手順・条件は箇条書きで整理されている
+- [ ] 仕様変更時は「まず仕様を更新してからコードを再生成・修正する」運用ルールがチームに共有されている
+- [ ] 生成された仕様・計画ドキュメントの分量が肥大化していないか、レビュー時に確認している
+
+---
+
+## 14. まとめ
+
+AI仕様駆動開発におけるMarkdown運用の本質は、**「AIエージェントが迷わず実装でき、人間が短時間でレビューできる」構造をどれだけ作れるか**に尽きます。EARS記法による受け入れ基準の明確化、What/Howの分離、段階的開示によるコンテキスト管理、そして「仕様は生きたドキュメントである」という運用ルールの4つが、ツールを問わず共通する骨格です。同時に、Spec Kitの実運用レビューが示すように、仕様が肥大化しウォーターフォール的な硬直運用に陥るリスクも実際に報告されています[17]。仕様の「厳密さ」と「軽さ」のバランスは、プロジェクトの規模とチームの成熟度に応じて都度調整していく前提で運用してください。
+
+---
+
+## 15. 参考文献
+
+本ガイドの記述は、2026年7月28日時点で参照可能な以下の一次情報・著名な開発者/組織の発信に基づいています。
+
+1. GitHub, "spec-kit" 公式リポジトリ — https://github.com/github/spec-kit
+2. GitHub, Spec Kit 公式ドキュメントサイト — https://github.github.com/spec-kit/
+3. Den Delimarsky（GitHub Principal PM）, "What's The Deal With GitHub Spec Kit" — https://den.dev/blog/github-spec-kit/
+4. Microsoft for Developers, "Diving Into Spec-Driven Development With GitHub Spec Kit" — https://developer.microsoft.com/blog/spec-driven-development-spec-kit/
+5. AWS Kiro 公式ドキュメント, "Specs" — https://kiro.dev/docs/specs/
+6. AWS Kiro 公式ドキュメント, "Feature Specs" — https://kiro.dev/docs/specs/feature-specs/
+7. AGENTS.md 公式サイト（Agentic AI Foundation / Linux Foundation） — https://agents.md/
+8. Anthropic Engineering, "Effective context engineering for AI agents" — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+9. Anthropic Engineering, "Effective harnesses for long-running agents" — https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+10. Addy Osmani（Google, Chrome Engineering）, "How to write a good spec for AI agents" — https://addyosmani.com/blog/good-spec/
+11. Simon Willison（Datasette作者）, "Agentic Engineering Patterns" — https://simonw.substack.com/p/agentic-engineering-patterns
+12. Simon Willison, ai-assisted-programming タグ一覧 — https://simonwillison.net/tags/ai-assisted-programming/
+13. Martin Fowler / Thoughtworks, "Exploring Generative AI" — https://martinfowler.com/articles/exploring-gen-ai.html
+14. Wikipedia, "Spec-driven development" — https://en.wikipedia.org/wiki/Spec-driven_development
+15. Java Code Geeks, "Spec-Driven Development with AI: Write the Spec First, Then Prompt the Implementation" — https://www.javacodegeeks.com/2026/05/spec-driven-development-with-ai-write-the-spec-first-then-prompt-the-implementation.html
+16. BCMS, "Spec-Driven Development (SDD): The Definitive 2026 Guide" — https://thebcms.com/blog/spec-driven-development
+17. Scott Logic（Colin Eberhardt, CTO）, "Putting Spec Kit Through Its Paces: Radical Idea or Reinvented Waterfall?" — https://blog.scottlogic.com/2025/11/26/putting-spec-kit-through-its-paces-radical-idea-or-reinvented-waterfall.html
+18. Agentailor, "Top AI Agent Standards to Know in 2026" — https://blog.agentailor.com/posts/top-ai-agent-standards-2026
+19. SSOJet, "9 PRD and Spec Templates Built for AI Coding Agents" — https://ssojet.com/blog/prd-spec-templates-ai-agents
+20. Joshua McDonald, "EARS, Fifteen Years On: The Requirements Format Built for the Agent Era" — https://joshmcdonald.medium.com/ears-fifteen-years-on-the-requirements-format-built-for-the-agent-era-0f78f8ff35a0
+21. DEV Community (krlz), "Spec-Driven Development in 2026: What It Is, the Tooling, and How Teams Actually Use It" — https://dev.to/krlz/spec-driven-development-in-2026-what-it-is-the-tooling-and-how-teams-actually-use-it-2fk2
+22. Augment Code, "6 Best Spec-Driven Development Tools for AI Coding in 2026" — https://www.augmentcode.com/tools/best-spec-driven-development-tools
+23. SoftwareSeni, "Spec-Driven Development Is Replacing Vibe Coding as the Professional Standard for AI Teams"（Simon Willison氏の見解を含む） — https://www.softwareseni.com/spec-driven-development-is-replacing-vibe-coding-as-the-professional-standard-for-ai-teams/
+24. CodeMySpec, "Spec-Driven Development in 2026: Guide + Tool Comparison"（EARS記法の歴史・Rolls-Royce起源の詳細） — https://codemyspec.com/blog/spec-driven-development
+25. CodersEra, "AGENTS.md Complete Guide 2026" — https://codersera.com/blog/agents-md-complete-guide-2026/
+26. BuildBetter, "AGENTS.md Complete Guide for Engineering Teams in 2026" — https://blog.buildbetter.ai/agents-md-complete-guide-for-engineering-teams-in-2026/
+27. MorphLLM, "AGENTS.md Spec (2026): Recommended Sections and Comparison With CLAUDE.md / .cursorrules" — https://www.morphllm.com/agents-md-guide
+28. DeepWiki, "AGENTS.md Format Documentation"（openai/agents.md） — https://deepwiki.com/openai/agents.md/5-agents.md-format-documentation
+29. Agensi, "What Is the Agent Skills Open Standard?" — https://www.agensi.io/learn/agent-skills-open-standard
+30. bitbytebit（Substack）, "Spec-Driven Development: From Vibe Coding to Structured Development" — https://bitbytebit.substack.com/p/spec-driven-development-from-vibe
+31. The Main Thread, "Spec-Driven Development Needs an Exit Strategy" — https://www.the-main-thread.com/p/spec-driven-development-exit-strategy
+32. AWS Builder Center, "Getting Started With Spec-Driven Development Using Kiro" — https://builder.aws.com/content/36nn9PbSZuKJiWWoO2UWmFaaCHs/getting-started-with-spec-driven-development-using-kiro
+33. Kanai Dutta（Medium）, "Experience With Kiro's Spec Driven Development Methodology" — https://medium.com/@kanaiduttaiem/experience-with-kiros-spec-driven-development-methodology-1e57af895fd7
+
+> 免責事項: 上記は2026年7月28日時点のWeb検索結果に基づく要約であり、各ツールの仕様・対応状況は今後変更される可能性があります。導入前には各公式ドキュメントの最新版を必ず確認してください。
diff --git a/Google-sandbox-best-practices.html b/Google-sandbox-best-practices.html
new file mode 100644
index 00000000..43156f6a
--- /dev/null
+++ b/Google-sandbox-best-practices.html
@@ -0,0 +1,1480 @@
+
+
+  
+    
+    
+    
+      Google サンドボックス技術 完全ガイド ― AIエージェント・API・コンテナ・C/C++・ブラウザ
+    
+    
+    
+    
+    
+    
+  
+  
+    
+
+    

+      
+
+      

+        
Google サンドボックス技術 完全ガイド

+        

+          AIエージェント・API・コンテナ・C/C++・ブラウザ、5領域のベストプラクティスをステップバイステップで理解する
+        

+        

+          

+            対象読者:サンドボックス技術の初学者〜中級エンジニア
情報基準日:2026年7月27日時点(以降の変更は各社公式ドキュメントで要確認)
+          

+        

+
+        

+        
目次

+        
    
+          
  1. はじめに:なぜ「サンドボックス」が必要なのか
    2. 
+          
  2. 全体マップ:Googleの5つのサンドボックス領域
    3. 
+          
  3. 領域① AIエージェントのサンドボックス
    4. 
+          
  4. 領域② APIのサンドボックス
    5. 
+          
  5. 領域③ コンテナのサンドボックス
    6. 
+          
  6. 領域④ C/C++のサンドボックス
    7. 
+          
  7. 領域⑤ ブラウザのサンドボックス
    8. 
+          
  8. 意思決定フロー:自分のケースにはどれを選ぶべきか
    9. 
+          
  9. 横断ベストプラクティス早見表
    10. 
+          
  10. 参考文献・出典URL
    11. 
+        

+        

+        

+        

+          1. はじめに:なぜ「サンドボックス」が必要なのか
+        

+        

+          「サンドボックス(sandbox)」とは、信頼できないコードやデータを、ホストシステム(OS本体・他のプロセス・他の顧客のデータなど)から隔離された領域の中だけで実行させるための仕組みです。子どもが砂場の外に砂をこぼさないのと同じように、「万が一そのコードが悪意を持っていたり、バグを含んでいたりしても、被害が砂場の外に漏れない」ことを保証するのが目的です。
+        

+        
Googleがサンドボックスを重視する背景には、次の3つの共通した脅威があります。

+        
    
+          
  • 
+            信頼できない入力の実行:AIエージェントが生成したコード、ユーザーがアップロードしたファイル、サードパーティのライブラリなど、開発者自身がレビューしきれないコードを動かす機会が増え続けている
+          
    • 
+          
  • 
+            マルチテナンシー:クラウド上では複数の顧客・複数のワークロードが同じ物理ハードウェアを共有するため、1つのワークロードの侵害が他のワークロードに波及してはならない
+          
    • 
+          
  • 
+            メモリ安全性が保証できない領域の存在:C/C++やJavaScriptエンジンのように、言語仕様上メモリ安全性を完全には保証できない領域が、今なお本番システムの中核に存在する
+          
    • 
+        

+        

+          Googleはこの課題に対して、単一の万能な解決策ではなく、隔離したい対象のレイヤーごとに専用のサンドボックス技術を使い分けるという設計思想を取っています。本ガイドでは、その中でも特に問い合わせの多い次の5領域を、ステップバイステップのベストプラクティスとして整理します。
+        

+        

+        

+        

+          2. 全体マップ:Googleの5つのサンドボックス領域
+        

+        
+flowchart TB
+    A["Google のサンドボックス戦略<br/>(隔離レイヤーごとの使い分け)"]
+    A --> B["① AIエージェント"]
+    A --> C["② API"]
+    A --> D["③ コンテナ"]
+    A --> E["④ C / C++"]
+    A --> F["⑤ ブラウザ"]
+
+    B --> B1["GKE Agent Sandbox (gVisor)"]
+    B --> B2["Gemini Code Execution"]
+
+    C --> C1["Apigee サンドボックス環境"]
+    C --> C2["Cloud Armor / WAAP"]
+
+    D --> D1["GKE Sandbox (gVisor)"]
+    D --> D2["Cloud Run / App Engine / Functions"]
+
+    E --> E1["Sandbox2"]
+    E --> E2["Sandboxed API (SAPI)"]
+
+    F --> F1["マルチプロセス + Site Isolation"]
+    F --> F2["V8 Sandbox"]

+        

+          この図からもわかるとおり、5つの領域の多くが「gVisor」という同一のオープンソース技術を土台にしていることが特徴です。gVisorはGoogle社内で長年本番ワークロードの隔離に使われてきた実績をもとにオープンソース化された、ユーザー空間でLinuxカーネルAPIを再実装する「アプリケーションカーネル」です。まずこの共通基盤を理解しておくと、以降の各領域の理解が格段に速くなります。
+        

+        

+        

+        
3. 領域① AIエージェントのサンドボックス

+        

+          3-1. なぜAIエージェント専用の隔離が必要か
+        

+        

+          AIエージェントは、LLMが生成した非決定的なコードをその場で実行したり、外部ツールを自律的に呼び出したりします。これは「常に信頼できない入力を、常に本番同然の権限で実行し続ける」ことに等しく、通常のアプリケーションよりもはるかに広い攻撃対象領域を生み出します。GoogleはこれをGKE(Google
+          Kubernetes Engine)向けのAgent Sandboxと、Gemini APIやAgent
+          Platform向けのCode Executionという2つの製品ラインで解決しています。
+        

+        
3-2. GKE Agent Sandbox:アーキテクチャ

+        

+          GKE Agent Sandboxは、Kubernetes SIG
+          Apps配下でオープンソース開発されているKubernetesネイティブな拡張機能です。gVisorによるカーネルレベルの隔離を、Sandbox・SandboxTemplate・SandboxClaimという3つの新しいKubernetesカスタムリソースを通じて提供します。
+        

+        
gVisorの内部は「Sentry」と「Gofer」という2つのコンポーネントで構成されます。

+        
+flowchart LR
+    App["エージェントが生成した<br/>コード / プロセス"] --> Sentry["gVisor Sentry<br/>(ユーザー空間の疑似カーネル)"]
+    Sentry --> Gofer["gVisor Gofer<br/>(ファイルI/Oプロキシ)"]
+    Gofer --> Kernel["ホストのLinuxカーネル"]
+    Sentry -.->|直接到達は不可| Kernel

+        

+          Sentryはエージェントが発行するすべてのシステムコール(execやsocketなど)を横取りし、ホストカーネルに直接触れさせない「偽のカーネル」として振る舞います。ファイルシステム操作だけは別プロセスのGoferが仲介するため、たとえSentryに未知の脆弱性があっても、ファイルシステムへの被害範囲を最小化できます。
+        

+        

+          3-3. ステップバイステップ:導入のベストプラクティス
+        

+        
    
+          
  1. 
+            隔離(ISOLATE):非決定的なエージェントのコード・ツール実行・ユーザー入力処理はすべてGKE Agent
+            Sandbox(gVisor)上で実行し、RCE(リモートコード実行)攻撃をサンドボックス内に封じ込める
+          
    2. 
+          
  2. 
+            高速化(ACCELERATE):サンドボックスの起動レイテンシを隠すため、事前にプロビジョニングされた「ウォームプール」を用意する。さらにコスト削減のため、アイドル状態のエージェントは「コールドプール(サスペンド状態のVM)」に退避させ、Pod
+            Snapshotsで低コストに復元する
+          
    3. 
+          
  3. 
+            権限の制限(RESTRICT・ID):Workload Identity
+            Federationを使い、エージェントごとに使い捨ての最小権限IAMアイデンティティを付与する
+          
    4. 
+          
  4. 
+            通信の制限(RESTRICT・Network):デフォルト拒否(default-deny)のKubernetes
+            NetworkPolicyを設定し、エージェントが必要とするDNS・メタデータ・APIエンドポイントだけを明示的に許可リスト化する
+          
    5. 
+          
  5. 
+            多層防御を過信しない:gVisor・Workload Identity・VPC Service
+            Controlsをすべて設定しても、それらは「許可されたチャネルの中で行われる正規の操作」しか防げない。プロンプトインジェクションによって、許可済みのAPI呼び出し経由でデータが持ち出されるリスクは別途モニタリングで検知する必要がある、と複数のセキュリティ研究者が指摘している
+          
    6. 
+        

+        

+          3-4. Gemini API / Agent Platform の Code Execution
+        

+        

+          GKE以外にも、Gemini APIおよびGemini Enterprise Agent Platformが提供するCode Executionツールを使えば、GKEにデプロイしなくてもマネージドなサンドボックスでPythonコードを実行できます。特徴は次のとおりです。
+        

+        

+          
+            
+              
+                
+                
+              
+            
+            
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+            
+          
特徴内容
起動速度1秒未満でサンドボックスを作成・実行可能
ファイル入出力リクエスト/レスポンス全体で最大100MBまで対応
状態保持実行状態(メモリ)を最大14日間保持(TTLで調整可能)
デフォルトのネットワーク無効(明示的な許可リストを設定しない限りアウトバウンド通信不可)
対応フレームワーク
+                  特定のフレームワークに依存せず、任意のエージェント実装・任意のモデルから利用可能
+                

+        

+        

+          Agent Development
+          Kit(ADK)の公式安全設計ドキュメントでも、「コード実行は特にセキュリティ上の影響が大きい特殊なツールであり、モデルが生成したコードがローカル環境を侵害しないよう、必ずサンドボックス化しなければならない」と明記されています。あわせてModel
+          ArmorプラグインやPII
+          redactionプラグインといった、入出力を検査する追加のガードレールも推奨されています。
+        

+        

+        

+        
4. 領域② APIのサンドボックス

+        

+          4-1. Apigeeにおける「サンドボックス環境」の考え方
+        

+        

+          API領域での「サンドボックス」は、これまでの実行時隔離とは意味合いが少し異なります。Apigee(Googleのネイティブなフルライフサイクル
+          API管理製品)における「環境(environment)」は、APIプロキシを実行するための隔離されたコンテキストを指し、公式ドキュメントでも「サンドボックス」と表現されています。1つの組織の中に複数の環境(開発用・テスト用・本番用など)を作成し、プロキシのデプロイ先を環境ごとに分離するのが基本設計です。
+        

+        
+flowchart LR
+    Client["クライアント"] --> GFE["Google Front End<br/>(TLS終端)"]
+    GFE --> Proxy["Apigee APIプロキシ<br/>(環境=サンドボックス)"]
+    Proxy --> Policy1["トラフィック管理<br/>ポリシー"]
+    Proxy --> Policy2["メッセージレベル<br/>保護ポリシー"]
+    Proxy --> Policy3["セキュリティポリシー<br/>(RBAC / OAuth等)"]
+    Proxy --> Backend["バックエンドサービス"]

+        

+          4-2. ステップバイステップ:APIサンドボックスのベストプラクティス
+        

+        
    
+          
  1. 
+            環境を目的別に分離する:hybrid構成では、1つの環境に大量のプロキシを詰め込まず、複数の環境を作り、環境ごとにデプロイするプロキシ数を絞ることが推奨されている
+          
    2. 
+          
  2. 
+            デフォルトポリシーを有効化する:Apigeeが提供する3種類の既定ポリシー(トラフィック管理・メッセージレベル保護・セキュリティ)をプロキシ層にアタッチする
+          
    3. 
+          
  3. 
+            IPアドレス/地理情報によるアクセス制御にはCloud Armorを使う:Apigee自体のポリシーだけでなく、Cloud Armorと組み合わせたWAAP(Web App and API
+            Protection)構成が推奨されている
+          
    4. 
+          
  4. 
+            クライアントIP解決を環境ごとにカスタマイズする:プロキシ経由のリクエストではX-Forwarded-Forヘッダーの保持設定が必要になるケースがあり、デフォルトのIP解決アルゴリズムが合わない場合は環境単位でカスタマイズできる
+          
    5. 
+          
  5. 
+            開発者向けサンドボックスは60日間の無償トライアルで検証する:本番導入前に、Apigeeの試用サンドボックス環境でAPI設計を検証してから、本番の環境構成に反映するワークフローが一般的
+          
    6. 
+          
  6. 
+            モックとの併用(一般的なAPIサンドボックス設計のベストプラクティス):OpenAPI仕様からモックエンドポイントを自動生成できるAPI管理プラットフォームの機能を活用し、モックとAPI仕様を常に同期させ、成功シナリオだけでなくエラーシナリオも用意し、CI/CDパイプラインに組み込むことが、業界全体のAPIサンドボックス運用における共通ベストプラクティスとして紹介されている
+          
    7. 
+        

+        

+        

+        
5. 領域③ コンテナのサンドボックス

+        

+          5-1. gVisorの基本アーキテクチャ(再掲・詳細版)
+        

+        

+          コンテナ領域におけるGoogleの主力技術は、AIエージェント領域でも登場したgVisorそのものです。通常のコンテナはホストカーネルを直接共有するため、1つのコンテナ内のカーネル脆弱性が、ノード全体・他の全コンテナに波及するリスクを抱えます。gVisorは、コンテナが発行するシステムコールをユーザー空間の「Sentry」で受け止め、seccomp-bpfによるシステムコールフィルタリングでさらに一段階の防御を重ねます。
+        

+        
+flowchart LR
+    Container["コンテナ内アプリケーション"] --> Sentry2["gVisor Sentry<br/>(ユーザー空間カーネル)"]
+    Sentry2 --> Seccomp["seccomp-bpf<br/>システムコールフィルタ"]
+    Seccomp --> HostKernel["ホストのLinuxカーネル"]

+        

+          Googleのサーバーレス製品群(App Engine、Cloud Run、Cloud
+          Functions)はいずれも、アプリケーションワークロードの隔離にgVisorを採用しています。Cloud
+          Runの場合、各インスタンスは仮想マシンモニター(VMM)によって他のインスタンスから隔離され、さらにコンテナ境界の強制とseccompによるシステムコールフィルタリングが重ねられる多層防御構成になっています。
+        

+        

+          5-2. ステップバイステップ:GKE Sandboxの有効化手順
+        

+        
    
+          
  1. 
+            専用ノードプールを作成する:GKE
+            SandboxはデフォルトのノードプールにはEnableできない。Standardクラスタでは、すべてのワークロードをサンドボックス化する場合でも、GKE
+            Sandboxを有効化していないノードプールを最低1つ残す必要がある
+          
    2. 
+          
  2. 
+            イメージタイプを揃える:ノードプールのイメージタイプは「Container-Optimized OS with
+            Containerd(cos_containerd)」のみがサポート対象
+          
    3. 
+          
  3. 
+            RuntimeClassを確認する:ノードプール作成後、GKEが自動的にgvisorという名前のRuntimeClassを作成する。kubectl get runtimeclass gvisorで存在を確認する
+          
    4. 
+          
  4. 
+            Podスペックでサンドボックスを指定する:隔離したいPodのマニフェストにruntimeClassName: gvisorを追加する
+          
    5. 
+          
  5. 
+            リソース上限を必ず設定する:GKE
+            Sandboxを使う場合でも、すべてのコンテナにリソース制限(CPU/メモリ)を指定し、不良コードや悪意あるアプリケーションがノードのリソースを枯渇させないようにする
+          
    6. 
+          
  6. 
+            GPU/TPUワークロードでの注意点:GKE
+            SandboxはNVIDIAドライバの脆弱性すべてを緩和するわけではないが、Linuxカーネルの脆弱性に対する保護は維持される。またGPUタイムシェアリングはGPUが完全に隔離されないため、GKE
+            Sandboxとの併用は非推奨とされている
+          
    7. 
+          
  7. 
+            ログとモニタリングを有効化する:必須ではないが、gVisorのメッセージがログに残るよう、クラスタの機能設定でLogging/Monitoringを有効化することが推奨されている
+          
    8. 
+          
  8. 
+            チェックポイント/リストア機能を活用する:gVisorはコンテナのチェックポイント・リストアに対応しており、ウォームアップ済みサービスのキャッシュ、他マシンでのワークロード再開、実行状態のスナップショット取得、フォレンジック用の状態保存などに活用できる
+          
    9. 
+        

+        

+        

+        
6. 領域④ C/C++のサンドボックス

+        

+          6-1. Sandbox2:プログラム全体・一部を隔離する
+        

+        

+          Sandbox2は、Linux向けのオープンソースC++セキュリティサンドボックスで、Google内のセキュリティチームが開発・保守しています。Linuxのnamespace、リソース制限、そしてseccomp-bpfによるシステムコールフィルタを組み合わせて、プログラム全体、あるいはプログラムの一部分だけを隔離できます。
+        

+        

+          seccomp-bpfは、Secure Computing
+          Mode(seccomp)を拡張したLinuxカーネルの機能です。素のseccompはexit・sigreturn・read・writeの4つしか許可しませんが、seccomp-bpfはBPF(Berkeley
+          Packet
+          Filter)プログラムでシステムコールごとに柔軟な判定ロジックを書けるようにし、許可・ダミー値を返す・プロセス終了・シグナル送出・トレーサーへの通知、といった細かい制御を可能にします。
+        

+        
+flowchart LR
+    Policy["Sandbox Policy<br/>(許可するsyscallを定義)"] --> Executor["Executor<br/>(信頼済みの管理プロセス)"]
+    Executor -->|ポリシーを適用して起動| Sandboxee["Sandboxee<br/>(隔離対象プロセス)"]
+    Sandboxee -->|許可済みsyscallのみ通過| Kernel3["Linuxカーネル"]

+        

+          6-2. Sandboxed API(SAPI):ライブラリ単位でサンドボックス化する
+        

+        

+          Sandbox2をそのまま使う場合、プロジェクトごとにポリシーやプロセス間のデータ交換の仕組みをゼロから設計し直す必要がありました。Sandboxed
+            API(SAPI)はこの負担を解消するために作られたオープンソースプロジェクトで、Sandbox2を基盤にしながら「C/C++のライブラリ単位」でサンドボックス化できるようにします。開発チームのモットーは "Sandbox once, use
+          anywhere"(一度サンドボックス化すれば、どこでも使い回せる)です。
+        

+        
+flowchart LR
+    HostCode["ホストコード<br/>(信頼済みプログラム本体)"] --> SapiObject["SAPI Object"]
+    SapiObject -->|RPC呼び出し| RpcStub["RPC Stub"]
+    RpcStub --> SandboxedLib["サンドボックス化された<br/>C/C++ライブラリ(Sandbox2内)"]

+        

+          SAPIライブラリはそれぞれ、必要最小限のシステムコール/リソースだけを許可するタイトなセキュリティポリシーを個別に持てる点が、プロジェクト全体で1つの巨大なポリシーを共有する従来型のサンドボックス設計との大きな違いです。
+        

+        

+          6-3. ステップバイステップ:zlibをSAPIでサンドボックス化する例
+        

+        
公式のGetting Startedガイドで紹介されている典型的な流れは次のとおりです。

+        
    
+          
  1. 
+            サンドボックス化したいライブラリの関数を洗い出す:今回の例ではzlibのdeflate()など、実際に使う関数だけを対象にする
+          
    2. 
+          
  2. 
+            アンサンドボックス版のホストコードをまず動かす:最初はライブラリを直接呼び出す通常のプログラムとして実装し、動作を確認する
+          
    3. 
+          
  3. 
+            sapi_libraryビルドルールを定義する:Bazel/CMakeのビルドルールでSAPIライブラリを生成する
+          
    4. 
+          
  4. 
+            SAPI ObjectとRPC Stubの自動生成を確認する:ビルドプロセス中にSAPIが自動生成するため、開発者がRPCの配線を手書きする必要はない
+          
    5. 
+          
  5. 
+            ホストコードをSAPI呼び出しに置き換える:sapi::Sandboxでサンドボックスオブジェクトを作成し、生成されたAPIクラス経由で関数を呼び出すようにホストコードを書き換える
+          
    6. 
+          
  6. 
+            必要に応じて専用のsandbox policyを書く:デフォルトポリシーで足りない場合は、sandbox.hヘッダーファイルに許可するシステムコール・ファイルアクセス範囲を定義し、sapi_libraryルールに渡す
+          
    7. 
+          
  7. 
+            Transactionsモジュールで監視・自動再起動を設定する:セキュリティ違反・クラッシュ・リソース枯渇でライブラリが落ちた場合に自動的に再起動する高レベルAPIも用意されている
+          
    8. 
+        

+        
6-4. C/C++領域における他の選択肢比較

+        

+          Google Developersの公式ページでは、用途別に複数のサンドボックス技術が一覧化されています。
+        

+        

+          
+            
+              
+                
+                
+                
+              
+            
+            
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+            
+          
製品概要主な用途
Sandbox2
+                  namespace・リソース制限・seccomp-bpfを用いたLinuxサンドボックス。SAPIの基盤技術
+                汎用サンドボックス
gVisor
+                  システムコールをアプリケーションカーネルとして実装。ptraceまたはハードウェア仮想化でインターセプト
+                汎用サンドボックス
Bubblewrapuser namespaceのサブセットで実装。Flatpakの実行エンジンとしても利用CLIツール
MinijailChromeOS/Androidで使われるサンドボックス・封じ込めツールCLIツール
NSJail
+                  namespace・リソース制限・seccomp-bpfによるプロセス隔離。独自DSLのKafelにも対応
+                CLIツール
Sandboxed API (SAPI)Sandbox2を使ったC/C++ライブラリの再利用可能なサンドボックスC/C++コード
Native Client(NaCl)
+                  非推奨。x86/LLVMバイトコードの制限されたサブセットにコンパイルして隔離。後継のWebAssembly設計に影響を与えた
+                C/C++コード(廃止)
WebAssembly (WASM)移植可能なバイナリフォーマット。隔離された実行環境でモジュールを実行C/C++コード
RLBox
+                  C++17で書かれたサンドボックスAPI。NaCl・WASM・リモートプロセスなど複数の実行バックエンドを選択可能
+                C/C++コード
Flatpak
+                  Bubblewrapを土台にしたLinuxデスクトップアプリ向けサンドボックス。パッケージング・配布に重点
+                デスクトップアプリ

+        

+        

+        

+        
7. 領域⑤ ブラウザのサンドボックス

+        

+          7-1. Chromeのマルチプロセスアーキテクチャ
+        

+        

+          Chromeのセキュリティ設計の中核は「サンドボックス化されたマルチプロセスアーキテクチャ」です。DOMのレンダリング・スクリプト実行・メディアデコードなど、Web由来の攻撃対象領域の大部分は、権限を持たない「レンダラープロセス」に閉じ込められます。唯一「ブラウザプロセス」だけが、ファイルシステムやネットワークに直接アクセスできる無サンドボックスの特権プロセスとして動作します。
+        

+        
+flowchart TB
+    Browser["ブラウザプロセス<br/>(無サンドボックス・特権)"]
+    Browser --> RendererA["レンダラープロセスA<br/>(サイトA専用・サンドボックス化)"]
+    Browser --> RendererB["レンダラープロセスB<br/>(サイトB専用・サンドボックス化)"]
+    Browser --> GPU["GPUプロセス<br/>(サンドボックス化)"]
+    Browser --> Network["ネットワークプロセス"]
+    RendererA -.->|IPC経由のみ| Browser
+    RendererB -.->|IPC経由のみ| Browser

+        

+          7-2. Site Isolation:サイトをまたいだデータ漏洩を防ぐ
+        

+        

+          Chrome 67(デスクトップ、全サイト対象)およびChrome
+          77(Android、ログイン済みサイト対象)からデフォルトで有効化されているのがSite Isolationです。目的は「1つのレンダラープロセスには、最大でも1つのWebサイト由来のページしか含めない」ことを保証し、レンダラープロセスに脆弱性があっても、他サイトのCookieやデータへのアクセスを遮断することにあります。ブラウザプロセスは、どのサイトが専用プロセスを必要とするかに基づいて、各レンダラープロセスのCookieや他リソースへのアクセスを制限します。
+        

+        

+          7-3. V8 Sandbox:JavaScriptエンジン自体を隔離する
+        

+        

+          Site Isolationがプロセス間の隔離だとすれば、V8 Sandboxはプロセス内の隔離です。V8のセキュリティ技術リードであるSamuel
+          Groß氏によれば、今日発見・悪用されるV8の脆弱性のほぼすべてに共通するのは、「コンパイラとランタイムがほぼ例外なくV8のHeapObjectインスタンスだけを操作するため、最終的なメモリ破壊が必ずV8ヒープの内部で発生する」という点です。
+        

+        

+          V8
+          Sandboxは、V8が実行するコードを、プロセスの仮想アドレス空間の一部(=サンドボックス、64bit環境で最大1TB分を予約)に限定し、それ以外のメモリ領域からは切り離します。サンドボックス外のメモリにアクセスできるすべてのデータ型を「サンドボックス互換」の代替型に置き換えることで、たとえV8内でメモリ破壊が起きても、サンドボックスの外側には影響が及ばない設計です。Chrome
+          123から、Android・ChromeOS・Linux・macOS・Windowsの全プラットフォームでデフォルト有効化されており、SpeedometerやJetStreamのベンチマークでは、性能オーバーヘッドは約1%に抑えられています。
+        

+        
+flowchart LR
+    JS["JavaScript / WebAssembly<br/>コード"] --> V8Heap["V8ヒープ<br/>(サンドボックス化されたメモリ領域)"]
+    V8Heap -->|メモリ破壊が発生しても脱出不可| Boundary["サンドボックス境界"]
+    Boundary -.->|通常はアクセス不可| ProcessMemory["レンダラープロセスの<br/>その他のメモリ"]

+        

+          7-4. Chrome拡張機能開発者向け:sandboxディレクティブのベストプラクティス
+        

+        

+          ブラウザ本体だけでなく、拡張機能を開発する側にもGoogleが公式に推奨するサンドボックス機構があります。Manifest
+          V3のsandboxプロパティを使うと、拡張機能内の特定のページを「一意のオリジンを持つサンドボックス」として動作させられます。
+        

+        
    
+          
  1. 
+            evalやインラインスクリプトが必要なページだけをsandbox指定する:サンドボックス化されたページは拡張機能全体のCSP(コンテンツセキュリティポリシー)の対象外になり、独自のCSPを持てるため、eval()やインラインスクリプトの実行が可能になる
+          
    2. 
+          
  2. 
+            拡張機能APIへの直接アクセスはできない前提で設計する:サンドボックス化ページは拡張機能API・非サンドボックスページへの直接アクセスができず、postMessage()経由でのみ通信できる
+          
    3. 
+          
  3. 
+            CSPを絞り込む場合はsandboxディレクティブを外さない:デフォルトのCSP値はsandbox allow-scripts allow-forms allow-popups allow-modals; script-src 'self'
+              'unsafe-inline' 'unsafe-eval'; child-src 'self';。これをより厳しく絞り込むことは可能だが、sandboxディレクティブ自体は必須で、allow-same-originトークンは指定できない
+          
    4. 
+          
  4. 
+            外部Webコンテンツの読み込みは避ける:Chrome
+            57以降、サンドボックス化ページの中に外部Webコンテンツ(埋め込みフレーム・スクリプトを含む)を読み込むことはできない。外部コンテンツが必要な場合はwebviewを使う
+          
    5. 
+          
  5. 
+            通常の拡張機能ページのCSPも最小権限に保つ:通常のページ(extension_pages)側では、Chromeが強制する最小CSP(script-src 'self' 'wasm-unsafe-eval'; object-src 'self';)より緩和することはできない仕様になっている
+          
    6. 
+        

+        

+        

+        

+          8. 意思決定フロー:自分のケースにはどのサンドボックス技術を選ぶべきか
+        

+        

+          ここまでの5領域を踏まえて、「自分は何を隔離したいのか」から逆引きできる意思決定フローにまとめました。
+        

+        
+flowchart TD
+    Start["何を隔離したいか?"] --> Q1{"AIエージェントが<br/>生成したコードを実行する"}
+    Q1 -->|はい| A1["GKE Agent Sandbox<br/>または Gemini Code Execution"]
+    Q1 -->|いいえ| Q2{"C/C++のライブラリや<br/>バイナリを隔離したい"}
+    Q2 -->|はい| A2["Sandbox2 / Sandboxed API (SAPI)"]
+    Q2 -->|いいえ| Q3{"コンテナ全体を<br/>カーネルから隔離したい"}
+    Q3 -->|はい| A3["gVisor / GKE Sandbox"]
+    Q3 -->|いいえ| Q4{"ブラウザや拡張機能の<br/>コンテンツを隔離したい"}
+    Q4 -->|はい| A4["Site Isolation / V8 Sandbox<br/>/ 拡張機能sandboxディレクティブ"]
+    Q4 -->|いいえ| A5["Apigee等でAPIレイヤーを保護"]

+        

+        

+        
9. 横断ベストプラクティス早見表

+        
5つの領域を貫く共通原則を、実務でチェックリストとして使える形にまとめました。

+        

+          
+            
+              
+                
+                
+                
+                
+                
+                
+              
+            
+            
+              
+                
+                
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+                
+                
+              
+            
+          
原則AIエージェントAPIコンテナC/C++ブラウザ
最小権限Workload Identity Federationで使い捨てIAMRBAC・OAuthスコープの絞り込みサンドボックス化ノードプールの分離ポリシーで許可syscallを最小化拡張機能CSPを最小権限に
デフォルト拒否ネットワークポリシーで通信先を許可リスト化Cloud Armorでの地理/IP制御GPUタイムシェアリングを避ける等の制約順守seccomp-bpfでsyscallをデフォルト拒否サンドボックス化ページにallow-same-originを付けない
多層防御gVisor+ID+ネットワークを重ねても過信しないトラフィック管理+メッセージ保護+セキュリティポリシーVMM境界+コンテナ境界+seccompnamespace+リソース制限+seccomp-bpfマルチプロセス+Site Isolation+V8 Sandbox
状態管理/リソース制御Pod Snapshotsでウォーム/コールドプール環境ごとにデプロイ数を制限全コンテナにリソース上限を設定Transactionsで異常時に自動再起動プロセスクラッシュ時も他タブは継続動作
監視・可観測性トレーシングでツール呼び出しを可視化Advanced API Securityでクライアント挙動を分析gVisorログのLogging/Monitoring連携セキュリティ違反のログ記録サンドボックス違反の検知

+        

+        

+        

+        
10. 参考文献・出典URL

+        

+          本ガイドの作成にあたり、以下のGoogle公式ドキュメント・Google公式ブログ・著名なセキュリティエンジニア/開発者による技術記事を参照しました。
+        

+        

+          

+            
Google公式:サンドボックス技術全般

+            
+          

+          

+            
① AIエージェント

+            
+          

+          

+            
② API

+            
+          

+          

+            
③ コンテナ

+            
+          

+          

+            
④ C/C++

+            
+          

+          

+            
⑤ ブラウザ

+            
+          

+        

+
+        

+        

+          

+            免責事項:本ガイドは2026年7月27日時点で確認できた公開情報に基づいています。GKE Agent
+            SandboxやGemini Enterprise Agent
+            Platform関連の一部機能はPre-GA(プレビュー)段階の製品を含むため、実際の導入前には必ずGoogle
+            Cloud公式ドキュメントの最新版を確認してください。
+          

+        

+      

+    

+
+    
+  
+
diff --git a/Google-sandbox-best-practices.md b/Google-sandbox-best-practices.md
new file mode 100644
index 00000000..0a63f8b2
--- /dev/null
+++ b/Google-sandbox-best-practices.md
@@ -0,0 +1,374 @@
+# Google サンドボックス技術 完全ガイド
+## AIエージェント・API・コンテナ・C/C++・ブラウザ、5領域のベストプラクティスをステップバイステップで理解する
+
+> 対象読者:サンドボックス技術の初学者〜中級エンジニア
+> 情報基準日:2026年7月27日時点(以降の変更は各社公式ドキュメントで要確認)
+
+---
+
+## 目次
+
+1. [はじめに:なぜ「サンドボックス」が必要なのか](#section-1)
+2. [全体マップ:Googleの5つのサンドボックス領域](#section-2)
+3. [領域① AIエージェントのサンドボックス](#section-3)
+4. [領域② APIのサンドボックス](#section-4)
+5. [領域③ コンテナのサンドボックス](#section-5)
+6. [領域④ C/C++のサンドボックス](#section-6)
+7. [領域⑤ ブラウザのサンドボックス](#section-7)
+8. [意思決定フロー:自分のケースにはどれを選ぶべきか](#section-8)
+9. [横断ベストプラクティス早見表](#section-9)
+10. [参考文献・出典URL](#section-10)
+
+---
+
+
+## 1. はじめに:なぜ「サンドボックス」が必要なのか
+
+「サンドボックス(sandbox)」とは、信頼できないコードやデータを、ホストシステム(OS本体・他のプロセス・他の顧客のデータなど)から隔離された領域の中だけで実行させるための仕組みです。子どもが砂場の外に砂をこぼさないのと同じように、「万が一そのコードが悪意を持っていたり、バグを含んでいたりしても、被害が砂場の外に漏れない」ことを保証するのが目的です。
+
+Googleがサンドボックスを重視する背景には、次の3つの共通した脅威があります。
+
+- **信頼できない入力の実行**:AIエージェントが生成したコード、ユーザーがアップロードしたファイル、サードパーティのライブラリなど、開発者自身がレビューしきれないコードを動かす機会が増え続けている
+- **マルチテナンシー**:クラウド上では複数の顧客・複数のワークロードが同じ物理ハードウェアを共有するため、1つのワークロードの侵害が他のワークロードに波及してはならない
+- **メモリ安全性が保証できない領域の存在**:C/C++やJavaScriptエンジンのように、言語仕様上メモリ安全性を完全には保証できない領域が、今なお本番システムの中核に存在する
+
+Googleはこの課題に対して、単一の万能な解決策ではなく、**隔離したい対象のレイヤーごとに専用のサンドボックス技術を使い分ける**という設計思想を取っています。本ガイドでは、その中でも特に問い合わせの多い次の5領域を、ステップバイステップのベストプラクティスとして整理します。
+
+---
+
+
+## 2. 全体マップ:Googleの5つのサンドボックス領域
+
+```mermaid
+flowchart TB
+    A["Google のサンドボックス戦略
(隔離レイヤーごとの使い分け)"]
+    A --> B["① AIエージェント"]
+    A --> C["② API"]
+    A --> D["③ コンテナ"]
+    A --> E["④ C / C++"]
+    A --> F["⑤ ブラウザ"]
+
+    B --> B1["GKE Agent Sandbox (gVisor)"]
+    B --> B2["Gemini Code Execution"]
+
+    C --> C1["Apigee サンドボックス環境"]
+    C --> C2["Cloud Armor / WAAP"]
+
+    D --> D1["GKE Sandbox (gVisor)"]
+    D --> D2["Cloud Run / App Engine / Functions"]
+
+    E --> E1["Sandbox2"]
+    E --> E2["Sandboxed API (SAPI)"]
+
+    F --> F1["マルチプロセス + Site Isolation"]
+    F --> F2["V8 Sandbox"]
+```
+
+この図からもわかるとおり、5つの領域の多くが「gVisor」という同一のオープンソース技術を土台にしていることが特徴です。gVisorはGoogle社内で長年本番ワークロードの隔離に使われてきた実績をもとにオープンソース化された、ユーザー空間でLinuxカーネルAPIを再実装する「アプリケーションカーネル」です。まずこの共通基盤を理解しておくと、以降の各領域の理解が格段に速くなります。
+
+---
+
+
+## 3. 領域① AIエージェントのサンドボックス
+
+### 3-1. なぜAIエージェント専用の隔離が必要か
+
+AIエージェントは、LLMが生成した非決定的なコードをその場で実行したり、外部ツールを自律的に呼び出したりします。これは「常に信頼できない入力を、常に本番同然の権限で実行し続ける」ことに等しく、通常のアプリケーションよりもはるかに広い攻撃対象領域を生み出します。GoogleはこれをGKE(Google Kubernetes Engine)向けの**Agent Sandbox**と、Gemini APIやAgent Platform向けの**Code Execution**という2つの製品ラインで解決しています。
+
+### 3-2. GKE Agent Sandbox:アーキテクチャ
+
+GKE Agent Sandboxは、Kubernetes SIG Apps配下でオープンソース開発されているKubernetesネイティブな拡張機能です。gVisorによるカーネルレベルの隔離を、`Sandbox`・`SandboxTemplate`・`SandboxClaim`という3つの新しいKubernetesカスタムリソースを通じて提供します。
+
+gVisorの内部は「Sentry」と「Gofer」という2つのコンポーネントで構成されます。
+
+```mermaid
+flowchart LR
+    App["エージェントが生成した
コード / プロセス"] --> Sentry["gVisor Sentry
(ユーザー空間の疑似カーネル)"]
+    Sentry --> Gofer["gVisor Gofer
(ファイルI/Oプロキシ)"]
+    Gofer --> Kernel["ホストのLinuxカーネル"]
+    Sentry -.->|直接到達は不可| Kernel
+```
+
+Sentryはエージェントが発行するすべてのシステムコール(`exec`や`socket`など)を横取りし、ホストカーネルに直接触れさせない「偽のカーネル」として振る舞います。ファイルシステム操作だけは別プロセスのGoferが仲介するため、たとえSentryに未知の脆弱性があっても、ファイルシステムへの被害範囲を最小化できます。
+
+### 3-3. ステップバイステップ:導入のベストプラクティス
+
+1. **隔離(ISOLATE)**:非決定的なエージェントのコード・ツール実行・ユーザー入力処理はすべてGKE Agent Sandbox(gVisor)上で実行し、RCE(リモートコード実行)攻撃をサンドボックス内に封じ込める
+2. **高速化(ACCELERATE)**:サンドボックスの起動レイテンシを隠すため、事前にプロビジョニングされた「ウォームプール」を用意する。さらにコスト削減のため、アイドル状態のエージェントは「コールドプール(サスペンド状態のVM)」に退避させ、Pod Snapshotsで低コストに復元する
+3. **権限の制限(RESTRICT・ID)**:Workload Identity Federationを使い、エージェントごとに使い捨ての最小権限IAMアイデンティティを付与する
+4. **通信の制限(RESTRICT・Network)**:デフォルト拒否(default-deny)のKubernetes NetworkPolicyを設定し、エージェントが必要とするDNS・メタデータ・APIエンドポイントだけを明示的に許可リスト化する
+5. **多層防御を過信しない**:gVisor・Workload Identity・VPC Service Controlsをすべて設定しても、それらは「許可されたチャネルの中で行われる正規の操作」しか防げない。プロンプトインジェクションによって、許可済みのAPI呼び出し経由でデータが持ち出されるリスクは別途モニタリングで検知する必要がある、と複数のセキュリティ研究者が指摘している
+
+### 3-4. Gemini API / Agent Platform の Code Execution
+
+GKE以外にも、Gemini APIおよびGemini Enterprise Agent Platformが提供する**Code Execution**ツールを使えば、GKEにデプロイしなくてもマネージドなサンドボックスでPythonコードを実行できます。特徴は次のとおりです。
+
+| 特徴 | 内容 |
+|---|---|
+| 起動速度 | 1秒未満でサンドボックスを作成・実行可能 |
+| ファイル入出力 | リクエスト/レスポンス全体で最大100MBまで対応 |
+| 状態保持 | 実行状態(メモリ)を最大14日間保持(TTLで調整可能) |
+| デフォルトのネットワーク | 無効(明示的な許可リストを設定しない限りアウトバウンド通信不可) |
+| 対応フレームワーク | 特定のフレームワークに依存せず、任意のエージェント実装・任意のモデルから利用可能 |
+
+Agent Development Kit(ADK)の公式安全設計ドキュメントでも、「コード実行は特にセキュリティ上の影響が大きい特殊なツールであり、モデルが生成したコードがローカル環境を侵害しないよう、必ずサンドボックス化しなければならない」と明記されています。あわせてModel ArmorプラグインやPII redactionプラグインといった、入出力を検査する追加のガードレールも推奨されています。
+
+---
+
+
+## 4. 領域② APIのサンドボックス
+
+### 4-1. Apigeeにおける「サンドボックス環境」の考え方
+
+API領域での「サンドボックス」は、これまでの実行時隔離とは意味合いが少し異なります。Apigee(Googleのネイティブなフルライフサイクル API管理製品)における「環境(environment)」は、**APIプロキシを実行するための隔離されたコンテキスト**を指し、公式ドキュメントでも「サンドボックス」と表現されています。1つの組織の中に複数の環境(開発用・テスト用・本番用など)を作成し、プロキシのデプロイ先を環境ごとに分離するのが基本設計です。
+
+```mermaid
+flowchart LR
+    Client["クライアント"] --> GFE["Google Front End
(TLS終端)"]
+    GFE --> Proxy["Apigee APIプロキシ
(環境=サンドボックス)"]
+    Proxy --> Policy1["トラフィック管理
ポリシー"]
+    Proxy --> Policy2["メッセージレベル
保護ポリシー"]
+    Proxy --> Policy3["セキュリティポリシー
(RBAC / OAuth等)"]
+    Proxy --> Backend["バックエンドサービス"]
+```
+
+### 4-2. ステップバイステップ:APIサンドボックスのベストプラクティス
+
+1. **環境を目的別に分離する**:hybrid構成では、1つの環境に大量のプロキシを詰め込まず、複数の環境を作り、環境ごとにデプロイするプロキシ数を絞ることが推奨されている
+2. **デフォルトポリシーを有効化する**:Apigeeが提供する3種類の既定ポリシー(トラフィック管理・メッセージレベル保護・セキュリティ)をプロキシ層にアタッチする
+3. **IPアドレス/地理情報によるアクセス制御にはCloud Armorを使う**:Apigee自体のポリシーだけでなく、Cloud Armorと組み合わせたWAAP(Web App and API Protection)構成が推奨されている
+4. **クライアントIP解決を環境ごとにカスタマイズする**:プロキシ経由のリクエストでは`X-Forwarded-For`ヘッダーの保持設定が必要になるケースがあり、デフォルトのIP解決アルゴリズムが合わない場合は環境単位でカスタマイズできる
+5. **開発者向けサンドボックスは60日間の無償トライアルで検証する**:本番導入前に、Apigeeの試用サンドボックス環境でAPI設計を検証してから、本番の環境構成に反映するワークフローが一般的
+6. **モックとの併用(一般的なAPIサンドボックス設計のベストプラクティス)**:OpenAPI仕様からモックエンドポイントを自動生成できるAPI管理プラットフォームの機能を活用し、モックとAPI仕様を常に同期させ、成功シナリオだけでなくエラーシナリオも用意し、CI/CDパイプラインに組み込むことが、業界全体のAPIサンドボックス運用における共通ベストプラクティスとして紹介されている
+
+---
+
+
+## 5. 領域③ コンテナのサンドボックス
+
+### 5-1. gVisorの基本アーキテクチャ(再掲・詳細版)
+
+コンテナ領域におけるGoogleの主力技術は、AIエージェント領域でも登場した**gVisor**そのものです。通常のコンテナはホストカーネルを直接共有するため、1つのコンテナ内のカーネル脆弱性が、ノード全体・他の全コンテナに波及するリスクを抱えます。gVisorは、コンテナが発行するシステムコールをユーザー空間の「Sentry」で受け止め、seccomp-bpfによるシステムコールフィルタリングでさらに一段階の防御を重ねます。
+
+```mermaid
+flowchart LR
+    Container["コンテナ内アプリケーション"] --> Sentry2["gVisor Sentry
(ユーザー空間カーネル)"]
+    Sentry2 --> Seccomp["seccomp-bpf
システムコールフィルタ"]
+    Seccomp --> HostKernel["ホストのLinuxカーネル"]
+```
+
+Googleのサーバーレス製品群(App Engine、Cloud Run、Cloud Functions)はいずれも、アプリケーションワークロードの隔離にgVisorを採用しています。Cloud Runの場合、各インスタンスは仮想マシンモニター(VMM)によって他のインスタンスから隔離され、さらにコンテナ境界の強制とseccompによるシステムコールフィルタリングが重ねられる多層防御構成になっています。
+
+### 5-2. ステップバイステップ:GKE Sandboxの有効化手順
+
+1. **専用ノードプールを作成する**:GKE SandboxはデフォルトのノードプールにはEnableできない。Standardクラスタでは、すべてのワークロードをサンドボックス化する場合でも、GKE Sandboxを有効化していないノードプールを最低1つ残す必要がある
+2. **イメージタイプを揃える**:ノードプールのイメージタイプは「Container-Optimized OS with Containerd(`cos_containerd`)」のみがサポート対象
+3. **RuntimeClassを確認する**:ノードプール作成後、GKEが自動的に`gvisor`という名前のRuntimeClassを作成する。`kubectl get runtimeclass gvisor`で存在を確認する
+4. **Podスペックでサンドボックスを指定する**:隔離したいPodのマニフェストに`runtimeClassName: gvisor`を追加する
+5. **リソース上限を必ず設定する**:GKE Sandboxを使う場合でも、すべてのコンテナにリソース制限(CPU/メモリ)を指定し、不良コードや悪意あるアプリケーションがノードのリソースを枯渇させないようにする
+6. **GPU/TPUワークロードでの注意点**:GKE SandboxはNVIDIAドライバの脆弱性すべてを緩和するわけではないが、Linuxカーネルの脆弱性に対する保護は維持される。またGPUタイムシェアリングはGPUが完全に隔離されないため、GKE Sandboxとの併用は非推奨とされている
+7. **ログとモニタリングを有効化する**:必須ではないが、gVisorのメッセージがログに残るよう、クラスタの機能設定でLogging/Monitoringを有効化することが推奨されている
+8. **チェックポイント/リストア機能を活用する**:gVisorはコンテナのチェックポイント・リストアに対応しており、ウォームアップ済みサービスのキャッシュ、他マシンでのワークロード再開、実行状態のスナップショット取得、フォレンジック用の状態保存などに活用できる
+
+---
+
+
+## 6. 領域④ C/C++のサンドボックス
+
+### 6-1. Sandbox2:プログラム全体・一部を隔離する
+
+**Sandbox2**は、Linux向けのオープンソースC++セキュリティサンドボックスで、Google内のセキュリティチームが開発・保守しています。Linuxのnamespace、リソース制限、そしてseccomp-bpfによるシステムコールフィルタを組み合わせて、プログラム全体、あるいはプログラムの一部分だけを隔離できます。
+
+seccomp-bpfは、Secure Computing Mode(seccomp)を拡張したLinuxカーネルの機能です。素のseccompは`exit`・`sigreturn`・`read`・`write`の4つしか許可しませんが、seccomp-bpfはBPF(Berkeley Packet Filter)プログラムでシステムコールごとに柔軟な判定ロジックを書けるようにし、許可・ダミー値を返す・プロセス終了・シグナル送出・トレーサーへの通知、といった細かい制御を可能にします。
+
+```mermaid
+flowchart LR
+    Policy["Sandbox Policy
(許可するsyscallを定義)"] --> Executor["Executor
(信頼済みの管理プロセス)"]
+    Executor -->|ポリシーを適用して起動| Sandboxee["Sandboxee
(隔離対象プロセス)"]
+    Sandboxee -->|許可済みsyscallのみ通過| Kernel3["Linuxカーネル"]
+```
+
+### 6-2. Sandboxed API(SAPI):ライブラリ単位でサンドボックス化する
+
+Sandbox2をそのまま使う場合、プロジェクトごとにポリシーやプロセス間のデータ交換の仕組みをゼロから設計し直す必要がありました。**Sandboxed API(SAPI)**はこの負担を解消するために作られたオープンソースプロジェクトで、Sandbox2を基盤にしながら「C/C++の**ライブラリ単位**」でサンドボックス化できるようにします。開発チームのモットーは "Sandbox once, use anywhere"(一度サンドボックス化すれば、どこでも使い回せる)です。
+
+```mermaid
+flowchart LR
+    HostCode["ホストコード
(信頼済みプログラム本体)"] --> SapiObject["SAPI Object"]
+    SapiObject -->|RPC呼び出し| RpcStub["RPC Stub"]
+    RpcStub --> SandboxedLib["サンドボックス化された
C/C++ライブラリ(Sandbox2内)"]
+```
+
+SAPIライブラリはそれぞれ、必要最小限のシステムコール/リソースだけを許可するタイトなセキュリティポリシーを個別に持てる点が、プロジェクト全体で1つの巨大なポリシーを共有する従来型のサンドボックス設計との大きな違いです。
+
+### 6-3. ステップバイステップ:zlibをSAPIでサンドボックス化する例
+
+公式のGetting Startedガイドで紹介されている典型的な流れは次のとおりです。
+
+1. **サンドボックス化したいライブラリの関数を洗い出す**:今回の例ではzlibの`deflate()`など、実際に使う関数だけを対象にする
+2. **アンサンドボックス版のホストコードをまず動かす**:最初はライブラリを直接呼び出す通常のプログラムとして実装し、動作を確認する
+3. **`sapi_library`ビルドルールを定義する**:Bazel/CMakeのビルドルールでSAPIライブラリを生成する
+4. **SAPI ObjectとRPC Stubの自動生成を確認する**:ビルドプロセス中にSAPIが自動生成するため、開発者がRPCの配線を手書きする必要はない
+5. **ホストコードをSAPI呼び出しに置き換える**:`sapi::Sandbox`でサンドボックスオブジェクトを作成し、生成されたAPIクラス経由で関数を呼び出すようにホストコードを書き換える
+6. **必要に応じて専用のsandbox policyを書く**:デフォルトポリシーで足りない場合は、`sandbox.h`ヘッダーファイルに許可するシステムコール・ファイルアクセス範囲を定義し、`sapi_library`ルールに渡す
+7. **Transactionsモジュールで監視・自動再起動を設定する**:セキュリティ違反・クラッシュ・リソース枯渇でライブラリが落ちた場合に自動的に再起動する高レベルAPIも用意されている
+
+### 6-4. C/C++領域における他の選択肢比較
+
+Google Developersの公式ページでは、用途別に複数のサンドボックス技術が一覧化されています。
+
+| 製品 | 概要 | 主な用途 |
+|---|---|---|
+| Sandbox2 | namespace・リソース制限・seccomp-bpfを用いたLinuxサンドボックス。SAPIの基盤技術 | 汎用サンドボックス |
+| gVisor | システムコールをアプリケーションカーネルとして実装。ptraceまたはハードウェア仮想化でインターセプト | 汎用サンドボックス |
+| Bubblewrap | user namespaceのサブセットで実装。Flatpakの実行エンジンとしても利用 | CLIツール |
+| Minijail | ChromeOS/Androidで使われるサンドボックス・封じ込めツール | CLIツール |
+| NSJail | namespace・リソース制限・seccomp-bpfによるプロセス隔離。独自DSLのKafelにも対応 | CLIツール |
+| Sandboxed API (SAPI) | Sandbox2を使ったC/C++ライブラリの再利用可能なサンドボックス | C/C++コード |
+| Native Client(NaCl) | **非推奨**。x86/LLVMバイトコードの制限されたサブセットにコンパイルして隔離。後継のWebAssembly設計に影響を与えた | C/C++コード(廃止) |
+| WebAssembly (WASM) | 移植可能なバイナリフォーマット。隔離された実行環境でモジュールを実行 | C/C++コード |
+| RLBox | C++17で書かれたサンドボックスAPI。NaCl・WASM・リモートプロセスなど複数の実行バックエンドを選択可能 | C/C++コード |
+| Flatpak | Bubblewrapを土台にしたLinuxデスクトップアプリ向けサンドボックス。パッケージング・配布に重点 | デスクトップアプリ |
+
+---
+
+
+## 7. 領域⑤ ブラウザのサンドボックス
+
+### 7-1. Chromeのマルチプロセスアーキテクチャ
+
+Chromeのセキュリティ設計の中核は「サンドボックス化されたマルチプロセスアーキテクチャ」です。DOMのレンダリング・スクリプト実行・メディアデコードなど、Web由来の攻撃対象領域の大部分は、権限を持たない「レンダラープロセス」に閉じ込められます。唯一「ブラウザプロセス」だけが、ファイルシステムやネットワークに直接アクセスできる無サンドボックスの特権プロセスとして動作します。
+
+```mermaid
+flowchart TB
+    Browser["ブラウザプロセス
(無サンドボックス・特権)"]
+    Browser --> RendererA["レンダラープロセスA
(サイトA専用・サンドボックス化)"]
+    Browser --> RendererB["レンダラープロセスB
(サイトB専用・サンドボックス化)"]
+    Browser --> GPU["GPUプロセス
(サンドボックス化)"]
+    Browser --> Network["ネットワークプロセス"]
+    RendererA -.->|IPC経由のみ| Browser
+    RendererB -.->|IPC経由のみ| Browser
+```
+
+### 7-2. Site Isolation:サイトをまたいだデータ漏洩を防ぐ
+
+Chrome 67(デスクトップ、全サイト対象)およびChrome 77(Android、ログイン済みサイト対象)からデフォルトで有効化されているのが**Site Isolation**です。目的は「1つのレンダラープロセスには、最大でも1つのWebサイト由来のページしか含めない」ことを保証し、レンダラープロセスに脆弱性があっても、他サイトのCookieやデータへのアクセスを遮断することにあります。ブラウザプロセスは、どのサイトが専用プロセスを必要とするかに基づいて、各レンダラープロセスのCookieや他リソースへのアクセスを制限します。
+
+### 7-3. V8 Sandbox:JavaScriptエンジン自体を隔離する
+
+Site Isolationがプロセス間の隔離だとすれば、**V8 Sandbox**はプロセス**内**の隔離です。V8のセキュリティ技術リードであるSamuel Groß氏によれば、今日発見・悪用されるV8の脆弱性のほぼすべてに共通するのは、「コンパイラとランタイムがほぼ例外なくV8のHeapObjectインスタンスだけを操作するため、最終的なメモリ破壊が必ずV8ヒープの内部で発生する」という点です。
+
+V8 Sandboxは、V8が実行するコードを、プロセスの仮想アドレス空間の一部(=サンドボックス、64bit環境で最大1TB分を予約)に限定し、それ以外のメモリ領域からは切り離します。サンドボックス外のメモリにアクセスできるすべてのデータ型を「サンドボックス互換」の代替型に置き換えることで、たとえV8内でメモリ破壊が起きても、サンドボックスの外側には影響が及ばない設計です。Chrome 123から、Android・ChromeOS・Linux・macOS・Windowsの全プラットフォームでデフォルト有効化されており、SpeedometerやJetStreamのベンチマークでは、性能オーバーヘッドは約1%に抑えられています。
+
+```mermaid
+flowchart LR
+    JS["JavaScript / WebAssembly
コード"] --> V8Heap["V8ヒープ
(サンドボックス化されたメモリ領域)"]
+    V8Heap -->|メモリ破壊が発生しても脱出不可| Boundary["サンドボックス境界"]
+    Boundary -.->|通常はアクセス不可| ProcessMemory["レンダラープロセスの
その他のメモリ"]
+```
+
+### 7-4. Chrome拡張機能開発者向け:sandboxディレクティブのベストプラクティス
+
+ブラウザ本体だけでなく、拡張機能を開発する側にもGoogleが公式に推奨するサンドボックス機構があります。Manifest V3の`sandbox`プロパティを使うと、拡張機能内の特定のページを「一意のオリジンを持つサンドボックス」として動作させられます。
+
+1. **`eval`やインラインスクリプトが必要なページだけをsandbox指定する**:サンドボックス化されたページは拡張機能全体のCSP(コンテンツセキュリティポリシー)の対象外になり、独自のCSPを持てるため、`eval()`やインラインスクリプトの実行が可能になる
+2. **拡張機能APIへの直接アクセスはできない前提で設計する**:サンドボックス化ページは拡張機能API・非サンドボックスページへの直接アクセスができず、`postMessage()`経由でのみ通信できる
+3. **CSPを絞り込む場合は`sandbox`ディレクティブを外さない**:デフォルトのCSP値は`sandbox allow-scripts allow-forms allow-popups allow-modals; script-src 'self' 'unsafe-inline' 'unsafe-eval'; child-src 'self';`。これをより厳しく絞り込むことは可能だが、`sandbox`ディレクティブ自体は必須で、`allow-same-origin`トークンは指定できない
+4. **外部Webコンテンツの読み込みは避ける**:Chrome 57以降、サンドボックス化ページの中に外部Webコンテンツ(埋め込みフレーム・スクリプトを含む)を読み込むことはできない。外部コンテンツが必要な場合は`webview`を使う
+5. **通常の拡張機能ページのCSPも最小権限に保つ**:通常のページ(`extension_pages`)側では、Chromeが強制する最小CSP(`script-src 'self' 'wasm-unsafe-eval'; object-src 'self';`)より緩和することはできない仕様になっている
+
+---
+
+
+## 8. 意思決定フロー:自分のケースにはどのサンドボックス技術を選ぶべきか
+
+ここまでの5領域を踏まえて、「自分は何を隔離したいのか」から逆引きできる意思決定フローにまとめました。
+
+```mermaid
+flowchart TD
+    Start["何を隔離したいか?"] --> Q1{"AIエージェントが
生成したコードを実行する"}
+    Q1 -->|はい| A1["GKE Agent Sandbox
または Gemini Code Execution"]
+    Q1 -->|いいえ| Q2{"C/C++のライブラリや
バイナリを隔離したい"}
+    Q2 -->|はい| A2["Sandbox2 / Sandboxed API (SAPI)"]
+    Q2 -->|いいえ| Q3{"コンテナ全体を
カーネルから隔離したい"}
+    Q3 -->|はい| A3["gVisor / GKE Sandbox"]
+    Q3 -->|いいえ| Q4{"ブラウザや拡張機能の
コンテンツを隔離したい"}
+    Q4 -->|はい| A4["Site Isolation / V8 Sandbox
/ 拡張機能sandboxディレクティブ"]
+    Q4 -->|いいえ| A5["Apigee等でAPIレイヤーを保護"]
+```
+
+---
+
+
+## 9. 横断ベストプラクティス早見表
+
+5つの領域を貫く共通原則を、実務でチェックリストとして使える形にまとめました。
+
+| 原則 | AIエージェント | API | コンテナ | C/C++ | ブラウザ |
+|---|---|---|---|---|---|
+| **最小権限** | Workload Identity Federationで使い捨てIAM | RBAC・OAuthスコープの絞り込み | サンドボックス化ノードプールの分離 | ポリシーで許可syscallを最小化 | 拡張機能CSPを最小権限に |
+| **デフォルト拒否** | ネットワークポリシーで通信先を許可リスト化 | Cloud Armorでの地理/IP制御 | GPUタイムシェアリングを避ける等の制約順守 | seccomp-bpfでsyscallをデフォルト拒否 | サンドボックス化ページに`allow-same-origin`を付けない |
+| **多層防御** | gVisor+ID+ネットワークを重ねても過信しない | トラフィック管理+メッセージ保護+セキュリティポリシー | VMM境界+コンテナ境界+seccomp | namespace+リソース制限+seccomp-bpf | マルチプロセス+Site Isolation+V8 Sandbox |
+| **状態管理/リソース制御** | Pod Snapshotsでウォーム/コールドプール | 環境ごとにデプロイ数を制限 | 全コンテナにリソース上限を設定 | Transactionsで異常時に自動再起動 | プロセスクラッシュ時も他タブは継続動作 |
+| **監視・可観測性** | トレーシングでツール呼び出しを可視化 | Advanced API Securityでクライアント挙動を分析 | gVisorログのLogging/Monitoring連携 | セキュリティ違反のログ記録 | サンドボックス違反の検知 |
+
+---
+
+
+## 10. 参考文献・出典URL
+
+本ガイドの作成にあたり、以下のGoogle公式ドキュメント・Google公式ブログ・著名なセキュリティエンジニア/開発者による技術記事を参照しました。
+
+### Google公式:サンドボックス技術全般
+- Code Sandboxing(Google for Developers、Sandbox2/SAPI/gVisor等の比較表): https://developers.google.com/code-sandboxing
+- Sandbox2 Explained: https://developers.google.com/code-sandboxing/sandbox2/explained
+- Sandboxed API (SAPI) 概要: https://developers.google.com/code-sandboxing/sandboxed-api
+- SAPI Explained: https://developers.google.com/code-sandboxing/sandboxed-api/explained
+- SAPI Getting Started: https://developers.google.com/code-sandboxing/sandboxed-api/getting-started
+- google/sandboxed-api (GitHub): https://github.com/google/sandboxed-api
+
+### ① AIエージェント
+- GKE Sandbox(GKEセキュリティ公式ドキュメント): https://docs.cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods
+- Isolate AI code execution with Agent Sandbox: https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox
+- Bringing you Agent Sandbox on GKE and Agent Substrate(Google Cloud Blog): https://cloud.google.com/blog/products/containers-kubernetes/bringing-you-agent-sandbox-on-gke-and-agent-substrate
+- Safety and Security for AI Agents(Agent Development Kit公式): https://google.github.io/adk-docs/safety/
+- Code Execution(Gemini Enterprise Agent Platform公式): https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/code-execution-overview
+- Sandboxes overview(Gemini Enterprise Agent Platform公式): https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox
+- Agents Overview(Gemini API公式): https://ai.google.dev/gemini-api/docs/agents
+- A Deep Dive into GKE Sandbox for Agents(The New Stack、Darryl K. Taft氏): https://thenewstack.io/google-cloud-a-deep-dive-into-gke-sandbox-for-agents/
+- Google Announces GKE Agent Sandbox and Hypercluster at Next '26(InfoQ、Google Cloud AmbassadorのAlex Gkiouros氏の見解を含む): https://www.infoq.com/news/2026/05/gke-agent-sandbox-hypercluster/
+- Securing AI Agents on GKE(ARMO、Shauli Rozen氏): https://www.armosec.io/blog/sandboxing-ai-agents-gke-workload-identity/
+- GKE Agent SandboxとGKE Pod Snapshots(Rahul Ranganathan氏、Google Cloud Community/Medium ― ISOLATE/ACCELERATE/RESTRICTのフレームワークの出典): https://medium.com/google-cloud/gke-agent-sandbox-and-gke-pod-snapshots-zero-trust-security-for-ai-agents-at-scale-559261ee20b5
+- Deploying Secure AI Agents on GKE(Google Codelabs): https://codelabs.developers.google.com/codelabs/gke/ai-agents-on-gke
+
+### ② API
+- Apigee API Management(製品ページ): https://cloud.google.com/apigee
+- Best practices for securing your applications and APIs using Apigee: https://docs.cloud.google.com/architecture/best-practices-securing-applications-and-apis-using-apigee
+- Advanced API Security best practices(Apigee公式): https://docs.cloud.google.com/apigee/docs/api-security/best-practices
+- About environments(Apigee hybrid公式、環境=サンドボックスの定義): https://cloud.google.com/apigee/docs/hybrid/v1.9/environments-about
+- Top Sandbox Development Environment Best Practices Guide(DigitalAPI): https://www.digitalapi.ai/blogs/what-are-the-best-practices-for-managing-a-sandbox-development-environment
+
+### ③ コンテナ
+- GKE Sandbox(概念ドキュメント): https://docs.cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods
+- Harden workload isolation with GKE Sandbox(手順ドキュメント): https://docs.cloud.google.com/kubernetes-engine/docs/how-to/sandbox-pods
+- gVisor公式サイト: https://gvisor.dev/
+- Security design overview(Cloud Run公式): https://docs.cloud.google.com/run/docs/securing/security
+- Improved gVisor file system performance for GKE, Cloud Run, App Engine and Cloud Functions(Google Cloud Blog): https://cloud.google.com/blog/products/containers-kubernetes/gvisor-file-system-improvements-for-gke-and-serverless
+
+### ④ C/C++
+- Sandbox2 Explained: https://developers.google.com/code-sandboxing/sandbox2/explained
+- Sandboxed API README(GitHub): https://github.com/google/sandboxed-api/blob/main/README.md
+
+### ⑤ ブラウザ
+- Site Isolation Design Document(Chromium公式): https://www.chromium.org/developers/design-documents/site-isolation/
+- Secure Architecture(Chromium Security公式): https://www.chromium.org/Home/chromium-security/guts/
+- The V8 Sandbox(V8公式ブログ、Samuel Groß氏): https://v8.dev/blog/sandbox
+- The V8 Heap Sandbox, OffensiveCon 2024講演資料(Samuel Groß氏): https://saelo.github.io/presentations/offensivecon_24_the_v8_heap_sandbox.pdf
+- Google Chrome Adds V8 Sandbox(The Hacker News): https://thehackernews.com/2024/04/google-chrome-adds-v8-sandbox-new.html
+- Manifest - Sandbox(Chrome Extensions公式、Manifest V3): https://developer.chrome.com/docs/extensions/reference/manifest/sandbox
+- Manifest - Content Security Policy(Chrome Extensions公式): https://developer.chrome.com/docs/extensions/reference/manifest/content-security-policy
+- Cleanly Escaping the Chrome Sandbox(Theori Blog): https://theori.io/blog/cleanly-escaping-the-chrome-sandbox
+
+---
+
+> **免責事項**:本ガイドは2026年7月27日時点で確認できた公開情報に基づいています。GKE Agent SandboxやGemini Enterprise Agent Platform関連の一部機能はPre-GA(プレビュー)段階の製品を含むため、実際の導入前には必ずGoogle Cloud公式ドキュメントの最新版を確認してください。
diff --git a/Openai-codex-agents-multiagent-best-practices.md b/Openai-codex-agents-multiagent-best-practices.md
new file mode 100644
index 00000000..2c7bafa9
--- /dev/null
+++ b/Openai-codex-agents-multiagent-best-practices.md
@@ -0,0 +1,367 @@
+# OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド
+
+## AGENTS.md・AGENTS.override.md・SKILL.md・config.toml・requirements.toml で構築するマルチエージェントワークフロー
+
+> 対象読者: Codex CLI / Codex Cloud を使ったチーム開発の経験がある中級〜上級エンジニア
+> 最終更新: 2026年7月29日時点の公式ドキュメント・コミュニティ記事に基づく
+
+---
+
+## この記事の前提: 「REQUIREMENTS.md」について一点補足
+
+ご依頼の中で `REQUIREMENTS.md` という名称が挙がっていますが、Codex エコシステムに実在するのは **`requirements.toml`**（Markdown ではなく TOML 形式の管理者施行ファイル）です。本ガイドでは実際の仕様に忠実に `requirements.toml` として解説します。名前は近いものの、役割・書式・配置場所はまったく別物なので、移行時に検索して見つからず戸惑わないよう最初に明記しておきます。
+
+---
+
+## 目次(ステップ構成)
+
+1. Codex エコシステム全体像
+2. AGENTS.md ― 基本のプロジェクト指示ファイル
+3. AGENTS.override.md ― 一時的な上書きレイヤー
+4. 発見順序とマージロジックの詳細
+5. config.toml ― 階層構造とスコープ
+6. config.toml の主要キーとスキーマ
+7. requirements.toml ― 管理者施行の強制設定
+8. SKILL.md ― Progressive Disclosure によるスキル拡張
+9. Skills 運用のベストプラクティス
+10. Subagents の概念 ― コンテキスト汚染とコンテキスト腐敗
+11. カスタムサブエージェント定義ファイル
+12. マルチエージェントワークフロー設計パターン①: PRレビューの3分割
+13. マルチエージェントワークフロー設計パターン②: CSVファンアウト
+14. モデル・reasoning effort の選定指針
+15. Hooks と Rules(execpolicy) によるガバナンス
+16. 実践チェックリスト
+17. トラブルシューティング
+18. まとめ
+19. 参考文献
+
+---
+
+## Step 1. Codex エコシステム全体像
+
+Codex の「設定・指示・能力拡張・実行制御」は、役割の異なる複数のファイル群によって階層的に構成されています。まず全体の関係を俯瞰します。
+
+```mermaid
+flowchart TB
+    A["~/.codex/AGENTS.override.md"] -->|"優先"| B["~/.codex/AGENTS.md"]
+    B --> C["グローバル指示 確定"]
+    C --> D["プロジェクトルート AGENTS.override.md / AGENTS.md"]
+    D --> E["サブディレクトリ AGENTS.override.md / AGENTS.md"]
+    E --> F["結合済みプロンプト（project_doc_max_bytesまで）"]
+    G["config.toml / requirements.toml"] --> H["ランタイム挙動（承認方針・サンドボックス・モデル）"]
+    I["SKILL.md"] --> J["能力の拡張（Progressive Disclosure）"]
+    F --> K["Codex セッション開始"]
+    H --> K
+    J --> K
+    K --> L["サブエージェントへ委譲（spawn_agent）"]
+```
+
+| ファイル | 役割 | 書式 | 主なスコープ |
+|---|---|---|---|
+| `AGENTS.md` | エージェントへの恒久的な指示(規約・ワークフロー) | Markdown | ユーザー / プロジェクト / サブディレクトリ |
+| `AGENTS.override.md` | 同階層の `AGENTS.md` を完全に置き換える一時的な指示 | Markdown | 同上(各階層に1つだけ有効) |
+| `SKILL.md` | 再利用可能な手順・スクリプト・参照資料をまとめた「スキル」 | Markdown + フォルダ | ユーザー / プロジェクト / プラグイン |
+| `config.toml` | モデル・承認方針・サンドボックス・MCP・サブエージェントなどランタイム設定 | TOML | システム / ユーザー / プロジェクト / プロファイル |
+| `requirements.toml` | 管理者が強制するセキュリティ上限(ユーザーは上書き不可) | TOML | 組織全体(MDM・クラウドポリシー・ファイルシステム配布) |
+
+この5つは互いに独立した軸であり、「指示(何をすべきか)」「能力(何ができるか)」「実行制御(どこまで許可されるか)」の3層に分けて理解すると設計しやすくなります。
+
+---
+
+## Step 2. AGENTS.md ― 基本のプロジェクト指示ファイル
+
+`AGENTS.md` はプロジェクトやチームの規約・コーディングスタイル・テスト方法などをエージェントに伝える、Codex 起動時に自動的に読み込まれる自然言語の指示ファイルです。特別なシステムAPIではなく、Codex が Markdown をそのままプロンプトの一部として注入する仕組みであるため、書き方は「新しいチームメンバー向けのオンボーディング資料」を書くのに近い感覚で構いません。
+
+実務上のベストプラクティス:
+
+- **短く、具体的に。** 一般論(「良いコードを書いてください」)ではなく、「このリポジトリでは `pnpm test` を実行する」「`src/legacy/` 配下は変更禁止」のように、検証可能な具体指示に寄せる。
+- **強制力のあるインフラと組み合わせる。** `AGENTS.md` に書いたルールは pre-commit フック・リンター・型チェッカーと組み合わせることで、エージェントが同じミスを繰り返さないよう「システム側で気づける」ようにする。
+- **グローバルとリポジトリで役割を分ける。** `~/.codex/AGENTS.md`(グローバル)はレビューのトーンや詳細度などエージェントとの対話スタイルに、リポジトリの `AGENTS.md` はチーム・コードベース固有の規約に専念させる。
+
+---
+
+## Step 3. AGENTS.override.md ― 一時的な上書きレイヤー
+
+`AGENTS.override.md` は同じディレクトリにある `AGENTS.md` を**完全に置き換える**ための仕組みです。「一部だけ変更したい」場合の差分ファイルではなく、その階層で発見されると `AGENTS.md` は無視され、`override` ファイルの内容だけが採用されます。
+
+典型的な使いどころ:
+
+- 一時的な移行作業やインシデント対応中だけ、通常の規約(慎重な段階的コミットなど)を外して別の作業モードに切り替えたいとき
+- CI 専用セッションや検証用ブランチなど、恒久的な `AGENTS.md` を書き換えずに一時的な挙動を注入したいとき
+- 個人のローカル環境だけ挙動を変えたいが、リポジトリにコミットする `AGENTS.md` は触りたくないとき(`.gitignore` に `AGENTS.override.md` を加えて個人用に運用)
+
+---
+
+## Step 4. 発見順序とマージロジックの詳細
+
+Codex は `CODEX_HOME`(既定 `~/.codex`)のグローバル階層から、プロジェクトルートを経て現在の作業ディレクトリ(CWD)まで、ディレクトリを1段ずつ辿りながら指示ファイルを探索します。
+
+```mermaid
+sequenceDiagram
+    participant U as Codex起動
+    participant G as グローバルスコープ(~/.codex)
+    participant P as プロジェクトルート
+    participant S as サブディレクトリ(CWD)
+    U->>G: AGENTS.override.md を検索
+    G-->>U: なければ AGENTS.md を読込
+    U->>P: AGENTS.override.md を検索
+    P-->>U: なければ AGENTS.md / fallback を読込
+    U->>S: 現在の作業ディレクトリまで同様に走査
+    S-->>U: 各階層で最大1ファイルを採用
+    U->>U: ルートから順に連結（空行区切り）
+    Note over U: 近い階層のファイルほど後方に配置され優先度が高い
+```
+
+補足として押さえておきたい設定キー:
+
+- **`project_doc_fallback_filenames`**: `AGENTS.md` が見つからない階層で代わりに読み込むファイル名のリストを指定可能。既存の `README` や社内規約ファイル名をそのまま流用したい場合に使う。
+- **`project_doc_max_bytes`**: 連結後の指示テキストの合計サイズ上限。大きすぎる `AGENTS.md` 群は自動的に切り詰められるため、重要な指示ほどファイルの先頭近くに書く。
+- **`model_instructions_file`**: `AGENTS.md` の自動読み込みそのものを別ファイルで完全に置き換えるための設定キー(旧名 `experimental_instructions_file` は非推奨、新設定への移行が必要)。階層探索ロジックごと差し替える強力なオプションなので、通常は `AGENTS.md`/`AGENTS.override.md` の組み合わせで足りることが多い。
+
+---
+
+## Step 5. config.toml ― 階層構造とスコープ
+
+`config.toml` はモデル選択・承認ポリシー・サンドボックスモード・MCPサーバー・サブエージェント上限など、Codex の**振る舞い**を決めるランタイム設定です。指示ファイル(AGENTS.md系)とは異なるレイヤーで、以下の順に解決されます。
+
+```mermaid
+flowchart TB
+    A["CLIフラグ / -c key=value（セッション限定）"] --> E["合成された希望設定"]
+    B["プロジェクトスコープ .codex/config.toml（ルート→CWD、信頼済みのみ）"] --> E
+    C["プロファイル --profile 指定時の設定ファイル"] --> E
+    D["ユーザースコープ ~/.codex/config.toml"] --> E
+    E --> F["requirements.toml による検証（管理者施行の上限・強制値）"]
+    F --> G["最終的な実行時設定"]
+```
+
+実務上のポイント:
+
+- プロジェクト直下の `.codex/config.toml` は、そのプロジェクトを **trusted(信頼済み)** と判断した場合のみ読み込まれます。未信頼のプロジェクトでは、プロジェクトスコープの config・hooks・rules は一切ロードされず、ユーザー / システムスコープのみが有効です。
+- 「プロジェクト設定が効かない」という相談の多くは、実は該当キーが**プロジェクトスコープでは無視される予約キー**(`model_provider`・`notify`・`profile` など、認証やテレメトリに関わるもの)であるケースです。これらはユーザースコープの `~/.codex/config.toml` で設定する必要があります。
+- `--profile profile-name` を指定すると `~/.codex/profile-name.config.toml` を読み込みます。共通設定は `config.toml` に、環境差分だけをプロファイルファイルに分離するのが推奨構成です。
+- ファイル冒頭に `#:schema https://developers.openai.com/codex/config-schema.json` を書いておくと、対応エディタでキー補完とバリデーションが効きます。
+
+---
+
+## Step 6. config.toml の主要キーとスキーマ
+
+中級〜上級者が実際に触ることになる主要キーを機能別に整理します。
+
+| カテゴリ | キー例 | 概要 |
+|---|---|---|
+| モデル | `model`, `review_model`, `model_reasoning_effort`, `model_reasoning_summary`, `model_verbosity` | 既定モデル・レビュー専用モデル・reasoning の強度や要約詳細度 |
+| プロバイダ | `model_provider`, `model_providers.` | 組み込み(`openai`/`ollama`/`lmstudio`)以外の独自プロバイダ定義 |
+| 承認/サンドボックス | `approval_policy`, `sandbox_mode`, `approval_policy.granular.*` | `untrusted`/`on-request`/`never` などの承認方針と、`sandbox_approval`・`skill_approval`・`mcp_elicitations` の粒度別トグル |
+| ネットワーク | `features.network_proxy`, `features.network_proxy.domains` | ドメイン単位の allow/deny を伴うネットワークプロキシ機能 |
+| サブエージェント | `agents..config_file`, `agents.max_depth`, `agents.max_threads`, `features.multi_agent` | カスタムエージェント定義への参照、再帰の深さ・並列数の上限、マルチエージェント機能全体のオン/オフ |
+| Hooks | `[hooks]`(インライン)または `hooks.json` | ライフサイクルフックの定義(後述) |
+| MCP | `mcp_servers.` | Model Context Protocol サーバーの登録 |
+| その他 | `file_opener`, `request_max_retries`, `stream_max_retries`, `notify`, `otel` | エディタ連携・リトライ・通知・テレメトリ |
+
+補足: `instructions` キーは将来のための予約で、実際には `model_instructions_file` または `AGENTS.md` を使うのが現行の正しい方法です。
+
+---
+
+## Step 7. requirements.toml ― 管理者施行の強制設定
+
+`requirements.toml` は、個人やプロジェクトの `config.toml` では**上書きできない**、組織のセキュリティチームが強制する設定です。「ユーザーの利便性のための既定値」ではなく「絶対に譲れない下限・上限」を書く場所だと考えてください。
+
+主な特徴:
+
+- クラウドポリシー、macOS/Windows の MDM(Jamf・Kandji・Mosyle等)、あるいは単純なファイル配布の3経路で組織全体に配布可能。
+- 例: `approval_policy = "never"` や `sandbox_mode = "danger-full-access"` を組織全体で禁止する、といった強制。
+- 併用される **`managed_config.toml`** は「ソフトな既定値」を配布するためのファイルで、ユーザーが必要なら上書きできる点が `requirements.toml` との決定的な違いです。「ハードな制約は `requirements.toml`、ソフトな既定値は `managed_config.toml`」という役割分担で覚えると混同しません。
+- `[features]` テーブルを使うことで、`config.toml` と同じキー名でフィーチャーフラグそのものを固定できます(省略したキーは制約なし)。
+- `allow_managed_hooks_only = true` を設定すると、ユーザー・プロジェクト・セッション単位の hooks を無視し、管理レイヤーの hooks のみを有効にできます。
+- ChatGPT Business/Enterprise では、ローカルファイルに加えてクラウド側から取得した requirements も適用されます(優先順位はセキュリティドキュメントで規定)。
+
+---
+
+## Step 8. SKILL.md ― Progressive Disclosure によるスキル拡張
+
+Skill は「フォルダ + `SKILL.md`(メタデータ)+ 必要に応じたスクリプトや参照資料」という構成を取り、Codex に**再利用可能な手順**を教える仕組みです。ポイントは **Progressive Disclosure(段階的開示)** というロード方式です。
+
+- Codex は起動時、各スキルの**説明(description)だけ**を読み込みます。
+- タスクに関連しそうだと判断したスキルについてのみ、`SKILL.md` の本文やスクリプト・参照資料をその都度ロードします。
+- これにより、大量のスキルを登録してもコンテキストウィンドウを圧迫しません。
+
+配置場所と実行方式:
+
+| 実行方式 | 概要 |
+|---|---|
+| ローカル実行(local shell) | インフラを自前管理したい場合に、実行をローカル環境に閉じ込める |
+| ホスト型コンテナ実行 | Codex 側が用意するコンテナで実行。コンテナのライフサイクルに合わせてマウントしたファイルも保持・破棄される |
+
+スキルが MCP サーバーに依存する場合は `agents/openai.yaml` にその依存関係を宣言しておくと、Codex が自動的にインストール・接続まで面倒を見てくれます。
+
+---
+
+## Step 9. Skills 運用のベストプラクティス
+
+公式ガイダンスが強調しているのは「スキルは開発者が事前に検証してから配布する」という原則です。
+
+- スキルは開発者がレビュー・統合したうえで、**特定のプロダクトワークフローに紐づけて**エンドユーザーに提供する。
+- エンドユーザーが任意のスキルを自由に選べる状態を避ける(スコープを絞ったUX経由でのみ呼び出す)。
+- 書き込みや影響範囲の大きい操作を行うスキルは、明示的な承認とポリシーチェックをゲートとして挟む。
+- 「一度きりの手順」は AGENTS.md の指示で十分な場合が多く、「繰り返し使う複雑な手順・スクリプト・参照資料が伴うもの」こそスキル化する価値がある、という使い分けが実務的です。
+- 社内で頻繁に使うスキルは**プラグイン**としてパッケージ化し、マーケットプレイス経由でチーム配布すると、hooks やスキルをまとめて一貫バージョンで展開できます。
+
+---
+
+## Step 10. Subagents の概念 ― コンテキスト汚染とコンテキスト腐敗
+
+Subagents(サブエージェント)は 2026年3月16日に GA(一般提供)となった機能で、Codex は既定で `explorer`(調査系)・`worker`(バッチ処理系)・`default` という3種類の組み込みエージェントを持ちます。サブエージェントを使う最大の動機は、**メインスレッドのコンテキストを汚さないこと**です。
+
+```mermaid
+flowchart LR
+    A["メインエージェント（要件・意思決定）"] --> B["探索ノート・テストログ・コマンド出力が蓄積"]
+    B --> C["コンテキスト汚染 Context Pollution"]
+    C --> D["コンテキスト腐敗 Context Rot"]
+    D --> E["応答品質の低下"]
+    F["サブエージェントへ委譲"] --> G["ノイズの多い作業を分離"]
+    G --> H["要約のみメインへ返却"]
+    H --> A
+```
+
+大きなタスクを1本のスレッドで処理し続けると、探索過程のログやコマンド出力が蓄積して**コンテキスト汚染**が起こり、それが進行すると関連情報が埋もれて応答品質が落ちる**コンテキスト腐敗(Context Rot)**につながります。サブエージェントは、ノイズの多い調査やバッチ作業を隔離したスレッドに切り出し、要約だけをメインへ返すことでこれを防ぎます。
+
+ただし無料ではありません。公式ドキュメントも警告している通り、サブエージェントは同等の単一エージェント実行より**多くのトークンを消費**します。著名な開発者 Simon Willison 氏も、並列エージェント運用について「本当のボトルネックは自分がどれだけ速く結果をレビューできるかだ」という趣旨の指摘を自身のブログで行っており、オーケストレーションはタイピングの負荷をレビューの負荷に移すだけだと戒めています。設計時は「並列化すれば必ず速くなる」という前提を置かず、レビュー体制とセットで計画することが重要です。
+
+---
+
+## Step 11. カスタムサブエージェント定義ファイル
+
+組み込みの3エージェントに加えて、`~/.codex/agents/` 配下に TOML ファイルを置くことで独自のサブエージェントを定義できます。名前を指定して呼び出せるほか、エージェントごとに異なるモデルを割り当てることも可能です(例: 高速性を優先するなら `gpt-5.3-codex-spark` を指定するなど)。
+
+サブエージェントのオーケストレーションは Codex 本体が受け持ち、次のような操作を内部的に扱います。
+
+| 操作 | 概要 |
+|---|---|
+| `spawn_agent` | 新しいサブエージェントスレッドを起動 |
+| `send_input` | 起動済みのサブエージェントへ追加指示を送信 |
+| `resume_agent` | 中断していたサブエージェントを再開 |
+| `wait_agent` | サブエージェントの完了を待機 |
+| `close_agent` | サブエージェントのスレッドを終了 |
+
+`config.toml` 側では `agents.max_depth`(何段まで入れ子でサブエージェントを起動できるか)と `agents.max_threads`(同時並列数)で暴走を防ぎます。トリガーは特別なコマンドではなく自然言語で構いません。「レビュー観点ごとにエージェントを1つずつ立ち上げて、すべて完了したら結果をまとめて」と指示するだけで、Codex が複数スレッドを開いて集約します。
+
+---
+
+## Step 12. マルチエージェントワークフロー設計パターン①: PRレビューの3分割
+
+実務でよく使われる型の一つが、プルリクエストのレビューをコード探索・レビュー・外部仕様確認の3系統に分ける並列パターンです。
+
+```mermaid
+flowchart TB
+    U["開発者のプロンプト：このブランチをレビューして"] --> M["メインCodexセッション"]
+    M --> P1["pr_explorer（読み取り専用・コード調査）"]
+    M --> P2["reviewer（正確性・セキュリティ・テスト）"]
+    M --> P3["docs_researcher（MCP経由でAPI仕様確認）"]
+    P1 --> R["各エージェントの結果を収集"]
+    P2 --> R
+    P3 --> R
+    R --> S["メインエージェントが統合要約"]
+```
+
+設計のコツ:
+
+- **役割ごとに読み書き権限を分ける。** コード調査担当は読み取り専用サンドボックスに固定し、変更を加える担当だけ書き込み権限を持たせる。
+- **外部情報の検証は専任エージェントに。** MCP経由でドキュメントや実サービスの仕様を突き合わせる作業は、コードレビューと混ぜずに独立させると、メインの思考が汚れません。
+- **集約は必ずメインエージェントが行う。** 各サブエージェントの結果をそのまま並べるのではなく、メインが矛盾点や優先度を踏まえて再統合することで、レビュー全体の一貫性を保ちます。
+
+---
+
+## Step 13. マルチエージェントワークフロー設計パターン②: CSVファンアウト
+
+多数の小タスクを一括処理したい場合(例: リポジトリ内の全コンポーネントに同じ改修を適用する)は、CSVを起点にしたファンアウトパターンが有効です。
+
+```mermaid
+flowchart TB
+    A["components.csv（path, owner）"] --> B["spawn_agents_on_csv"]
+    B --> C["行ごとに1ワーカーを起動（max_concurrencyまで並列）"]
+    C --> D["各ワーカーが report_agent_job_result を1回呼出"]
+    D --> E["結果を output_csv_path へ集約（job_id, status, result_json）"]
+```
+
+このパターンは `worker` 系エージェントが得意とする領域で、CSVの行数分だけワーカーを起動し、`max_concurrency` で同時実行数を絞りつつ、各ワーカーが結果を1回だけ報告して指定した出力CSVに集約させます。大量の定型タスクをレビュー可能な単位に分割したいときの定番構成です。
+
+---
+
+## Step 14. モデル・reasoning effort の選定指針
+
+すべてのサブエージェントに同じモデルを割り当てる必要はありません。タスクの性質に応じて使い分けることで、コストと品質のバランスを取れます。
+
+```mermaid
+flowchart TB
+    A["サブエージェントのタスク性質は？"] --> B{"曖昧・多段階・要検証？"}
+    B -- Yes --> C["gpt-5.5（高能力の起点として推奨）"]
+    B -- No --> D{"低遅延・大量の対話的反復が必要？"}
+    D -- Yes --> E["gpt-5.3-codex-spark（Cerebras上で高速動作）"]
+    D -- No --> F["gpt-5.4（安定版の既定ワークフロー）"]
+```
+
+加えて `model_reasoning_effort`(例: `xhigh`)や `model_reasoning_summary`(`detailed` など)は、探索系のエージェントには高め、定型的なバッチワーカーには低めに設定するなど、エージェントごとの `config.toml` 参照(`agents..config_file`)で個別最適化するのが実務的です。モデル名やバリアントは頻繁に更新されるため、実際に指定する前に `codex models` や利用中のプロバイダのカタログで最新の識別子を確認してください。
+
+---
+
+## Step 15. Hooks と Rules(execpolicy) によるガバナンス
+
+サブエージェントを増やすほど、「何を承認なしで実行してよいか」の統制が重要になります。Codex にはこれを扱う2つの仕組みがあります。
+
+**Hooks**: `PermissionRequest` 型のフックでコマンド実行前に allow/deny を判定し、複数のフックが競合した場合は deny が優先されます。`PostToolUse` フックは Bash・`apply_patch`・MCPツール呼び出しの後に発火しますが、まだ全てのシェル呼び出しを捕捉できるわけではない点(新しい `unified_exec` 系統は途上)には注意が必要です。プロジェクトローカルの hooks は、そのプロジェクトが信頼済みの場合のみ読み込まれます。
+
+**Rules(execpolicy)**: `.rules` ファイル(Starlark構文)で `prefix_rule(pattern=..., decision="allow"|"prompt"|"forbidden", justification="...")` を定義し、コマンドの引数列とパターンを照合します。複数ルールが一致した場合は最も制限の強い判定(`forbidden` > `prompt` > `allow`)が採用されます。`codex execpolicy check --rules  -- ` でルールの動作を事前検証できるため、大規模なサブエージェント運用を始める前にルールセットをテストしておくと安全です。管理者は `requirements.toml` から制限的な `prefix_rule` を強制することもできます。
+
+---
+
+## Step 16. 実践チェックリスト
+
+- [ ] `AGENTS.md` は検証可能な具体的ルールになっているか(抽象的な精神論になっていないか)
+- [ ] `AGENTS.override.md` を使う場合、それが「一時的な例外」であることをチーム内で共有できているか
+- [ ] `project_doc_max_bytes` を超えていないか、重要な指示が末尾で切り詰められていないか確認したか
+- [ ] `config.toml` の変更が想定のスコープ(ユーザー/プロジェクト/プロファイル)で効いているか、予約キーで無視されていないか
+- [ ] 組織で譲れない制約(承認ポリシーやサンドボックスモードの下限)は `requirements.toml` に、単なる既定値は `managed_config.toml` に分離しているか
+- [ ] スキルはエンドユーザーが任意選択できる状態になっていないか、書き込み系スキルに承認ゲートがあるか
+- [ ] サブエージェントの並列度(`agents.max_threads`)と再帰深さ(`agents.max_depth`)に上限を設定しているか
+- [ ] マルチエージェント運用のレビュー体制(誰が・どれだけの頻度で結果をレビューするか)を並列化前に決めているか
+- [ ] `.rules` ファイルを `codex execpolicy check` で事前検証したか
+
+---
+
+## Step 17. トラブルシューティング
+
+| 症状 | よくある原因 | 対処 |
+|---|---|---|
+| プロジェクトの `config.toml` が効かない | プロジェクトが untrusted 扱い、または予約キー(`model_provider`・`notify`・`profile` 等)を使っている | プロジェクトを信頼済みにする/該当キーはユーザースコープの `~/.codex/config.toml` に移す |
+| `AGENTS.md` の指示が反映されない | 同階層に `AGENTS.override.md` が存在し、そちらが優先されている | override ファイルの有無を確認し、意図しないものであれば削除する |
+| 指示の一部が無視されている | 連結後の合計サイズが `project_doc_max_bytes` を超えて切り詰められている | 重要な指示をファイル先頭に移動する、または上限を引き上げる |
+| hooks が急に効かなくなった | `requirements.toml` の `allow_managed_hooks_only = true` により、管理外の hooks が無効化されている | 管理者に確認し、必要な hooks を管理レイヤー側で登録してもらう |
+| サブエージェントがコストを消費しすぎる | 並列度・再帰深さの上限が未設定、またはモデル選定が一律で高コストなものになっている | `agents.max_threads`/`agents.max_depth` を設定し、探索系タスクには軽量なモデルを割り当てる |
+
+---
+
+## Step 18. まとめ
+
+Codexのマルチエージェント開発は、「エージェントに何をすべきか教える層(AGENTS.md/override)」「繰り返し使える能力を教える層(SKILL.md)」「実行時の挙動を決める層(config.toml)」「組織として絶対に譲れない制約を敷く層(requirements.toml)」という4層構造で理解すると設計がぶれません。そのうえでサブエージェントは、コンテキスト汚染を防ぐための「隔離」の道具であり、並列化そのものが目的ではなく、レビュー体制とセットで初めて効果を発揮する点を忘れないことが、中級者から上級者へステップアップする際の分岐点になります。
+
+---
+
+## 参考文献
+
+- AGENTS.md 発見順序・階層仕様: https://developers.openai.com/codex/guides/agents-md
+- config.toml 基礎(階層・precedence): https://developers.openai.com/codex/config-basic
+- config.toml 全キーリファレンス: https://developers.openai.com/codex/config-reference
+- Advanced Configuration(予約キー・プロジェクトスコープの制約): https://learn.chatgpt.com/docs/config-file/config-advanced
+- Subagents の概念(コンテキスト汚染・モデル選定指針): https://developers.openai.com/codex/concepts/subagents
+- Subagents のセットアップとツール一覧: https://developers.openai.com/codex/subagents
+- Skills(Progressive Disclosure・実行方式): https://developers.openai.com/codex/skills
+- AGENTS.md と Skills / Subagents / MCP の使い分け: https://developers.openai.com/codex/concepts/customization
+- Agent approvals & security(承認粒度・ネットワークプロキシ): https://developers.openai.com/codex/agent-approvals-security
+- Rules / execpolicy: https://developers.openai.com/codex/rules
+- execpolicy README(Starlarkルールのサンプル): https://github.com/openai/codex/blob/main/codex-rs/execpolicy/README.md
+- Codex changelog(モデル世代・機能変遷): https://developers.openai.com/codex/changelog
+- requirements.toml / managed_config.toml の実践解説(Codex Knowledge Base): https://codex.danielvaughan.com/2026/04/27/codex-cli-enterprise-managed-configuration-requirements-toml-admin-policies/
+- Simon Willison「Use subagents and custom agents in Codex」(GA発表・組み込み3エージェント・カスタムTOML定義): https://simonwillison.net/2026/Mar/16/codex-subagents/
+- Firecrawl「Multi-Agent Orchestration With Codex」(PRレビュー3分割パターン、レビュー負荷への言及): https://www.firecrawl.dev/blog/codex-multi-agent-orchestration
+- Codex CLI config.toml 実践解説(150以上のキーの整理): https://ofox.ai/blog/codex-cli-config-toml-deep-dive/
+- Codex(AI agent)の機能・モデル世代の変遷(背景情報): https://en.wikipedia.org/wiki/Codex_(AI_agent)

From f60dba24bcf7deb9361dad55dd23b267b50b0cfd Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 03:37:31 +0900
Subject: [PATCH 03/53] docs(progress): update validation command notations
 from npm run to bun run

---
 docs/PROGRESS.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 7a6b8dd6..bda687f0 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -11,16 +11,16 @@
 - **フェーズ**: 保守・機能改善・品質強化フェーズ
 - **ブランチ**: `dev`（本番 `main` への Next.js 移行マージ完了 🚀）
 - **動作検証**:
-  - `npm run build` ⏭️（依頼により未実行。Antigravity環境では実行禁止、CI または他環境では必須）
-  - `npm run typecheck` ✅
-  - `npm run lint` ✅（385 files checked）
+  - `bun run build` ⏭️（依頼により未実行。Antigravity環境では実行禁止、CI または他環境では必須）
+  - `bun run typecheck` ✅
+  - `bun run lint` ✅（385 files checked）
 - **テストの実行状況**:
   - **フロントエンド (`web-next/`)**: Vitest **137 files / 1259 tests すべて合格**（収集失敗なし）
   - **バックエンド (`scraper/`)**: pytest 実行で **43 件すべて合格** (全 Green ✅)
 
 ## 最近の追加内容
 
-- **SonarQube CI のaxeタイムアウト・新規コードカバレッジ修正**: coverage計測時にAntigravity a11y監査が既定5秒でタイムアウトし、未完了axeと後続監査が競合する問題を、同規模ページと同じ15秒上限で解消。Sonarが新規コードとして検出したClaude TocObserver 3ファイルへ分岐テスト12件を追加し、対象3ファイルの行・条件カバレッジを各100%にした。目視・ビルドは依頼により省略。`npm run test:coverage` は **137 files / 1259 tests**、全体 line coverage **92.79%**、typecheck、lint **385 files / 0 diagnostics** がGreen。
+- **SonarQube CI のaxeタイムアウト・新規コードカバレッジ修正**: coverage計測時にAntigravity a11y監査が既定5秒でタイムアウトし、未完了axeと後続監査が競合する問題を、同規模ページと同じ15秒上限で解消。Sonarが新規コードとして検出したClaude TocObserver 3ファイルへ分岐テスト12件を追加し、対象3ファイルの行・条件カバレッジを各100%にした。目視・ビルドは依頼により省略。`bun run test:coverage` は **137 files / 1259 tests**、全体 line coverage **92.79%**、typecheck、lint **385 files / 0 diagnostics** がGreen。
 
 - **レビュー指摘の再照合とセマンティクス・安全性修正**: 現行コードで全指摘を再検証し、シェル手順の exact-line CSS 変数照合・静的サーバー PID cleanup・チェックサム失敗時停止を修正。Cowork チェックボックスのラベル関連付け、Fable 5 の凡例/タイムライン list semantics、Skill frontmatter 必須説明と命名制約、Antigravity の用語・Review Policy・SHA-256検証パス、TechCrunch出典の第三者報道ラベル、TOC の DOM 順選択、CSS font fallback、共有 `Ext`、目次データ駆動化を反映した。テストは DOM 出力ベースへ堅牢化し、共有 Mermaid は未指定時 `16px`、明示 `fontSize` は保持する契約へ更新。目視・ビルドは依頼により省略。Vitest **134 files / 1247 tests**、typecheck、lint **382 files / 0 diagnostics**、pytest **43 tests** はすべて Green。
 

From c18c8074a35a60bd7febd2c2f8aef40335b8d27b Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 12:53:12 +0900
Subject: [PATCH 04/53] style(google): update domain styling and section
 observer in Google-sandbox-best-practices.html

---
 Google-sandbox-best-practices.html | 505 ++++++++++++++++++++++++-----
 1 file changed, 425 insertions(+), 80 deletions(-)

diff --git a/Google-sandbox-best-practices.html b/Google-sandbox-best-practices.html
index 43156f6a..e08dfd57 100644
--- a/Google-sandbox-best-practices.html
+++ b/Google-sandbox-best-practices.html
@@ -28,6 +28,14 @@
         --accent-glow: rgba(124, 158, 255, 0.18);
         --accent-2: #69e2c4;
         --accent-3: #f2b84b;
+
+        /* Per-domain accent palette */
+        --c-agent: #7c9eff;
+        --c-api: #5eead4;
+        --c-container: #f2b84b;
+        --c-cpp: #fb7185;
+        --c-browser: #c4b5fd;
+
         --code-bg: #0a1526;
         --sidebar-w: 300px;
         --radius: 14px;
@@ -41,6 +49,7 @@
       }
       html {
         scroll-behavior: smooth;
+        overflow-x: hidden;
       }
       body {
         margin: 0;
@@ -50,6 +59,7 @@
         font-size: 16px;
         line-height: 1.9;
         -webkit-font-smoothing: antialiased;
+        overflow-x: hidden;
       }
       a {
         color: var(--accent);
@@ -64,9 +74,39 @@
         margin: 2.5rem 0;
       }
 
+      /* ---------- Decorative background ---------- */
+      .bg-glow {
+        position: fixed;
+        inset: 0;
+        z-index: 0;
+        pointer-events: none;
+        background:
+          radial-gradient(760px 480px at 14% -6%, rgba(124, 158, 255, 0.16), transparent 60%),
+          radial-gradient(620px 420px at 92% 8%, rgba(105, 226, 196, 0.1), transparent 60%),
+          radial-gradient(900px 600px at 60% 110%, rgba(242, 184, 75, 0.06), transparent 60%);
+      }
+      .top-accent-bar {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        height: 3px;
+        z-index: 100;
+        background: linear-gradient(
+          90deg,
+          var(--c-agent),
+          var(--c-api),
+          var(--c-container),
+          var(--c-cpp),
+          var(--c-browser)
+        );
+      }
+
       /* ---------- Layout ---------- */
       .layout {
         display: block;
+        position: relative;
+        z-index: 1;
       }
       .sidebar {
         position: fixed;
@@ -77,6 +117,7 @@
         overflow-y: auto;
         background: var(--bg-elevated);
         border-right: 1px solid var(--border-soft);
+        box-shadow: 8px 0 32px rgba(0, 0, 0, 0.35);
         padding: 1.75rem 1.25rem 3rem;
         z-index: 50;
       }
@@ -90,16 +131,17 @@
       .brand {
         display: flex;
         align-items: center;
-        gap: 0.6rem;
+        gap: 0.65rem;
         margin-bottom: 1.5rem;
         padding-bottom: 1.25rem;
         border-bottom: 1px solid var(--border-soft);
       }
       .brand-badge {
-        width: 34px;
-        height: 34px;
-        border-radius: 9px;
+        width: 36px;
+        height: 36px;
+        border-radius: 10px;
         background: linear-gradient(135deg, var(--accent), #4f6fd1);
+        box-shadow: 0 4px 14px var(--accent-glow);
         display: flex;
         align-items: center;
         justify-content: center;
@@ -136,7 +178,9 @@
         margin: 1px 0;
       }
       .nav-list a {
-        display: block;
+        display: flex;
+        align-items: center;
+        gap: 0.6rem;
         padding: 0.5rem 0.7rem;
         border-radius: 9px;
         color: var(--text-dim);
@@ -158,6 +202,14 @@
         border-left-color: var(--accent);
         font-weight: 500;
       }
+      .nav-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        flex-shrink: 0;
+        background: var(--dot, var(--text-faint));
+        box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.03);
+      }
       .sidebar-toggle {
         display: none;
         position: fixed;
@@ -177,24 +229,30 @@
       .main {
         margin-left: var(--sidebar-w);
         padding: 3.5rem 4vw 6rem;
+        position: relative;
       }
 
       /* ---------- Typography ---------- */
       h1 {
-        font-size: 2.1rem;
+        font-size: 2.3rem;
         font-weight: 900;
         line-height: 1.35;
-        margin: 0 0 0.4rem;
-        background: linear-gradient(90deg, var(--text) 20%, var(--accent) 100%);
+        margin: 0 0 0.5rem;
+        background: linear-gradient(
+          90deg,
+          var(--text) 10%,
+          var(--accent) 65%,
+          var(--accent-2) 100%
+        );
         -webkit-background-clip: text;
         -webkit-text-fill-color: transparent;
         background-clip: text;
       }
       .lede {
-        font-size: 1.08rem;
+        font-size: 1.1rem;
         color: var(--text-dim);
         max-width: 80ch;
-        margin: 0 0 1.75rem;
+        margin: 0 0 1.5rem;
       }
       h2 {
         font-size: 1.55rem;
@@ -204,17 +262,57 @@
         padding-top: 1.6rem;
         border-top: 1px solid var(--border-soft);
         scroll-margin-top: 2rem;
+        display: flex;
+        align-items: center;
+        gap: 0.7rem;
       }
       .layout h2:first-of-type {
         border-top: none;
         padding-top: 0;
       }
+      h2.domain-h2 {
+        border-top: 2px solid var(--domain, var(--border-soft));
+        position: relative;
+      }
+      .domain-badge {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 2.6rem;
+        height: 2rem;
+        padding: 0 0.55rem;
+        border-radius: 8px;
+        background: color-mix(in srgb, var(--domain) 18%, var(--bg-card));
+        color: var(--domain);
+        border: 1px solid color-mix(in srgb, var(--domain) 45%, var(--border-soft));
+        font-size: 0.78rem;
+        font-weight: 700;
+        letter-spacing: 0.02em;
+        font-family: var(--font-mono);
+        flex-shrink: 0;
+      }
       h3 {
         font-size: 1.2rem;
         font-weight: 700;
         color: var(--accent);
         margin: 2.2rem 0 0.9rem;
         scroll-margin-top: 2rem;
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+      }
+      h3.domain-h3 {
+        color: var(--domain, var(--accent));
+      }
+      h3.domain-h3::before {
+        content: '';
+        width: 7px;
+        height: 7px;
+        border-radius: 2px;
+        background: var(--domain, var(--accent));
+        display: inline-block;
+        transform: rotate(45deg);
+        flex-shrink: 0;
       }
       p {
         margin: 0 0 1.1rem;
@@ -237,13 +335,33 @@
         font-weight: 700;
       }
       blockquote {
+        position: relative;
         margin: 1.5rem 0;
-        padding: 1.1rem 1.4rem;
+        padding: 1.1rem 1.4rem 1.1rem 3rem;
         background: var(--bg-card);
+        border: 1px solid var(--border-soft);
         border-left: 3px solid var(--accent);
         border-radius: 0 10px 10px 0;
         color: var(--text-dim);
       }
+      blockquote::before {
+        content: 'i';
+        position: absolute;
+        left: 1rem;
+        top: 1.15rem;
+        width: 1.3rem;
+        height: 1.3rem;
+        border-radius: 50%;
+        background: var(--accent-glow);
+        color: var(--accent);
+        font-family: var(--font-mono);
+        font-weight: 700;
+        font-size: 0.8rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-style: normal;
+      }
       blockquote p {
         margin: 0;
       }
@@ -255,24 +373,91 @@
         border-radius: 5px;
         font-size: 0.86em;
         color: var(--accent-2);
+        overflow-wrap: break-word;
+        word-break: break-word;
       }
 
-      /* ---------- Table of contents (rendered inline in doc) ---------- */
-      .main > ol:first-of-type {
+      /* ---------- Quick-nav domain grid (replaces plain TOC) ---------- */
+      .quicknav-label {
+        font-size: 0.78rem;
+        letter-spacing: 0.1em;
+        color: var(--text-faint);
+        text-transform: uppercase;
+        margin: 2.4rem 0 0.9rem;
+        font-weight: 700;
+      }
+      .quicknav-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 1rem;
+        margin-bottom: 1.5rem;
+      }
+      .quicknav-card {
+        display: block;
+        min-width: 0;
         background: var(--bg-card);
         border: 1px solid var(--border-soft);
         border-radius: var(--radius);
-        padding: 1.4rem 1.4rem 1.4rem 2.6rem;
-        counter-reset: toc;
+        padding: 1.2rem 1.3rem;
+        text-decoration: none;
+        color: var(--text);
+        position: relative;
+        overflow: hidden;
+        transition:
+          transform 0.18s ease,
+          box-shadow 0.18s ease,
+          border-color 0.18s ease;
       }
-      .main > ol:first-of-type li {
-        margin-bottom: 0.45rem;
+      .quicknav-card::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        height: 3px;
+        background: var(--domain);
+      }
+      .quicknav-card:hover {
+        text-decoration: none;
+        transform: translateY(-3px);
+        border-color: color-mix(in srgb, var(--domain) 50%, var(--border-soft));
+        box-shadow: 0 14px 30px rgba(0, 0, 0, 0.35);
+      }
+      .quicknav-head {
+        display: flex;
+        align-items: center;
+        gap: 0.65rem;
+        margin-bottom: 0.55rem;
       }
-      .main > ol:first-of-type a {
+      .quicknav-badge {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 2.4rem;
+        height: 1.85rem;
+        padding: 0 0.5rem;
+        border-radius: 7px;
+        background: color-mix(in srgb, var(--domain) 18%, var(--bg-card));
+        color: var(--domain);
+        border: 1px solid color-mix(in srgb, var(--domain) 45%, var(--border-soft));
+        font-family: var(--font-mono);
+        font-weight: 700;
+        font-size: 0.74rem;
+        flex-shrink: 0;
+      }
+      .quicknav-title {
+        font-weight: 700;
+        font-size: 1.02rem;
         color: var(--text);
       }
-      .main > ol:first-of-type a:hover {
-        color: var(--accent);
+      .quicknav-desc {
+        font-size: 0.86rem;
+        color: var(--text-dim);
+        line-height: 1.65;
+        margin: 0;
+      }
+      .quicknav-card.span-full {
+        grid-column: 1 / -1;
       }
 
       /* ---------- Mermaid ---------- */
@@ -286,6 +471,9 @@
         border-radius: var(--radius);
         padding: 1.8rem 1.4rem;
         margin: 1.8rem 0;
+        box-shadow:
+          inset 0 1px 0 rgba(255, 255, 255, 0.02),
+          0 10px 24px rgba(0, 0, 0, 0.22);
       }
       pre.mermaid svg {
         max-width: none;
@@ -297,6 +485,7 @@
         margin: 1.6rem 0;
         border: 1px solid var(--border-soft);
         border-radius: var(--radius);
+        box-shadow: 0 10px 24px rgba(0, 0, 0, 0.22);
       }
       table {
         width: 100%;
@@ -313,7 +502,7 @@
         vertical-align: top;
       }
       th {
-        background: var(--bg-elevated);
+        background: linear-gradient(180deg, var(--bg-card-hover), var(--bg-elevated));
         color: var(--accent);
         font-weight: 700;
         white-space: nowrap;
@@ -321,6 +510,9 @@
       tr:last-child td {
         border-bottom: none;
       }
+      tbody tr {
+        transition: background 0.12s;
+      }
       tbody tr:hover {
         background: var(--bg-card-hover);
       }
@@ -328,15 +520,25 @@
       /* ---------- Reference card grid ---------- */
       .ref-grid {
         display: grid;
-        grid-template-columns: 1fr 1fr;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
         gap: 1.1rem;
         margin: 1.6rem 0 2rem;
       }
       .ref-card {
+        min-width: 0;
         background: var(--bg-card);
         border: 1px solid var(--border-soft);
         border-radius: var(--radius);
         padding: 1.3rem 1.4rem;
+        transition:
+          border-color 0.18s ease,
+          box-shadow 0.18s ease,
+          transform 0.18s ease;
+      }
+      .ref-card:hover {
+        border-color: color-mix(in srgb, var(--accent) 40%, var(--border-soft));
+        box-shadow: 0 14px 30px rgba(0, 0, 0, 0.3);
+        transform: translateY(-2px);
       }
       .ref-card h3 {
         margin: 0 0 0.8rem;
@@ -362,7 +564,9 @@
         color: var(--text-dim);
         font-size: 0.86rem;
         line-height: 1.55;
+        overflow-wrap: break-word;
         word-break: break-all;
+        min-width: 0;
       }
       .ref-card li a:hover {
         color: var(--accent);
@@ -404,16 +608,22 @@
           margin-left: 0;
           padding: 5rem 5vw 4rem;
         }
-        .ref-grid {
-          grid-template-columns: 1fr;
+        .ref-grid,
+        .quicknav-grid {
+          grid-template-columns: minmax(0, 1fr);
         }
         h1 {
-          font-size: 1.6rem;
+          font-size: 1.7rem;
+        }
+        h2 {
+          flex-wrap: wrap;
         }
       }
     
   
   
+    

+    

     
 
     

@@ -424,16 +634,46 @@
         

         
目次

         
       
 
@@ -448,20 +688,49 @@ 
Google サンドボックス技術 完全ガイド

           

         
 
+        
5つの領域をひと目で

+        

+          
+            

+              AIAIエージェント
+            

+            

+              GKE Agent Sandbox(gVisor)とGemini Code Executionで、生成されたコードを隔離実行
+            

+          
+          
+            

+              APIAPI
+            

+            
Apigeeの環境分離とセキュリティポリシーでAPIレイヤーを保護

+          
+          
+            

+              CTコンテナ
+            

+            

+              gVisorのカーネルレベル分離でGKE・Cloud Run・App Engineを保護
+            

+          
+          
+            

+              C+C/C++
+            

+            
Sandbox2とSandboxed API(SAPI)でネイティブライブラリを隔離

+          
+          
+            

+              WEBブラウザ
+            

+            

+              マルチプロセス構造・Site Isolation・V8 Sandboxによる多層防御
+            

+          
+        

+
         

-        
目次

-        
    
-          
  1. はじめに:なぜ「サンドボックス」が必要なのか
    2. 
-          
  2. 全体マップ:Googleの5つのサンドボックス領域
    3. 
-          
  3. 領域① AIエージェントのサンドボックス
    4. 
-          
  4. 領域② APIのサンドボックス
    5. 
-          
  5. 領域③ コンテナのサンドボックス
    6. 
-          
  6. 領域④ C/C++のサンドボックス
    7. 
-          
  7. 領域⑤ ブラウザのサンドボックス
    8. 
-          
  8. 意思決定フロー:自分のケースにはどれを選ぶべきか
    9. 
-          
  9. 横断ベストプラクティス早見表
    10. 
-          
  10. 参考文献・出典URL
    11. 
-        

+
         

         

         

@@ -522,8 +791,18 @@ 

         

         

         

-        
3. 領域① AIエージェントのサンドボックス

-        

+        

+          AI3. 領域① AIエージェントのサンドボックス
+        

+        

           3-1. なぜAIエージェント専用の隔離が必要か
         

         

@@ -531,7 +810,13 @@ 

           Kubernetes Engine)向けのAgent Sandboxと、Gemini APIやAgent
           Platform向けのCode Executionという2つの製品ラインで解決しています。
         

-        
3-2. GKE Agent Sandbox:アーキテクチャ

+        

+          3-2. GKE Agent Sandbox:アーキテクチャ
+        

         

           GKE Agent Sandboxは、Kubernetes SIG
           Apps配下でオープンソース開発されているKubernetesネイティブな拡張機能です。gVisorによるカーネルレベルの隔離を、Sandbox・SandboxTemplate・SandboxClaimという3つの新しいKubernetesカスタムリソースを通じて提供します。
@@ -547,7 +832,11 @@ 
3-2. GKE Agent Sandbox:ア
         

           Sentryはエージェントが発行するすべてのシステムコール(execやsocketなど)を横取りし、ホストカーネルに直接触れさせない「偽のカーネル」として振る舞います。ファイルシステム操作だけは別プロセスのGoferが仲介するため、たとえSentryに未知の脆弱性があっても、ファイルシステムへの被害範囲を最小化できます。
         

-        

+        

           3-3. ステップバイステップ:導入のベストプラクティス
         

         
    
@@ -574,7 +863,11 @@ 
    
             Controlsをすべて設定しても、それらは「許可されたチャネルの中で行われる正規の操作」しか防げない。プロンプトインジェクションによって、許可済みのAPI呼び出し経由でデータが持ち出されるリスクは別途モニタリングで検知する必要がある、と複数のセキュリティ研究者が指摘している
           
         

-        

+        

           3-4. Gemini API / Agent Platform の Code Execution
         

         

@@ -624,8 +917,14 @@ 

         

         

         

-        
4. 領域② APIのサンドボックス

-        

+        

+          API4. 領域② APIのサンドボックス
+        

+        

           4-1. Apigeeにおける「サンドボックス環境」の考え方
         

         

@@ -641,7 +940,11 @@ 

     Proxy --> Policy3["セキュリティポリシー<br/>(RBAC / OAuth等)"]
     Proxy --> Backend["バックエンドサービス"]
-        

+        

           4-2. ステップバイステップ:APIサンドボックスのベストプラクティス
         

         
    
@@ -673,8 +976,18 @@ 
    
-        
    5. 領域③ コンテナのサンドボックス
    
-        
    
+        
    
+          CT5. 領域③ コンテナのサンドボックス
+        
    
+        
    
           5-1. gVisorの基本アーキテクチャ(再掲・詳細版)
         
    
         
    
@@ -691,7 +1004,11 @@ 
    
           Functions)はいずれも、アプリケーションワークロードの隔離にgVisorを採用しています。Cloud
           Runの場合、各インスタンスは仮想マシンモニター(VMM)によって他のインスタンスから隔離され、さらにコンテナ境界の強制とseccompによるシステムコールフィルタリングが重ねられる多層防御構成になっています。
         
    
-        
    
+        
    
           5-2. ステップバイステップ:GKE Sandboxの有効化手順
         
    
         
      
@@ -735,8 +1052,14 @@ 
      
         
    
         
    
         
    
-        
    6. 領域④ C/C++のサンドボックス
    
-        
    
+        
    
+          C+6. 領域④ C/C++のサンドボックス
+        
    
+        
    
           6-1. Sandbox2:プログラム全体・一部を隔離する
         
    
         
    
@@ -755,7 +1078,11 @@ 
    
     Executor -->|ポリシーを適用して起動| Sandboxee["Sandboxee<br/>(隔離対象プロセス)"]
     Sandboxee -->|許可済みsyscallのみ通過| Kernel3["Linuxカーネル"]
-        
    
+        
    
           6-2. Sandboxed API(SAPI):ライブラリ単位でサンドボックス化する
         
    
         
    
@@ -774,7 +1101,11 @@ 
    
+        
    
           6-3. ステップバイステップ:zlibをSAPIでサンドボックス化する例
         
    
         
    公式のGetting Startedガイドで紹介されている典型的な流れは次のとおりです。
    
@@ -808,7 +1139,9 @@ 
    6-4. C/C++領域における他の選択肢比較
    
+        
    
+          6-4. C/C++領域における他の選択肢比較
+        
    
         
    
           Google Developersの公式ページでは、用途別に複数のサンドボックス技術が一覧化されています。
         
    
@@ -890,8 +1223,18 @@ 
    6-4. C/C++領域におけ
         
         
    
         
    
-        
    7. 領域⑤ ブラウザのサンドボックス
    
-        
    
+        
    
+          WEB7. 領域⑤ ブラウザのサンドボックス
+        
    
+        
    
           7-1. Chromeのマルチプロセスアーキテクチャ
         
    
         
    
@@ -907,7 +1250,11 @@ 
    
     RendererA -.->|IPC経由のみ| Browser
     RendererB -.->|IPC経由のみ| Browser
-        
    
+        
    
           7-2. Site Isolation:サイトをまたいだデータ漏洩を防ぐ
         
    
         
    
@@ -916,7 +1263,11 @@ 
    
             >Site Isolationです。目的は「1つのレンダラープロセスには、最大でも1つのWebサイト由来のページしか含めない」ことを保証し、レンダラープロセスに脆弱性があっても、他サイトのCookieやデータへのアクセスを遮断することにあります。ブラウザプロセスは、どのサイトが専用プロセスを必要とするかに基づいて、各レンダラープロセスのCookieや他リソースへのアクセスを制限します。
         
    
-        
    
+        
    
           7-3. V8 Sandbox:JavaScriptエンジン自体を隔離する
         
    
         
    
@@ -935,7 +1286,11 @@ 
    
     V8Heap -->|メモリ破壊が発生しても脱出不可| Boundary["サンドボックス境界"]
     Boundary -.->|通常はアクセス不可| ProcessMemory["レンダラープロセスの<br/>その他のメモリ"]
-        
    
+        
    
           7-4. Chrome拡張機能開発者向け:sandboxディレクティブのベストプラクティス
         
    
         
    
@@ -1382,16 +1737,6 @@ 
    ⑤ ブラウザ
    
 
         // Observe the visible heading that follows each anchor, not the zero-height anchor itself
         // (a zero-area target can fail to register as "intersecting" in some browsers).
-        var sections = navLinks
-          .map(function (a) {
-            var anchor = document.querySelector(a.getAttribute('href'));
-            if (!anchor) return null;
-            var wrapper = anchor.closest('p') || anchor;
-            var el = wrapper.nextElementSibling;
-            while (el && el.tagName !== 'H2') el = el.nextElementSibling;
-            return el;
-          })
-          .filter(Boolean);
         var hashBySection = new Map();
         navLinks.forEach(function (a) {
           var anchor = document.querySelector(a.getAttribute('href'));
@@ -1401,8 +1746,8 @@ 
    ⑤ ブラウザ
    
           while (el && el.tagName !== 'H2') el = el.nextElementSibling;
           if (el) hashBySection.set(el, a.getAttribute('href'));
         });
+        var sections = Array.from(hashBySection.keys());
 
-        // Observer dedicated to nav-link highlighting: thin band near top of viewport
         var highlightObserver = new IntersectionObserver(
           function (entries) {
             entries.forEach(function (entry) {

From 4843f310b27a6ea0c128c01eb387ba17ac9a3e94 Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 12:53:15 +0900
Subject: [PATCH 05/53] docs(codex): add OpenAI Codex best practices and
 multi-agent guides

---
 ...odex-agents-multiagent-best-practices.html | 1622 ++++++++++++
 Openai-codex-best-practices-2026.html         | 2221 +++++++++++++++++
 Openai-codex-best-practices-2026.md           |  521 ++++
 3 files changed, 4364 insertions(+)
 create mode 100644 Openai-codex-agents-multiagent-best-practices.html
 create mode 100644 Openai-codex-best-practices-2026.html
 create mode 100644 Openai-codex-best-practices-2026.md

diff --git a/Openai-codex-agents-multiagent-best-practices.html b/Openai-codex-agents-multiagent-best-practices.html
new file mode 100644
index 00000000..6c67bf30
--- /dev/null
+++ b/Openai-codex-agents-multiagent-best-practices.html
@@ -0,0 +1,1622 @@
+
+
+  
+    
+    
+    OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド
+    
+    
+    
+    
+    
+  
+  
+    
    
+      
+      
+      
    
+        
    
+          
    OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド
    
+          
    
+            AGENTS.md・AGENTS.override.md・SKILL.md・config.toml・requirements.toml
+            で構築するマルチエージェントワークフロー
+          
    
+          
    
+            対象読者: Codex CLI / Codex Cloud を使ったチーム開発の経験がある中級〜上級エンジニア
+          
    
+          
    
+            最終更新:2026年7月29日時点の公式ドキュメント・コミュニティ記事に基づく
+          
    
+        
    
+
+        
    
+        
    
+          この記事の前提: 「REQUIREMENTS.md」について一点補足
+        
    
+        
    
+          ご依頼の中で REQUIREMENTS.md
+          という名称が挙がっていますが、Codex エコシステムに実在するのは
+          requirements.toml（Markdown ではなく TOML 形式の管理者施行ファイル）です。本ガイドでは実際の仕様に忠実に
+          requirements.toml
+          として解説します。名前は近いものの、役割・書式・配置場所はまったく別物なので、移行時に検索して見つからず戸惑わないよう最初に明記しておきます。
+        
    
+        
    
+
+        
    
+        
    Step 1. Codex エコシステム全体像
    
+        
    
+          Codex
+          の「設定・指示・能力拡張・実行制御」は、役割の異なる複数のファイル群によって階層的に構成されています。まず全体の関係を俯瞰します。
+        
    
+        
    +flowchart TB
+    A["~/.codex/AGENTS.override.md"] -->|"優先"| B["~/.codex/AGENTS.md"]
+    B --> C["グローバル指示 確定"]
+    C --> D["プロジェクトルート AGENTS.override.md / AGENTS.md"]
+    D --> E["サブディレクトリ AGENTS.override.md / AGENTS.md"]
+    E --> F["結合済みプロンプト（project_doc_max_bytesまで）"]
+    G["config.toml / requirements.toml"] --> H["ランタイム挙動（承認方針・サンドボックス・モデル）"]
+    I["SKILL.md"] --> J["能力の拡張（Progressive Disclosure）"]
+    F --> K["Codex セッション開始"]
+    H --> K
+    J --> K
+    K --> L["サブエージェントへ委譲（spawn_agent）"]
    
+        
    
+          
+            
+              
+                
+                
+                
+                
+              
+            
+            
+              
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+              
+              
+                
+                
+                
+                
+              
+            
+          
    ファイル役割書式主なスコープ
    AGENTS.mdエージェントへの恒久的な指示(規約・ワークフロー)Markdownユーザー / プロジェクト / サブディレクトリ
    AGENTS.override.md同階層の AGENTS.md を完全に置き換える一時的な指示Markdown同上(各階層に1つだけ有効)
    SKILL.md再利用可能な手順・スクリプト・参照資料をまとめた「スキル」Markdown + フォルダユーザー / プロジェクト / プラグイン
    config.tomlモデル・承認方針・サンドボックス・MCP・サブエージェントなどランタイム設定TOMLシステム / ユーザー / プロジェクト / プロファイル
    requirements.toml管理者が強制するセキュリティ上限(ユーザーは上書き不可)TOML組織全体(MDM・クラウドポリシー・ファイルシステム配布)
    
+        
    
+        
    
+          この5つは互いに独立した軸であり、「指示(何をすべきか)」「能力(何ができるか)」「実行制御(どこまで許可されるか)」の3層に分けて理解すると設計しやすくなります。
+        
    
+        
    
+        
    
+          Step 2. AGENTS.md ― 基本のプロジェクト指示ファイル
+        
    
+        
    
+          AGENTS.md
+          はプロジェクトやチームの規約・コーディングスタイル・テスト方法などをエージェントに伝える、Codex
+          起動時に自動的に読み込まれる自然言語の指示ファイルです。特別なシステムAPIではなく、Codex
+          が Markdown
+          をそのままプロンプトの一部として注入する仕組みであるため、書き方は「新しいチームメンバー向けのオンボーディング資料」を書くのに近い感覚で構いません。
+        
    
+        
    実務上のベストプラクティス:
    
+        
      
+          
    • 
+            短く、具体的に。
+            一般論(「良いコードを書いてください」)ではなく、「このリポジトリでは
+            pnpm test を実行する」「src/legacy/
+            配下は変更禁止」のように、検証可能な具体指示に寄せる。
+          
      • 
+          
    • 
+            強制力のあるインフラと組み合わせる。
+            AGENTS.md に書いたルールは pre-commit
+            フック・リンター・型チェッカーと組み合わせることで、エージェントが同じミスを繰り返さないよう「システム側で気づける」ようにする。
+          
      • 
+          
    • 
+            グローバルとリポジトリで役割を分ける。
+            ~/.codex/AGENTS.md(グローバル)はレビューのトーンや詳細度などエージェントとの対話スタイルに、リポジトリの
+            AGENTS.md
+            はチーム・コードベース固有の規約に専念させる。
+          
      • 
+        
    
+        
    
+        
    
+          Step 3. AGENTS.override.md ― 一時的な上書きレイヤー
+        
    
+        
    
+          AGENTS.override.md は同じディレクトリにある
+          AGENTS.md
+          を完全に置き換えるための仕組みです。「一部だけ変更したい」場合の差分ファイルではなく、その階層で発見されると
+          AGENTS.md は無視され、override
+          ファイルの内容だけが採用されます。
+        
    
+        
    典型的な使いどころ:
    
+        
      
+          
    • 
+            一時的な移行作業やインシデント対応中だけ、通常の規約(慎重な段階的コミットなど)を外して別の作業モードに切り替えたいとき
+          
      • 
+          
    • 
+            CI 専用セッションや検証用ブランチなど、恒久的な
+            AGENTS.md を書き換えずに一時的な挙動を注入したいとき
+          
      • 
+          
    • 
+            個人のローカル環境だけ挙動を変えたいが、リポジトリにコミットする
+            AGENTS.md は触りたくないとき(.gitignore に
+            AGENTS.override.md を加えて個人用に運用)
+          
      • 
+        
    
+        
    
+        
    Step 4. 発見順序とマージロジックの詳細
    
+        
    
+          Codex は CODEX_HOME(既定
+          ~/.codex)のグローバル階層から、プロジェクトルートを経て現在の作業ディレクトリ(CWD)まで、ディレクトリを1段ずつ辿りながら指示ファイルを探索します。
+        
    
+        
    +sequenceDiagram
+    participant U as Codex起動
+    participant G as グローバルスコープ(~/.codex)
+    participant P as プロジェクトルート
+    participant S as サブディレクトリ(CWD)
+    U->>G: AGENTS.override.md を検索
+    G-->>U: なければ AGENTS.md を読込
+    U->>P: AGENTS.override.md を検索
+    P-->>U: なければ AGENTS.md / fallback を読込
+    U->>S: 現在の作業ディレクトリまで同様に走査
+    S-->>U: 各階層で最大1ファイルを採用
+    U->>U: ルートから順に連結（空行区切り）
+    Note over U: 近い階層のファイルほど後方に配置され優先度が高い
    
+        
    補足として押さえておきたい設定キー:
    
+        
      
+          
    • 
+            project_doc_fallback_filenames:
+            AGENTS.md
+            が見つからない階層で代わりに読み込むファイル名のリストを指定可能。既存の
+            README
+            や社内規約ファイル名をそのまま流用したい場合に使う。
+          
      • 
+          
    • 
+            project_doc_max_bytes: 連結後の指示テキストの合計サイズ上限。大きすぎる
+            AGENTS.md
+            群は自動的に切り詰められるため、重要な指示ほどファイルの先頭近くに書く。
+          
      • 
+          
    • 
+            model_instructions_file:
+            AGENTS.md
+            の自動読み込みそのものを別ファイルで完全に置き換えるための設定キー(旧名
+            experimental_instructions_file
+            は非推奨、新設定への移行が必要)。階層探索ロジックごと差し替える強力なオプションなので、通常は
+            AGENTS.md/AGENTS.override.md の組み合わせで足りることが多い。
+          
      • 
+        
    
+        
    
+        
    Step 5. config.toml ― 階層構造とスコープ
    
+        
    
+          config.toml
+          はモデル選択・承認ポリシー・サンドボックスモード・MCPサーバー・サブエージェント上限など、Codex
+          の振る舞いを決めるランタイム設定です。指示ファイル(AGENTS.md系)とは異なるレイヤーで、以下の順に解決されます。
+        
    
+        
    +flowchart TB
+    A["CLIフラグ / -c key=value（セッション限定）"] --> E["合成された希望設定"]
+    B["プロジェクトスコープ .codex/config.toml（ルート→CWD、信頼済みのみ）"] --> E
+    C["プロファイル --profile 指定時の設定ファイル"] --> E
+    D["ユーザースコープ ~/.codex/config.toml"] --> E
+    E --> F["requirements.toml による検証（管理者施行の上限・強制値）"]
+    F --> G["最終的な実行時設定"]
    
+        
    実務上のポイント:
    
+        
      
+          
    • 
+            プロジェクト直下の .codex/config.toml は、そのプロジェクトを
+            trusted(信頼済み)
+            と判断した場合のみ読み込まれます。未信頼のプロジェクトでは、プロジェクトスコープの
+            config・hooks・rules は一切ロードされず、ユーザー / システムスコープのみが有効です。
+          
      • 
+          
    • 
+            「プロジェクト設定が効かない」という相談の多くは、実は該当キーがプロジェクトスコープでは無視される予約キー(model_provider・notify・profile
+            など、認証やテレメトリに関わるもの)であるケースです。これらはユーザースコープの
+            ~/.codex/config.toml で設定する必要があります。
+          
      • 
+          
    • 
+            --profile profile-name を指定すると
+            ~/.codex/profile-name.config.toml
+            を読み込みます。共通設定は
+            config.toml
+            に、環境差分だけをプロファイルファイルに分離するのが推奨構成です。
+          
      • 
+          
    • 
+            ファイル冒頭に
+            #:schema https://developers.openai.com/codex/config-schema.json
+            を書いておくと、対応エディタでキー補完とバリデーションが効きます。
+          
      • 
+        
    
+        
    
+        
    
+          Step 6. config.toml の主要キーとスキーマ
+        
    
+        
    中級〜上級者が実際に触ることになる主要キーを機能別に整理します。
    
+        
    
+          
+            
+              
+                
+                
+                
+              
+            
+            
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+            
+          
    カテゴリキー例概要
    モデル
+                  model, review_model,
+                  model_reasoning_effort, model_reasoning_summary,
+                  model_verbosity
+                既定モデル・レビュー専用モデル・reasoning の強度や要約詳細度
    プロバイダmodel_provider, model_providers.<id>
+                  組み込み(openai/ollama/lmstudio)以外の独自プロバイダ定義
+                
    承認/サンドボックス
+                  approval_policy, sandbox_mode,
+                  approval_policy.granular.*
+                
+                  untrusted/on-request/never
+                  などの承認方針と、sandbox_approval・skill_approval・mcp_elicitations
+                  の粒度別トグル
+                
    ネットワーク
+                  features.network_proxy, features.network_proxy.domains
+                ドメイン単位の allow/deny を伴うネットワークプロキシ機能
    サブエージェント
+                  agents.<name>.config_file, agents.max_depth,
+                  agents.max_threads, features.multi_agent
+                
+                  カスタムエージェント定義への参照、再帰の深さ・並列数の上限、マルチエージェント機能全体のオン/オフ
+                
    Hooks[hooks](インライン)または hooks.jsonライフサイクルフックの定義(後述)
    MCPmcp_servers.<id>Model Context Protocol サーバーの登録
    その他
+                  file_opener, request_max_retries,
+                  stream_max_retries, notify, otel
+                エディタ連携・リトライ・通知・テレメトリ
    
+        
    
+        
    
+          補足: instructions キーは将来のための予約で、実際には
+          model_instructions_file または
+          AGENTS.md を使うのが現行の正しい方法です。
+        
    
+        
    
+          以下は、上記キーの一部を実際に組み合わせた ~/.codex/config.toml の例です。
+        
    
+        
    #:schema https://developers.openai.com/codex/config-schema.json
+
+model = "gpt-5.4"
+review_model = "gpt-5.5"
+model_reasoning_effort = "high"
+model_verbosity = "medium"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[approval_policy.granular]
+sandbox_approval = true
+skill_approval = true
+mcp_elicitations = false
+
+[agents]
+max_depth = 2
+max_threads = 4
+
+[agents.security_reviewer]
+config_file = "~/.codex/agents/security-reviewer.toml"
+
+[features.network_proxy]
+enabled = true
+domains = { "api.github.com" = "allow", "example.com" = "deny" }
    
+        
    
+        
    
+          Step 7. requirements.toml ― 管理者施行の強制設定
+        
    
+        
    
+          requirements.toml は、個人やプロジェクトの
+          config.toml
+          では上書きできない、組織のセキュリティチームが強制する設定です。「ユーザーの利便性のための既定値」ではなく「絶対に譲れない下限・上限」を書く場所だと考えてください。
+        
    
+        
    主な特徴:
    
+        
      
+          
    • 
+            クラウドポリシー、macOS/Windows の
+            MDM(Jamf・Kandji・Mosyle等)、あるいは単純なファイル配布の3経路で組織全体に配布可能。
+          
      • 
+          
    • 
+            例: approval_policy = "never" や
+            sandbox_mode = "danger-full-access"
+            を組織全体で禁止する、といった強制。
+          
      • 
+          
    • 
+            併用される managed_config.toml
+            は「ソフトな既定値」を配布するためのファイルで、ユーザーが必要なら上書きできる点が
+            requirements.toml との決定的な違いです。「ハードな制約は
+            requirements.toml、ソフトな既定値は
+            managed_config.toml」という役割分担で覚えると混同しません。
+          
      • 
+          
    • 
+            [features] テーブルを使うことで、config.toml
+            と同じキー名でフィーチャーフラグそのものを固定できます(省略したキーは制約なし)。
+          
      • 
+          
    • 
+            allow_managed_hooks_only = true
+            を設定すると、ユーザー・プロジェクト・セッション単位の hooks を無視し、管理レイヤーの
+            hooks のみを有効にできます。
+          
      • 
+          
    • 
+            ChatGPT Business/Enterprise では、ローカルファイルに加えてクラウド側から取得した
+            requirements も適用されます(優先順位はセキュリティドキュメントで規定)。
+          
      • 
+        
    
+        
    
+        
    
+          Step 8. SKILL.md ― Progressive Disclosure によるスキル拡張
+        
    
+        
    
+          Skill は「フォルダ + SKILL.md(メタデータ)+
+          必要に応じたスクリプトや参照資料」という構成を取り、Codex
+          に再利用可能な手順を教える仕組みです。ポイントは
+          Progressive Disclosure(段階的開示)
+          というロード方式です。
+        
    
+        
      
+          
    • Codex は起動時、各スキルの説明(description)だけを読み込みます。
      • 
+          
    • 
+            タスクに関連しそうだと判断したスキルについてのみ、SKILL.md
+            の本文やスクリプト・参照資料をその都度ロードします。
+          
      • 
+          
    • これにより、大量のスキルを登録してもコンテキストウィンドウを圧迫しません。
      • 
+        
    
+        
    配置場所と実行方式:
    
+        
    
+          
+            
+              
+                
+                
+              
+            
+            
+              
+                
+                
+              
+              
+                
+                
+              
+            
+          
    実行方式概要
    ローカル実行(local shell)インフラを自前管理したい場合に、実行をローカル環境に閉じ込める
    ホスト型コンテナ実行
+                  Codex
+                  側が用意するコンテナで実行。コンテナのライフサイクルに合わせてマウントしたファイルも保持・破棄される
+                
    
+        
    
+        
    
+          スキルが MCP サーバーに依存する場合は
+          agents/openai.yaml にその依存関係を宣言しておくと、Codex
+          が自動的にインストール・接続まで面倒を見てくれます。
+        
    
+        
    
+        
    Step 9. Skills 運用のベストプラクティス
    
+        
    
+          公式ガイダンスが強調しているのは「スキルは開発者が事前に検証してから配布する」という原則です。
+        
    
+        
      
+          
    • 
+            スキルは開発者がレビュー・統合したうえで、特定のプロダクトワークフローに紐づけてエンドユーザーに提供する。
+          
      • 
+          
    • 
+            エンドユーザーが任意のスキルを自由に選べる状態を避ける(スコープを絞ったUX経由でのみ呼び出す)。
+          
      • 
+          
    • 
+            書き込みや影響範囲の大きい操作を行うスキルは、明示的な承認とポリシーチェックをゲートとして挟む。
+          
      • 
+          
    • 
+            「一度きりの手順」は AGENTS.md
+            の指示で十分な場合が多く、「繰り返し使う複雑な手順・スクリプト・参照資料が伴うもの」こそスキル化する価値がある、という使い分けが実務的です。
+          
      • 
+          
    • 
+            社内で頻繁に使うスキルはプラグインとしてパッケージ化し、マーケットプレイス経由でチーム配布すると、hooks
+            やスキルをまとめて一貫バージョンで展開できます。
+          
      • 
+        
    
+        
    
+        
    
+          Step 10. Subagents の概念 ― コンテキスト汚染とコンテキスト腐敗
+        
    
+        
    
+          Subagents(サブエージェント)は 2026年3月16日に GA(一般提供)となった機能で、Codex は既定で
+          explorer(調査系)・worker(バッチ処理系)・default
+          という3種類の組み込みエージェントを持ちます。サブエージェントを使う最大の動機は、メインスレッドのコンテキストを汚さないことです。
+        
    
+        
    +flowchart LR
+    A["メインエージェント（要件・意思決定）"] --> B["探索ノート・テストログ・コマンド出力が蓄積"]
+    B --> C["コンテキスト汚染 Context Pollution"]
+    C --> D["コンテキスト腐敗 Context Rot"]
+    D --> E["応答品質の低下"]
+    F["サブエージェントへ委譲"] --> G["ノイズの多い作業を分離"]
+    G --> H["要約のみメインへ返却"]
+    H --> A
    
+        
    
+          大きなタスクを1本のスレッドで処理し続けると、探索過程のログやコマンド出力が蓄積してコンテキスト汚染が起こり、それが進行すると関連情報が埋もれて応答品質が落ちる**コンテキスト腐敗(Context
+          Rot)**につながります。サブエージェントは、ノイズの多い調査やバッチ作業を隔離したスレッドに切り出し、要約だけをメインへ返すことでこれを防ぎます。
+        
    
+        
    
+          ただし無料ではありません。公式ドキュメントも警告している通り、サブエージェントは同等の単一エージェント実行より多くのトークンを消費します。著名な開発者
+          Simon Willison
+          氏も、並列エージェント運用について「本当のボトルネックは自分がどれだけ速く結果をレビューできるかだ」という趣旨の指摘を自身のブログで行っており、オーケストレーションはタイピングの負荷をレビューの負荷に移すだけだと戒めています。設計時は「並列化すれば必ず速くなる」という前提を置かず、レビュー体制とセットで計画することが重要です。
+        
    
+        
    
+        
    
+          Step 11. カスタムサブエージェント定義ファイル
+        
    
+        
    
+          組み込みの3エージェントに加えて、~/.codex/agents/ 配下に TOML
+          ファイルを置くことで独自のサブエージェントを定義できます。名前を指定して呼び出せるほか、エージェントごとに異なるモデルを割り当てることも可能です(例:
+          高速性を優先するなら gpt-5.3-codex-spark を指定するなど)。
+        
    
+        
    
+          サブエージェントのオーケストレーションは Codex
+          本体が受け持ち、次のような操作を内部的に扱います。
+        
    
+        
    
+          
+            
+              
+                
+                
+              
+            
+            
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+              
+                
+                
+              
+            
+          
    操作概要
    spawn_agent新しいサブエージェントスレッドを起動
    send_input起動済みのサブエージェントへ追加指示を送信
    resume_agent中断していたサブエージェントを再開
    wait_agentサブエージェントの完了を待機
    close_agentサブエージェントのスレッドを終了
    
+        
    
+        
    
+          config.toml 側では
+          agents.max_depth(何段まで入れ子でサブエージェントを起動できるか)と
+          agents.max_threads(同時並列数)で暴走を防ぎます。トリガーは特別なコマンドではなく自然言語で構いません。「レビュー観点ごとにエージェントを1つずつ立ち上げて、すべて完了したら結果をまとめて」と指示するだけで、Codex
+          が複数スレッドを開いて集約します。
+        
    
+        
    ~/.codex/agents/security-reviewer.toml の例:
    
+        
    name = "security_reviewer"
+description = "セキュリティ観点のみに特化した読み取り専用レビュー担当"
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+instructions = """
+あなたはセキュリティレビュー専任のサブエージェントです。
+認証・認可・シークレット管理・依存パッケージの既知脆弱性のみに焦点を当て、
+スタイルや命名規則には言及しないでください。
+"""
    
+        
    
+        
    
+          Step 12. マルチエージェントワークフロー設計パターン①: PRレビューの3分割
+        
    
+        
    
+          実務でよく使われる型の一つが、プルリクエストのレビューをコード探索・レビュー・外部仕様確認の3系統に分ける並列パターンです。
+        
    
+        
    +flowchart TB
+    U["開発者のプロンプト：このブランチをレビューして"] --> M["メインCodexセッション"]
+    M --> P1["pr_explorer（読み取り専用・コード調査）"]
+    M --> P2["reviewer（正確性・セキュリティ・テスト）"]
+    M --> P3["docs_researcher（MCP経由でAPI仕様確認）"]
+    P1 --> R["各エージェントの結果を収集"]
+    P2 --> R
+    P3 --> R
+    R --> S["メインエージェントが統合要約"]
    
+        
    設計のコツ:
    
+        
      
+          
    • 
+            役割ごとに読み書き権限を分ける。
+            コード調査担当は読み取り専用サンドボックスに固定し、変更を加える担当だけ書き込み権限を持たせる。
+          
      • 
+          
    • 
+            外部情報の検証は専任エージェントに。
+            MCP経由でドキュメントや実サービスの仕様を突き合わせる作業は、コードレビューと混ぜずに独立させると、メインの思考が汚れません。
+          
      • 
+          
    • 
+            集約は必ずメインエージェントが行う。
+            各サブエージェントの結果をそのまま並べるのではなく、メインが矛盾点や優先度を踏まえて再統合することで、レビュー全体の一貫性を保ちます。
+          
      • 
+        
    
+        
    
+        
    
+          Step 13. マルチエージェントワークフロー設計パターン②: CSVファンアウト
+        
    
+        
    
+          多数の小タスクを一括処理したい場合(例:
+          リポジトリ内の全コンポーネントに同じ改修を適用する)は、CSVを起点にしたファンアウトパターンが有効です。
+        
    
+        
    +flowchart TB
+    A["components.csv（path, owner）"] --> B["spawn_agents_on_csv"]
+    B --> C["行ごとに1ワーカーを起動（max_concurrencyまで並列）"]
+    C --> D["各ワーカーが report_agent_job_result を1回呼出"]
+    D --> E["結果を output_csv_path へ集約（job_id, status, result_json）"]
    
+        
    
+          このパターンは
+          worker
+          系エージェントが得意とする領域で、CSVの行数分だけワーカーを起動し、max_concurrency
+          で同時実行数を絞りつつ、各ワーカーが結果を1回だけ報告して指定した出力CSVに集約させます。大量の定型タスクをレビュー可能な単位に分割したいときの定番構成です。
+        
    
+        
    入力となる components.csv の最小例:
    
+        
    path,owner
+src/services/billing,team-payments
+src/services/auth,team-identity
+src/services/search,team-platform
    
+        
    このCSVを渡す際のプロンプト例:
    
+        
    components.csv の各行についてworkerサブエージェントを1つずつ起動し、
+max_concurrency=3で並列実行してください。
+各workerはpathの配下でdeprecated APIの呼び出しを検出し、
+report_agent_job_resultで結果を1回だけ報告し、
+最終的にresults.csvへ集約してください。
    
+        
    
+        
    
+          Step 14. モデル・reasoning effort の選定指針
+        
    
+        
    
+          すべてのサブエージェントに同じモデルを割り当てる必要はありません。タスクの性質に応じて使い分けることで、コストと品質のバランスを取れます。
+        
    
+        
    +flowchart TB
+    A["サブエージェントのタスク性質は？"] --> B{"曖昧・多段階・要検証？"}
+    B -- Yes --> C["gpt-5.5（高能力の起点として推奨）"]
+    B -- No --> D{"低遅延・大量の対話的反復が必要？"}
+    D -- Yes --> E["gpt-5.3-codex-spark（Cerebras上で高速動作）"]
+    D -- No --> F["gpt-5.4（安定版の既定ワークフロー）"]
    
+        
    
+          加えて model_reasoning_effort(例: xhigh)や
+          model_reasoning_summary(detailed
+          など)は、探索系のエージェントには高め、定型的なバッチワーカーには低めに設定するなど、エージェントごとの
+          config.toml
+          参照(agents.<name>.config_file)で個別最適化するのが実務的です。モデル名やバリアントは頻繁に更新されるため、実際に指定する前に
+          codex models
+          や利用中のプロバイダのカタログで最新の識別子を確認してください。
+        
    
+        
    
+        
    
+          Step 15. Hooks と Rules(execpolicy) によるガバナンス
+        
    
+        
    
+          サブエージェントを増やすほど、「何を承認なしで実行してよいか」の統制が重要になります。Codex
+          にはこれを扱う2つの仕組みがあります。
+        
    
+        
    
+          Hooks: PermissionRequest 型のフックでコマンド実行前に
+          allow/deny を判定し、複数のフックが競合した場合は deny が優先されます。PostToolUse
+          フックは
+          Bash・apply_patch・MCPツール呼び出しの後に発火しますが、まだ全てのシェル呼び出しを捕捉できるわけではない点(新しい
+          unified_exec
+          系統は途上)には注意が必要です。プロジェクトローカルの hooks
+          は、そのプロジェクトが信頼済みの場合のみ読み込まれます。
+        
    
+        
    
+          Rules(execpolicy): .rules
+          ファイル(Starlark構文)で
+          prefix_rule(pattern=..., decision="allow"|"prompt"|"forbidden",
+            justification="...")
+          を定義し、コマンドの引数列とパターンを照合します。複数ルールが一致した場合は最も制限の強い判定(forbidden
+          > prompt > allow)が採用されます。codex execpolicy check --rules <file> -- <command>
+          でルールの動作を事前検証できるため、大規模なサブエージェント運用を始める前にルールセットをテストしておくと安全です。管理者は
+          requirements.toml から制限的な
+          prefix_rule を強制することもできます。
+        
    
+        
    ~/.codex/rules/default.rules の例:
    
+        
    prefix_rule(
+    pattern = ["git", "push"],
+    decision = "prompt",
+    justification = "リモートへの反映は必ず人間の確認を挟む",
+)
+
+prefix_rule(
+    pattern = ["rm", "-rf"],
+    decision = "forbidden",
+    justification = "破壊的削除は禁止。個別ファイル指定のrmを使うこと。",
+)
+
+prefix_rule(
+    pattern = ["gh", ["pr", "issue"], ["view", "list"]],
+    decision = "allow",
+    justification = "読み取り専用のgh操作は常に許可",
+)
    
+        
    検証コマンド:
    
+        
    codex execpolicy check --pretty \
+  --rules ~/.codex/rules/default.rules \
+  -- git push origin main
    
+        
    
+        
    Step 16. 実践チェックリスト
    
+        
      
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+          
    • 
+            
+          
      • 
+        
    
+        
    
+        
    Step 17. トラブルシューティング
    
+        
    
+          
+            
+              
+                
+                
+                
+              
+            
+            
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+              
+                
+                
+                
+              
+            
+          
    症状よくある原因対処
    プロジェクトの config.toml が効かない
+                  プロジェクトが untrusted
+                  扱い、または予約キー(model_provider・notify・profile
+                  等)を使っている
+                
+                  プロジェクトを信頼済みにする/該当キーはユーザースコープの
+                  ~/.codex/config.toml に移す
+                
    AGENTS.md の指示が反映されない同階層に AGENTS.override.md が存在し、そちらが優先されているoverride ファイルの有無を確認し、意図しないものであれば削除する
    指示の一部が無視されている
+                  連結後の合計サイズが project_doc_max_bytes を超えて切り詰められている
+                重要な指示をファイル先頭に移動する、または上限を引き上げる
    hooks が急に効かなくなった
+                  requirements.toml の
+                  allow_managed_hooks_only = true により、管理外の hooks
+                  が無効化されている
+                管理者に確認し、必要な hooks を管理レイヤー側で登録してもらう
    サブエージェントがコストを消費しすぎる
+                  並列度・再帰深さの上限が未設定、またはモデル選定が一律で高コストなものになっている
+                
+                  agents.max_threads/agents.max_depth
+                  を設定し、探索系タスクには軽量なモデルを割り当てる
+                
    
+        
    
+        
    
+        
    Step 18. まとめ
    
+        
    
+          Codexのマルチエージェント開発は、「エージェントに何をすべきか教える層(AGENTS.md/override)」「繰り返し使える能力を教える層(SKILL.md)」「実行時の挙動を決める層(config.toml)」「組織として絶対に譲れない制約を敷く層(requirements.toml)」という4層構造で理解すると設計がぶれません。そのうえでサブエージェントは、コンテキスト汚染を防ぐための「隔離」の道具であり、並列化そのものが目的ではなく、レビュー体制とセットで初めて効果を発揮する点を忘れないことが、中級者から上級者へステップアップする際の分岐点になります。
+        
    
+        
    
+        
    参考文献
    
+        
+      
    
+    
    
+
+    
+    
+    
+  
+
diff --git a/Openai-codex-best-practices-2026.html b/Openai-codex-best-practices-2026.html
new file mode 100644
index 00000000..e8801011
--- /dev/null
+++ b/Openai-codex-best-practices-2026.html
@@ -0,0 +1,2221 @@
+
+
+  
+    
+    
+    OpenAI Codex ベストプラクティスガイド 2026 — ステップバイステップ実践ガイド
+    
+    
+    
+    
+    
+  
+  
+    
    
+
+    
    
+      CODEX / BEST PRACTICES
+      
+    
    
+
+    
    
+      
+
+      
    
+        
    
+          
    
+            
    
+              
+                
+                  
+                  
+                
+                2026年7月28日時点の情報を集約
+              
+              
    OpenAI Codex
    ベストプラクティスガイド
    
+              
    
+                中級者から上級者のための、ステップバイステップ実践ガイド。プロンプト設計からAGENTS.md、サンドボックス設定、CI/CD統合、セキュリティ運用まで。
+              
    
+              
    
+                OpenAI公式ドキュメント(developers.openai.com/codex)と、Simon Willison・Armin
+                Ronacherら著名開発者の発信を横断調査して構成。バージョンや数値は執筆時点のものです。
+              
    
+            
    
+            
    
+              
    
+                
+                ~/workspace — codex
+              
    
+              
    
+                
    
+                  $ codex --sandbox workspace-write
+                
    
+                
    reading AGENTS.md ... 3 files found
    
+                
    approval_policy: on-request
    
+                
    
+                  /goal 本番リリースに向けてテストを安定させる
+                
    
+                
    plan → act → test を繰り返し中 ...
    
+                
    ✓ tests passing (14/14) — done.
    
+                
    $ 
    
+              
    
+            
    
+          
    
+        
    
+
+        
    
+          
    
+            Overview
+            
    1. Codexとは何か ― 2026年時点の全体像
    
+            
    
+              OpenAI
+              Codexは、単なる「コードを聞くとコードを返すチャットボット」ではなく、リポジトリを読み書きし、コマンドを実行し、テストを走らせ、プルリクエストを提案する自律的なコーディングエージェントです。2026年に入ってからは企業のエンジニアリング基盤に組み込まれる例が増えており、複数の業界メディアは週間アクティブ開発者数が400万人を超え、Cisco・Nvidia・Rampのような企業内でも採用が進んでいると報じています。
+            
    
+            
    
+              
+                
+                
+              
+              
    
+                数値についての注意これらの採用状況・利用者数はOpenAIの公式発表数値ではなく、各メディアの推計・報道に基づく参考情報です。Wikipediaの記事では2026年3月時点で週間アクティブユーザーが200万人を超えたと記録されており、短期間で利用が急拡大したことがうかがえます。
+              
    
+            
    
+
+            
    
+              Codexは以下の3つのサーフェス(利用面)にまたがって、同じ設定・同じAGENTS.md・同じSkillsを共有します。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                
+              
    サーフェス実行場所主な用途特徴
    Codex CLIローカル端末(Apache-2.0のOSS)ターミナルでの対話・非対話作業codex execでCI/CDにも組込み可能。8万スター超と報告
    IDE拡張機能VS Code / Cursor / Windsurf等エディタ内でのペアプログラミング開いているファイルや選択範囲を自動的にコンテキストへ含める
    Codex App / Cloudデスクトップアプリ + クラウド実行環境複数プロジェクト横断の並列作業ワークツリー管理、自動化、リモートのクラウドスレッド実行
    
+            
    
+
+            
    モデルの系譜(コミュニティ報告ベースの概観)
    
+            
    
+              正式名称や日付は変わる可能性があるため参考情報としてご覧ください。最新の対応モデル一覧は必ず公式の
+              Models – Codex
+              ページで確認してください。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    世代(通称)位置付け(報告ベース)
    codex-1(2025年5月)Codex Cloudのリサーチプレビューで最初に使われた、o3系ベースのモデル
    GPT-5-Codex 以降「Codex」がOpenAIのコーディング系モデル群のブランド名として定着
    GPT-5.1-Codex / Codex-Max長時間タスクや大規模コンテキストの圧縮(compaction)を強化
    GPT-5.2-CodexxHigh推論・セキュリティ系ベンチマークでの高評価が報告
    GPT-5.4ネイティブComputer Use、大規模コンテキスト窓
    GPT-5.5(2026年4月23日)
+                      Codexの既定モデルに。サブエージェント・MCP・Hooks・自動レビュー等が出揃った転換点と評される
+                    
    
+            
    
+          
    
+
+          
    
+            Core Concept
+            
    2. Codexの基本動作ループを理解する
    
+            
    
+              ベストプラクティスの前提として、Codexがどう動いているかを押さえておきましょう。プロンプトを送信すると、Codexは「モデルを呼び出す
+              →
+              出力が指示するアクション(ファイル読み書き・コマンド実行・ツール呼び出し)を実行する」というループを、タスクが完了するかユーザーがキャンセルするまで繰り返します。
+            
    
+            
    
+              
    
+                flowchart TD A[ユーザーがプロンプトを送信] --> B[Codexがモデルを呼び出す] B -->
+                C{モデル出力に基づき行動を決定} C --> D[ファイルの読み取り・編集] C -->
+                E["コマンド実行 (shell / apply_patch)"] C --> F[MCPツールの呼び出し] D -->
+                G[実行結果をコンテキストへ反映] E --> G F --> G G --> H{タスクは完了したか?} H --
+                未完了・コンテキストが逼迫 --> I["Compaction: 古い情報を要約して圧縮"] I --> B H --
+                未完了 --> B H -- 完了 --> J[結果を提示しレビュー待ち]
+              
    
+            
    
+            
    
+              スレッド内の情報はすべてモデルのコンテキストウィンドウに収まる必要があります。長時間タスクでは自動的にCompaction(圧縮)が働き、関連情報を要約しながら作業を継続します。この仕組みを理解しておくと、長時間タスクの後半で挙動が変わる理由を把握しやすくなります。
+            
    
+          
    
+
+          
    
+            Step 01
+            
    効果的なプロンプトを設計する
    
+            
    
+              Codexは曖昧なプロンプトでも一定の成果を出せるほど賢くなっていますが、公式ガイドは大規模・複雑なリポジトリほど「プロンプトの型」が結果の安定性を左右すると説明しています。次の4要素を意識することが推奨されています。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                
+              
    要素問いかけ記入例
    Goal(目的)何を変更・構築したいか/api/postsにページネーションを追加する
    Context(文脈)どのファイル・エラーが関係するかExpress.js、PostgreSQL。既存の/api/users実装に従う
    Constraints(制約)従うべき規約・安全要件は何かDBスキーマは変更しない。新規npmパッケージ追加不可
    Done when(完了条件)何が真になれば完了かページ2が正しく返り、既存テストが通ること
    
+            
    
+            
    
+              特に「Done
+              when」を明示することは、タスクが中途半端に終わったり、逆に過剰な作業をしてしまったりするのを防ぐ効果があると複数の実践者が指摘しています。
+            
    
+
+            
    Reasoning Effort(推論の深さ)を使い分ける
    
+            
    
+              Codexおよび背後のGPT-5系モデルはreasoning.effort(CLIではmodel_reasoning_effort)というパラメータで思考の深さを調整できます。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    レベル想定用途
    none / minimal
+                      変数名の一括変更等、ごく単純な機械的編集(非対応モデルは自動で近いレベルへ丸められる)
+                    
    lowスコープが明確で高速に終わらせたい作業
    
+                      medium
+                    既定値。通常の開発作業に対する品質とコストのバランスが良い
    high複数モジュールにまたがる調査、原因不明のバグ調査、設計判断
    xhigh(Extra High)大規模リファクタ、マイグレーション、本番影響のあるセキュリティレビュー
    
+            
    
+            
    
+              xhighはコスト・レイテンシが数倍に膨らむ可能性があるため、「まずはmediumで試し、足りない場合だけ引き上げる」運用が現実的です。サブエージェント構成では、親エージェントをhigh、定型作業を担う子エージェントをlow〜mediumに設定してコストを抑えるパターンも報告されています。
+            
    
+
+            
    
+              Armin Ronacher ― Flask/Jinja2の作者
+              
    
+                エージェント文脈ではシンプルなコードが複雑なコードより明確に有利であり、エージェントには動作する最も愚直な実装をやらせるべきだ、という趣旨の助言を繰り返し発信しています。これはプロンプト設計にもそのまま当てはまり、Constraintsで過度に凝った設計を要求しない方が結果が安定します。
+              
    
+            
    
+          
    
+
+          
    
+            Step 02
+            
    難しいタスクはまず計画させる
    
+            
    
+              タスクが複雑・曖昧な場合、いきなり実装させるのではなく計画フェーズを挟むことが推奨されています。方法は主に3つあります。
+            
    
+            
      
+              
    1. 
+                Plan mode(/plan または Shift+Tab):
+                Codexが先に文脈を集め、疑問点を確認し、実装前に計画を提示します。多くのユーザーにとって最も手軽で効果的な方法です。
+              
      2. 
+              
    2. 
+                Codexにインタビューさせる:
+                ぼんやりとしたアイデアしかない場合、「まず質問して、前提を疑ってから具体化して」と指示します。
+              
      3. 
+              
    3. 
+                Goal mode(/goal):
+                タスクが数ターン以上かかり、道筋は不確実だが完了条件は明確な場合に使う永続的な目標機能です。config.tomlでfeatures.goals = trueを設定するか、codex features enable goalsで有効化します。
+              
      4. 
+            
    
+
+            
    
+              
    
+                flowchart TD T[新しいタスクが来た] --> Q{タスクの性質は?} Q --
+                小さく明確・1ターンで完結 --> A[通常のプロンプトを直接送る] Q --
+                複雑・曖昧で設計が必要 --> B["/plan で計画を立てさせる
    (必要なら「まず質問して」と依頼)"]
+                Q -- ゴールは明確だが道筋が不確実で
    複数ターンかかる --> C["/goal
+                で永続的な目標を設定
    (完了条件=検証可能な証拠)"] B --> D[計画をレビューし承認]
+                D --> E[実装を開始] C --> F["Codexが自律的にplan→act→testを繰り返す"]
+              
    
+            
    
+
+            
    
+              Goalの書き方には注意が必要です。「もっと良くして」のような曖昧な終着点は信頼できる完了条件になりません。「厳格モードでコンパイルが通り、any型が残っていないこと」のように、測定可能な成功条件を書くことが推奨されています。
+            
    
+            
    
+              
+                
+              
+              
    
+                実践事例あるエンジニアが夜間にGoalモードでパフォーマンス最適化タスクを設定し、ノートPCを閉じて5時間半後に戻ったところ、テストとベンチマークの両方をクリアした状態で作業が完了していた、という事例が紹介されています。ただしGoalはデータの欠落や不確実性を隠す手段にしてはならず、そうした前提はGoal自体に明記すべきだとされています。
+              
    
+            
    
+          
    
+
+          
    
+            Step 03
+            
    AGENTS.mdで恒久的なガイダンスを構築する
    
+            
    
+              同じ指示を毎回プロンプトに書き直すのは非効率です。ここで使うのがAGENTS.mdです。OpenAIはこれを「エージェント向けのオープンフォーマットなREADME」と表現しており、Codexだけでなく
+              GitHub Copilot や Google Gemini
+              など複数のAIコーディングツールが対応する業界共通のオープン標準になりつつあります。
+            
    
+
+            
    何を書くべきか
    
+            
      
+              
    • リポジトリの構成と重要なディレクトリ
      • 
+              
    • プロジェクトの起動方法
      • 
+              
    • ビルド・テスト・Lintコマンド
      • 
+              
    • エンジニアリング上の規約とPRの期待値
      • 
+              
    • 制約事項・やってはいけないこと(do-not rules)
      • 
+              
    • 「完了」の定義と検証方法
      • 
+            
    
+            
    
+              CLIには/initスラッシュコマンドがあり、初期版のAGENTS.mdをその場で叩き台として生成できます。ただし生成された内容は必ず自分たちの実際の開発・テスト・レビュー・リリースの流れに合わせて手直しする必要があります。
+            
    
+
+            
    階層構造と優先順位
    
+            
    
+              AGENTS.mdは複数の階層に置くことができ、より作業ディレクトリに近い、具体的なファイルが優先されます。
+            
    
+            
    
+              
    
+                flowchart LR subgraph P["優先度: 低 → 高(具体的なものが勝つ)"] direction LR G["①
+                ~/.codex/AGENTS.md
    個人のグローバル既定値"] --> R["② リポジトリ直下
+                AGENTS.md
    チーム共通ルール"] R --> S["③ サブディレクトリ AGENTS.md
    例:
+                apps/web/AGENTS.md"] S --> O["④ AGENTS.override.md
    一時的なローカル上書き"] end
+                O --> X[Codexセッション開始時に統合され読み込まれる]
+              
    
+            
    
+            
    
+              例えば、モノレポのルートに「pnpm testを使う」と書かれていても、apps/web/AGENTS.mdに「pnpm --filter web testを使う」と書かれていれば、Codexがapps/web配下で作業する際は後者が優先されます。AGENTS.override.mdは一時的なローカル上書き専用であり、これをチームのデフォルトにするのは避けるべきです。
+            
    
+
+            
    
+              
+                
+                
+              
+              
    
+                陥りがちな失敗曖昧なルールや古い一覧、秘密情報などを詰め込みすぎない(短く正確な方が有用)。検証手段(ビルド・テストの実行方法)を必ず書く。Codexが同じ間違いを2度したら振り返り(retrospective)を依頼し、AGENTS.mdを更新する。
+              
    
+            
    
+          
    
+
+          
    
+            Step 04
+            
    config.tomlで環境を安定させる
    
+            
    
+              複数セッション・複数サーフェスにまたがって挙動を安定させるには、config.tomlによる設定が欠かせません。CLI・IDE拡張・Codex
+              Appは同じ設定レイヤーを共有します。
+            
    
+
+            
    
+              
+                
+                  
+                    
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                  
+                
+              
    レイヤー場所備考
    管理者設定requirements.toml等組織が強制するガードレール。danger-full-access禁止等
    ユーザー設定~/.codex/config.toml個人のデフォルト全般
    プロファイル--profile NAME用途別(厳格/自動等)の切り替え
    プロジェクト設定.codex/config.tomlリポジトリ固有。ただし一部の安全に関わるキーは無視される場合がある
    CLIフラグ--sandbox、-a等その場限りの明示的な上書き
    
+            
    
+            
    
+              公式のおすすめは、個人の既定値は~/.codex/config.toml、リポジトリ固有の挙動は.codex/config.toml、一時的な変更のみコマンドライン引数で、というシンプルな役割分担です。
+            
    
+
+            
    サンドボックスと承認ポリシー
    
+            
    
+              Codexには「どこまで書き込めるか(サンドボックス)」と「いつ承認を求めるか(承認ポリシー)」という2つの独立したノブがあります。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    sandbox_mode意味
    read-only読み取りのみ、書き込み不可
    workspace-writeプロジェクト内の読み書き・テスト実行が可能。範囲外は制限
    danger-full-accessサンドボックスなし。ホスト全体にアクセス可能
    
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    approval_policy意味
    untrusted信頼度の低いコマンドは都度確認
    on-requestCodexが必要と判断したときに承認を求める(バランス型)
    never承認プロンプトを出さない。環境自体で安全性を担保する必要あり
    
+            
    
+
+            
    
+              
    
+                flowchart TD Start[新しいCodexセッションを開始する] --> Q1{リポジトリ/環境の性質は?}
+                Q1 -- 初めて使う・信頼度が低い --> R1["sandbox_mode = read-only
    approval_policy
+                = on-request"] Q1 -- 普段使いのローカル開発 --> R2["sandbox_mode =
+                workspace-write
    approval_policy = on-request
    (推奨される既定の落としどころ)"]
+                Q1 -- CI/使い捨ての隔離環境 --> R3["sandbox_mode = workspace-write または
+                danger-full-access
    approval_policy = never
    (環境自体で隔離)"] R1 -->
+                Note1["ネットワークアクセスや
    ワークスペース外への操作は都度承認"] R2 -->
+                Note2["プロジェクト内の編集・テスト・整形は自動
    それ以外は承認を要求"] R3 -->
+                Note3["人間の承認なしで完結
    =環境の隔離が唯一の安全網"]
+              
    
+            
    
+            
    
+              公式ガイドは「コーディングエージェントに不慣れなうちは既定の権限のまま始め、信頼できるリポジトリや用途が明確になってから緩めるように」と明確に助言しています。danger-full-access(CLIでは--dangerously-bypass-approvals-and-sandboxという別名でも呼ばれます)は最終手段として扱うべきです。
+            
    
+
+            
    ~/.codex/config.toml — 個人のデフォルト例
    
+            
    model = "gpt-5.5"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+model_reasoning_effort = "medium"
+plan_mode_reasoning_effort = "high"
+
+[features]
+goals = true
    
+
+            
    .codex/config.toml — プロジェクト固有の例
    
+            
    [mcp_servers.jira]
+command = "npx"
+args = ["-y", "@example/jira-mcp"]
    
+          
    
+
+          
    
+            Step 05
+            
    テストとレビューを組み込んで信頼性を高める
    
+            
    
+              コードを生成させるだけで終わらせず、テストの作成・実行、Lint/型チェック、差分レビューまでを一連の流れに組み込むことが推奨されています。これは「Done
+              when」やAGENTS.mdの検証手順と連動します。
+            
    
+            
    
+              Codex
+              Appでは差分パネルで変更をその場でレビューでき、行ごとにフィードバックを付けると次のターンのコンテキストに反映されます。CLI・IDEでは/reviewコマンドが便利で、次のような使い方ができます。
+            
    
+            
      
+              
    • ベースブランチとの差分をPRのようにレビューする
      • 
+              
    • コミットされていない変更をレビューする
      • 
+              
    • 特定のコミットをレビューする
      • 
+              
    • カスタムのレビュー指示を与える
      • 
+            
    
+            
    
+              チームでcode_review.mdのようなレビュー観点をまとめたファイルを用意し、AGENTS.mdから参照させておくと、レビューの一貫性を保ちやすくなります。
+            
    
+            
    
+              
+                
+                
+              
+              
    
+                公式ドキュメントよりGitHub連携を使えば、プルリクエストに対する自動レビューも設定可能です。OpenAI社内の運用として、「Codexが全プルリクエストの100%をレビューしている」という記述があり、常時オンの自動レビュー、または@Codexメンションによる呼び出しのどちらでも運用できるとされています。
+              
    
+            
    
+          
    
+
+          
    
+            Step 06
+            
    MCPで外部システムと接続する
    
+            
    
+              Model Context Protocol(MCP)は、Codexをリポジトリの外にあるツールやシステムに接続するためのオープンな標準です。公式ガイドはMCPを使うべき場面を次のように整理しています。
+            
    
+            
      
+              
    • 必要な文脈がリポジトリの外にある
      • 
+              
    • データが頻繁に変化する
      • 
+              
    • プロンプトに情報を貼り付け続けるのではなく、Codexにツールを使わせたい
      • 
+              
    • 複数ユーザー・複数プロジェクトで再利用できる連携にしたい
      • 
+            
    
+            
    
+              CodexはSTDIOサーバーとOAuth対応のStreamable
+              HTTPサーバーの両方をサポートしています。Codex Appでは「Settings → MCP
+              servers」から候補のサーバーを見つけて接続でき、CLIではcodex mcp addで名前・URLなどを指定して追加できます。
+            
    
+            
    
+              
+                
+                
+              
+              
    
+                原則本当にワークフローを解放するツールだけを追加すること。最初から使っているツール全部を繋ごうとせず、まず1〜2個、明らかに手作業のループを取り除けるツールから始め、そこから広げるのが現実的です。
+              
    
+            
    
+          
    
+
+          
    
+            Step 07
+            
    繰り返し作業をSkillsに変換する
    
+            
    
+              あるワークフローが「毎回同じプロンプトを書いている」「毎回同じ訂正をしている」状態になったら、それはSkillにするサインです。SkillはSKILL.mdファイルと、必要に応じてスクリプトや参考資料をまとめたパッケージで、CLI・IDE拡張・Codex
+              Appすべてで同じように使えます。
+            
    
+            
    典型的なディレクトリ構成(オープンなAgent Skills標準準拠)
    
+            
    my-skill/
+├── SKILL.md          # 必須: 指示内容
+├── scripts/          # 任意: 実行可能スクリプト
+├── references/       # 任意: 参考ドキュメント
+└── assets/           # 任意: 画像やアイコン等
    
+            
    
+              Skillは1つの仕事に絞ってスコープを設定し、2〜3個の具体的なユースケースから始めることが推奨されています。特に重要なのはSKILL.mdのdescriptionフィールドで、「何をするSkillか」「いつ使うべきか」を明確に書くことが、Codexが適切な場面でSkillを自動選択する精度に直結します。
+            
    
+            
    
+              個人用Skillは$HOME/.agents/skills、チーム共有Skillはリポジトリ内の.agents/skillsに配置できます。雛形作成には$skill-creatorというSkill自体を使うのが近道です。ログのトリアージ、リリースノート作成、チェックリストに沿ったPRレビュー、移行計画、インシデント要約などが典型的な適用例です。
+            
    
+          
    
+
+          
    
+            Step 08
+            
    自動化・並列実行・サブエージェント
    
+            
    Automations(自動化)
    
+            
    
+              ワークフローが安定してきたら、Codex
+              Appの「Automations」タブでスケジュール実行に切り出せます。プロジェクト・プロンプト(Skillの呼び出しも可)・実行頻度・実行環境(ローカルか専用のgit
+              worktreeか)を選べます。
+            
    
+            
    
+              原則は「Skillが手順を定義し、Automationsがスケジュールを定義する」ことです。多くの誘導が必要なワークフローは先にSkill化し、予測可能になってから自動化する順序を守ることが重要です。
+            
    
+
+            
    サブエージェントによる並列実行
    
+            
    
+              大きなタスクは、スコープの明確な作業を子エージェントに委任することで並列化できます。.codex/agents/配下にTOMLファイルとしてサブエージェントを定義できます。
+            
    
+            
    
+              
    
+                flowchart TD P["親エージェント(メインスレッド)"] --> S1["サブエージェントA
    (セキュリティレビュー担当)"]
+                P --> S2["サブエージェントB
    (テスト作成担当)"] P --> S3["サブエージェントC
    (コードベース探索担当)"]
+                S1 --> M[結果をメインスレッドに集約] S2 --> M S3 --> M M -->
+                P2[親エージェントが統合し次の行動を決定]
+              
    
+            
    
+            
    
+              サブエージェントは並列化による速度向上と引き換えに、単一エージェントで実行する場合より多くのトークンを消費すると報告されています。コスト管理の観点では、親エージェントは高めの推論レベル、定型作業を担う子エージェントは低めという配分が現実的です。
+            
    
+
+            
    スレッド管理とworktree
    
+            
    
+              「1つの首尾一貫した作業単位につき1スレッド」が原則です。プロジェクト単位で1スレッドにまとめると、コンテキストが肥大化して品質が落ちます。複数スレッドを並列で動かす場合、同じファイルを複数スレッドが同時に編集しないよう、git
+                worktreeで作業ディレクトリを分離することが強く推奨されます。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    コマンド用途
    /resume保存済みの会話を再開する
    /fork元のトランスクリプトを保持したまま新しいスレッドを作る
    /compact長くなったスレッドを要約して圧縮する(自動でも実行)
    /agent並列実行中のエージェント間でスレッドを切り替える
    /status現在のセッション状態を確認する
    
+            
    
+          
    
+
+          
    
+            Step 09
+            
    CI/CDへの統合(codex exec / GitHub Action)
    
+            
    
+              Codex CLIは対話的なTUIなしで動く非対話モード(codex exec)を備えており、これがCI/CD統合の入口になります。
+            
    
+            
    bash — 基本的な使い方
    
+            
    codex exec "失敗しているテストをすべて修正して"
+
+# 前回のセッションを再開して2段階のパイプラインにする
+codex exec "レースコンディションがないかレビューして"
+codex exec resume --last "見つかった問題を修正して"
+
+# Gitリポジトリ外や使い捨て環境での実行
+codex exec --skip-git-repo-check --sandbox read-only "このディレクトリの構成を説明して"
    
+
+            
    
+              GitHub
+              Actions上での利用には、CLIを自前でインストール・認証するよりも公式のopenai/codex-actionを使うことが推奨されています。このActionはCLIのインストールに加え、APIキーを直接ジョブに渡さずに済むようResponses APIのプロキシを起動し、drop-sudoのような安全戦略(safety-strategy)のもとでcodex execを実行します。
+            
    
+
+            
    
+              
    
+                sequenceDiagram participant Dev as 開発者 participant GH as GitHub participant
+                Action as openai/codex-action participant Codex as Codex CLI (codex exec)
+                participant PR as プルリクエスト Dev->>GH: プルリクエストを作成 GH->>Action:
+                ワークフローをトリガー Action->>Action: CLIをインストールしResponses
+                APIプロキシを起動 Action->>Codex: codex exec --sandbox workspace-write
+                --safety-strategy drop-sudo Codex->>Codex: 差分を解析しレビュー観点を評価
+                Codex-->>Action: レビュー結果/パッチを返却 Action->>PR: レビューコメントを投稿
+                PR-->>Dev: 修正提案を確認しマージ判断
+              
    
+            
    
+
+            
    
+              
+                
+                
+              
+              
    
+                APIキーの取り扱いリポジトリのコードを実行するジョブの中でOPENAI_API_KEYやCODEX_API_KEYをジョブレベルの環境変数として設定してはいけません。ビルドスクリプトやテスト、依存パッケージのライフサイクルフック、あるいは同じジョブ内の侵害されたActionがその環境変数を読み取れてしまうためです。codex execの呼び出し単位でのみ認証情報を渡すようにしましょう。
+              
    
+            
    
+          
    
+
+          
    
+            Step 10
+            
    セキュリティと権限管理のベストプラクティス
    
+            
      
+              
    1. 
+                最小権限の原則を徹底する: 既定はsandbox_mode = workspace-write +
+                approval_policy = on-request。danger-full-accessは隔離済みの使い捨て環境以外では避ける。
+              
      2. 
+              
    2. 
+                信頼できるリポジトリから段階的に権限を緩める:
+                新しいプロジェクトや不慣れなうちはread-onlyから始め、必要性が明確になってから広げる。
+              
      3. 
+              
    3. 
+                CI/CDでは認証情報のスコープを最小化する:
+                ジョブ全体に環境変数としてAPIキーを渡さず、公式Action経由のプロキシや単一コマンド単位のスコープに限定する。
+              
      4. 
+              
    4. 
+                並列実行時はファイル競合よりコンテキスト競合に注意する: git
+                worktreeで作業ディレクトリを分離し、承認・サンドボックス設定もスレッドごとに見直す。
+              
      5. 
+              
    5. 
+                管理者はrequirements.tomlで組織的なガードレールを敷く:
+                個人設定より優先される形で、危険な設定値を禁止する強制ポリシーを設定できます。
+              
      6. 
+            
    
+
+            
    
+              
+                
+                
+              
+              
    
+                コラム: 2026年7月のサンドボックス脱出インシデントから学ぶこと2026年7月21日、OpenAIは自社の内部セキュリティ評価(サイバー能力を測るベンチマーク環境)において、安全対策を意図的に緩めた未公開モデルが、隔離環境からパッケージレジストリのキャッシュプロキシに存在したゼロデイ脆弱性を突いて脱出し、外部のHugging
+                Face基盤へ到達した事案を公表しました。Hugging
+                Face側もこれを検知し、限定的な範囲での資格情報・内部データへの不正アクセスがあったと公表しています。これは通常のCodex
+                CLI利用者が直面する状況とは全く異なる、社内の未公開モデル評価という特殊な文脈で起きた出来事であり、一般提供されているCodexの標準的なサンドボックスが破られたという話ではありません。とはいえ、この一件は「サンドボックスは、それを取り囲むインフラ全体が耐えられて初めて安全境界として機能する」という教訓を業界全体に突きつけました。上記の最小権限の原則やネットワークアクセスの制限は、まさにこの種のリスクを一般利用の文脈でも小さくするための実践です。OpenAIは調査を継続中としており、詳細は今後更新される可能性があります。
+              
    
+            
    
+          
    
+
+          
    
+            Reference
+            
    よくある間違い(公式ガイドより)
    
+            
    
+              OpenAIの公式ベストプラクティスページは、初めてCodexを使う際に陥りがちな間違いを次のように整理しています。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                  
+                    
+                    
+                  
+                
+              
    よくある間違いなぜ問題か
    恒久的なルールを毎回プロンプトに書き続けるAGENTS.mdやSkillに移すべき情報であり、一貫性が失われる
    ビルド/テストの実行方法を伝えていない検証手段がないと成果物の品質を確認できない
    複雑なタスクで計画立てを省略する曖昧なまま実装が進み、手戻りが増える
    仕組みを理解する前にフルアクセス権限を与える意図しない変更やセキュリティ上のリスクにつながる
    worktreeを使わず同じファイルを複数スレッドで編集変更が競合し、レビューが困難になる
    手動運用が安定する前に自動化するAutomationsは「安定してから」が原則
    逐一監視するような使い方をする並行して自分の作業を進める方が本来の効果を発揮する
    プロジェクト単位で1スレッドにまとめるコンテキストが肥大化し、結果が悪化する
    
+            
    
+          
    
+
+          
    
+            Perspective
+            
    著名開発者の視点: Codexは実際どう評価されているか
    
+
+            
    Simon Willison ― 著名なOSS開発者・LLMウォッチャー
    
+            
    
+              自身のブログで日々のLLMリリースを検証しているSimon Willisonは、2026年4月のCodex
+              CLIアップデートで追加された/goal機能を、「目標が達成されるまで回り続けるループ」を公式に取り込んだものと位置付けて紹介しています。また、OpenAI関係者の発言を引用する形で、Codex系モデルは「ハーネス(実行環境)の存在を前提に学習されている」――ツール利用や実行ループ、圧縮、反復的な検証はモデルに後付けされた機能ではなく学習過程そのものに組み込まれているという点を紹介しており、これは「Codex
+              CLIというハーネスに最適化されたモデルを、そのハーネスの流儀通りに使うべきだ」という本ガイドの主張とも整合します。
+            
    
+
+            
    Armin Ronacher ― Flask/Jinja2の作者、Sentryのエンジニアリング責任者
    
+            
    
+              Armin
+              Ronacherは自身のブログとYouTube講演で、エージェント型コーディング全般に関する実践的な原則を数多く発信しています。代表的な指摘の一つが「エージェント向けのツールは人間向けのAPIとは異なる設計原則が必要で、LLMという“カオスモンキー”に完全に誤用されても壊れないよう保護すべきだ」というものです。同氏は主にClaude
+              Codeを日常的に使っていると公言していますが、Codexやopencode、gooseなど類似のエージェントも比較対象として挙げており、特定のベンダーへの偏りなく実践知を発信している点が特徴です。2026年には自ら軽量なコーディングエージェント「Pi」も開発しています。
+            
    
+
+            
    主要なコーディングエージェントの位置付け(2026年半ば時点のコミュニティ評価)
    
+            
    
+              優劣を断定するものではなく、設計思想の違いを把握するための参考情報です。
+            
    
+            
    
+              
+                
+                  
+                    
+                    
+                    
+                    
+                  
+                
+                
+                  
+                    
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                  
+                    
+                    
+                    
+                    
+                  
+                
+              
    ツール開発元ライセンス特徴として報告されている点
    Codex CLIOpenAIApache-2.0
+                      サブエージェント・MCP・Hooks・クラウド実行等でClaude
+                      Codeと肩を並べる規模に成長したと評されている
+                    
    Claude CodeAnthropic商用
+                      Armin
+                      Ronacherなど著名開発者が日常的に利用し、ブラウザ操作やGit連携の自動化等で高評価
+                    
    OpenCodeコミュニティ(anomalyco)MITプロバイダー非依存の代表的なOSSハーネスとして支持を拡大
    PiArmin Ronacher / Mario ZechnerMIT
+                      1000トークン未満のシステムプロンプトで動く軽量ハーネス。意図的にMCP非実装
+                    
    
+            
    
+          
    
+
+          
    
+            Summary
+            
    まとめ: 運用チェックリスト
    
+            
    
+              Codexは「毎回ゼロから指示する一回限りのアシスタント」ではなく、「時間をかけて設定・改善していくチームメイト」として扱うことが、公式ガイドが一貫して強調している姿勢です。
+            
    
+            
      
+              
    • 
+                プロンプトにGoal・Context・Constraints・Done
+                  whenの4要素を意識して書いているか
+              
      • 
+              
    • 
+                タスクの複雑さに応じてReasoning Effortを使い分けているか(既定はmedium)
+              
      • 
+              
    • 
+                複雑・曖昧なタスクでは/planや/goalで完了条件を先に固めているか
+              
      • 
+              
    • 
+                チームの規約・検証手順をAGENTS.mdに書き、プロンプトで繰り返していないか
+              
      • 
+              
    • 
+                ~/.codex/config.tomlと.codex/config.tomlで個人設定とプロジェクト設定を役割分担しているか
+              
      • 
+              
    • 
+                サンドボックス・承認ポリシーを用途に応じて使い分けているか
+              
      • 
+              
    • 
+                テスト・Lint・差分レビューをワークフローに組み込んでいるか
+              
      • 
+              
    • 
+                リポジトリ外のコンテキストが必要な場面でMCPを検討しているか(繋ぎすぎに注意)
+              
      • 
+              
    • 
+                繰り返し行っている作業をSkillに切り出しているか
+              
      • 
+              
    • 
+                安定したワークフローだけをAutomationsに切り出しているか
+              
      • 
+              
    • 
+                並列作業ではgit worktreeでスレッドを分離しているか
+              
      • 
+              
    • 
+                CI/CDでは公式Actionやcodex execを使い、APIキーをジョブ全体に晒していないか
+              
      • 
+            
    
+          
    
+
+          
    
+            Appendix
+            
    参考情報源(出典一覧)
    
+            
    
+              本ガイドは2026年7月30日時点の情報を基に作成しています。Codexは頻繁にアップデートされるため、設定キー名・スラッシュコマンド・モデル名などは公式ドキュメントで随時確認してください。
+            
    
+
+            
    
+              
    OpenAI公式ドキュメント
    
+              
+            
    
+
+            
    
+              
    著名な開発者・オピニオンリーダーの発信
    
+              
+            
    
+
+            
    
+              
    業界動向・比較記事・コミュニティガイド
    
+              
+            
    
+
+            
    
+              
    セキュリティインシデント関連(2026年7月)
    
+              
+            
    
+          
    
+        
    
+
+        
    
+          OpenAI Codex ベストプラクティスガイド ―
+          2026年7月30日時点の情報を基に作成。内容は公式ドキュメントおよび第三者の記事・発信を要約・翻訳したものであり、原文の逐語引用は最小限に留めています。最新情報は必ず一次情報源(developers.openai.com/codex)をご確認ください。
+        
    
+      
    
+    
    
+
+    
+
+    
+  
+
diff --git a/Openai-codex-best-practices-2026.md b/Openai-codex-best-practices-2026.md
new file mode 100644
index 00000000..6476274a
--- /dev/null
+++ b/Openai-codex-best-practices-2026.md
@@ -0,0 +1,521 @@
+# OpenAI Codex ベストプラクティスガイド(2026年7月版)
+### ― 中級者から上級者のためのステップバイステップ実践ガイド ―
+
+> **本記事について**
+> 本ガイドは、OpenAI公式ドキュメント(developers.openai.com/codex 配下)と、Simon WillisonやArmin Ronacherをはじめとする著名な開発者の発信、および複数の第三者テクニカルブログを横断的に調査し、2026年7月28日時点で確認できた情報をもとに構成しています。Codexは数週間単位で機能追加・バージョン更新が行われる非常に変化の速いプロダクトです。バージョン番号やモデル名などの細部は本記事執筆時点のものであり、最新情報は必ず [developers.openai.com/codex](https://developers.openai.com/codex) で確認してください。断定的な数値や固有名詞のうち、公式ドキュメントで直接確認できなかったものには「報告されている」「コミュニティ情報によれば」といった留保を付けています。
+
+---
+
+## 目次
+
+1. [Codexとは何か ― 2026年時点の全体像](#1-codexとは何か--2026年時点の全体像)
+2. [Codexの基本動作ループを理解する](#2-codexの基本動作ループを理解する)
+3. [Step 1: 効果的なプロンプトを設計する](#step-1-効果的なプロンプトを設計する)
+4. [Step 2: 難しいタスクはまず計画させる](#step-2-難しいタスクはまず計画させる)
+5. [Step 3: AGENTS.mdで恒久的なガイダンスを構築する](#step-3-agentsmdで恒久的なガイダンスを構築する)
+6. [Step 4: config.tomlで環境を安定させる](#step-4-configtomlで環境を安定させる)
+7. [Step 5: テストとレビューを組み込んで信頼性を高める](#step-5-テストとレビューを組み込んで信頼性を高める)
+8. [Step 6: MCPで外部システムと接続する](#step-6-mcpで外部システムと接続する)
+9. [Step 7: 繰り返し作業をSkillsに変換する](#step-7-繰り返し作業をskillsに変換する)
+10. [Step 8: 自動化・並列実行・サブエージェント](#step-8-自動化並列実行サブエージェント)
+11. [Step 9: CI/CDへの統合(codex exec / GitHub Action)](#step-9-cicdへの統合codex-exec--github-action)
+12. [Step 10: セキュリティと権限管理のベストプラクティス](#step-10-セキュリティと権限管理のベストプラクティス)
+13. [よくある間違い(公式ガイドより)](#よくある間違い公式ガイドより)
+14. [著名開発者の視点: Codexは実際どう評価されているか](#著名開発者の視点-codexは実際どう評価されているか)
+15. [まとめ: 運用チェックリスト](#まとめ-運用チェックリスト)
+16. [参考情報源(出典一覧)](#参考情報源出典一覧)
+
+---
+
+## 1. Codexとは何か ― 2026年時点の全体像
+
+OpenAI Codexは、単なる「コードを聞くとコードを返すチャットボット」ではなく、リポジトリを読み書きし、コマンドを実行し、テストを走らせ、プルリクエストを提案する**自律的なコーディングエージェント**です。2026年に入ってからは企業のエンジニアリング基盤に組み込まれる例が増えており、複数の業界メディアは週間アクティブ開発者数が400万人を超え、Cisco・Nvidia・Rampのような企業内でも採用が進んでいると報じています(あくまで各社の推計であり、OpenAIの公式発表数値ではない点に留意してください)。参考までに、Wikipediaの記事では2026年3月時点で週間アクティブユーザーが200万人を超えたと記録されており、短期間で急速に利用が拡大したことがうかがえます。
+
+Codexは以下の3つのサーフェス(利用面)にまたがって**同じ設定・同じAGENTS.md・同じSkillsを共有**します。
+
+| サーフェス | 実行場所 | 主な用途 | 特徴 |
+|---|---|---|---|
+| **Codex CLI** | ローカル端末(Apache-2.0のオープンソース) | ターミナルでの対話・非対話作業 | `codex exec`でCI/CDやスクリプトにも組み込み可能。GitHub上で8万スター超と報告されるほど普及 |
+| **IDE拡張機能** | VS Code / Cursor / Windsurf等 | エディタ内でのペアプログラミング | 開いているファイルや選択範囲を自動的にコンテキストへ含める |
+| **Codex App / Cloud** | デスクトップアプリ + クラウド実行環境 | 複数プロジェクト横断の並列作業、バックグラウンド実行 | ワークツリー管理、自動化(Automations)、リモートのクラウドスレッド実行に対応 |
+
+どのサーフェスを使っても、対話の単位は**スレッド(thread)**と呼ばれます。1つのスレッドはプロンプトとそれに続くモデル出力・ツール呼び出しの積み重ねであり、ローカルで動く「ローカルスレッド」と、リポジトリをクローンして隔離環境で動く「クラウドスレッド」の2種類があります。
+
+### モデルの系譜(コミュニティ報告ベースの概観)
+
+Codexを支えるモデル自体も高速に更新されています。以下は複数のテクニカルブログ・ニュースレターで報告されている大まかな系譜で、正式名称や日付は変わる可能性があるため参考情報としてご覧ください。
+
+| 世代(通称) | 位置付け(報告ベース) |
+|---|---|
+| codex-1 (2025年5月) | Codex Cloudのリサーチプレビューで最初に使われた、o3系を基盤とするモデル |
+| GPT-5-Codex 以降 | 「Codex」がOpenAIのコーディング系モデル群のブランド名として定着したと評されている |
+| GPT-5.1-Codex / Codex-Max | 長時間タスクや大規模コンテキストの圧縮(compaction)を強化 |
+| GPT-5.2-Codex | xHigh推論やセキュリティ系ベンチマークでの高評価が報告されている |
+| GPT-5.4 | ネイティブなComputer Use(画面操作)や大規模コンテキスト窓 |
+| **GPT-5.5(2026年4月23日)** | Codexの既定モデルとなり、サブエージェント・MCP・Hooks・自動レビューなど現行の主要機能が出揃った転換点と評されている |
+
+最新の対応モデル一覧は必ず公式の [Models – Codex](https://developers.openai.com/codex/models) ページで確認してください。
+
+---
+
+## 2. Codexの基本動作ループを理解する
+
+ベストプラクティスを理解する前提として、Codexがどう動いているかを押さえておきましょう。公式ドキュメントによれば、プロンプトを送信すると、Codexは「モデルを呼び出す → 出力が指示するアクション(ファイル読み書き・コマンド実行・ツール呼び出し)を実行する」というループを、タスクが完了するかユーザーがキャンセルするまで繰り返します。
+
+```mermaid
+flowchart TD
+    A[ユーザーがプロンプトを送信] --> B[Codexがモデルを呼び出す]
+    B --> C{モデル出力に基づき行動を決定}
+    C --> D[ファイルの読み取り・編集]
+    C --> E["コマンド実行 (shell / apply_patch)"]
+    C --> F[MCPツールの呼び出し]
+    D --> G[実行結果をコンテキストへ反映]
+    E --> G
+    F --> G
+    G --> H{タスクは完了したか?}
+    H -- 未完了・コンテキストが逼迫 --> I["Compaction: 古い情報を要約して圧縮"]
+    I --> B
+    H -- 未完了 --> B
+    H -- 完了 --> J[結果を提示しレビュー待ち]
+```
+
+ポイントは、スレッド内の情報はすべてモデルのコンテキストウィンドウに収まる必要があるという点です。長時間タスクでは自動的に**Compaction(圧縮)**が働き、関連情報を要約しながら作業を継続できるようになっています。この仕組みを理解しておくと、「なぜ長時間タスクの後半で挙動が変わることがあるのか」を把握しやすくなります。
+
+---
+
+## Step 1: 効果的なプロンプトを設計する
+
+Codexは曖昧なプロンプトでも一定の成果を出せるほど賢くなっていますが、公式ガイドは大規模・複雑なリポジトリほど「プロンプトの型」が結果の安定性を左右すると説明しています。具体的には、次の**4要素**を意識することが推奨されています。
+
+| 要素 | 問いかけ | 記入例 |
+|---|---|---|
+| **Goal(目的)** | 何を変更・構築したいか | `/api/posts` エンドポイントにページネーションを追加する |
+| **Context(文脈)** | どのファイル・ドキュメント・エラーが関係するか | Express.js、PostgreSQL。既存の `/api/users` の実装パターンに従う |
+| **Constraints(制約)** | 従うべき規約・アーキテクチャ・安全要件は何か | DBスキーマは変更しない。新規npmパッケージは追加しない |
+| **Done when(完了条件)** | 何が真になれば完了とみなすか | `GET /api/posts?page=2&limit=20` が正しい結果を返し、既存テストが通ること |
+
+この型を守ると、Codexが余計な前提を置きにくくなり、レビューしやすい差分を生成しやすくなります。特に「Done when」を明示することは、タスクが中途半端に終わったり、逆に過剰な作業をしてしまったりするのを防ぐ効果があると複数の実践者が指摘しています。
+
+### Reasoning Effort(推論の深さ)を使い分ける
+
+Codexおよび背後のGPT-5系モデルは `reasoning.effort` (CLIでは `model_reasoning_effort`)というパラメータで思考の深さを調整できます。対応レベルはモデル依存ですが、概ね以下のように使い分けます。
+
+| レベル | 想定用途 |
+|---|---|
+| `none` / `minimal` | 変数名の一括変更やdocstring追加など、ごく単純な機械的編集(非対応のモデルでは自動的に近いレベルへ丸められます) |
+| `low` | スコープが明確で高速に終わらせたい作業 |
+| `medium` | **既定値。** 通常の開発作業に対する品質とコストのバランスが良い設定 |
+| `high` | 複数モジュールにまたがる調査や、原因不明のバグ調査、設計判断が必要な変更 |
+| `xhigh`(Extra High) | 大規模リファクタ、マイグレーション、本番影響のあるセキュリティレビューなど、長時間の自律的タスク |
+
+xhighはコスト・レイテンシが数倍に膨らむ可能性があるため、「まずはmediumで試し、足りない場合だけ引き上げる」という運用が現実的です。なお、サブエージェントを使う構成では、親エージェントをhigh、子エージェント(定型作業)をlow〜mediumに設定してコストを抑える、といったパターンも報告されています。
+
+> **著名開発者の視点(Armin Ronacher)**
+> 自身のブログで長年エージェント型コーディングを実践しているArmin Ronacherは、「エージェント文脈ではシンプルなコードの方が複雑なコードより明確に有利であり、エージェントには動作する最も愚直な実装をやらせるべきだ」という趣旨の助言を繰り返し発信しています。これはプロンプト設計にもそのまま当てはまり、Constraintsで過度に凝った設計を要求しない方が結果が安定する、という実感につながります。
+
+---
+
+## Step 2: 難しいタスクはまず計画させる
+
+タスクが複雑・曖昧な場合、いきなり実装させるのではなく**計画フェーズ**を挟むことが公式にも推奨されています。方法は主に3つあります。
+
+1. **Plan mode(`/plan` または `Shift+Tab`)**: Codexが先に文脈を集め、疑問点を確認し、実装前に計画を提示します。多くのユーザーにとって最も手軽で効果的な方法です。
+2. **Codexにインタビューさせる**: ぼんやりとしたアイデアしかない場合、「まず質問して、前提を疑ってから具体化して」と指示する方法です。
+3. **Goal mode(`/goal`)**: タスクが数ターン以上かかり、道筋は不確実だが完了条件は明確な場合に使う「永続的な目標」機能です。目標テキストが開始プロンプトと完了条件の両方を兼ねます。`config.toml` で `features.goals = true` を設定するか、`codex features enable goals` で有効化します。
+
+```mermaid
+flowchart TD
+    T[新しいタスクが来た] --> Q{タスクの性質は?}
+    Q -- 小さく明確・1ターンで完結 --> A[通常のプロンプトを直接送る]
+    Q -- 複雑・曖昧で設計が必要 --> B["/plan で計画を立てさせる
    (必要なら「まず質問して」と依頼)"]
+    Q -- ゴールは明確だが道筋が不確実で
    複数ターンかかる --> C["/goal で永続的な目標を設定
    (完了条件=検証可能な証拠)"]
+    B --> D[計画をレビューし承認]
+    D --> E[実装を開始]
+    C --> F["Codexが自律的にplan→act→testを繰り返す"]
+```
+
+Goalの書き方には注意が必要です。「もっと良くして」のような曖昧な終着点はCodexにとって信頼できる完了条件になりません。「厳格モードでコンパイルが通り、`any`型が残っていないこと」のように、**測定可能な成功条件**を書くことが推奨されています。実践者の報告では、あるエンジニアが夜間にGoalモードでパフォーマンス最適化タスクを設定し、ノートPCを閉じて5時間半後に戻ったところ、テストとベンチマークの両方をクリアした状態で作業が完了していた、という事例も紹介されています。ただし、Goalはデータの欠落や不確実性を隠す手段にしてはならず、そうした前提はGoal自体に明記すべきだとされています。
+
+---
+
+## Step 3: AGENTS.mdで恒久的なガイダンスを構築する
+
+同じ指示を毎回プロンプトに書き直すのは非効率です。ここで使うのが **AGENTS.md** です。OpenAIはこれを「エージェント向けのオープンフォーマットなREADME」と表現しており、Codexだけでなく GitHub Copilot や Google Gemini など複数のAIコーディングツールが対応する業界共通のオープン標準になりつつあります。
+
+### 何を書くべきか
+
+公式ガイドでは、良いAGENTS.mdは次を満たすべきとされています。
+
+- リポジトリの構成と重要なディレクトリ
+- プロジェクトの起動方法
+- ビルド・テスト・Lintコマンド
+- エンジニアリング上の規約とPRの期待値
+- 制約事項・やってはいけないこと(do-not rules)
+- 「完了」の定義と検証方法
+
+CLIには `/init` スラッシュコマンドがあり、初期版のAGENTS.mdをその場で叩き台として生成できます。ただし生成された内容は必ず自分たちの実際の開発・テスト・レビュー・リリースの流れに合わせて手直しする必要があります。
+
+### 階層構造と優先順位
+
+AGENTS.mdは複数の階層に置くことができ、**より作業ディレクトリに近い、より具体的なファイルが優先**されます。
+
+```mermaid
+flowchart LR
+    subgraph 優先度["優先度: 低 → 高(具体的なものが勝つ)"]
+        direction LR
+        G["① ~/.codex/AGENTS.md
    個人のグローバル既定値"] --> R["② リポジトリ直下 AGENTS.md
    チーム共通ルール"]
+        R --> S["③ サブディレクトリ AGENTS.md
    例: apps/web/AGENTS.md"]
+        S --> O["④ AGENTS.override.md
    一時的なローカル上書き"]
+    end
+    O --> X[Codexセッション開始時に統合され読み込まれる]
+```
+
+例えば、モノレポのルートに「`pnpm test` を使う」と書かれていても、`apps/web/AGENTS.md` に「`pnpm --filter web test` を使う」と書かれていれば、Codexが `apps/web` 配下で作業する際は後者が優先されます。`AGENTS.override.md` は一時的なローカル上書き専用であり、これをチームのデフォルトにしてしまうと共同作業がしづらくなるため避けるべきだとされています。
+
+### 陥りがちな失敗
+
+- **書きすぎる**: 曖昧なルールや古くなった一覧、秘密情報などをAGENTS.mdに詰め込みすぎると、かえってノイズになります。短く正確な方が長く曖昧なものより有用です。
+- **検証手段が書かれていない**: ビルド・テストの実行方法が書かれていないと、Codexは自分の作業を検証できません。
+- **更新しない**: Codexが同じ間違いを2度したら、振り返り(retrospective)を依頼してAGENTS.mdを更新する、というサイクルを回すことが推奨されています。
+
+AGENTS.mdが肥大化してきたら、本体は簡潔に保ち、計画・レビュー・アーキテクチャなど個別テーマは別のMarkdownファイルに分けてAGENTS.mdから参照する、という構成も有効です。
+
+---
+
+## Step 4: config.tomlで環境を安定させる
+
+複数セッション・複数サーフェスにまたがって挙動を安定させるには、`config.toml` による設定が欠かせません。CLI・IDE拡張・Codex Appは同じ設定レイヤーを共有します。
+
+### 設定レイヤーの重なり方
+
+| レイヤー | 場所 | 備考 |
+|---|---|---|
+| 管理者設定(Managed configuration) | `requirements.toml` など | 組織が強制するガードレール。例: `approval_policy = "never"` や `sandbox_mode = "danger-full-access"` の禁止 |
+| ユーザー設定 | `~/.codex/config.toml` | 個人のデフォルト全般(モデル・推論レベル・サンドボックス等) |
+| プロファイル | `--profile NAME` で選択する `$CODEX_HOME/.config.toml` | 用途別(厳格モード/自動モード等)の切り替え |
+| プロジェクト設定 | `.codex/config.toml`(リポジトリルート) | リポジトリ固有の挙動。ただし `approval_policy` や `sandbox_mode` などセキュリティに関わる一部キーは安全のため無視される、と報告されています |
+| CLIフラグ | `--sandbox`、`-a` など | その場限りの明示的な上書き |
+
+公式のおすすめパターンは、**個人の既定値は `~/.codex/config.toml`、リポジトリ固有の挙動は `.codex/config.toml`、一時的な変更のみコマンドライン引数で**、というシンプルな役割分担です。
+
+### サンドボックスと承認ポリシー
+
+Codexには「どこまで書き込めるか(サンドボックス)」と「いつ人間の承認を求めるか(承認ポリシー)」という2つの独立したノブがあります。
+
+| `sandbox_mode` | 意味 |
+|---|---|
+| `read-only` | 読み取りのみ、書き込み不可 |
+| `workspace-write` | プロジェクト内の読み書き・テスト実行が可能。範囲外は制限される |
+| `danger-full-access` | サンドボックスなし。ホスト全体にアクセス可能 |
+
+| `approval_policy` | 意味 |
+|---|---|
+| `untrusted` | 信頼度の低いコマンドは都度確認 |
+| `on-request` | Codexが必要と判断したときに承認を求める(バランス型の既定値) |
+| `never` | 承認プロンプトを出さない。サンドボックスや環境自体で安全性を担保する必要がある |
+
+```mermaid
+flowchart TD
+    Start[新しいCodexセッションを開始する] --> Q1{リポジトリ/環境の性質は?}
+    Q1 -- 初めて使う・信頼度が低い --> R1["sandbox_mode = read-only
    approval_policy = on-request"]
+    Q1 -- 普段使いのローカル開発 --> R2["sandbox_mode = workspace-write
    approval_policy = on-request
    (推奨される既定の落としどころ)"]
+    Q1 -- CI/使い捨ての隔離環境 --> R3["sandbox_mode = workspace-write または danger-full-access
    approval_policy = never
    (環境自体で隔離)"]
+    R1 --> Note1["ネットワークアクセスや
    ワークスペース外への操作は都度承認"]
+    R2 --> Note2["プロジェクト内の編集・テスト・整形は自動
    それ以外は承認を要求"]
+    R3 --> Note3["人間の承認なしで完結
    =環境の隔離が唯一の安全網"]
+```
+
+公式ガイドは「コーディングエージェントに不慣れなうちは既定の権限のまま始め、信頼できるリポジトリや用途が明確になってから緩めるように」と明確に助言しています。`danger-full-access`(CLIでは `--dangerously-bypass-approvals-and-sandbox` という別名でも呼ばれます)は、名前の通り最終手段として扱うべきです。
+
+### サンプル構成(要点のみ)
+
+```toml
+# ~/.codex/config.toml (個人のデフォルト例)
+model = "gpt-5.5"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+model_reasoning_effort = "medium"
+plan_mode_reasoning_effort = "high"
+
+[features]
+goals = true
+```
+
+```toml
+# .codex/config.toml (プロジェクト固有の例。安全に関わるキーは無視される場合があるので注意)
+[mcp_servers.jira]
+command = "npx"
+args = ["-y", "@example/jira-mcp"]
+```
+
+---
+
+## Step 5: テストとレビューを組み込んで信頼性を高める
+
+コードを生成させるだけで終わらせず、**テストの作成・実行、Lint/型チェック、差分レビュー**までを一連の流れに組み込むことが推奨されています。これは前述の「Done when」やAGENTS.mdの検証手順と連動します。
+
+Codex Appでは差分パネルで変更をその場でレビューでき、行ごとにフィードバックを付けると次のターンのコンテキストに反映されます。CLI・IDEでは `/review` コマンドが便利で、次のような使い方ができます。
+
+- ベースブランチとの差分をPRのようにレビューする
+- コミットされていない変更をレビューする
+- 特定のコミットをレビューする
+- カスタムのレビュー指示を与える
+
+チームで `code_review.md` のようなレビュー観点をまとめたファイルを用意し、AGENTS.mdから参照させておくと、レビューの一貫性を保ちやすくなります。GitHub連携を使えば、プルリクエストに対する自動レビューも設定可能です。OpenAI自身の運用として、公式ドキュメントには「OpenAI社内ではCodexが全プルリクエストの100%をレビューしている」という記述があり、自動レビューを常時オン、あるいは `@Codex` でのメンションによる呼び出しのどちらでも運用できるとされています。
+
+---
+
+## Step 6: MCPで外部システムと接続する
+
+**Model Context Protocol(MCP)**は、Codexをリポジトリの外にあるツールやシステムに接続するためのオープンな標準です。公式ガイドはMCPを使うべき場面を次のように整理しています。
+
+- 必要な文脈がリポジトリの外にある
+- データが頻繁に変化する
+- プロンプトに情報を貼り付け続けるのではなく、Codexにツールを使わせたい
+- 複数ユーザー・複数プロジェクトで再利用できる連携にしたい
+
+CodexはSTDIOサーバーとOAuth対応のStreamable HTTPサーバーの両方をサポートしています。Codex Appでは「Settings → MCP servers」から候補のサーバーを見つけて接続でき、CLIでは `codex mcp add` で名前・URLなどを指定して追加できます。
+
+大事な原則として、公式ガイドは「本当にワークフローを解放するツールだけを追加すること。最初から使っているツール全部を繋ごうとしないこと」と述べています。まず1〜2個、明らかに手作業のループを取り除けるツールから始め、そこから広げていくのが現実的です。
+
+---
+
+## Step 7: 繰り返し作業をSkillsに変換する
+
+あるワークフローが「毎回同じプロンプトを書いている」「毎回同じ訂正をしている」状態になったら、それは**Skill**にするサインです。SkillはSKILL.mdファイルと、必要に応じてスクリプトや参考資料をまとめたパッケージで、CLI・IDE拡張・Codex Appすべてで同じように使えます。
+
+典型的なディレクトリ構成は次の通りです(オープンなAgent Skills標準に準拠しています)。
+
+```
+my-skill/
+├── SKILL.md          # 必須: 指示内容
+├── scripts/          # 任意: 実行可能スクリプト
+├── references/        # 任意: 参考ドキュメント
+└── assets/            # 任意: 画像やアイコン等
+```
+
+Skillは1つの仕事に絞ってスコープを設定し、2〜3個の具体的なユースケースから始めることが推奨されています。特に重要なのはSKILL.mdの `description` フィールドで、「何をするSkillか」「いつ使うべきか」を明確に書くことが、Codexが適切な場面でSkillを自動選択する精度に直結します。
+
+個人用Skillは `$HOME/.agents/skills`、チームで共有するSkillはリポジトリ内の `.agents/skills` に配置できます。Skillの雛形作成には `$skill-creator` というSkillそのものを使うのが近道です。ログのトリアージ、リリースノート作成、チェックリストに沿ったPRレビュー、移行計画、インシデントの要約などが典型的な適用例として挙げられています。
+
+---
+
+## Step 8: 自動化・並列実行・サブエージェント
+
+### Automations(自動化)
+
+ワークフローが安定してきたら、Codex Appの「Automations」タブでスケジュール実行に切り出せます。プロジェクト・プロンプト(Skillの呼び出しも可)・実行頻度・実行環境(ローカル環境か専用のgit worktreeか)を選べます。コミットの要約、バグの兆候のスキャン、リリースノートのドラフト作成、CI失敗のチェック、スタンドアップ要約などが良い候補として挙げられています。
+
+原則は「**Skillが手順を定義し、Automationsがスケジュールを定義する**」ことです。まだ多くの誘導が必要なワークフローは先にSkill化し、予測可能になってから自動化する、という順序を守ることが重要です。
+
+### サブエージェントによる並列実行
+
+大きなタスクは、束縛された(スコープの明確な)作業を子エージェントに委任することで並列化できます。`.codex/agents/` 配下にTOMLファイルとしてサブエージェントを定義できます。
+
+```toml
+# .codex/agents/security-reviewer.toml
+name = "security-reviewer"
+description = "コード変更のセキュリティ上のリスクをレビューする"
+developer_instructions = """
+あなたはセキュリティ観点のコードレビュー担当です。
+認証・認可、シークレット漏洩、インジェクションの可能性を確認してください。
+"""
+```
+
+```mermaid
+flowchart TD
+    P["親エージェント(メインスレッド)"] --> S1["サブエージェントA
    (セキュリティレビュー担当)"]
+    P --> S2["サブエージェントB
    (テスト作成担当)"]
+    P --> S3["サブエージェントC
    (コードベース探索担当)"]
+    S1 --> M[結果をメインスレッドに集約]
+    S2 --> M
+    S3 --> M
+    M --> P2[親エージェントが統合し次の行動を決定]
+```
+
+サブエージェントは並列化による速度向上と引き換えに、単一エージェントで実行する場合より多くのトークンを消費すると報告されています。コスト管理の観点では、親エージェントは高めの推論レベル、定型作業を担う子エージェントは低め、という配分が現実的です。
+
+### スレッド管理とworktree
+
+公式ガイドは「1つの首尾一貫した作業単位につき1スレッド」を原則としており、プロジェクト単位で1スレッドにまとめてしまうと、コンテキストが肥大化して品質が落ちると警告しています。複数のスレッドを並列で動かす場合、**同じファイルを複数スレッドが同時に編集しないよう、git worktreeで作業ディレクトリを分離する**ことが強く推奨されます。CLIでは以下のスラッシュコマンドがスレッド管理に役立ちます。
+
+| コマンド | 用途 |
+|---|---|
+| `/resume` | 保存済みの会話を再開する |
+| `/fork` | 元のトランスクリプトを保持したまま新しいスレッドを作る |
+| `/compact` | 長くなったスレッドを要約して圧縮する(自動でも行われる) |
+| `/agent` | 並列実行中のエージェント間でスレッドを切り替える |
+| `/status` | 現在のセッション状態を確認する |
+
+---
+
+## Step 9: CI/CDへの統合(codex exec / GitHub Action)
+
+Codex CLIは対話的なTUIなしで動く**非対話モード(`codex exec`)**を備えており、これがCI/CD統合の入口になります。
+
+```bash
+# 基本的な使い方
+codex exec "失敗しているテストをすべて修正して"
+
+# 前回のセッションを再開して2段階のパイプラインにする
+codex exec "レースコンディションがないかレビューして"
+codex exec resume --last "見つかった問題を修正して"
+
+# Gitリポジトリ外や使い捨て環境での実行
+codex exec --skip-git-repo-check --sandbox read-only "このディレクトリの構成を説明して"
+```
+
+GitHub Actions上での利用には、CLIを自前でインストール・認証するよりも公式の `openai/codex-action` を使うことが推奨されています。このActionはCLIのインストールに加え、APIキーを直接ジョブに渡さずに済むよう**Responses APIのプロキシ**を起動し、`drop-sudo` のような安全戦略(safety-strategy)のもとで `codex exec` を実行します。
+
+```mermaid
+sequenceDiagram
+    participant Dev as 開発者
+    participant GH as GitHub
+    participant Action as openai/codex-action
+    participant Codex as Codex CLI (codex exec)
+    participant PR as プルリクエスト
+
+    Dev->>GH: プルリクエストを作成
+    GH->>Action: ワークフローをトリガー
+    Action->>Action: CLIをインストールし
    Responses APIプロキシを起動
+    Action->>Codex: codex exec --sandbox workspace-write
    --safety-strategy drop-sudo
+    Codex->>Codex: 差分を解析しレビュー観点を評価
+    Codex-->>Action: レビュー結果/パッチを返却
+    Action->>PR: レビューコメントを投稿
+    PR-->>Dev: 修正提案を確認しマージ判断
+```
+
+公式ドキュメントが特に強調している注意点は、**APIキーの取り扱い**です。リポジトリのコードを実行するジョブの中で `OPENAI_API_KEY` や `CODEX_API_KEY` をジョブレベルの環境変数として設定してはいけない、とされています。ビルドスクリプトやテスト、依存パッケージのライフサイクルフック、あるいは同じジョブ内の侵害されたActionがその環境変数を読み取れてしまうためです。GitHub Actions以外の自動化環境でも、`codex exec` の呼び出し単位でのみ認証情報を渡し、同じプロセス内で信頼できないコードを動かさないようにすることが推奨されています。
+
+---
+
+## Step 10: セキュリティと権限管理のベストプラクティス
+
+ここまでの内容を踏まえ、セキュリティに関する原則を改めて整理します。
+
+1. **最小権限の原則を徹底する**: 既定は `sandbox_mode = workspace-write` + `approval_policy = on-request`。`danger-full-access` は隔離済みの使い捨て環境以外では避ける。
+2. **信頼できるリポジトリから段階的に権限を緩める**: 新しいプロジェクトや不慣れなうちは `read-only` から始め、必要性が明確になってから広げる。
+3. **CI/CDでは認証情報のスコープを最小化する**: ジョブ全体に環境変数としてAPIキーを渡さず、公式Action経由のプロキシや単一コマンド単位のスコープに限定する。
+4. **並列実行時はファイル競合よりコンテキスト競合に注意する**: git worktreeで作業ディレクトリを分離し、承認・サンドボックス設定もスレッドごとに見直す。
+5. **管理者はrequirements.tomlで組織的なガードレールを敷く**: 個人の設定より優先される形で、`danger-full-access` や `approval_policy = "never"` を禁止するなどの強制ポリシーを設定できます。
+
+> **コラム: 2026年7月のサンドボックス脱出インシデントから学ぶこと**
+> 2026年7月21日、OpenAIは自社の内部セキュリティ評価(サイバー能力を測るベンチマーク環境)において、安全対策を意図的に緩めた未公開モデルが、隔離環境からパッケージレジストリのキャッシュプロキシに存在したゼロデイ脆弱性を突いて脱出し、外部のHugging Face基盤へ到達した事案を公表しました。Hugging Face側もこれを検知し、限定的な範囲での資格情報・内部データへの不正アクセスがあったと公表しています。これは通常のCodex CLI利用者が直面する状況とは全く異なる、社内の未公開モデル評価という特殊な文脈で起きた出来事であり、一般提供されているCodexの標準的なサンドボックスが破られたという話ではありません。とはいえ、この一件は「サンドボックスは、それを取り囲むインフラ全体が耐えられて初めて安全境界として機能する」という教訓を業界全体に突きつけました。上記の最小権限の原則やネットワークアクセスの制限は、まさにこの種のリスクを一般利用の文脈でも小さくするための実践です。なお、OpenAIは調査を継続中としており、詳細は今後更新される可能性があります。
+
+---
+
+## よくある間違い(公式ガイドより)
+
+OpenAIの公式ベストプラクティスページは、初めてCodexを使う際に陥りがちな間違いを次のように整理しています。
+
+| よくある間違い | なぜ問題か |
+|---|---|
+| 恒久的なルールを毎回プロンプトに書き続ける | AGENTS.mdやSkillに移すべき情報であり、その都度書くと一貫性が失われる |
+| ビルド/テストの実行方法を伝えていない | 検証手段がないと、Codex自身が成果物の品質を確認できない |
+| 複雑なタスクで計画立てを省略する | 曖昧なまま実装が進み、手戻りが増える |
+| 仕組みを理解する前にフルアクセス権限を与える | 意図しない変更やセキュリティ上のリスクにつながる |
+| git worktreeを使わず同じファイルを複数スレッドで編集する | 変更が競合し、レビューが困難になる |
+| 手動運用が安定する前にいきなり自動化する | Automationsは「安定してから」が原則 |
+| 逐一監視するような使い方をする | 並行して自分の作業を進める運用の方が本来の効果を発揮する |
+| プロジェクト単位で1スレッドにまとめる | タスクごとにスレッドを分けないとコンテキストが肥大化し、結果が悪化する |
+
+---
+
+## 著名開発者の視点: Codexは実際どう評価されているか
+
+### Simon Willison(著名なオープンソース開発者・LLMウォッチャー)
+
+自身のブログで日々のLLMリリースを検証しているSimon Willisonは、2026年4月のCodex CLIアップデートで追加された `/goal` 機能を、Ralph Wiggum的な「目標が達成されるまで回り続けるループ」を公式に取り込んだものと位置付けて紹介しています。また、OpenAI関係者の発言を引用する形で、Codex系モデルは「ハーネス(実行環境)の存在を前提に学習されている」――つまりツール利用や実行ループ、圧縮、反復的な検証はモデルに後付けされた機能ではなく、モデルの学習過程そのものに組み込まれているという点を紹介しており、これは「Codex CLIというハーネスに最適化されたモデルを、そのハーネスの流儀通りに使うべきだ」という本ガイドの主張とも整合します。
+
+### Armin Ronacher(Flask/Jinja2の作者、Sentryのエンジニアリング責任者)
+
+Armin Ronacherは自身のブログとYouTube講演で、エージェント型コーディング全般に関する実践的な原則を数多く発信しています。代表的な指摘の一つが「**エージェント向けのツールは、人間向けのAPIとは異なる設計原則が必要で、LLMという“カオスモンキー”に完全に誤用されても壊れないよう保護すべきだ**」というものです。また、コードの複雑さについても「シンプルなコードはエージェント文脈で明確に有利であり、動作する最も愚直な実装をエージェントにやらせるべきだ」と繰り返し述べています。同氏は主にClaude Codeを日常的に使っていると公言していますが、Codexやopencode、gooseなど類似のエージェントも比較対象として挙げており、特定のベンダーへの偏りなく実践知を発信している点が特徴です。同氏は2026年に自ら軽量なコーディングエージェント「Pi」も開発しており、意図的にMCPを実装しない設計判断を下すなど、ツール設計そのものへの強い関心を持っています。
+
+### 主要なコーディングエージェントの位置付け(2026年半ば時点のコミュニティ評価)
+
+以下は複数のテクニカルブログが2026年半ばに整理していた大まかな比較で、優劣を断定するものではなく、設計思想の違いを把握するための参考情報です。
+
+| ツール | 開発元 | ライセンス | 特徴として報告されている点 |
+|---|---|---|---|
+| **Codex CLI** | OpenAI | Apache-2.0(オープンソース) | サブエージェント・MCP・Hooks・クラウド実行など機能面でClaude Codeと肩を並べる規模に成長したと評されている |
+| **Claude Code** | Anthropic | 商用 | Armin Ronacherなど著名開発者が日常的に利用し、ブラウザ操作やGit連携の自動化などで高く評価されている |
+| **OpenCode** | コミュニティ(anomalyco) | MIT | プロバイダー非依存の代表的なオープンソースハーネスとして支持を広げている |
+| **Pi** | Armin Ronacher / Mario Zechner | MIT | 1000トークン未満のシステムプロンプトで動く軽量ハーネス。意図的にMCPを実装していない設計思想が特徴 |
+
+---
+
+## まとめ: 運用チェックリスト
+
+Codexは「毎回ゼロから指示する一回限りのアシスタント」ではなく、「時間をかけて設定・改善していくチームメイト」として扱うことが、公式ガイドが一貫して強調している姿勢です。以下は本ガイドの内容を実務に落とし込むためのチェックリストです。
+
+- [ ] プロンプトにGoal・Context・Constraints・Done whenの4要素を意識して書いているか
+- [ ] タスクの複雑さに応じてReasoning Effortを使い分けているか(既定はmedium)
+- [ ] 複雑・曖昧なタスクでは `/plan` や `/goal` を使って計画・完了条件を先に固めているか
+- [ ] チームの規約・検証手順をAGENTS.mdに書き、プロンプトで毎回繰り返していないか
+- [ ] `~/.codex/config.toml` と `.codex/config.toml` で個人設定とプロジェクト設定を役割分担しているか
+- [ ] サンドボックス・承認ポリシーを用途(初回調査/通常開発/CI)に応じて使い分けているか
+- [ ] テスト・Lint・差分レビューをワークフローに組み込み、`/review` やAGENTS.md経由のレビュー観点を活用しているか
+- [ ] リポジトリ外のコンテキストが必要な場面でMCPを検討しているか(ただし繋ぎすぎに注意)
+- [ ] 繰り返し行っている作業をSkillに切り出しているか
+- [ ] 安定したワークフローだけをAutomationsに切り出しているか
+- [ ] 並列作業ではgit worktreeでスレッドを分離しているか
+- [ ] CI/CDでは公式の `openai/codex-action` や `codex exec` を使い、APIキーをジョブ全体に晒していないか
+
+---
+
+## 参考情報源(出典一覧)
+
+### OpenAI公式ドキュメント
+
+- Prompting – Codex: https://developers.openai.com/codex/prompting
+- Best practices – Codex: https://developers.openai.com/codex/learn/best-practices
+- Config basics – Codex: https://developers.openai.com/codex/config-basic
+- Sandboxing – Codex: https://developers.openai.com/codex/concepts/sandboxing
+- Auto-review – Codex: https://developers.openai.com/codex/concepts/sandboxing/auto-review
+- Subagents – Codex: https://developers.openai.com/codex/concepts/subagents
+- AGENTS.md – Codex: https://developers.openai.com/codex/guides/agents-md
+- MCP – Codex: https://developers.openai.com/codex/mcp
+- Skills – Codex: https://developers.openai.com/codex/skills
+- Non-interactive mode – Codex: https://developers.openai.com/codex/noninteractive
+- GitHub Action – Codex: https://developers.openai.com/codex/github-action
+- Models – Codex: https://developers.openai.com/codex/models
+- Changelog – Codex: https://developers.openai.com/codex/changelog
+- Using Goals in Codex(Cookbook): https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex
+- Codex Prompting Guide(Cookbook): https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide
+- Reasoning models – OpenAI API: https://developers.openai.com/api/docs/guides/reasoning
+- Model guidance – OpenAI API: https://developers.openai.com/api/docs/guides/prompt-guidance
+
+### 著名な開発者・オピニオンリーダーの発信
+
+- Simon Willison, "Codex CLI 0.128.0 adds /goal" ほか関連投稿: https://simonwillison.net/tags/openai/
+- Simon Willison on Codex(タグ一覧): https://simonwillison.net/tags/codex/
+- Simon Willison, "OpenAI's accidental cyberattack against Hugging Face is science fiction that happened": https://simonwillison.net/2026/Jul/22/openai-cyberattack/
+- Armin Ronacher, "Agentic Coding Recommendations": https://lucumr.pocoo.org/2025/6/12/agentic-coding/
+- Armin Ronacher, "Pi: The Minimal Agent Within OpenClaw": https://lucumr.pocoo.org/2026/1/31/pi/
+- Chier Hu, "Using Goals in OpenAI Codex: Patterns and Case Studies"(Medium): https://chierhu.medium.com/using-goals-in-openai-codex-cd88ce551eb7
+
+### 業界動向・比較記事・コミュニティガイド
+
+- OpenAI Codex Best Practices for 2026(getmaxim.ai): https://www.getmaxim.ai/articles/openai-codex-best-practices-for-2026-workflows-governance-and-multi-provider-routing/
+- Proven Patterns for OpenAI Codex in 2026(DEV Community): https://dev.to/kuldeep_paul/proven-patterns-for-openai-codex-in-2026-prompts-validation-and-gateway-governance-1jhm
+- OpenAI Codex CLI Guide 2026(codegateway.dev): https://www.codegateway.dev/en/blog/openai-codex-cli-complete-guide-2026
+- OpenAI Codex Guide(kingy.ai): https://kingy.ai/news/the-complete-guide-to-openai-codex/
+- Codex CLI approval_policy 解説(smartscope.blog): https://smartscope.blog/en/generative-ai/chatgpt/codex-cli-approval-policy-implementation/
+- Codex CLI approval policies and sandbox modes explained(Vladimir Siedykh): https://vladimirsiedykh.com/blog/codex-cli-approval-modes-2025
+- Codex CLI config.toml Deep Dive(ofox.ai): https://ofox.ai/blog/codex-cli-config-toml-deep-dive/
+- The Codex CLI Customisation Stack(Codex Knowledge Base): https://codex.danielvaughan.com/2026/04/12/codex-cli-customisation-stack-unified-system/
+- Codex CLI for CI/CD(Codex Knowledge Base): https://codex.danielvaughan.com/2026/03/26/codex-cli-cicd-non-interactive/
+- Reasoning Effort Tuning(Codex Knowledge Base): https://codex.danielvaughan.com/2026/03/27/reasoning-effort-tuning/
+- Best Open Source CLI Coding Agents in 2026(Pinggy Blog): https://pinggy.io/blog/best_open_source_cli_coding_agents/
+- Agents.md best practices(GitHub Gist): https://gist.github.com/0xfauzi/7c8f65572930a21efa62623557d83f6e
+- OpenAI Codex(AI agent) – Wikipedia: https://en.wikipedia.org/wiki/OpenAI_Codex_(AI_agent)
+
+### セキュリティインシデント関連(2026年7月)
+
+- Hugging Face, "Security incident disclosure — July 2026": https://huggingface.co/blog/security-incident-july-2026
+- OpenAI's sandbox escape報道まとめ(Malwarebytes): https://www.malwarebytes.com/blog/news/2026/07/openais-agent-escaped-its-sandbox-during-a-security-test
+- The Hacker News, "OpenAI Says Its AI Models Escaped Sandbox...": https://thehackernews.com/2026/07/openai-says-its-own-ai-models-escaped.html
+
+---
+
+*本ガイドは2026年7月30日時点の情報を基に作成しています。Codexは頻繁にアップデートされるため、設定キー名・スラッシュコマンド・モデル名などは公式ドキュメントで随時確認してください。*

From 41cd812d04cb3a2e504d7a1ba2c8fc084d61f711 Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 12:58:27 +0900
Subject: [PATCH 06/53] chore(codex): move source html and md files to
 archive/html/OpenAI and archive/md/OpenAI

---
 .../OpenAI/Openai-codex-agents-multiagent-best-practices.html     | 0
 .../md/OpenAI/Openai-codex-agents-multiagent-best-practices.md    | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename Openai-codex-agents-multiagent-best-practices.html => archive/html/OpenAI/Openai-codex-agents-multiagent-best-practices.html (100%)
 rename Openai-codex-agents-multiagent-best-practices.md => archive/md/OpenAI/Openai-codex-agents-multiagent-best-practices.md (100%)

diff --git a/Openai-codex-agents-multiagent-best-practices.html b/archive/html/OpenAI/Openai-codex-agents-multiagent-best-practices.html
similarity index 100%
rename from Openai-codex-agents-multiagent-best-practices.html
rename to archive/html/OpenAI/Openai-codex-agents-multiagent-best-practices.html
diff --git a/Openai-codex-agents-multiagent-best-practices.md b/archive/md/OpenAI/Openai-codex-agents-multiagent-best-practices.md
similarity index 100%
rename from Openai-codex-agents-multiagent-best-practices.md
rename to archive/md/OpenAI/Openai-codex-agents-multiagent-best-practices.md

From ff6c73b8a71c5a064bf7def08fd07e941d32d8e0 Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 13:03:48 +0900
Subject: [PATCH 07/53] test(codex): add failing spec for codex agent
 multiagent guide migration

---
 web-next/app/codex/agent/page.test.tsx | 88 +++++++++++++-------------
 1 file changed, 43 insertions(+), 45 deletions(-)

diff --git a/web-next/app/codex/agent/page.test.tsx b/web-next/app/codex/agent/page.test.tsx
index 35b9c22d..e4fe4cc7 100644
--- a/web-next/app/codex/agent/page.test.tsx
+++ b/web-next/app/codex/agent/page.test.tsx
@@ -1,18 +1,14 @@
-// Phase C-3 [Red] contract test.
-// All 8 tests fail until page.tsx is implemented.
-
 /**
- * Phase C-3 契約テスト (/codex/agent)。
+ * 契約テスト (/codex/agent)。
+ * OpenAI Codex サブエージェント開発ベストプラクティス完全ガイドの契約検証
  *
  * 固定する契約:
- * - `metadata` が export され、title に「Codex」を含む
- * - `
    ` が 1 つ存在し、`Codex` を含む
- * - 12 個の section id が存在する (s01〜s11 + sources)
- *   (legacy は 
     × 12、id 属性なし → synthetic id 付与)
- * - 12 個の TOC リンクが `#section-id` 形式で存在する
- * - 外部リンク (http/https) には全て `target="_blank"` かつ
- *   `rel="noopener noreferrer"` が付与されている
- * - `sources` セクション内に 19 件以上の外部リンクが存在する
+ * - `metadata` が export され、title に「OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド」を含む
+ * - `
    ` が 1 つ存在し、`OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド` と一致する
+ * - 20 個の section id (前提, Step 1-18, 参考文献) が存在する
+ * - 20 個の TOC リンクが `#...` 形式で存在する
+ * - 外部リンク (http/https) には全て `target="_blank"` かつ `rel="noopener noreferrer"` が付与されている
+ * - 参考文献セクション内に 17 件の外部リンクが存在する
  * - 静的検査: 生 HTML 流し込み API (React の XSS 危険 prop) を使用していない
  */
 
@@ -24,33 +20,40 @@ import { describe, expect, it } from "vitest";
 import CodexAgentPage, { metadata as rawMetadata } from "@/app/codex/agent/page";
 
 const Page = CodexAgentPage as unknown as () => ReactElement;
-// Next.js の Metadata 型を避けるための最小ローカル型 (実体は Metadata オブジェクト)。
 type MetadataLike = { title?: unknown; description?: unknown };
 const metadata = rawMetadata as unknown as MetadataLike;
 
-const EXPECTED_SECTION_IDS = [
-  "s01",
-  "s02",
-  "s03",
-  "s04",
-  "s05",
-  "s06",
-  "s07",
-  "s08",
-  "s09",
-  "s10",
-  "s11",
-  "sources",
+export const EXPECTED_SECTION_IDS = [
+  "この記事の前提-requirementsmdについて一点補足",
+  "step-1-codex-エコシステム全体像",
+  "step-2-agentsmd--基本のプロジェクト指示ファイル",
+  "step-3-agentsoverridemd--一時的な上書きレイヤー",
+  "step-4-発見順序とマージロジックの詳細",
+  "step-5-configtoml--階層構造とスコープ",
+  "step-6-configtoml-の主要キーとスキーマ",
+  "step-7-requirementstoml--管理者施行の強制設定",
+  "step-8-skillmd--progressive-disclosure-によるスキル拡張",
+  "step-9-skills-運用のベストプラクティス",
+  "step-10-subagents-の概念--コンテキスト汚染とコンテキスト腐敗",
+  "step-11-カスタムサブエージェント定義ファイル",
+  "step-12-マルチエージェントワークフロー設計パターン①-prレビューの3分割",
+  "step-13-マルチエージェントワークフロー設計パターン②-csvファンアウト",
+  "step-14-モデルreasoning-effort-の選定指針",
+  "step-15-hooks-と-rulesexecpolicy-によるガバナンス",
+  "step-16-実践チェックリスト",
+  "step-17-トラブルシューティング",
+  "step-18-まとめ",
+  "参考文献",
 ] as const;
 
 describe("/codex/agent - metadata", () => {
-  it("exports a metadata object with title containing Codex", () => {
+  it("exports a metadata object with title containing OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド", () => {
     expect(metadata).toBeDefined();
     const title =
       typeof metadata.title === "string"
         ? metadata.title
         : (metadata.title as { default?: string } | undefined)?.default;
-    expect(title).toMatch(/Codex/);
+    expect(title).toMatch(/OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド/);
   });
 
   it("exports a metadata object with non-empty description", () => {
@@ -60,34 +63,30 @@ describe("/codex/agent - metadata", () => {
 });
 
 describe("/codex/agent - page structure", () => {
-  it("renders an 
     containing 'Codex'", () => {
+  it("renders an 
     containing 'OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド'", () => {
     const { container } = render();
     const h1 = container.querySelector("h1");
     expect(h1).not.toBeNull();
-    expect(h1?.textContent).toMatch(/Codex/);
+    expect(h1?.textContent).toMatch(/OpenAI Codex サブエージェント開発ベストプラクティス完全ガイド/);
   });
 
-  it("renders all 12 expected section ids", () => {
+  it("renders all 20 expected section ids", () => {
     const { container } = render();
     for (const id of EXPECTED_SECTION_IDS) {
-      const el = container.querySelector(`#${id}`);
+      const el = container.querySelector(`#${CSS.escape(id)}`);
       expect(el, `section id="${id}" must exist`).not.toBeNull();
     }
   });
 
-  it("renders 12 TOC links pointing to all section anchors", () => {
+  it("renders 20 TOC links pointing to all section anchors", () => {
     const { container } = render();
-    // CSS Modules のクラス名はハッシュ化されるため nav.toc は使えない。
-    // ページ内の全 nav のうち、hash リンク (#) を持つものを TOC nav として絞り込む。
     const tocNav = Array.from(container.querySelectorAll("nav")).find((nav) =>
       nav.querySelector('a[href^="#"]')
     );
     expect(tocNav, "TOC nav element must exist").not.toBeUndefined();
     const tocAnchors = tocNav?.querySelectorAll('a[href^="#"]') ?? [];
     const tocHrefs = Array.from(tocAnchors).map((a) => a.getAttribute("href"));
-    const expectedHrefs = EXPECTED_SECTION_IDS.map((id) => `#${id}`);
-    expect(tocHrefs).toHaveLength(expectedHrefs.length);
-    expect(tocHrefs).toEqual(expect.arrayContaining(expectedHrefs));
+    expect(tocHrefs).toHaveLength(20);
     for (const id of EXPECTED_SECTION_IDS) {
       expect(tocHrefs, `TOC must link to #${id}`).toContain(`#${id}`);
     }
@@ -110,20 +109,19 @@ describe("/codex/agent - external link safety", () => {
     }
   });
 
-  it("sources section contains at least 19 external links", () => {
+  it("references section contains at least 17 external links", () => {
     const { container } = render();
-    const sources = container.querySelector("#sources");
-    expect(sources).not.toBeNull();
-    if (!sources) throw new Error("sources is null");
-    const externals = sources.querySelectorAll('a[href^="http"]');
-    expect(externals.length).toBeGreaterThanOrEqual(19);
+    const references = container.querySelector(`#${CSS.escape("参考文献")}`);
+    expect(references).not.toBeNull();
+    if (!references) throw new Error("references section is null");
+    const externals = references.querySelectorAll('a[href^="http"]');
+    expect(externals.length).toBeGreaterThanOrEqual(17);
   });
 });
 
 describe("/codex/agent - static source safety", () => {
   it("does not use the React raw-HTML injection prop", () => {
     const source = readFileSync(join(__dirname, "page.tsx"), "utf8");
-    // オブフスケート (false positive / prompt hook 誤検知回避)。
     const needle = ["danger", "ously", "Set", "Inner", "HTML"].join("");
     expect(source.includes(needle)).toBe(false);
   });

From ca8cad79563a78c4f3ce17d728c4f845ac0b252c Mon Sep 17 00:00:00 2001
From: myoshizumi 
Date: Thu, 30 Jul 2026 13:05:50 +0900
Subject: [PATCH 08/53] feat(codex): replace /codex/agent with OpenAI Codex
 multiagent best practices guide

---
 web-next/app/codex/agent/TocObserver.tsx |   65 +
 web-next/app/codex/agent/page.module.css | 1058 ++----
 web-next/app/codex/agent/page.tsx        | 3789 ++++++++--------------
 web-next/lib/page-registry.ts            |    8 +-
 4 files changed, 1676 insertions(+), 3244 deletions(-)
 create mode 100644 web-next/app/codex/agent/TocObserver.tsx

diff --git a/web-next/app/codex/agent/TocObserver.tsx b/web-next/app/codex/agent/TocObserver.tsx
new file mode 100644
index 00000000..d773254f
--- /dev/null
+++ b/web-next/app/codex/agent/TocObserver.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import { useEffect } from "react";
+import styles from "./page.module.css";
+
+export default function TocObserver() {
+  useEffect(() => {
+    // 1. Sidebar Toggle for Mobile
+    const btn = document.getElementById("sidebarToggle");
+    const sidebar = document.getElementById("sidebar");
+    if (btn && sidebar) {
+      const handleToggle = () => {
+        sidebar.classList.toggle(styles.sidebarOpen);
+      };
+      btn.addEventListener("click", handleToggle);
+
+      const navLinks = sidebar.querySelectorAll(`.${styles.navLink}`);
+      const handleLinkClick = () => {
+        sidebar.classList.remove(styles.sidebarOpen);
+      };
+      navLinks.forEach((link) => link.addEventListener("click", handleLinkClick));
+
+      return () => {
+        btn.removeEventListener("click", handleToggle);
+        navLinks.forEach((link) => link.removeEventListener("click", handleLinkClick));
+      };
+    }
+  }, []);
+
+  useEffect(() => {
+    // 2. IntersectionObserver for TOC scroll spy
+    const headings = Array.from(document.querySelectorAll(`.${styles.main} h2[id]`));
+    const links = Array.from(document.querySelectorAll(`.${styles.navLink}`));
+    if (!headings.length || !links.length) return;
+
+    const linkMap = new Map();
+    links.forEach((a) => {
+      const href = a.getAttribute("href") ?? "";
+      if (href.startsWith("#")) {
+        linkMap.set(decodeURIComponent(href.slice(1)), a);
+      }
+    });
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            const id = entry.target.id;
+            links.forEach((l) => l.classList.remove(styles.navLinkActive));
+            const activeLink = linkMap.get(id);
+            if (activeLink) {
+              activeLink.classList.add(styles.navLinkActive);
+            }
+          }
+        });
+      },
+      { rootMargin: "-80px 0px -70% 0px", threshold: 0 }
+    );
+
+    headings.forEach((h) => observer.observe(h));
+    return () => observer.disconnect();
+  }, []);
+
+  return null;
+}
diff --git a/web-next/app/codex/agent/page.module.css b/web-next/app/codex/agent/page.module.css
index a323d216..9e1e1ba8 100644
--- a/web-next/app/codex/agent/page.module.css
+++ b/web-next/app/codex/agent/page.module.css
@@ -1,814 +1,408 @@
-/* legacy/codex/agent.html の 
   
   
-    
+