Codex チュートリアル — バグ修正タスクで一連の流れを体験する

このチュートリアルで体験すること

Codex は GitHub リポジトリに接続し、クラウド上のサンドボックスでコードを実行しながら問題を解決するエージェントだ。利用者はブラウザや CLI から自然言語でタスクを指示し、Codex が生成した差分を確認してマージするかどうかを判断する。

本チュートリアルのゴールは次の3点だ。

1. バグが存在するリポジトリを Codex に接続し、修正タスクを依頼できるようにする
2. Codex が生成した差分の読み方と確認方法を身につける
3. 修正をマージした後の動作確認まで一連の流れをつかむ

対象となる読者は「Codex のアカウントは持っているが、実際の開発作業で使ったことがない」という段階の方を想定している。コードの読み書きができること、Git の基本操作（クローン・ブランチ・プッシュ）を知っていることが前提だ。

チュートリアルで使用するのは、シンプルな Node.js の Express API だ。バリデーションエラーが発生したとき、本来は HTTP 400 を返すべきところを誤って 200 を返してしまうというバグが仕込まれている。実際のプロジェクトでも発生しやすい典型例として選んだ。

なお、Codex を初めて使う場合はまず公式ドキュメントでリポジトリとの接続手順を確認してほしい（出典: https://openai.com/codex）。

事前準備 — リポジトリと Codex の接続

Codex はクラウド上で動作するため、対象リポジトリを事前に接続する必要がある。GitHub との接続はアカウント設定から行い、対象組織・リポジトリへのアクセスを許可するだけで完了する。接続済みのリポジトリは Codex アプリのホーム画面に表示される（出典: https://platform.openai.com/docs/codex）。

このチュートリアルに使うリポジトリには、以下のような Express ハンドラが含まれているとする。

// src/routes/user.js
router.post('/users', async (req, res) => {
  const { email, name } = req.body;
  if (!email || !name) {
    return res.status(200).json({ error: 'email and name are required' });
  }
  // ... ユーザー作成処理
});

バリデーションエラーの行で res.status(200) としているのが問題だ。本来は res.status(400) を返さなければ、呼び出し側はエラーなのか成功なのか区別できない。このバグを Codex に指摘して修正させる。

Step 1: 接続の確認

Codex アプリを開き、左サイドバーから「Repositories」を選択する。接続済みリポジトリの一覧が表示されるので、該当リポジトリが含まれていることを確認する。表示されていない場合は「Connect repository」から GitHub 連携を済ませる。

接続後はリポジトリのデフォルトブランチ（通常は main または master）が自動的に参照される。タスクを実行すると Codex がブランチを新規作成してそこに変更をコミットする仕組みなので、既存ブランチを直接変更される心配はない。

バグの状況を確認する

タスクを依頼する前に、バグの症状を整理しておくことが重要だ。Codex は自然言語の指示をもとに動くが、情報が曖昧なほど余分な箇所まで変更したり、見当違いの修正を提案したりするリスクが高まる。

今回のバグについて整理すると次のようになる。

• 症状: POST /users にメールアドレスや名前を省略してリクエストすると、レスポンスのステータスコードが 200 で返ってくる
• 期待する動作: バリデーション失敗時は 400 Bad Request を返すべき
• 影響範囲: クライアントアプリでエラーハンドリングが正常に動かない

この3点を頭に入れた上でタスクの指示文を作る。Codex は指示文を読んで修正候補を生成するため、症状・期待動作・影響範囲を文章に盛り込むと精度が上がりやすい。

Codex にタスクを渡す

Step 2: タスクの作成

Codex アプリのホーム画面で「New task」ボタンを押し、対象リポジトリを選択する。タスクの指示文フォームが開いたら、次のような内容を入力する。

POST /users エンドポイントがバリデーションエラー時に HTTP 200 を返す不具合を修正してください。

再現手順:
1. email または name を省略して POST /users にリクエストする
2. レスポンスのステータスコードを確認する

期待する動作:
バリデーションエラーが発生した場合は HTTP 400 Bad Request を返すこと

修正範囲:
src/routes/user.js の該当箇所を修正し、この動作をカバーするテストを追加してください。

指示文を書いたら「Create task」をクリックする。Codex はリポジトリのクローン・コードの探索・修正・テスト実行を自律的に行い、完了したら差分を表示する。処理時間はリポジトリの規模にもよるが、小〜中規模であれば数分程度だ（出典: https://github.com/openai/codex/releases）。

タスクを実行している間、Codex のログ画面にはどのファイルを参照しているか、どんなコマンドを実行しているかがリアルタイムで表示される。処理が止まっているように見えても、多くの場合は内部で探索や実行を続けているので、しばらく待つのが基本だ。ただし 15〜20 分を超えても進まない場合は、タスクを停止して指示文を見直すとよい（出典: https://openai.com/codex）。

差分を確認してマージする

Step 3: 差分の読み方

タスクが完了すると、Codex はブランチを作成して変更をコミットし、プルリクエストを自動的に起票する。Codex アプリでは変更の概要と差分が一覧できる。今回の修正では次のような変更が期待される。

- return res.status(200).json({ error: 'email and name are required' });
+ return res.status(400).json({ error: 'email and name are required' });

差分を確認する際のポイントは次の通りだ。

1. 変更ファイル一覧: 指定した src/routes/user.js だけが変更されているか確認する。意図しないファイルが含まれている場合は、修正を採用する前に理由を把握しておく
2. テストコードの追加: tests/ ディレクトリ以下に新しいテストファイルが追加されているか、あるいは既存のテストファイルに検証コードが追記されているかを確認する
3. コメントや変数名: ロジック以外の部分(コメント・変数名・インポート)も変わっていないかスクロールして確認する

小規模な修正であれば差分は短く、すぐに確認できる。規模が大きい修正の場合は変更行数が多くなるため、重要な箇所だけ抜き出して読む判断も必要だ。

Step 4: マージの判断

差分を確認して問題がなければ、Codex アプリの「Merge」ボタンをクリックするか、GitHub 上で自動生成されたプルリクエストをマージする。Codex が起票したプルリクエストは通常の PR と同じ扱いで、チームの CI を通過させてからマージするのが推奨される運用だ。

差分の内容に疑問がある場合は、Codex のタスクに対してコメントを追加して修正を依頼できる。「ステータスコードは正しいが、エラーメッセージのフォーマットも JSON ではなく文字列に変えてほしい」といった追加指示を送ると、Codex が差分を更新する。

動作確認

マージが完了したら、実際にエンドポイントを呼び出して動作を確認する。ローカル環境でサーバーを起動し、curl やツールを使って POST /users に不完全なリクエストを送る。

curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"email": ""}'

このコマンドを実行してレスポンスが 400 になっていれば、修正は正常に機能している。以前は 200 が返っていたので、ステータスコードの変化がそのまま修正の成果になる。

テストを追加した場合は、テストスイートを走らせて新しいテストがパスしていることも確認する。Codex が追加したテストは修正した動作を検証するように書かれているため、通常はそのまま動作するはずだが、プロジェクトのテストフレームワークや設定によっては微調整が必要な場合もある（出典: https://platform.openai.com/docs/codex）。

よくあるつまずきと対処法

Codex チュートリアルを進める中でよく発生する問題と、その対処法を整理する。

指示文が曖昧でファイルを特定できない

Codex はリポジトリ全体を探索してバグを探そうとするが、指示文に対象ファイルが記載されていないと探索範囲が広がりすぎてタイムアウトすることがある。ファイルパスやディレクトリ名を指示文に含めると精度が上がる。先ほどの例でも src/routes/user.js とパスを明記しているのはこのためだ。

テストが失敗する

Codex がテストを追加した場合、実行環境の依存関係や設定ファイルが整っていないとテストが失敗することがある。エラーメッセージを読んで npm install や設定ファイルの調整が必要かどうかを確認する。Codex のログ画面にもテスト実行結果が記録されているので、どの依存関係が不足しているかをそこから特定できる場合が多い。

差分に意図しないファイルが含まれている

Codex がバグの探索中に関連ありと判断して複数のファイルを修正することがある。意図しない変更が含まれている場合は、マージせずにタスクに追加コメントを送る。「src/routes/user.js のみ修正してください。他のファイルは変更しないでください」と指示すると、Codex が差分を絞り込んで再提案する。

次のステップ

このチュートリアルでは単一ファイルのバグ修正を題材にしたが、Codex は複数ファイルにまたがる変更や、新機能の実装にも対応している。慣れてきたら次のようなタスクを試してみると、Codex の能力範囲がより具体的につかめる。

1. リファクタリング依頼: 既存の関数を分割して可読性を上げてほしい、などのコード品質改善
2. 新機能の追加: 既存の API に新しいエンドポイントを追加し、テストまで一括で任せる
3. ドキュメント生成: 関数のコメントや README の一部を Codex に書かせ、その後人間がレビューする

複雑なタスクになるほど指示文の精度が問われる。「どういう状態になってほしいか」を結果ベースで書くと、Codex が取り得るアプローチの幅が広がり、より適切な実装を選んでくることが多い。「〜を実装してください」よりも「〜という条件を満たすようにしてください」という書き方が有効なことを覚えておくと、より高度なタスクにも応用できる。

Codex の最新情報やリリースノートは GitHub の公式リポジトリで随時公開されている（出典: https://github.com/openai/codex）。今後のバージョンアップでできることが増える可能性もあるため、定期的に確認することを勧める。