Codexの使い方 既存コードの小さな修正から始める

Codexの使い方を身につける最初の一歩は、ローカルの既存プロジェクトを1つ開き、「1箇所の小さなバグ修正」に絞って作業計画・変更差分（diff）・動作確認テストの3点を順に確かめることです。指定したファイルだけに差分が収まり、正常・空入力・長文入力のテストがすべて通る状態を目指します。

※2026年10月29日時点の公式クイックスタート（Quickstart）および開発ワークフロー解説（Iterating Development Workflows with Codex）にもとづく手順ガイドです。Codexアプリ・CLIの実機操作検証は未実施であり、記事内のフォーム題材・プロンプト・差分・確認表は練習用の独自教材です。

使うCodexの環境を決める

最初に「どの画面（デスクトップアプリ・CLI・クラウド環境）でコードを扱うか」を1つに固定します。作業中に複数の画面から同じフォルダを触ると、どの変更が反映されたか追えなくなります。

製品面と利用条件を現行公式で確認

公式の Quickstart では、デスクトップアプリ（macOS・Windows・Linux）やWeb・モバイル環境において「Chat」「Work」「Codex」の各モードを切り替える構成が案内されています。開発向けのCodexモードでは、手元のローカルフォルダを開いてファイルの読み書きやターミナル連携を行えるほか、クラウド環境でのリモート実行にも対応しています。

対応プランや導入手順は更新されるため、事前に公式クイックスタートで確認してください。本記事では手元のローカルリポジトリを開いて修正する手順に固定して説明します。

準備済みサンプルを開く

練習では本番サイトではなく、Git管理された小さなサンプルフォルダを開きます。ここではお問い合わせフォームの入力エラー表示を扱う最小構成（contact-form-sample/）を題材にします。

contact-form-sample/
├── index.html      # フォームの画面（氏名・本文・送信ボタン・エラー表示欄）
├── form.js         # 入力チェックとエラー表示のプログラム
└── form.test.js    # 入力判定を確かめるテストコード

なお、OpenAIのCookbook（Iterating Development Workflows with Codex）では、複数フェーズの開発例として AGENTS.md や GOALS.md、PLANS.md、PROMPTS.md、harness/ などの補助ファイル群が紹介されていますが、これらは必須ではありません。最初の1箇所を直す段階では、既存のコードファイルだけで始めて問題ありません。

作業を始める前に、未整理の変更が残っていないことをターミナルで確認します。

git status --short

何も表示されなければ作業前の状態が整っています。変更中のファイルが出た場合は、コミットやスタッシュで保存してから作業に入ります（ブランチ作成だけでは未コミットの変更は分離されません）。

変更の依頼を具体化する

既存プロジェクトのバグ修正の頼み方で失敗しやすいのは、「エラー表示がおかしいので直して」と現象だけを伝えることです。関係ないファイルまで書き換えられるのを防ぐため、依頼文には次の4項目を入れます。

再現手順・期待動作・変更範囲

1. 再現手順：例「本文欄にスペースだけを入力して送信した」
2. 現在の動作と期待動作：例「現在は送信に進んでしまう。空白のみのときは送信を止め『本文を入力してください』と出し、201文字以上は『本文は200文字以内で入力してください』と出す」
3. 変更許可ファイルと変更禁止範囲：例「変更は form.js と form.test.js のみ。index.html の構造や外部ライブラリは変更しない」
4. 作業計画の先行提示：ファイルを書き換える前に、原因箇所と修正方針を説明させる

曖昧な依頼との比較

以下は、練習用サンプルにそのまま使えるバグ修正依頼のプロンプトテンプレートです。

既存のフォーム（`contact-form-sample`）の入力エラー表示について、小さなバグ修正をお願いします。
まだファイルの変更は行わず、最初に原因箇所と作業計画、変更予定のファイル名を説明してください。

【現在の問題と再現手順】
1. `index.html` のお問い合わせ本文（`#message`）をスペースだけ入力して送信ボタンを押すと、エラーが表示されずに送信完了メッセージが出てしまいます。空欄のエラー表示は維持したいです。
2. 200文字を超える長文を入力したときのエラー表示が未設定です。

【期待する動作】
- 前後の空白を除いた文字数が0文字のときは送信を止め、`#error-message` に「本文を入力してください」と表示する
- 文字数が1〜200文字のときはエラー表示を消し、正常に送信完了へ進む
- 文字数が201文字以上のときは送信を止め、`#error-message` に「本文は200文字以内で入力してください」と表示する

【変更範囲のルール】
- 変更してよいファイルは `form.js` と `form.test.js` のみとする
- `index.html` のHTML構造やCSS、既存の関数名は変更しない
- 新しい外部パッケージは追加しない

作業計画と変更を追う

まず作業計画の提示を受け、対象ファイルと方針が妥当ならコード変更へ進めます。変更が生成されたら、採用前に必ず変更差分（diff）の確認を行います。

途中の説明と差分の読み方

Codexの画面表示とあわせて、ターミナルで次の2つのコマンドを実行すると変更差分を正確に確認できます。

git status --short
git diff

git status --short では、変更されたファイル一覧を確認します。指定した2ファイルだけが表示されていれば範囲内です。

 M form.js
 M form.test.js

指定外の index.html や package.json、未追跡ファイル（??）が出ている場合は、依頼範囲を超えた変更が起きています。

git diff では、行単位の書き換え内容を確認します（以下は編集側で用意した練習用の差分例です）。

diff --git a/form.js b/form.js
--- a/form.js
+++ b/form.js
@@ -1,8 +1,16 @@
 export function validateMessage(rawText) {
-  if (!rawText) {
+  const text = String(rawText ?? "").trim();
+  if (text.length === 0) {
     return { valid: false, error: "本文を入力してください" };
   }
+  if (text.length > 200) {
+    return { valid: false, error: "本文は200文字以内で入力してください" };
+  }
   return { valid: true, error: "" };
 }

差分では次の3点を点検します。

• -（削除行）に既存の必要な処理が含まれていないか：別の入力チェックや送信処理まで消されていないか。
• +（追加行）が依頼条件と一致しているか：.trim() による空白除去、text.length > 200 の境界条件、エラー文言が指定どおりか。
• 不要な仮コードが残っていないか：確認用の console.log 等が混入していないか。

既存変更との区別

作業前に自分で編集していたファイルがあると、Codexの変更と自分の変更が1つの差分に混ざり、AIの変更だけを取り消せなくなります。依頼前に git status --short で作業ツリーが空であることを確認し、作業用ブランチを切って進めてください。

完成した動作を確認する

差分を確認したら、正常系・失敗系・境界値の入力で実際の動作を検証します。

正常系と失敗系を試す

手元で試せる関数と5件のテスト

編集側の検証関数とテストファイルを同じフォルダへ保存し、Node.js環境で node --test form.test.mjs を実行できます。編集側では通常入力、空文字、空白のみ、200文字、201文字の5件が通過しました（掲載した参考関数の確認であり、Codex実機での生成結果や画面表示テストではありません。またJavaScriptの length 判定のため、サロゲートペア等の文字数判定は別課題です）。

テスト報告と実行ログの対応

Codexが「テスト成功」と報告した場合も、実行されたコマンドとログを確認し、手元のターミナルでも同じテストを実行して再現を確かめます。

Codexでの修正後にテストが失敗する場合は、原因を次の3つに切り分けて追加指示を出します。

1. 今回の修正で壊れた新規失敗
   修正前は通っていたテストが落ちたケースです（例：.trim() 追加で改行を含む既存テストの期待値とずれた）。
2. 修正前から壊れていた既存失敗
   form.js と無関係なテストが最初から落ちていたケースです。git stash 等で変更を一時退避してテストを実行すると切り分けられます。
3. テストコード側の条件ミス
   実装は「200文字以内が正常、201文字以上がエラー」と正しいのに、テスト側が「200文字でエラー」を期待しているケースです。この場合は form.test.js の境界値を直すよう指示します。

再依頼時は、実行コマンド・入力値・期待結果・実際の出力ログをセットで渡します。

次の修正へ進む

指摘を再現可能な形で伝える

動作確認で「一度エラーを出した後、正しい文字を入れて再送信してもエラー表示が消えない」といった残課題が見つかった場合は、成功している部分と再現手順を分けて伝えます。

先ほどの変更を確認したところ、空入力と201文字以上のエラー表示は期待どおり動きました。
ただ、1点だけ次の問題が残っています。

【再現手順】
1. 空欄のまま送信して「本文を入力してください」のエラーを表示させる
2. 続けて20文字の正しい本文を入力し、もう一度送信ボタンを押す

【期待する結果】
エラー表示（`#error-message`）が空になり、送信完了メッセージが表示される。

【実際の結果】
送信完了にはなるが、前回の「本文を入力してください」というエラー文字が画面に残ったままになっている。

`form.js` の送信成功時の処理を確認し、エラー表示をクリアするように修正してください。他ファイルは変更しないでください。

採用する差分を整理

確認表の3パターンとテストがすべて通ったら、再度 git status --short と git diff で不要な変更がないことを確かめてコミットします。1つの修正ごとにコミットを分けておくと、次の修正で問題が出ても直前の状態へすぐ戻せます。

同じリポジトリで毎回伝えるテストコマンドや変更禁止ルールが固まったら、AGENTS.mdの書き方 Codexへプロジェクトの前提を伝える を参考に AGENTS.md へまとめておくと反復作業を短縮できます。

よくある質問（FAQ）

アプリとCLIは同じ操作？

画面構成は異なりますが、「ローカルフォルダを開く → 変更範囲と期待動作を伝えて計画を出させる → git diff とテスト結果を確認する」という基本手順は同じです。作業中は1つの環境だけを使い、複数画面から同時に同じフォルダを書き換えないようにします。

勝手に広く変更された場合は？

そのまま追加指示を重ねず、一度変更を取り消して依頼条件を絞り直します。git status --short で変更ファイルを確認して元に戻し、「変更は form.js の validateMessage 関数のみに限定してください」と対象を狭めて再依頼してください。

テストに合格すれば確認不要？

自動テスト合格だけでは不十分です。AIが書いたテスト自体が実装と同じ勘違いを含んでいたり、エラー表示の消去漏れなど画面上の挙動を検査していなかったりするためです。テスト実行ログ、git diff の差分、主要3パターンの動作確認を組み合わせて完了を判断してください。

出典・参考資料

• ChatGPT / Codex Docs - Quickstart
• OpenAI Cookbook - Iterating Development Workflows with Codex

AmoriのAI実験室

本文執筆：agy ／ 確認・編集：制作担当

編集・検証方針X @nin_amori

すべての記事を見る