Codex 上級使用テクニック

基本的なインストールと最初の対話を完了した後、Codex の真の価値はそれを日々の開発ワークフローに組み込むことにあります。

この記事では、プロジェクト設定、セッション管理、エディタ統合、CI/CD自動化、プロンプトテクニックという5つの上級方向性を取り上げ、Codex があなたのプロジェクトを理解し、あなたの取り決めを覚え、パイプラインで自動的に作業を実行できるように支援します。


一、AGENTS.md で Codex に「入社ドキュメント」を書く

AGENTS.md は Codex 向けのプロジェクト説明書であり、プロジェクトのルートディレクトリに置かれ、起動のたびに自動的に読み込まれ、セッション全体を通して有効です。

なぜそれが必要か

Codex はデフォルトではあなたのプロジェクトについて何も知りません。

それは、あなたが App Router と Pages Router のどちらを使っているのか、データベース操作をどのファイルに統一すべきなのか、どのファイルに触れてはいけないのかを知りません。

毎回の対話で背景を改めて説明しなければならないと、効率が非常に低くなり、エラーも発生しやすくなります。

AGENTS.md を使えば、これらの情報を一度書き込むだけで持続的に有効になり、繰り返し説明する手間が省けます。

何を書くのか

効果的な AGENTS.md には通常、プロジェクト概要、技術スタック、重要な取り決め、禁止事項の4種類の情報が含まれます。

以下は完全な例です:

# AGENTS.md

## 项目概述
这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。
使用 App Router,不使用 Pages Router。

## 技术栈
- 前端:Next.js 14, React 18, TailwindCSS, shadcn/ui
- 后端:Next.js API Routes, Prisma ORM
- 数据库:PostgreSQL 15
- 认证:NextAuth.js

## 重要约定
- 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例
- API 路由错误统一用 lib/api-error.ts 处理
- 环境变量在 .env.local 中,参考 .env.example

## 禁止事项
- 不要修改 prisma/schema.prisma,除非我明确要求
- 不要删除任何现有测试
- 生产环境的 .env 文件不要碰

「禁止事項」のセクションは特に重要です。Codex はタスク実行時にどのファイルを変更する必要があるかを自律的に推測するため、明確な境界がない場合、あなたが触れてほしくない場所に手を出す可能性があります。禁止事項を明確に書いておくほうが、問題が起きてから対処するよりはるかに手間がかかりません。

設定の階層構造

AGENTS.md は3層のネストをサポートしており、優先度は低いものから高いものへと並んでいます。

現在のディレクトリに近いファイルほど優先度が高くなります。同じディレクトリ内に AGENTS.override.md が存在する場合、同レベルの AGENTS.md はスキップされます。

階層 パス 適用範囲 優先度
グローバル層 ~/.codex/AGENTS.md プロジェクト横断的な共通の取り決め 低
プロジェクト層 repo/AGENTS.md リポジトリレベルの規約 中
オーバーライド層 repo/services/payments/AGENTS.override.md サブディレクトリの特殊ルール 高

グローバル層には、すべてのプロジェクトで通用する取り決めを書くのが適しています。例えば:

# ~/.codex/AGENTS.md

## 全局约定
- 安装依赖时优先使用 pnpm
- 修改 JavaScript 文件后始终运行 npm test
- 新增生产依赖前先请求确认

設定完了後、次のコマンドで正しく読み込まれるか検証できます:

codex --ask-for-approval never "Summarize the current instructions."

二、セッション管理:日をまたいで大規模タスクを継続する

セッション管理機能を使うと、現在の対話状態をファイルにエクスポートし、次回は直接復元できます。背景を改めて説明する必要はありません。

問題の背景

Codex のコンテキストウィンドウには限りがあります。

複数のファイルにまたがり、段階的に進める必要がある大規模タスクを処理しているとき、途中でターミナルを閉じたり他のことに切り替えたりすると、戻ってきたときにはコンテキストが途切れています。Codex は以前に何を議論し、どのような決定をしたかを覚えていません。

セッションをエクスポートすればこの問題を解決でき、任意の時点で以前の対話状態に復元できます。

基本的な使い方

以下はセッション管理に関連するよく使うコマンドです:

例

# 対話の途中でいつでも現在のセッションをエクスポート
/export session-2024-01-15.json

# 次回続きを再開するときは復元
/load session-2024-01-15.json

# 最近のセッションを直接復元(最もよく使う)
codex resume --last

# 保存されたすべてのセッションを表示
ls ~/.codex/sessions/

いつエクスポートすべきか

毎回の対話でエクスポートする必要はありません。以下のような場合に保存する価値があります:

シナリオ 説明
日をまたいで行う多段階のタスク タスクが複数日にわたって行われ、間に明確な段階の区切りがある場合。保存しておくと、次回は前回の途中から直接続きを始められます。
重要なアーキテクチャ決定 Codex と重要なアーキテクチャ決定について議論し、後続のタスクがこの決定に基づいて進める必要がある場合
複雑なデバッグプロセス 複雑なバグをデバッグ中に、いくつかの方向性をすでに除外しており、次回最初からやり直したくない場合

三、VS Code との統合

Codex は公式の VS Code 拡張機能を提供しており、インストールするとエディタ内で直接対話を開始でき、ターミナルに切り替える必要はありません。

インストールとログイン

インストール手順は次のとおりです:

  • ステップ1:拡張機能マーケットプレイスを開きます(Cmd/Ctrl + Shift + X)。

  • ステップ2:「Codex」または「OpenAI Codex」を検索し、公式プラグインをインストールします。

  • ステップ3:初回使用時には ChatGPT アカウントへのログインが必要です。

  • ステップ4:サイドバーに Codex アイコンが表示されたら使用できます。

インストール完了後、以下のショートカットキーで素早く操作できます:

ショートカットキー 機能
Alt + G 選択したコードを現在のファイルのコンテキスト付きで Codex に送信
Cmd + Shift + P コマンドパレットを開き、"Codex" と入力して利用可能なすべてのコマンドを表示

BYO モード(ChatGPT を購読していないユーザー向け)

CLI で自分の API キー(Anthropic、OpenAI、その他互換性のあるプロバイダ)をすでに設定している場合、無料の ChatGPT アカウントで VS Code プラグインにログインできます。

プラグインは CLI のモデル設定を自動的に再利用するため、ChatGPT Plus を使用する必要はありません。

適用シナリオ 説明
API キーはすでにあるが、ChatGPT を追加で購読したくない 自分の API キーを直接使用するため、追加の有料購読は不要
VS Code と CLI で同じモデルを使いたい プラグインが CLI 設定を自動的に再利用するため、両端の体験は完全に一致します

4. CI/CD統合

Codex CLI はヘッドレスモードでの実行をサポートしており、人手による対話を必要としないため、自動化フローへの組み込みに適しています。

Codex はパイプラインで何ができるのか

以下はヘッドレスモードでの CI/CD における Codex の一般的な用途です:

用途 説明 代表的なトリガーのタイミング
CHANGELOG の自動更新 メインブランチへのマージのたびに、コミット履歴に基づいて CHANGELOG.md を自動更新します main ブランチへのマージ後
API ドキュメントの生成 コードの変更に基づいて API ドキュメントを自動生成または同期 コードのプッシュ後
自動コードレビュー PR パイプラインでコードレビューを自動実行し、コメントを残します PR の作成または更新時

GitHub Actions の例

次のワークフローは、main ブランチにプッシュされるたびに、Codex が最新のコミットに基づいて CHANGELOG.md を自動更新するものです:

例

# ファイルパス:.github/workflows/codex-changelog.yml

name
: Auto Update Changelog
on
:
  push
:
    branches
: [main]

jobs
:
  update-changelog
:
    runs-on
: ubuntu-latest
    steps
:
      - uses
: actions/checkout@v4

      - name
: Setup Node.js
        uses
: actions/setup-node@v4
        with
:
          node-version
: '22'

      - name
: Install Codex CLI
        run
: npm install -g @openai/codex

      - name
: Run Codex Task
        env
:
          OPENAI_API_KEY
: ${{ secrets.OPENAI_API_KEY }}
          CODEX_QUIET_MODE
: 1
        run
: |
codex exec --full-auto "根据最新 commits 更新 CHANGELOG.md"

      - name
: Commit changes
        run
: |
         git config --local user.email 'action@github.com'
          git add CHANGELOG.md
          git commit -m 'chore: update changelog [skip ci]'
          git push

設定には、特に注意すべき2つの重要なポイントがあります:

設定項目 役割 説明
CODEX_QUIET_MODE: 1 対話型出力の抑制 パイプラインが対話入力を待って止まるのを防ぐ
--full-auto ヘッドレスモードでの実行 Codex が無人で直接実行し、確認を待たないようにする

CI で使用する場合は、プロジェクトルートの AGENTS.md に、Codex が自動モードで変更を許可されるファイル範囲を明確に制限しておくことをお勧めします。プロンプトの解釈のずれによる意図しない変更を防ぐためです。


五、プロンプトのテクニック

Codexの出力品質は、あなたの質問の仕方に大きく左右されます。

以下の5つのテクニックは、新規ユーザーが最も頻繁に直面する問題に向けたもので、各項目には具体的な例が付いています。

テクニック1:十分なコンテキストを提供する

Codexには読心術はありません。「バグを修正」のような指示では、Codexは当てずっぽうに推測し、結果は往々にして望んだものにはなりません。

以下は対比する例です:

推奨しない書き方 推奨する書き方
「バグを修正」 「ユーザーログイン時に TypeError: Cannot read properties of null というエラーが発生します。エラーは src/auth/login.ts の42行目で発生しており、この関数はJWTトークンの検証を担当しています。この問題を特定して修正してください」

効果的なコンテキストには3つの要素が含まれます:

要素 説明 例
具体的な現象 エラーメッセージまたは具体的な症状 TypeError: Cannot read properties of null
関連する場所 ファイルと行番号 src/auth/login.ts の42行目
コードの役割 このコードの本来の機能 JWTトークンの検証

テクニック2:複雑なタスクは2段階に分ける

変更範囲が大きいタスクでは、まずCodexに分析させてプランを列挙させ、問題がないことを確認してから実行します。

一気に完了させるほうが速く見えますが、方向がずれた場合のコストはより大きくなります。

例

# ステップ1:分析のみ、変更しない
codex 「src/api/ ディレクトリのコード品質を分析し、主要な問題を列挙してください。いかなるファイルも変更しないでください」

# ステップ2:プランを確認してから実行する
codex 「わかりました。あなたのプランに従って、まずエラーハンドリングの問題を処理してください。その他は私がレビューしてから判断します」

テクニック3:ask モードでコードベースを先に把握する

askaskモードは読み取り専用モードで、着手する前に既存コードの構造とロジックを理解するのに適しています。

理解してから変更するほうが、変更してから振り返って理解するよりも時間を節約できます。

実例

# ask 模式不会触发任何文件修改
codex -a ask "这个项目是如何处理用户认证的?梳理完整的认证流程"

理解が明確になったら、現在のセッションを終了し、編集可能モードで再起動します:

# 可编辑模式(需要确认)
codex -a auto

# 全自动执行(谨慎使用)
codex -a full-auto

推奨ワークフロー:

ask
↓
理解代码结构
↓
确定修改方案
↓
重新启动 Codex
↓
进入可编辑模式
↓
执行修改

注意:CLIでは、実行中に権限モードを切り替えることはサポートされなくなりました。/approvals起動時にパラメータで指定する必要があります。-aデスクトップクライアントでは、セッション内での切り替えは引き続きサポートされています。

テクニック4:否定命令で境界を定める

Codexに「触れてはいけないもの」を伝えることは、「何をすべきか」を伝えることと同様に重要です。

特に複数の関連ファイルに及ぶリファクタリングタスクでは、境界が不明確だと不要な付随変更が発生しやすくなります。

例

# 変更してはいけない範囲を明確に定める
codex 「utils/date.ts の日付フォーマット関数をリファクタリングしてください。関数シグネチャは変更しないでください。テストファイルも変更しないでください」

テクニック5:まず計画を求め、それから実行を始める

確信が持てないタスクでは、まずCodexにどう進めるつもりかを列挙させましょう。

このステップはほとんど時間がかかりませんが、方向のずれを早期に発見でき、誤った道筋を進みすぎるのを防げます。

# 先要计划
codex "你打算怎么实现这个功能?先列出步骤,不要执行"

# 确认计划合理后再推进
codex "计划没问题,开始执行第一步"

まとめ

この5つの方向性は、「プロジェクト設定」から「日常操作」、「自動化」に至るまでの完全な流れをカバーしています。

最初はすべてを使う必要はありません。順番に進めることをおすすめします。まずAGENTS.mdをしっかり書き、Codexにプロジェクトを理解させてから、徐々にVS CodeワークフローやCI/CDフローに組み込んでいきます。

プロンプトのテクニックは、日常の使用の中で少しずつ蓄積するほうが、一度に覚えるよりも効果的です。

その他の拡張