コンテンツにスキップ

Codex CLI 実践ベストプラクティス — 使い方の勘所とFAQ

Codex CLI 完全ガイド

このページは「Codex CLIの実運用で迷いやすい点」をまとめた実践ガイドです。既存のベストプラクティス（計画分解・最小差分など）に加えて、AGENTS.mdの取り扱い、モデル選択、コンテキスト/トークン、UIのパーセンテージ表示、コストの考え方をFAQ形式で補完します。

1. AGENTS.md とカスタマイズ方針

  • 自動生成の有無: 本リポジトリでは AGENTS.md は自動再生成していません（手動管理）。自動化する場合は専用スクリプトを導入し、生成元と実行タイミングをREADMEに明記してください。
  • 変更の粒度: 大規模な書き換えより「方針・前提・制約」の最小更新を推奨。CLIの動作は会話中の明示方針（preamble/plan）で十分に誘導できます。
  • 機密と責務: 機密や認証情報は書かない。運用ルール（昇格要求・破壊的操作）は明文化。役割/境界/優先順を最小セットでキープ。
  • どこまでカスタムするか: まずは既定ルールで運用→繰り返し痛点が出た箇所のみピンポイントに追記。テンプレ化できたらテンプレート/スクリプト化。

2. モデル選択の考え方（実務基準）

  • 原則: 「難易度×コスト×長さ」で決める。
  • 高難度の設計/リファクタ/バグ追跡: 高推論モデル（手元環境で最も強いモデル）
  • 広範囲の読み取り/要約・軽作業: コスト効率モデル（小型/ミニ系）
  • 長文/大規模差分の検討: 長いコンテキストに強いモデル
  • 切替タイミング: フェーズ単位でモデル固定（設計→実装→検証）。途中で頻繁に切り替えない方が一貫性が上がります。
  • 再現性: 重要タスクはモデルと温度・実行条件を記録（Issue/PRに明記）。

3. コンテキスト/トークン管理の実務Tips

  • 読み取りは絞る: rg で検索→関連部分を最大250行程度で段階読み。巨大ファイルの一括貼付は避ける。
  • 要約を足場に: 長い経緯は数行で要約→「前提/決定/未解決」を明文化。以降の判断基準に使う。
  • 差分最小: apply_patch は1タスク=1論点。無関係な整形や命名変更は別タスクへ。
  • 参照はパスで: 大量コードのコピペではなく path:line 単位で指示。必要箇所だけ抜粋。
  • ログの抑制: ビルド/テストの冗長ログは要点だけ抜粋。全文はローカルで確認。

4. パーセンテージ表示の意味（なぜ減るの？）

  • 何を示すか: 一般に「会話/実行で消費しているリソース指標」（トークン・ツール出力・実行回数の合成）として表示されます。長文の入出力や大きなファイル読みで減少が速くなります。
  • 減少時に起きること: しきい値到達でトークン切れ/ツール抑制/要約強制などが発生。回答の粗さや省略が増えます。
  • うまく使うコツ:
  • 読みは段階化し、要点を要約して次のターンに渡す。
  • 不要な全量ログ/全文コピペを避ける。
  • 追加の検証は「近接→広域」の順で行う（小さく刻む）。

5. コスト最適化（時間/料金/失敗率のバランス）

  • タスク分割: 高推論モデルは「設計・要件整理・重要判断」に集中。機械的作業や探索は軽量モデル/ローカル検索に寄せる。
  • 先に仕様を固める: update_plan で段取り合意→無駄な反復を削減。
  • 変更の検証を近接化: 影響範囲を限定して検証→確度が上がってから広げる。
  • キャッシュ思考: 一度読んだ構造や決定は短いメモにして以降のターンで再利用（長文の再投入を避ける）。

6. 具体的な運用Q&A

Q1. AGENTS.mdは毎回自動再生成されますか？

いいえ。本リポジトリでは手動管理です。自動化する場合は生成スクリプト・生成元・スケジュールを明記し、PRで合意を取ってください。

Q2. どこまでカスタマイズすべき？

まずは標準ルールで運用し、実務で繰り返し困った箇所だけ最小限を追記。巨大な包括プロンプトより、各タスクの前置き（preamble）と明快なupdate_planで誘導する方が失敗率が低いです。

Q3. モデルは何を使うべき？

「高推論×重要判断」は強いモデル、「広範囲読み/要約/定型作業」は軽量モデルを推奨。フェーズ単位で固定して再現性を担保してください。

Q4. コンテキストに表示される数値/パーセンテージは？

会話内でのリソース消費イメージ（主にトークン）。長文I/Oや大きな出力で減少が早まります。段階読み・要約・差分最小を徹底すれば十分余裕を確保できます。

Q5. トークンが枯渇しやすい時の対策は？

  • rgで的を絞る→最大250行ずつ読む
  • 要約を次ターンの前提にする
  • パッチは小さく（関連箇所だけ）
  • ログ/全文の貼付を避ける

7. 設定と拡張・セッション管理（概要）

Codexの挙動を一貫させるため、設定（config.toml）、外部ツール連携（MCP）、長文セッションの管理（/fork, /compact, /resume 等）などの高度な機能が提供されています。

これらの具体的な導入手順や運用ルールについては、以下の専用ガイドを参照してください。 - 設定とMCP連携: Codex CLI 完全ガイド - 定期実行とスキル化: Codex CLI 自動化ワークフロー

8. このリポジトリでの検証手順（再掲）

  • 厳格ビルド: mkdocs build --strict
  • ペア確認: JP/EN記事ペア検証スクリプトを実行
  • 追加（任意）: リダイレクト検証スクリプトを実行（事前に認証とネットワーク権限が必要）