Codexベストプラクティス：同じ指摘を2回受けたらAGENTS.mdに書かせる

先週「テストコマンドは npm test であって npm run test ではない」と指摘したのに、今日また npm run test を書いてテストが落ちた——という経験はありませんか。原因はプロンプトの腕ではなく、修正がプロンプトの中にしか存在しないことです。公式のCodexベストプラクティスガイド（2026年10月2日時点で確認）は、これを「繰り返し指示」から「資産としての蓄積」へ変える問題として扱います。

以下のコマンドは公式ドキュメントに基づいていますが、本稿では個別に実行していません。実行前に現行の公式ドキュメントを確認してください。

まず普通のチャットで2つの実験

インストール不要。どんなチャットでも動きます。

実験1：曖昧な指示を4要素に書き直す。「ログインページのエラーを直して」の一行では、モデルが対象ファイル・実行コマンド・完了の判定を推測します。公式テンプレートで補う：

目標：ログインページの送信で500エラーが出る。復旧させる。
文脈：スタックトレースは error.log。ログイン処理は src/login/。テストは npm test。
制約：決済モジュールは触らない。既存のコードスタイルに従う。依存を増やさない。
完了条件：npm test が全件通過し、ログイン後にホームへ遷移し、エラーが再現しない。

1行の指示では範囲と終点がモデル任せ、4要素では境界とゴールが明示されます。公式の説明によれば、仮定が減り、レビューしやすい出力になります。覚えるのは一句：任す前に「完了の定義」を口にする。

**実験2：AIにインタビューさせる。**要件が曖昧で説明しにくいときは、逆に質問させます：

チーム向けの週報整理ツールを作りたいが、要件が固まっていない。
まだ着手しない。5つ質問して仮定に挑戦し、
回答を具体的な要件リストに整理して。

質問と回答の往復だけで、自分が言語化できていなかった要件リストが手に入ります。

Codexが組み込んでいる5段階の梯子

1. Plan mode：/plan または Shift+Tab。文脈収集・質問・計画を先に行い、実装は承認後。
2. AGENTS.md：/init で雛形を生成。実行方法・テスト・禁止事項・完了定義を実態に合わせて編集します。鍵になる規律は同じ間違いを2回されたら振り返り（レトロスペクティブ）させて AGENTS.md に反映させること。3層構造（個人 ~/.codex、リポジトリ直下、サブディレクトリ）は近いファイルが優先。
3. 設定の層：個人既定は ~/.codex/config.toml、リポジトリは .codex/config.toml、CLIフラグは一回限り。approval mode（いつ確認を求めるか）と sandbox mode（何を読み書きできるか）は最初は厳しく、信頼ができてから緩める。公式が指摘する通り、「AIの品質問題」の多くは設定問題——作業ディレクトリ、書き込み権限、既定モデル——です。
4. 検証ループ：テスト作成・実行・lint・diffレビューをエージェントにやらせ、人が目視確認してから受け入れる。/review はPR形式、未コミット変更、特定コミットに対応。公式ドキュメントの一節：「At OpenAI, Codex reviews 100% of PRs.」
5. 反復のパッケージ化：外部コンテキストの貼り付けが毎回なら MCP（まず1〜2個）、プロンプトの再利用なら skill（1スキル1役割）、安定したワークフローだけ scheduled task。公式の表現：「skills define the method and scheduled tasks define the schedule」。手動で安定していないワークフローを予約してはいけない、という規律が付随します。

一度やってみる

1. プロジェクトで Codex を起動し、/init で AGENTS.md の雛形を生成。
2. 雛形を実運用の約定に書き換える（実行・テスト・禁止事項・完了定義）。
3. 説明ゼロで小さなタスクを1つ任せ、AGENTS.md に従うか観察する。
4. ミスしたら振り返らせて AGENTS.md に追記し、セッションを開き直して再検証する。

これで手に入るのは完了した1タスクではなく、自動で読み込まれるプロジェクトの約定書です。AIが二度と間違わない保証にはなりませんが、同じ間違いに3回目はありません。

まだやらなくていいこと

• MCP を一度に大量接続しない（まず1個）。
• 手動で安定していないワークフローの予約化。
• 既定サンドボックスのまま信頼を積まずに全権限解放。
• 並列タスクで同一ファイル群を共有しない（並列化は Git worktree で分離）。
• プロジェクト全体を1チャットで運用しない（1タスク1チャット、長くなったら /compact）。

参考：ベストプラクティス、AGENTS.md、設定リファレンス、統合マニュアル。