Codexハンズオンで小さな修正を安全に進める実践ガイド

Codexハンズオンを今始める理由

Codexの使い方は、説明を読むだけではつかみにくい。実際に自分のプロジェクトを読み込ませ、どこを見て、どの程度の変更を提案し、結果をどう説明するのかを確認して初めて、道具との距離感が分かるからだ。ここでいうハンズオンは、難しい機能を一度に作らせる実験ではない。小さな課題を選び、準備、依頼、差分確認、検証という四つの場面を順番に観察する練習である。

2026年9月24日に公式リリース一覧を確認すると、安定版のLatestとして0.156.1が表示され、先行版の0.158.0-alpha.8も同日に公開されている。0.156.1のリリース説明には、GPT-6 SolとGPT-6 Lunaをモデル選択画面から選べる変更がある。先行版の番号が新しく見えても、それだけで初めての練習に適しているとは限らない。まず安定版で手順を再現し、先行版は変更点を確認する対象として分けるのが現実的だ。出典 URL: https://github.com/openai/codex/releases/tag/rust-v0.156.1

ハンズオンのゴールを小さく決める

最初の課題は、成功したかどうかを人がすぐ判定できるものにする。たとえば表示文言の修正、入力値の境界条件を一つ追加、既存のテストを一つ読みやすくする、といった変更なら、作業前後の違いがはっきりする。反対に、「アプリ全体を改善する」「設計を最適化する」のような依頼は範囲が広く、Codexがどの判断をしたのか追いにくい。ハンズオンの目的は完成品を得ることではなく、依頼の大きさと結果の読みやすさの関係を体験することだ。

課題を決めるときは、次の条件を満たすかを確認する。

1. 変更する主なファイルを一つか二つに絞れる。
2. 変更前の状態を画面、テスト、または短い確認結果で記録できる。
3. 変更後に、期待する動作を人が短時間で確かめられる。
4. うまくいかなくても、元の状態へ戻す判断ができる。

この条件を満たす課題なら、Codexに任せる範囲を広げる前に、観察すべき点が見える。公式のCodex CLI資料も、ローカルのリポジトリを調べ、編集し、導入済みのツールを使う入口として案内している。まずは自分が内容を説明できる小さな場所から始め、結果を読める状態を保つことが大切だ。出典 URL: https://developers.openai.com/codex/cli/

まず読み取りだけの課題にする

最初から書き換えを頼まず、対象ファイルの役割、関係する呼び出し元、既存テストの位置を説明させる。読み取りだけなら、Codexがプロジェクトをどの順番で調べるか、無関係なファイルまで広げないかを確認できる。説明の中に事実と推測が混ざっていたら、ファイル名や行の位置を示して分けて聞き直す。この一手間が、後の修正範囲を小さくする。

変更する場所を一つに絞る

初回の修正は、画面の文言、単純な条件分岐、テストの追加のように、結果を目で判断できるものがよい。データベースや認証のように影響範囲が広い部分は、仕組みを理解してからにする。Codexに渡す依頼文には、触ってよい場所と触らない場所を明記し、目的に関係しない整理や名前変更は求めない。作業を広げない条件が、品質を判断する基準になる。

実践前に確認する項目

ハンズオンで大切なのは、Codexを起動することより、起動前の状態をそろえることだ。どのフォルダーで作業するか、変更が残っていないか、どの版とモデルを使うかが曖昧だと、結果がよくても何が効いたのか分からなくなる。作業場所と対象を確認し、変更前の状態を短く残してから依頼を始める。

確認の基準は、特別な設定を増やすことではなく、後から同じ条件をたどれることに置く。既存の変更がある場合は、今回の課題と混ざらないように対象を変えるか、先に人が内容を整理する。Codexが提案した差分を確認する人が、何を見ればよいか分かる状態を作っておく。

Step 1: 作業場所と変更前の状態を確認する

対象プロジェクトのルートを開き、目的のファイルが存在することを確認する。続いて現在の変更、関連するテスト、実行に必要な前提を人の目で確認する。既存の変更を消してきれいにすることが目的ではなく、今回の修正と混ざらない境界を決めることが目的だ。変更前の画面やテスト結果を短く保存しておけば、Codexが何かを変えた後に比較しやすい。

Step 2: 版と利用モデルを固定して始める

初回は公式リリース一覧の安定版を基準にし、モデルは利用できる選択肢の中から一つに固定する。2026年9月24日時点では0.156.1が安定版として表示され、同じ一覧に0.158.0-alpha.8などの先行版も並ぶ。モデルやクライアントを途中で変えると、出力の違いが依頼文によるものか環境によるものか判定しにくい。最初の記録には、版、モデル、推論の深さ、作業場所を残す。

Step 3: 期待する結果を一文で書く

依頼は「何を変えるか」だけでなく、「何を変えないか」と「どう確認するか」まで含める。たとえば、対象ファイル、望む挙動、変更してよい範囲、実行してほしい確認、最後に報告してほしい項目を一つの依頼にまとめる。曖昧な表現を減らし、見た目の改善や別の整理を追加しないよう伝える。成功条件が一文で言えないなら、課題をさらに小さく分ける。

Codexへの最初の依頼文を書く

依頼文は長ければよいわけではない。Codexが判断する材料を、対象、目的、制約、確認方法の順で置くと、返ってきた結果を読みやすい。背景をすべて説明するより、必要なファイルと期待する挙動を示し、足りない情報は先に質問させる方が安全だ。ここでは「変更してよい範囲」を具体的に書くことが重要になる。

次のような形で依頼すると、初回の判断を小さく保てる。

このプロジェクトの〇〇機能について調べてください。
まず関連するファイルと既存テストを読み、変更案を説明してください。
合意したら、対象ファイルだけを変更し、既存の確認方法を実行してください。
新しい依存関係の追加、無関係な整理、別機能の名前変更はしないでください。
最後に、変更したファイル、理由、確認結果、残る注意点を分けて報告してください。

この例では、先に調査と説明を置いているため、誤解したまま広い変更を始めにくい。Codexがすぐ編集を始めた場合は、いったん止めて、対象と確認方法を言い換える。依頼の主導権を人が持つとは、細かなコードを一行ずつ指定することではなく、範囲と合格条件を先に決めることだ。

Step 4: 調査結果を事実と提案に分ける

Codexの最初の報告を読んだら、実際にファイルへ書かれている事実、そこから導いた推測、これから行う提案を分けて確認する。ファイル名や関数名が示されているなら、その場所を開いて内容を照合する。提案がよく見えても、根拠が見えないまま承認しない。ハンズオンでは、答えの正しさだけでなく、答えに至る説明が追えるかも評価する。

Step 5: 変更範囲を守るよう伝える

変更後に差分が想定より大きければ、完成度を上げようとせず、まず範囲を戻すよう依頼する。ファイルの整形、名前の統一、コメントの追加は、それ自体が正しくても今回の目的とは別かもしれない。変更対象と対象外をもう一度示し、必要な箇所だけに絞った差分を作り直す。このやり取りを通じて、依頼文のどこが弱かったかも分かる。

差分・テスト・説明を読む

Codexが「完了」と報告しても、人が確認すべきことは残る。差分が依頼どおりか、既存の挙動を壊していないか、テストが本当に変更箇所を確かめているかを順番に見る。テストが通ったという事実は、すべての利用場面が正しいことと同じではない。特に初回は、結果を受け取るだけでなく、変更の理由を自分の言葉で説明できるところまで確認する。

確認の順序を固定すると、見落としが減る。

1. 変更されたファイルと行を確認する。
2. 依頼に含めた目的と差分が対応しているか読む。
3. 既存テストと今回の確認結果を分けて見る。
4. 境界条件、エラー時、入力が空のときの挙動を考える。
5. 残った注意点と、次に人が判断する項目を記録する。

Codex CLIの公式案内は、ローカルのコードを調べ、編集し、導入済みのツールを使う流れを示している。便利さの中心は、結果を無条件に受け入れることではない。人が差分を読み、必要な確認を選び、変更を採用するか判断できることにある。出典 URL: https://learn.chatgpt.com/docs/codex/cli

Step 6: 差分で意図と範囲を確認する

最初にファイル数を見て、依頼した範囲から外れていないかを確かめる。次に追加、削除、移動された行を読み、なぜその変更が必要なのかを説明する。説明できない行があるなら、Codexに理由を質問するか、不要な変更として戻す。小さな修正では、差分が短いことそのものが品質ではないが、短い差分ほど人の確認を行いやすい。

Step 7: テスト結果を鵜呑みにしない

テストが通っても、今回の条件を十分に含んでいるとは限らない。正常な入力だけでなく、空の値、上限付近、誤った形式など、変更した条件に直接関係する確認を一つ追加する。画面の修正なら実際の表示を見て、文言や折り返しが意図どおりか確かめる。Codexが実行した確認と、人が追加した確認を分けて記録すれば、結果の意味が明確になる。

Step 8: 変更理由を短く整理する

最後の報告は、変更したファイル、変更理由、確認内容、残る注意点の順にまとめる。コードの説明を長くするより、次に読む人が判断できる情報を残すことが大切だ。理由が「Codexがそう提案した」だけになっていたら、課題の目的と変更の関係を自分の言葉で言い直す。説明できない変更は、採用を保留してよい。

失敗しやすい依頼と直し方

ハンズオンでは、失敗をなくすことより、失敗した場所を切り分けることに価値がある。Codexが対象を見つけられない、変更範囲が広がる、確認が終わらないといった場合は、同じ依頼を何度も繰り返さない。最後にうまくいった状態、変えた条件、表示された結果を残し、一つの条件だけを戻して再確認する。

失敗を一つの原因に決めつけず、入力、対象、版、確認方法のどこで止まったかを切り分ける。再試行のたびに条件を変えるのではなく、変更は一つにとどめると、戻るべき状態と次に読むべき情報が見えやすい。

依頼が大きすぎる場合

「機能を改善する」ではなく、「この入力のときに表示される文言を変える」のように、対象と結果を一つにする。大きな課題を調査、修正、確認へ分け、それぞれの終了条件を決める。最初の調査で見つかった別の問題は、今回の差分へ混ぜず、別の候補として記録する。

同じファイルに変更が集中する場合

複数の要求を一つの依頼へ詰め込まず、目的の近い変更だけを一回に扱う。同じファイルを大きく直す必要があるなら、先に読み取りと変更案の説明を求め、順番を決めてから編集する。ファイルを触る担当を増やすより、境界を明示して一つずつ確認する方が、原因を追いやすい。

エラーを一度に直そうとする場合

表示されたエラー全文、発生した操作、直前に変えた条件を残し、原因の候補を一つずつ確認する。エラーを隠すために広い例外処理を追加したり、関係のない設定を変えたりしない。Codexには「原因候補を複数挙げる」ことと「最初に読む場所」を分けて頼み、確認できた事実を積み上げる。

複数エージェントへ広げる前に知っておくこと

一人のCodexで小さな課題を最後まで確認できるようになったら、複数エージェントへ分ける判断を考える。分割には、調査を速くできる可能性がある一方、報告の形式がそろわない、同じ場所を触る、重複した結論が返るといった負担もある。数を増やすことを目的にせず、独立した問いがあるか、結果を一つにまとめる人がいるかで判断する。

OpenAIのAgents API公式資料では、Codexの実行基盤を使うセッションに、作業を分けてサブエージェントへ委ねる機能が案内されている。これは現在のCodex CLIのすべての入口に同じ形で備わる、と断定する話ではない。CLIのハンズオンと、APIを使って複数担当を設計する作業は、入口と利用条件を分けて考える必要がある。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/overview

Codex CLIとAgents APIを混同しない

Codex CLIは手元のプロジェクトを読み、編集し、確認する入口として使う。一方、Agents APIはOpenAIが管理するセッションと実行場所を通じて、アプリケーションからエージェントを扱うための入口だ。名前にCodexが含まれていても、画面、料金、利用できる機能、確認方法は同じではない。記事やメモでは、どの入口で試した結果かを必ず書く。

分けてよい課題、まとめる課題

別々のファイルを読むだけの調査、異なる観点のレビュー、独立した原因候補の検討は、担当を分けやすい。反対に、一つの設計判断を順番に積み上げる作業、同じファイルの連続編集、前の結果を待たないと進められない修正は、一つの担当で進めた方がよい。公式のMulti-agent資料も、独立した課題は分け、同じファイルを編集する担当には調整が必要だと説明している。出典 URL: https://developers.openai.com/api/docs/guides/agents-api/multi-agent

結果を一つにまとめる人を決める

複数の担当がそれぞれ正しい報告を返しても、採用する結論は一つにする必要がある。各担当に対象、根拠、未確認点の形式で報告させ、最後に主担当が重複と食い違いを整理する。人が最終的な差分を読み、テスト結果を確認する地点を残せば、調査の数が増えても判断の責任がぼやけにくい。

2026年9月24日時点の確認ポイント

Codexのように更新が続く道具では、記事を読む日と実際に試す日がずれる。だからこそ、ハンズオンの冒頭に確認日と版を記録する。2026年9月24日現在、公式リリース一覧には安定版0.156.1がLatestとして表示され、0.158.0-alpha.8などの先行版が同日に公開されている。0.156.1の説明にはGPT-6 SolとGPT-6 Lunaのモデル選択が記載されているため、モデルの表示が自分の入口で同じかを確認する。

OpenAIのAPI側では、公式の変更履歴に2026年9月10日のAgents API公開ベータが掲載され、Codexの実行基盤、セッション、サブエージェントへの分割が案内されている。これはCodexハンズオンの基本手順を置き換えるものではなく、同じ「コードを調べ、変更し、結果を確認する」考え方を別の入口へ広げる動きとして読むとよい。出典 URL: https://developers.openai.com/api/docs/changelog

まとめ：小さく試してから任せる範囲を広げる

Codexハンズオンで最初に身につけたいのは、難しい依頼文ではなく、変更前の状態を残し、対象を絞り、差分と確認結果を読む習慣だ。小さな文言修正や一つの条件追加から始めれば、Codexがどこまで調べ、どの判断を提案し、どの部分を人が確認すべきかが見えてくる。

2026年9月24日時点では、安定版0.156.1と先行版0.158.0-alpha.8、GPT-6 SolとGPT-6 Luna、Agents APIの複数担当機能が同時に目に入る。だからこそ、版、入口、モデルを混ぜずに記録することが重要だ。先に一つの担当で小さな課題を終え、結果を説明できるようになってから、独立した調査だけを複数担当へ分ける。この順番なら、Codexを便利な道具として使いながら、変更の判断は人の手元に置ける。