RalphとCodexの使い方｜反復開発を安全に進める確認点

RalphとCodexは何を分担するか

RalphとCodexは似た文脈で語られますが、同じ製品ではありません。Ralphの公式リポジトリは、長く続く開発作業を、要件文書に書かれた課題の単位へ分けて進めるCLIツールとして説明しています。そこへCodexを指定すると、Ralphが課題を選び、Codexが対象のリポジトリを調べて変更し、結果を返す形になります。したがって、問題が起きたときは「Ralphが次の課題を選べない」のか、「Codexが現在の課題を終えられない」のかを分けて見ることが重要です。

Ralphは課題の順番を持つ

Ralphの役割は、課題を無限に増やすことではなく、あらかじめ用意した要求文書から次の一件を決めることです。公式リポジトリの説明では、初期設定を作り、利用するエージェントを選び、指定した回数だけ課題を順番に扱う流れが示されています。課題が完了したかどうかをRalphが判定できるよう、完了条件を文章やテスト結果で表せる形にしておく必要があります。

Ralphが管理するのは、コードの正しさそのものではありません。課題の状態や反復の回数が進んでも、変更が意図に沿っているとは限らないからです。Ralphの記録は「どの課題を選んだか」「何回目か」を追う材料と考え、差分の内容や設計上の判断はCodexの報告と人の確認で補います。

Codexは一件の課題を調査して仕上げる

Codexは、課題の目的を読み、既存コードの構造を確認し、必要な変更を加え、テストや確認結果を返す役割を担います。課題文書が「設定を直す」とだけ書かれている場合、どのファイルを触るのか、何をもって完了とするのかが曖昧なため、Codexの判断が広がりやすくなります。対象と対象外を一文ずつ書くと、結果を見直しやすくなります。

一件の課題が終わったら、次の課題へ移る前に、Codexが変更したファイル、実行したテスト、失敗した確認、残した注意点を確認します。Codexの返答が短くても、差分と実際の結果がそろっていれば判定できます。反対に、説明が詳しくても差分や結果が見えなければ、完了扱いにしない方が安全です。

いまRalphとCodexを組み合わせる理由

長時間の開発作業では、モデルの性能だけでなく、前回の判断を次の作業へ持ち越せるかが品質を左右します。2026年8月20日に公開されたCodex CLI 0.149.0では、複数の作業を見渡す codex agents、既存セッションへメッセージを送る codex queue、作業場所を確認する /pwd などが案内されました。Ralphを使う場合も、反復の外側にある作業状態を確認できると、同じ課題を重ねて選ぶ事故を見つけやすくなります（出典: https://github.com/openai/codex/releases/tag/rust-v0.149.0 ）。

同じ時期にOpenAIの公式記事は、繰り返す開発作業について、目的や前回の結果を記録し、計画を確認し、作業後に判断と結果を残す考え方を紹介しました。これはRalphの導入を推奨する発表ではありませんが、課題を一件ずつ扱い、次の担当者が前回の状態を読めるようにするという点で共通します。Ralphの実装を先に覚えるより、記録を読める課題へ整えることが先です（出典: https://developers.openai.com/blog/automating-repetitive-work-at-openai-with-codex ）。

さらに8月25日には 0.150.0-alpha.11 が Pre-release として公開されています。公式ページで確かめられる版番号と公開日を、0.149.0で案内された具体的な機能や手元の確認結果とは分けて読みます。先行版の番号だけから、Ralphとの互換性や動作の改善を推測しないことが大切です（出典: https://github.com/openai/codex/releases/tag/rust-v0.150.0-alpha.11 ）。

Codex CLI 0.149.0の更新をどう生かすか

0.149.0の codex agents は、作業を検索、開始、表示、名前変更、停止するための対話的な一覧として公式リリースに記載されています。Ralphが課題を選ぶ構成でも、Codex側に残った作業を一覧できれば、現在何が動いているかを把握しやすくなります。codex queue は既存のローカルまたはリモートのセッションへメッセージを送る機能です。

ただし、これらの機能があるからといって、確認を省いてよいわけではありません。Ralphが課題を選んだ記録と、Codexが実際に触れたファイルの差分は別に確認します。0.149.0を使う場合は、まず codex --version で版を確認し、短い読み取り作業で codex agents や codex queue の表示を確かめてから、対象範囲を広げるのが扱いやすい進め方です。

OpenAI公式記事が示す「次回に残す」視点

8月25日のOpenAI公式記事が示した大切な点は、単発の返答を得ることではなく、同じ種類の作業を次回も確認できる形へ整えることです。目的、入力、前回の結果、実施した内容、判断、未解決事項を記録しておけば、Ralphが次の課題を選ぶときも、Codexが初めて読むときも前提をそろえられます。記録は長ければよいのではなく、次に読む人が開始点を迷わないことが基準です。

Ralphを使わない場合でも、この視点は役に立ちます。課題文書と作業結果を同じ場所へ置き、完了条件と確認結果を紐付ければ、Codex CLIの単発利用でも再開しやすくなります。Ralphはこの整理を繰り返し扱う器であり、曖昧な課題を正しい課題へ変えてくれる道具ではない、と理解しておくと期待が膨らみすぎません。

導入前に三つの境界を決める

Ralphを初めて使うときに、起動方法だけを先に覚えると、課題が広がったときに止めにくくなります。まず「どのファイルを読むか」「どこまで変更してよいか」「何を確認して完了にするか」を決めます。これらはRalphの設定とCodexの依頼文の両方へ反映します。境界が決まっていれば、課題が失敗しても、次に直すべき場所を狭くできます。この準備に時間をかけるほど、失敗した一回を原因の分かる記録へ変えやすくなります。

対象範囲を一つの成果物へ寄せる

一つの課題に、画面変更、データ構造の変更、文書の書き換えを同時に入れると、失敗した原因が分かりにくくなります。最初は一つの機能、関連する少数のファイル、ひとまとまりのテストという大きさにそろえます。対象外の場所も明記し、見つけた別の問題は次の課題候補として記録だけ残します。

課題の名前は「改善する」ではなく、「設定画面の保存処理で空の値を拒否し、既存テストを通す」のように、対象と結果が読める形にします。Ralphが次の課題を選ぶためには、課題名だけでも目的を識別できる必要があります。Codexに渡す前に、初めて読む人が対象を誤解しないかを見直してください。

完了条件を観測できる形にする

「動くようにする」「きれいにする」といった言い方は、終わりを判定しにくい表現です。「特定の入力でエラーが返り、テストが通り、変更ファイルが三つ以内に収まる」のように、結果を観測できる条件へ変えます。数値を使う場合は測定方法と比較対象も書き、見た目の印象だけで完了を決めないようにします。

完了条件はCodexを縛るためだけのものではありません。Ralphが次の課題へ移る判断、確認者が差分を読む順番、問題が出たときの再試行の範囲をそろえるための共通の物差しです。条件を満たさない場合は、失敗として原因を記録するか、課題を分割してやり直すかを選びます。

反復回数と停止条件を先に決める

Ralphの公式READMEには、指定した反復回数で課題を進める使い方が示されています。回数を大きくすれば解決しやすくなるとは限りません。同じ誤解を繰り返したり、課題の対象を広げたりする可能性があるため、最初は少ない回数で結果を確認します。停止条件には、同じ失敗が続いたとき、対象外のファイルを触ろうとしたとき、テスト結果が不明なときを含めます。

止めることは失敗ではありません。原因が分からない状態で次の反復へ進まないことで、差分を小さく保ち、何が起きたかを人が説明できるからです。停止した課題には、最後に確認できた状態、試した方法、残っている疑問を追記し、再開時に同じ調査から始めないようにします。

Ralphを初期化してCodexを選ぶ手順

Ralphの公式リポジトリには、初期設定を作る ralph init と、指定した回数で課題を進める ralph run [iterations] が例として掲載されています。版によって設定ファイルの項目や表示は変わるため、実際に使うときは公式READMEとリポジトリの説明を確認し、手元のCodex CLIが起動できる状態で小さく試します。次の手順は、課題文書を用意してから結果を判定するまでの基本形です（出典: https://github.com/nitodeco/ralph ）。

Step 1: 課題を一件に絞る

最初に、失敗しても影響を戻しやすい課題を一件だけ選びます。課題文書には目的、対象ファイル、変更してはいけない場所、完了条件、確認方法を書きます。複数の課題がある場合も、最初の一件だけを実施対象として示し、残りは順番を持つ候補として区別します。こうすると、結果が良かった理由と悪かった理由が混ざりません。

課題の前提に、現在の版や作業場所が関係する場合は、記録欄を用意します。Codexの版が違えば出力や利用できる機能も変わるため、後から同じ条件を再現できる情報を残します。入力例や期待する結果があるなら、一つの短い例を先に置き、読み手が完了条件を具体的に想像できるようにします。

Step 2: Ralphの利用エージェントをCodexにする

公式READMEが示す初期化手順に沿ってRalphの設定を作り、利用するエージェントとしてCodexを選びます。初期化後は、Ralphが見ている課題文書の場所、Codex CLIを呼び出す設定、結果を記録する場所を確認します。ここで別のエージェント名や古い設定が残っていると、Codexへ渡したつもりの課題が別の入口へ送られるため、選択結果を画面と設定の両方で確かめます。

確認のために、公式READMEにある基本コマンドを少ない回数で実行します。例えば ralph init で初期設定を作り、課題を一件だけ用意したうえで ralph run 1 のように一回分の結果を観察します。コマンドの引数や設定名が版によって違う場合は、表示されたヘルプと公式リポジトリの最新説明を優先し、推測で書き換えないでください。

Step 3: Codexが読む前提を揃える

Codexに課題を渡す前に、対象リポジトリの構成、テスト方法、変更範囲、避ける場所を読める形にします。リポジトリに AGENTS.md を置く場合は、Codexが作業前に読む案内として、起動方法や確認方法を短く書きます。OpenAI公式ガイドも、プロジェクト固有の指示を AGENTS.md にまとめる考え方を説明しています（出典: https://developers.openai.com/codex/guides/agents-md ）。

指示文は長くするより、優先順位を明確にします。「まず関連ファイルを読む」「変更前に計画を説明する」「対象外は触らず報告する」「最後に差分とテストを示す」という順序にすると、途中の判断が追いやすくなります。課題文書と AGENTS.md に矛盾がある場合は、変更を始めず、どちらを優先するかを確認できる状態で止めます。

Step 4: 一回分の結果を差分で確認する

Codexが作業を終えたら、まず課題に書いた対象範囲と実際の変更ファイルを比べます。次に、差分の意図、テストの実行結果、確認できなかった項目、次に残したい事項を読みます。Ralph側で課題が完了になっていても、差分が広がっていたり、テストが未実施だったりする場合は、完了条件を満たしたとは判断しません。

確認結果は、短い文章で十分です。「採用」「修正して再確認」「保留」のいずれかと、その理由を書きます。失敗したコマンドや期待と違った表示も残しておけば、次の反復で同じ方法を繰り返さずに済みます。結果を課題文書へ戻すと、Ralphが次の課題を選ぶときにも、確認者が後から読むときにも前提がそろいます。

Step 5: 次の課題へ進むか止める

一回分の確認が終わったら、次の課題へ進む前に、現在の差分が保存され、課題の状態が正しく記録されていることを確かめます。完了条件を満たし、対象外への変更がなく、テスト結果を説明できるなら次へ進めます。条件の一つでも欠けている場合は、同じ課題を分割するか、原因を調査する課題へ戻し、未確認のまま新しい変更を重ねません。

止める判断をしたときは、Ralphの反復回数を増やす前に、Codexへ渡した前提と完了条件を見直します。課題文書の不足、対象範囲の広さ、確認方法の不備、版や設定の違いのどれが原因かを切り分けます。次に再開する人が迷わないよう、最後に見た差分と、再開直後に確認する項目を一文で残します。

Codex側で用意する確認環境

Ralphは課題を繰り返し渡せますが、Codexが安全に判断できる環境を用意する代わりにはなりません。Codex CLIの公式案内では、作業場所やサンドボックス、許可の範囲を設定として確認できます。課題ごとに触れてよい場所と確認方法をそろえ、Codexが想定外のファイルへ広がった場合には止められる状態を保ちます（出典: https://developers.openai.com/codex/config-reference ）。

AGENTS.mdにプロジェクトの前提を書く

AGENTS.md には、プロジェクトの構成、よく使う確認方法、命名や形式のルール、触れてはいけない場所を書きます。すべての知識を一つの文書へ詰め込むのではなく、Codexが毎回必要とする前提だけに絞ります。記述が古いと、Ralphが同じ課題を何度渡しても、Codexは誤った入口や確認方法を選び続けるため、文書を更新した日と見直す条件も残しておくと安心です。

課題文書には個別の目的を書き、AGENTS.md には複数の課題で共通する前提を書きます。この二つを分けると、個別課題が終わって次へ進んだときも、同じ説明を毎回繰り返さずに済みます。共通ルールを変更した場合は、次の課題へ進む前に、既存のテストや確認方法と矛盾しないかを一度見直してください。

作業範囲と許可を小さく保つ

Codexへ広い書き込み範囲を渡すほど、課題の誤解が大きな差分になりやすくなります。最初は対象プロジェクトの必要な場所だけを確認し、外部への接続や広い変更が必要になった時点で、なぜ必要なのかを人が判定します。許可の設定は「便利だから最大にする」のではなく、課題の完了に必要な最小範囲へ寄せます。

サンドボックスの設定を変えた場合は、変更前後の状態と、確認した課題を記録します。Ralphの反復を増やす前に、Codexの設定が今の作業場所と一致しているか、対象外の場所へ書き込めないかを確かめます。動いたという事実だけでなく、どの範囲で動いたかを残すことが、後から結果を説明する助けになります。

モデルと文脈を課題に合わせる

同じCodexでも、課題の難しさ、必要な文脈、推論の深さによって結果と所要時間は変わります。小さな形式変更に大きな課題設定を使う必要はなく、複雑な設計や原因調査では、関連する資料と確認条件を十分に渡します。毎回最大の設定を選ぶのではなく、課題の難度と、返ってくる結果を見ながら調整します。

文脈を増やしすぎると、Codexが重要な条件を見失うことがあります。課題に関係するファイル、再現手順、テスト結果、過去の判断を優先し、関係の薄い長いログは要点と参照先へまとめます。Ralphの反復で同じ説明が積み上がる場合は、記録を整理して、次の一回が読むべき情報を先頭へ寄せてください。

WindowsでRalphとCodexを試すときの注意点

Windowsでは、Codex CLIが動くことと、Ralphの配布形態・シェル前提が合っていることを別に確認します。Ralphの公式リポジトリに示された要件、インストール方法、対応する実行形式を読み、PowerShellから呼び出したときに同じ作業場所を見ているかを確かめます。ターミナルの種類を変えた場合、相対パスや環境設定の読み込み先が変わることがあるため、最初の課題は読み取り中心にします（出典: https://github.com/nitodeco/ralph ）。

版番号と実行場所を確認する

まずCodexとRalphが利用できるか、実行場所が想定どおりかを確認します。PowerShellなら次のように、版番号、ヘルプ、現在の場所を個別に見ます。

codex --version
ralph --help
Get-Location

Codexの版が0.149.0であることを確認する場合は、公式リリースに書かれた機能と、手元の表示を分けて記録します。Ralph側の表示が出ない場合は、Codexの問題だと決めつけず、配布物の場所、PATH、シェルの前提を確認します。作業場所が違うまま課題を進めると、変更が見えない、結果が別の場所に残るといった混乱が起きるため、最初に一つのテキストを読み取って一致を確かめます。

パスと改行を課題文書で揃える

Windowsと別のシェルでは、パスの区切り、引用符、改行、実行ファイルの呼び出し方が異なる場合があります。課題文書に絶対パスを大量に書くのではなく、作業ルートから見た相対位置と、対象ファイル名をそろえます。RalphとCodexへ同じ作業ルートを渡し、課題文書が読めたか、変更後のファイルが同じ場所にあるかを確認してください。

改行や文字コードが原因で差分が大きく見える場合は、機能変更を進めず、まず一つのファイルで表示と保存を確かめます。Windows Terminalで見えている結果と、Ralphが記録した結果が一致しないときも、課題を再試行するより先に、実行場所とファイルの実体を確認します。環境の違いを課題の失敗として数えないことが大切です。

初回は一回だけ動かして止める

Windowsで初めて試すときは、反復回数を増やさず、一件の読み取りや小さな変更だけで入口を確認します。Codexが対象を読める、指定したファイルだけが変わる、テスト結果が返る、Ralphが状態を記録する、という四つを個別に見ます。どれか一つが確認できなければ、次の課題を投入せず、その項目を直します。

一回分の結果を保存しておけば、シェルを変えたときにも比較できます。Windows側で起動できたからといって、別の端末や別の作業場所でも同じ結果になるとは限りません。版番号、実行場所、課題名、変更ファイル、確認結果を残し、条件が変わったときは新しい確認として扱います。

つまずきやすいパターンと直し方

RalphとCodexの組み合わせで起きる問題は、モデルが弱いという一言では片付けられません。課題が大きい、完了条件が曖昧、前提文書が古い、反復回数だけを増やしている、といった構造上の原因が多くあります。エラーが出たときは、Ralphが選んだ課題、Codexが読んだ前提、実際の差分、確認結果を順番に分けて見ます。最初に結果を否定するのではなく、どの層で止まったかを特定することから始めます。原因が見えれば、課題文書か設定か確認方法のどこを直すべきかを選べます。

同じ課題を繰り返しても進まない

同じ失敗が続く場合は、回数の不足より、入力の不足を疑います。失敗したテストの全文、再現条件、変更前の期待値、すでに試した方法のどれかが課題文書から抜けているかもしれません。Ralphの反復を増やす前に、失敗した結果を短く要約し、次の一回で何を変えるのかを一つだけ書きます。

それでも進まないときは、課題を「原因を調べる」と「修正を加える」へ分けます。Codexが調査と変更を同じ一回で行うと、原因の説明が曖昧なまま差分だけ増えることがあります。調査結果を人が確認してから修正課題を作れば、Ralphに渡す目的が明確になります。

完了になったのに差分が広い

Ralph側の状態が完了でも、変更が課題の対象を超えていれば、そのまま採用しません。差分に別の整理や形式変更が混ざっていないか、生成されたファイルや設定が増えていないか、テストが対象の変更を本当に確認しているかを見ます。広がった理由が説明できる場合も、今回の課題へ含めるか、別の課題へ分けるかを人が決めます。

差分を小さく戻したいときは、まず変更箇所を分類します。目的に必須な部分、テストや記録に必要な部分、偶然混ざった部分を分け、確認できない部分は保留にします。一度に全部を直させるのではなく、課題文書へ分類結果を戻し、次の一件として扱える大きさへ整えます。

前提文書がCodexの判断と合わない

AGENTS.md や課題文書が古い場合、Codexは書かれている条件を忠実に守って、現在は使っていないコマンドや場所を選ぶことがあります。文書を直すときは、その場の課題だけを通すための例外を増やさず、複数の課題に共通する前提を更新します。更新後は、既存のテスト方法や対象範囲と矛盾がないかを確認します。

前提が競合している場合は、Codexに解釈を任せて進めないことです。どの文書が正しいか、今回だけの指示なのか、今後も続くルールなのかを人が決めます。判断を記録すれば、次のRalphの反復で同じ競合を再現せずに済みます。

Ralphを使うべき場面と、Codexだけで足りる場面

Ralphを入れると、複数の小さな課題を同じ形式で順番に扱いやすくなります。一方、単発の修正や、途中で人の判断が頻繁に必要な設計作業では、Codex CLIを直接使った方が状況を把握しやすいこともあります。どちらが上かで決めず、課題の数、反復の必要性、確認者が結果を見るタイミングで選びます。

Ralphの公式READMEは、Codex以外にも複数のAIコーディングエージェントを選択肢として挙げています。ただし、入口を変えるとモデル、設定、結果の表示、確認方法が変わります。最初から複数製品を混ぜるのではなく、Codexで課題の大きさと完了条件を確かめ、必要になったときだけ別の入口との違いを記録するのが分かりやすい方法です。

まとめ：一件ずつ確認できる課題にする

RalphとCodexの使い方で重要なのは、Ralphを導入して反復回数を増やすことではありません。Ralphが課題の順番と回数を持ち、Codexが一件の課題を調査・変更・確認し、人が差分と結果を判定する分担を先に決めます。対象範囲、完了条件、停止条件がそろっていれば、失敗したときも原因を狭く追えます。

2026年8月20日のCodex CLI 0.149.0では、作業一覧や既存セッションへメッセージを送る機能が案内されました。8月25日のOpenAI公式記事は、反復する作業の目的、計画、結果、判断を次回へ残す考え方を示しています。これらをRalphの課題文書と組み合わせると、何を次に行うかだけでなく、なぜそこまで進めてよいのかも確認しやすくなります（出典: https://github.com/openai/codex/releases/tag/rust-v0.149.0、https://developers.openai.com/blog/automating-repetitive-work-at-openai-with-codex ）。

まずは課題を一件に絞り、ralph init、Codexの選択、ralph run 1、差分とテストの確認までを通してみてください。Windowsでは版番号、実行場所、パス、改行の違いを個別に確かめ、確認できない項目が残ったら次の課題へ進まないことが大切です。小さく始めて、結果を記録し、条件がそろった課題だけを次へ渡す——この型がRalphとCodexを安定して使う土台になります。