Codexのベストプラクティス＆Tips 45選コードとテストの95%をAIエージェントが書く現場で見えたこと

皆さんこんにちは！
現役IT執行役員のグイグイです⚡

今回は、Codexを使ううえで押さえておきたいベストプラクティスを整理します。

Codex用の情報として集めたものがベースですが、Claude Code、Gemini CLI、GitHub Copilotのエージェント機能、Cursorなど、AI開発エージェント全般にもかなり共通する内容です。

私の現場では、実装コードとテストコードの作成という意味では、体感で95%近くをAIエージェントが書いています。

個人開発では、コードを書く作業そのものはほぼ100%AIエージェントに任せています。

その中で感じているのは、ツールの性能差ももちろんありますが、それ以上に「渡し方」と「検証のさせ方」で結果がかなり変わるということです。

で、この記事は正直、かなり長いです💦

なので、最初から最後まで真面目に読まなくて大丈夫です。

ざっと流し読みして、自分の使い方に近いところ、今困っていることに関係ありそうなところ、あとで使えそうなところだけ拾ってください。

読むための記事というより、必要なときに戻ってくるための実務メモです。

ぜひ、自分の開発現場や個人開発で役立ててください。

この記事の読み方

45個すべてを一気に読む必要はありません。

まずは、以下の目印を参考にしてください。

🔥 最重要：AIエージェント活用の土台。最初に押さえたいもの
⭐ 重要：実務で効果が出やすく、優先して試す価値が高いもの
🔒 要注意：セキュリティ・事故防止の観点で必ず意識したいもの

また、各Tipsには適用範囲の目安も入れています。

🌐 AIエージェント全般：Codexに限らず、Claude Code、Cursor、Gemini CLIなどにも通じるもの
🧩 Codex寄り：Codexの機能・コマンド・仕様に特に関係が深いもの
🔌 連携系：MCP、SDK、Plugins、外部ツール連携に関するもの
🔒 安全系：サンドボックス、権限、セキュリティに関するもの

Codex固有の機能は 🧩 を付けています。

一方で、Codexの名前が出ていても、考え方自体は他のAIエージェントにも応用できるものがあります。

📂 カテゴリ1: プロンプトデザインとコンテキスト管理

🔥 1. 4つの基本要素（Goal, Context, Constraints, Done when）を明示する

適用範囲：🌐 AIエージェント全般

• やり方: プロンプトに「①ゴール（目的）」「②コンテキスト（参考ファイル）」「③制約」「④完了条件」を構造化して記述する。

• なぜ効果があるのか: AIの前提や憶測を排除し、タスクのスコープ（範囲）を厳密に絞り込めるためハルシネーション（嘘の生成）が激減する。

• どんな時に有効か: 大規模なコードベースへの変更や、手戻りが許されない高リスクな実装を依頼する時。

⭐ 2. ファイル指定（@mention）で探索範囲を絞る

適用範囲：🌐 AIエージェント全般

• やり方: プロンプト内で @auth_service.py のように対象ファイルを明示して指示する。

• なぜ効果があるのか: Codexがリポジトリ全体を無駄にスキャンするコストをカットし、ピンポイントで必要なトークンだけを作業メモリ（コンテキスト）に読み込めるため。

• どんな時に有効か: 修正すべき対象ファイルや、真似してほしい実装パターンの既存ファイルがはっきり分かっている時。

⭐ 3. スタックトレースは丸ごと貼り付ける

適用範囲：🌐 AIエージェント全般

• やり方: ターミナルに出力されたビルドエラーやランタイムエラーのエラーメッセージ、スタックトレース、環境情報をそのままプロンプトへ流し込む。

• なぜ効果があるのか: 断片的な情報よりも、エラーの発生源や依存関係のコールスタックを網羅した生データの方が、Codexモデルは因果関係を正確に推論できるため。

• どんな時に有効か: インシデント調査や、原因不明の難解な非同期バグが発生してデバッグが立ち行かない時。

⭐ 4. 命名やスタイルの「否定例（Do Not）」を提示する

適用範囲：🌐 AIエージェント全般

• やり方: 「console.log は使うな、必ず内部の logger モジュールを介せ」のように、やってはいけないアンチパターンを明確に指示する。

• なぜ効果があるのか: LLMは一般的なネット上のコードを多く学習しているため、指示がないと一般的な（しかし自社の規約には反する）コードを出力しがちになるのを防ぐため。

• どんな時に有効か: チーム特有の厳しいコーディング規約や、セキュリティ上禁止されているライブラリの混入を防ぎたい時。

⭐ 5. 複雑な作業はToDoリスト駆動型で指示する

適用範囲：🌐 AIエージェント全般

• やり方: 指示をステップバイステップ（1. 〇〇、2. ✕✕）のチェックリスト形式にして、上から順番に実行するよう命じる。

• なぜ効果があるのか: 一度に多くのことをやらせようとすると注意力が分散するが、タスクを最小単位に分解（ToDoリスト化）することで、各ステップの出力精度が高まるため。

• どんな時に有効か: 複数ファイルにまたがるAPI仕様の変更や、手順が複雑なマイグレーション作業。

⭐ 6. セッション（スレッド）は「1タスク1スレッド」を厳守する

適用範囲：🌐 AIエージェント全般

• やり方: 1つの機能実装やバグ修正が終わったら、次の作業に移る前に必ず /new コマンド等で新しいスレッド（セッション）を開始する。

• なぜ効果があるのか: 終わったタスクの履歴をスレッドに残したままだと、蓄積した過去のコンテキストがノイズとなり、次の新しいタスクの判断を鈍らせる（コンテキストの汚染）ため。

• どんな時に有効か: 日常の開発フローで、複数の異なる機能追加や微細な修正をテンポよく切り替えて進めていく時。

7. コンテキストが肥大化したら /compact コマンドを使用する

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: 会話が長くなり、AIの挙動が怪しくなってきたと感じたら /compact スラッシュコマンドを実行する。

• なぜ効果があるのか: 過去の生のやり取りトークンをスマートに要約・圧縮（Compaction）し、重要なシステム理解の文脈だけを維持したまま、作業メモリの空き容量を確保できるため。

• どんな時に有効か: 数時間に及ぶリファクタリングセッションなど、同一スレッド内で何度もエージェントと修正のラリーを繰り返している時。

8. 画面をクリアする際は /clear または Ctrl+L を使い分ける

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: スレッドの思考履歴は残したいがターミナルの見た目だけを綺麗にするなら Ctrl+L を、チャット自体を同じセッション内でリセットするなら /clear を使用する。

• なぜ効果があるのか: 表示上のデクラッター（整理）と思考コンテキストのクリアを物理的に分けることで、人間側の認知負荷を下げつつ、AIのメモリ状態を正しく制御できるため。

• どんな時に有効か: ターミナルのログが溢れて diff や直近の応答が見づらくなったが、直前の推論コンテキストはそのまま維持したい時。

9. 音声文字起こし機能（ホットキー設定）による文脈の多量投入

適用範囲：🌐 AIエージェント全般

• やり方: 設定画面で音声入力ホットキー（スペースキー長押し等）を登録し、やりたい内容を口頭で長めに説明してインプットする。

• なぜ効果があるのか: 人間はタイピングするよりも声で話す方が圧倒的に速いため、開発の背景や「なぜこの設計にするのか」というリッチな文脈情報を、認知コストをかけずに大量にAIへ供給できるため。

• どんな時に有効か: キーボードを叩くのが面倒な長文の仕様説明や、ルーチンワークのタスクを一発で詳細に任せたい時。

🛠️ カテゴリ2: プラニングと設計駆動

🔥 10. 実装前に「Askモード」または「/plan」で計画を作らせる

適用範囲：🌐 AIエージェント全般

• やり方: いきなりコードを書かせず、まずは /plan（または Askモード）を使って、AIにテキストベースの実装計画を出力させる。

• なぜ効果があるのか: 計画を一度挟むことで、AIが自身の出力した設計方針に強く条件付け（アンカー）され、Codeモードに移行した際の実装が安定・高速化するため。

• どんな時に有効か: 影響範囲が広く、複数のモジュールやファイルに手を入れる必要がある大規模リファクタリングの初期段階。

⭐ 11. 曖昧な要件では「AIにインタビュー（逆質問）」させる

適用範囲：🌐 AIエージェント全般

• やり方: 「こういう機能を作りたいが、要件が固まっていない。実装に必要な仕様や、私の前提で疑わしい点を洗い出すために私にインタビュー（質問）してくれ」とプロンプトで指示する。

• なぜ効果があるのか: 人間側の頭の中にある隠れた前提条件やビジネスロジックを、AIからの質問によって言語化し、実装前の仕様のズレを防ぐことができるため。

• どんな時に有効か: Greenfield（新規開拓）プロジェクトや、顧客からのフワッとした要望を具体的なコードへ落とし込まなければならない時。

⭐ 12. 長期タスクでは PLANS.md テンプレートを導入する

適用範囲：🌐 AIエージェント全般

• やり方: リポジトリ内に PLANS.md または pilot_execplan.md という設計・進捗管理ファイルを生成し、現在のタスクの進捗状況をマイルストーンごとにAI自身に更新させる。

• なぜ効果があるのか: セッションやスレッドを跨いでも、「現在どのマイルストーンまで完了し、次に何をすべきか」という大局的な記憶（ExecPlan）がファイルとして永続化され、エージェントが迷子にならないため。

• どんな時に有効か: 数日〜数週間に及ぶ、レガシーコードの近代化（モダナイゼーション）や大規模なフレームワークの移行作業。

⭐ 13. エージェントに過去の試行錯誤を振り返らせる（リバース・エンジニアリング）

適用範囲：🌐 AIエージェント全般

• やり方: 修正が成功した後に、「今回の修正で最も friction（摩擦）になった原因と、今後同じミスをしないための改善案を報告してくれ」と依頼する。

• なぜ効果があるのか: AI自身に自己反省（Reflection）を行わせることで、コードからだけでは読み取れなかった仕様の「罠」や、プロジェクト固有の癖を明文化できるため。

• どんな時に有効か: 独自のフレームワークや社内ライブラリを使っていて、Codexの一般的な学習データだけでは対応しきれない特殊なプロジェクト環境。

14. プロダクト仕様書（Spec）をそのまま貼ってモック/スタブを作らせる

適用範囲：🌐 AIエージェント全般

• やり方: PMやビジネスサイドが書いた製品仕様書や Markdown のドキュメントをそのままコンテキストに渡し、インターフェースの骨組み（スタブ実装）だけをスキャフォールド（雛形生成）させる。

• なぜ効果があるのか: 人間が手作業でルーティングやバリデーションのボイラープレート（定型コード）を配線する時間を減らし、すぐに動作確認可能なプロトタイプを手に入れやすくなるため。

• どんな時に有効か: 新規のAPIエンドポイント開発や、新しい画面・ドメインモデルを立ち上げる開発サイクルの最初期。

15. 複数提案を同時生成する「Best-of-N」機能を活用する

適用範囲：🌐 AIエージェント全般

• やり方: 1つの困難な問題に対して、同時に複数の異なる解決策（回答）を生成させ、人間がそれらを比較・マージする。

• なぜ効果があるのか: 1回限りの出力（一問一答）に頼ると局所的な解に縛られやすいが、バリエーションを持たせることで、パフォーマンスや可読性の面で最適なアプローチを人間が「良いとこ取り」できるため。

• どんな時に有効か: アルゴリズムの最適化や、複数の設計パターン（イベント駆動型 vs リクエスト応答型など）のトレードオフを比較検討したい時。

📝 カテゴリ3: AGENTS.md & 永続コンテキスト管理

🔥 16. リポジトリ固有の共通前提を AGENTS.md に集約する

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: プロジェクトのルートに AGENTS.md というエージェント専用のREADMEを作成し、ディレクトリマップ、ビルド方法、コーディング標準を記述する。

• なぜ効果があるのか: スレッドやプロンプトを跨いでも、Codexが常に自動でこのファイルを読み込むため、プロジェクト固有のルールを何度も手動で説明するコストがなくなるため。

• どんな時に有効か: 複数人のチームで開発しており、AIエージェントに全員共通の品質基準やCI/CDのルールを守らせたい時。

17. 個人デフォルトは `~/.codex/AGENTS.md` やグローバル設定に置く

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: 自分好みのコミットメッセージ生成ルールや、個人的なコードレビュー基準は、リポジトリ側ではなく、ユーザー単位のグローバル設定に配置する。Codexでは、個人向けの共通指示を `~/.codex/AGENTS.md` に置ける。

• なぜ効果があるのか: リポジトリ側のチーム共有設定を汚すことなく、自分のPCで動くCodexに、自分だけの一貫した作業ルールを適用できるため。

• どんな時に有効か: 会社のリポジトリ、個人の趣味の開発など、異なるプロジェクトを日常的に行き来しながらも、自分特有の作業フローは維持したい時。

18. 一時的な環境差異は AGENTS.override.md で制御する

適用範囲：🧩 Codex寄り

• やり方: Gitで管理されている共通の AGENTS.md を書き換える代わりに、ローカル環境にだけ AGENTS.override.md を作成して一時的なローカルルールを記載する。

• なぜ効果があるのか: チームの共有資産を汚す（不要な差分を生む）ことなく、特定のデバッグ作業や自分のマシン固有のパス設定をAIに優先して適用させることができるため。

• どんな時に有効か: ローカル環境でのみ特定のテストスイート（例：重いE2Eテストなど）をスキップさせたい、あるいは特定のモックサーバーを参照させたい時。

🔥 19. 2回同じ間違いをされたら AGENTS.md を更新する

適用範囲：🌐 AIエージェント全般 / 🧩 CodexではAGENTS.mdに反映

• やり方: エージェントが同じ種類のバグや規約違反を2回起こしたら、それを「AGENTS.mdに制約を書き足すトリガー」として運用する。

• なぜ効果があるのか: 机上の空論のルールを詰め込むのではなく、実際の開発で発生したリアルな「AIのつまずき」に基づいた、費用対効果の高い実戦的なガードレールが構築されていくため。

• どんな時に有効か: AI駆動開発をチームに導入した初期段階で、エージェントの出力のブレを徐々に調教・安定させていきたい時。

20. `AGENTS.md` は32KB未満に保ち、詳細は別ファイルへリンクする

適用範囲：🧩 Codex寄り

• やり方: 共通ルールファイルは極力簡潔（ミニマル）に保ち、長大なAPIリファレンスやドキュメントは別ファイルに切り分けて `AGENTS.md` から相対リンクを張る。

• なぜ効果があるのか: Codexは `AGENTS.md` などのプロジェクト指示を読み込みますが、読み込み量には上限があります。デフォルトでは `project_doc_max_bytes` が32KiBに設定されており、上限に達するとそれ以上の指示は読み込まれません。そのため、最も重要なコア規約を短く保つことが重要です。

• 補足: 必要に応じて `config.toml` の `project_doc_max_bytes` で上限を調整できます。ただし、むやみに増やすより、詳細ドキュメントを分割してリンクする方が運用しやすいです。

• どんな時に有効か: 歴史が長く、仕様書や環境構築マニュアルなどのドキュメント資産が大量に蓄積されている大規模プロジェクト。

21. コマンドライン引数を減らし config.toml で設定を一元管理する

適用範囲：🧩 Codex寄り

• やり方: モデルの選択、デフォルトの推論レベル（Reasoning Effort）、サンドボックスの権限設定などは、CLIの引数で毎回渡さずに .codex/config.toml で管理する。

• なぜ効果があるのか: ターミナル（CLI）、VS Code（IDE）、デスクトップアプリのどのインターフェースからCodexを起動しても、同一のモデル挙動や安全プロファイルが継承されるため。

• どんな時に有効か: 日によってターミナルでの高速な単発修正と、デスクトップアプリでの視覚的なマルチタスク管理をハイブリッドに使い分ける時。

22. 割り込みが多い環境ではセッションの保存と /resume 復元を活用する

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: オンコール対応や会議で作業を中断する際、現在のスレッドをそのまま保存し、戻ってきたら /resume（または codex resume）コマンドで思考コンテキストごと復元する。

• なぜ効果があるのか: 開発者が「どこまでやって、次に何をするつもりだったか」を思い出す（コンテキストスイッチ）コストを減らし、AI側もこれまでの推論の軌跡を維持したまま、続きから作業を再開できるため。

• どんな時に有効か: ミーティングが頻発するマネジメント兼務のエンジニアや、突発的な割り込み調査が多い運用・保守フェーズ。

🧪 カテゴリ4: テスト駆動開発（TDD）と自己検証

🔥 23. 実装前にテストコード（Failing Test）を書かせ、コミットする

適用範囲：🌐 AIエージェント全般

• やり方: 本装コードを1行も書く前に、要件定義からユニットテスト（まずは確実に落ちる赤状態のテスト）を作らせ、一度Gitにコミット（Checkpoint）する。

• なぜ効果があるのか: テストという「外部の客観的な正解の基準」を先に固定することで、AIが自身のコードの成否を人間を頼らずに自己判定できるようになるため。

• どんな時に有効か: アルゴリズムの実装や、境界値の判定ロジックなど、インプットに対するアウトプットの正解が数学的・論理的に定まっているタスク。

🔥 24. テストコード自体をAIに変更させない制約を課す

適用範囲：🌐 AIエージェント全般

• やり方: 実装を依頼するプロンプトに「制約：私の作成したテストファイル（*.test.ts）は絶対に修正するな。テストをパスするように本体コードだけを変更せよ」と明記する。

• なぜ効果があるのか: エージェントが実装に困った際、「コード側のバグに合わせて、テストコードの期待値を都合よく書き換えて合格を偽装する」というチート挙動を封じるため。

• どんな時に有効か: AIに自律的なリトライ（修正ループ）を任せ、後から成果物のプルリクエストを人間がレビューする委譲フロー。

⭐ 25. 境界条件（null入力、最大値など）の網羅をテスト生成で狙う

適用範囲：🌐 AIエージェント全般

• やり方: 関数が完成した後に、「このロジックに対して、null、空文字、配列の最大長、負の数など、人間が見落としがちな境界値（エッジケース）を網羅した失敗テストを生成してくれ」と指示する。

• なぜ効果があるのか: 人間はハッピーパス（正常系）の思考に囚われやすいが、AIは構造的なコードパス分析から機械的に境界条件を洗い出すのが得意であるため。

• どんな時に有効か: 金融計算、フォームのバリデーション、データパイプラインのパース処理など、不正な入力によるシステムのクラッシュが許されない領域。

26. プロパティベーステスト（Property-based Test）の自動生成を指示する

適用範囲：🌐 AIエージェント全般

• やり方: ランダムな大量の入力データを自動注入して不変の性質を検証する「プロパティベーステストをこのユーティリティ関数に対して生成してくれ」と依頼する。

• なぜ効果があるのか: 事前に想定した数個のテストケースだけでなく、数千パターンの自動生成された入力によって、コード内に潜む予期せぬ「特定の組み合わせでのみ発生するバグ」を炙り出すことができるため。

• どんな時に有効か: 自作のソートアルゴリズム、カスタムの暗号化/暗号復号ロジック、複雑な文字列変形ユーティリティ。

🔥 27. テスト自動実行（Self-verify）コマンドを AGENTS.md に登録する

適用範囲：🧩 Codex寄り / 🌐 考え方はAIエージェント全般に応用可

• やり方: AGENTS.md の # Commands セクションに npm run test などのテスト実行用コマンドを明確に記載しておく。

• なぜ効果があるのか: エージェントが「AGENTS.mdに書かれたコマンドを自律実行して成否を確認する」動きに寄せやすくなり、作業後の自己検証が安定するため。

• どんな時に有効か: パイプライン（CI/CD）にCodexを headless（非対話）モードで組み込み、自動でバグ修正PRを作らせたい時。

28. 決定論的シミュレーションテスト（Fixed Seed）でランダム要素の挙動を固定する

適用範囲：🌐 AIエージェント全般

• やり方: ゲームの敵のスポーン位置や、確率的なシミュレーションロジックをテストする際、プロンプトで乱数シード（Seed）を固定した決定論的テスト（Deterministic Simulation Test）を書かせる。

• なぜ効果があるのか: 実行するたびに結果が変わる flaky な状態を排除することで、AIが「コードのどの変更が原因でテストが落ちたのか」を追跡しやすくなるため。

• どんな時に有効か: ゲーム開発、シミュレーションアルゴリズムの調整、確率的な重み付けを持つビジネスロジックのデバッグ。

🤖 カテゴリ5: マルチエージェントオーケストレーションとSDK

29. Agents SDKとCodex MCPを組み合わせたカスタムシステムの構築

適用範囲：🧩 Codex固有 / 🔌 MCP・SDK連携

• やり方: Pythonなどの開発環境に Agents SDK を導入し、ターミナルで `codex mcp-server` を実行して、Codex CLIをMCPサーバーとして初期化して組み込む。

• 引数・関数の仕様: 初期化すると、対話を創出する `codex()` ツールと、対話を継続する `codex-reply()` ツールの2つがSDK側へ公開・マッピングされる。

• なぜ効果があるのか: 既存の既製品アプリ（Cursor等）のUIに縛られず、自社のローカルスクリプトや業務ロジックからCodexの思考・ファイル編集ループをプログラム制御できるようになるため。

• どんな時に有効か: 自社専用の特殊な開発フレームワークや、独自のDevOps自動化パイプラインを裏側で自動構築したい時。

⭐ 30. Project Managerエージェントを配置して全体のタスクリストを精査させる

適用範囲：🌐 AIエージェント全般 / 🔌 マルチエージェント連携

• やり方: 複数のエージェントを束ねるシステムを組む際、最初の入力（プロンプト）を開発者エージェントに直接渡さず、中間に Project Manager（PM）エージェントを噛ませる。

• なぜ効果があるのか: 人間の抽象的な指示を、PMエージェントが一度客観的に咀嚼して「具体的なタスクの分割リスト」や「要件定義ドキュメント」へ分解してから下流へ流すため、タスクの迷走が起きにくくなるため。

• どんな時に有効か: Greenfield開発や、設計・実装・テストといった複数のフェーズをまたぐ大規模な機能開発を丸投げしたい時。

⭐ 31. エージェント間に「ゲートキーパー（成果物検証）ロジック」を仕込む

適用範囲：🌐 AIエージェント全般 / 🔌 マルチエージェント連携

• やり方: 下流の「Frontendエージェント」や「Testerエージェント」へ処理を移行する前に、PMエージェントへ一度制御を戻す（transfer_to_project_manager_agent）構造を構築する。

• なぜ効果があるのか: 「前のエージェントが生成すべき設計書ファイルやスタブコードが、本当に指定ディレクトリに物理的に存在しているか」をPMが厳密に検証（ゲートキーパー）してから次へ進めるため、虚無のコード生成に突入するのを防げるため。

• どんな時に有効か: Jiraのタスクオーケストレーションや、企業の厳格なQAサインオフ工程をAIチームだけで再現したい時。

32. RECOMMENDED_PROMPT_PREFIX を用いてエージェント間の手引き（ハンドオフ）を最適化する

適用範囲：🔌 SDK・マルチエージェント連携

• やり方: 各専門エージェントのシステムプロンプトの冒頭に、SDK推奨の共通コンテキスト接頭辞（RECOMMENDED_PROMPT_PREFIX）を結合してデプロイする。

• なぜ効果があるのか: エージェントが自分のタスクを終えた際、勝手に会話を終了したりせず、「成果物をどこに置き、どのように親（PM）に処理をトランスファー（引き継ぎ）すべきか」の挙動がシステムレベルで統一されるため。

• どんな時に有効か: 3人以上の自律エージェントがバケツリレー式に成果物を磨き上げていく、高度なマルチエージェントシステムを運用する時。

🔥 33. 複数エージェント並行運用時は Git worktree による安全な分離環境を作る

適用範囲：🌐 AIエージェント全般 / 🔌 マルチエージェント連携

• やり方: デスクトップアプリ等で複数のエージェントを走らせる際、同一フォルダではなく、エージェントごとに独立した専用の Git worktree（コードの物理的コピー）を自動で割り当てる。

• なぜ効果があるのか: 複数のAIが同じリポジトリの同じファイルを同時に変更した際に発生する、ファイル書き込み競合（コンフリクト）やコードの上書き破壊を物理的に回避できるため。

• どんな時に有効か: 「バグ修正」と「新機能開発」と「テストコード作成」の3つのタスクを、別々のエージェントに並列で同時実行させて時短したい時。

34. 長時間タスクのモニタリングには Traces ダッシュボードを活用する

適用範囲：🔌 SDK・マルチエージェント連携

• やり方: エージェントシステムを走らせている間、SDKの Traces（トレースダッシュボード）をブラウザで開き、プロンプト、ツール呼び出し、エージェント間の遷移タイムラインを監視する。

• なぜ効果があるのか: 「どのエージェントがどのステップで無限ループ（リトライ）に陥っているか」や「どこで最も実行時間（トークン）を浪費しているか」がビジュアルスタックトレースで見えるため。

• どんな時に有効か: 実行完了までに10分以上かかるような、深いマルチエージェントシステムのボトルネック解消やプロンプトの微調整。

35. spawn_agents_on_csv で大量のルーチンタスクを自動ファンアウト（一括処理）する

適用範囲：🔌 SDK・マルチエージェント連携 / 🧩 Codex寄り

• やり方: 大量に処理したいタスク（例：50個の関数のリファクタ指示など）をCSVファイルにリストアップし、spawn_agents_on_csv コマンドで一気に並列エージェントをファンアウト（大量起動）する。

• なぜ効果があるのか: 1つずつ手動でチャットに入力する手間を排除し、進捗状況のインジケーターや完了予定時刻（ETA）をダッシュボードで一元管理しながら、バックグラウンドで自動処理できるため。

• どんな時に有効か: 巨大なモノリスコードの分割や、何百もの古いファイルに対する一括の依存関係アップデート対応。

🔌 カテゴリ6: 外部連携とMCPサーバー / Plugins

36. API化されていない領域やE2E検証には Computer Use 機能（macOS/Windows）を使う

適用範囲：🧩 Codex寄り / 🔌 外部操作・GUI連携

• やり方: Codexの設定から Computer Use を有効化し、必要な権限を付与する。macOSでは画面収録（Screen Recording）とアクセシビリティ権限が必要になる。Windowsでは、対象アプリをアクティブなデスクトップ上に表示した状態で、Codexが画面を見て、クリックし、入力する形で操作する。

• なぜ効果があるのか: APIやCLIのインターフェースが用意されていないレガシーなGUIアプリや、デスクトップアプリ、ブラウザ、シミュレータの画面をAIが実際に確認しながら操作できるため。PlaywrightやCLIだけでは拾いにくい、視覚的なE2E不具合の確認にも使える。

• 2026年6月時点の補足: 2026年5月29日のアップデートにより、Computer Use はWindowsでも利用可能になった。さらに Remote control もWindowsデバイスに対応し、ChatGPTのiOS/AndroidアプリやMac版Codexから、Windows上のCodex作業を開始・確認・追加入力できるようになっている。ただし、WindowsのComputer Useはアクティブなデスクトップ上で前面操作するため、同じWindowsセッションを人間が並行して使い続ける用途には向かない。

• どんな時に有効か: デスクトップアプリの動作確認、ブラウザ上の画面検証、GUIでしか再現できないバグの調査、iOS/AndroidシミュレータやWindowsアプリのE2E確認。

37. フロントエンドの微細な調整には In-app Browser と要素指定コメントを使う

適用範囲：🧩 Codex寄り / 🔌 外部操作・GUI連携

• やり方: アプリ内に組み込まれた In-app Browser でローカル開発サーバー（localhost）を開き、修正したいコンポーネントをマウスで選択してピンポイントでコメント（指示）を撃ち込む。

• なぜ効果があるのか: 「言葉だけ」では伝えにくい「ここのボタンの余白をあと4px詰めて」といった視覚的・位置的なレイアウト指示を、AIに正確な座標・DOM要素の文脈付きで伝えることができるため。

• どんな時に有効か: デザイナーからの Figma のモックアップを忠実にフロントエンドのCSS/Tailwindに落とし込み、ピクセルパーフェクトで磨き上げたい時。

38. チケット管理（Linear/Jira）プラグインを導入し、チケットを自動でインプログレスへ動かす

適用範囲：🔌 Plugins・外部ツール連携

• やり方: Atlassian Rovo や Linear のMCPプラグインをインストールし、AGENTS.md に自社のチケットワークフロー（アサインされたら status を In Progress に変更する、など）を明文化しておく。

• なぜ効果があるのか: エージェントがタスク（GR-144など）を認識した瞬間に、外部のプロジェクト管理ツールのステータスを自動で書き換え、コミットメッセージにも自動でチケットIDを注入するようになるため、人間の管理運用 toil（雑務）を減らせるため。

• どんな時に有効か: チケットの更新忘れが多発する、タスクの同時並行数が多い大規模なチーム開発環境。

⭐ 39. 繰り返される定型プロンプト（コミット生成等）は Skill としてパッケージ化する

適用範囲：🌐 AIエージェント全般 / 🧩 Codex寄り

• やり方: 3回以上同じプロンプトを書いたと感じたら、その手順を `SKILL.md` というファイルにまとめ、CodexのSkillとして管理する。個人用なら `~/.codex/skills`、リポジトリ共有なら `.codex/skills` に配置する。

• なぜ効果があるのか: Skillは、繰り返し使う作業手順を再利用可能な形でパッケージ化できる。CodexはSkillの名前、説明、ファイルパスなどをもとに必要な場面で読み込み、長いプロンプトを毎回コピペしなくても、標準化された作業手順を適用しやすくなるため。

• どんな時に有効か: 毎回のリリースノート（Changelog）の自動生成や、自社の特定の設計原則に則ったクリーンコードの一次レビュー。

🔒 40. Automations（定期スケジュール実行）の無人実行時は安全なサンドボックスプロファイルを指定する

適用範囲：🔒 安全系 / 🔌 自動化・定期実行

• やり方: 毎朝の依存関係スキャン（Dependency Sweep）やCIログの要約などを Automations タブからスケジュール登録する際、実行プロファイルを read-only または限定された workspace-write に制限する。

• なぜ効果があるのか: 夜間や休日など、人間がそばにいない無人のバックグラウンド環境でスケジュール実行（Automations）される際、AIがバグやプロンプトインジェクションによって、プロジェクトの外部ファイルを勝手に破壊・改ざんするリスクを抑えられるため。

• どんな時に有効か: 毎朝のスタンドアップミーティング用の進捗サマリー生成や、週次のコードヘルス/セキュリティ脆弱性チェックの全自動定期運用。

🔒 カテゴリ7: セキュリティ・サンドボックスとリスク管理

🔥 41. 初期導入時は workspace-write モードなどの保守的サンドボックス設定から始める

適用範囲：🔒 安全系 / 🌐 AIエージェント全般

• やり方: 構成ファイル（config.toml）または設定画面で、サンドボックスモードを workspace-write、承認ポリシーを approval on request に設定する。

• なぜ効果があるのか: Codexのサンドボックスは、Codex自身のファイル操作だけでなく、Codexが実行する `git`、パッケージマネージャ、テストランナーなどのコマンドにも適用される。作業範囲を明確に制限することで、低リスクな処理は自律的に進めつつ、境界を超える操作では人間に確認させやすくなるため。

• どんな時に有効か: チームに新しくAIコーディングエージェントを導入したばかりで、まだツールへの信頼や運用ルールが完全に固まっていないオンボーディング期。

🔒 42. 機密情報を扱う場合、専用の隔離されたOSユーザーアカウントを作る

適用範囲：🔒 安全系 / 🌐 AIエージェント全般

• やり方: 自分のメインのPC環境でそのまま動かさず、macOSやWindows上に「Codex専用のローカルOSユーザーアカウント」を新規作成し、そこでエージェントを起動する。

• なぜ効果があるのか: 万が一、AIエージェントが悪意あるGitHubのブランチ名や外部のプロンプトインジェクション攻撃によってハッキング（コマンドインジェクション）されても、メインアカウントのブラウザのクッキー、認証トークン、キーチェーンなどの最重要機密にアクセスしにくくなり、ブラストラジアスを小さくできるため。

• どんな時に有効か: オープンソースのサードパーティライブラリを多用するプロジェクトや、出所が完全に保証されていない外部リポジトリのコードをAIに読ませて調査させる時。

🔥 43. 外部ネットワークアクセスは既定でOFFにし、信頼アプリのみドメイン（Allowlist）を事前許可する

適用範囲：🔒 安全系 / 🌐 AIエージェント全般

• やり方: クラウド/ローカル環境ともにネットワークアクセスをデフォルトで遮断（Block）に設定し、パッケージのインストール等でどうしても必要なドメイン（例：registry.npmjs.org）だけをプロジェクト単位の Allowlist に個別登録する。

• なぜ効果があるのか: 万が一、AIがコード内の不正な指示を読み込んでしまっても、社内の機密ソースコードや環境変数のシークレット情報を、外部の攻撃者が用意したC2サーバーへ勝手に「Webアウトバウンド通信で送信（Exfiltration）」して漏洩させるルートを断てるため。

• どんな時に有効か: 自社の顧客データやコアアルゴリズムなど、秘匿性の高い知的財産（IP）が含まれる商用コードベースをAIエージェントに触らせる時。

🔒 44. パスワード管理や特権昇格（sudo認証等）が必要なステップは人間が立ち会って承認する

適用範囲：🔒 安全系 / 🌐 AIエージェント全般

• やり方: 承認ポリシー（Approval Policy）を Never にして完全自動化する運用であっても、sudo コマンド、認証キーチェーンへのアクセス、決済フォームの送信が発生するタスクだけは、人間が必ずPCの前に立ち会って1ステップずつ目視レビューし、手動でパスワードを入力・承認する。

• なぜ効果があるのか: Codexの安全設計上、OSレベルの特権昇格プロンプトや管理者認証ダイアログはAIが自己承認（権限の自動昇格）できないようになっており、ここが人間による最後の砦として機能するため。

• どんな時に有効か: 本番環境（プロダクション）へのビルドデプロイ、ファイアウォールやセキュリティポリシーの設定変更、有料外部APIの枠を大きく消費する可能性のあるコマンドの実行時。

🔒 45. Codex Security（アプリケーションセキュリティエージェント）を使ってリポジトリの脅威モデルをスキャンさせる

適用範囲：🧩 Codex寄り / 🔒 安全系

• やり方: 開発がひと段落したら、エージェントに直接コードを書かせるのではなく、Codex Security plugin や Codex Security cloud を使って、リポジトリ全体や差分に対する脅威モデリング、脆弱性検出、検証、レポート作成を行わせる。

• なぜ効果があるのか: 人間が書いたコードだけでなく、AIエージェント自身が高速で量産したコードの中に、一見まともに見えるが実は危険な認可漏れ、入力検証不足、SQLインジェクション、秘密情報の扱いミスなどがないかを、リポジトリ固有の文脈に基づいて確認しやすくなるため。

• 注意点: Codex Securityは、検出結果や提案パッチを人間がレビューする前提のツールです。自動で本番コードへ適用するものではなく、あくまで人間のレビューと判断を支援するものとして扱うべきです。

• どんな時に有効か: AIを駆使して高速でプロダクトを開発し、実際のユーザーへ向けて本番リリースする前のセキュリティ監査フェーズ。特に、認証、認可、入力検証、ファイル操作、シークレット管理、外部通信が絡む変更では有効。

🎯 まず何から始めるべきか

ここまで45個整理しましたが、全部を一気にやる必要はありません。

まず最初にやるなら、リポジトリのルートに AGENTS.md を1枚作るところからで良いと思います。

そこに、最低限以下を書きます。

• プロジェクトの概要

• 主要ディレクトリ

• ビルドコマンド

• テストコマンド

• コーディング規約

• 禁止事項

• 変更後に必ず確認すること

これだけでも、AIエージェントの動きはかなり変わります。

次に、テスト実行コマンドを明記する。
その次に、サンドボックスや権限設定を整える。
慣れてきたら、Skill化やマルチエージェント構成に進む。

この順番が現実的だと思います。

私の現場では、すでに実装コードとテストコードの大部分をAIエージェントが書く開発フローになっています。

個人開発では、コードを書く作業そのものはほぼAIエージェントに任せています。

だからこそ、はっきり感じていることがあります。

AIエージェントを使うというのは、AIに丸投げすることではありません。

目的、制約、完了条件、検証方法、権限設計。

これらを人間側が整理して渡すことで、AIエージェントは実務で使える相棒になります。

Codexか、Claude Codeか、Gemini CLIか、Cursorか。

ツールごとの違いはあります。

ただ、実務で差が出るのは、ツール名だけではありません。

AIにどう仕事を渡せるか。

ここが、これからの開発現場ではかなり大事になっていくはずです。

コードを書く量は減っても、考える量が減るわけではありません。

むしろ、AIエージェントに任せる割合が増えるほど、人間側の設計力、判断力、レビュー力、セキュリティ感覚が問われます。

この記事が参考になった方は、スキやフォローをしてもらえると嬉しいです。

#生成AI
#AIエージェント
#Codex
#AI駆動開発
#ClaudeCode
#Cursor
#プログラミング
#ソフトウェア開発
#エンジニア
#業務効率化