Codexとripgrepの使い方｜コード検索を速く正確にする

ripgrep Codexを今使う理由

ripgrepは、現在のディレクトリ以下を正規表現で再帰検索する行指向の検索ツールです。公式リポジトリによると、既定で.gitignore、.ignore、.rgignoreを尊重し、隠しファイルとバイナリを自動的に除外します。Windows、macOS、Linuxを正式に扱い、コード検索向けの絞り込み機能も備えています（出典: https://github.com/BurntSushi/ripgrep ）。

2026年7月16日に公開されたripgrep 15.2.0では、複数ディレクトリをまたいだ検索で無視設定が正しく一致しない問題が修正され、非常に大きなディレクトリツリーの走査時間も改善されました。さらにGIT_CONFIG_GLOBALとGIT_CONFIG_SYSTEMを参照する変更も入っています（出典: https://github.com/BurntSushi/ripgrep/releases/tag/15.2.0 ）。複数の場所を一度に調べる利用者にとって、検索結果の正確さに直結する更新です。

一方、Codexのデスクトップアプリは2026年7月23日に、ローカルプロジェクトへ複数の関連フォルダーを追加し、主フォルダーを選べるようになりました（出典: https://learn.chatgpt.com/docs/changelog#codex-2026-07-23-app ）。調査対象を広げやすくなった今ほど、「どこを探し、どこを外したか」を明確にする価値が高まっています。ただし、Codexが常にripgrepを選ぶとは限りません。確実に使わせたい場面では、依頼文でrgと検索条件を指定します。

Codexとripgrepの役割を分ける

Codex CLIの公式ページは、ローカルリポジトリのファイルを調べ、編集し、端末に入っているツールを実行できると説明しています（出典: https://learn.chatgpt.com/docs/codex/cli ）。つまりripgrepはCodexの代わりに判断する道具ではなく、Codexが判断に使う証拠を短時間で集める道具です。この役割分担を理解すると、単に「バグを直して」と頼むより、結果の追跡がしやすくなります。

ripgrepが得意なのは、文字列や規則に合う行、対象ファイル、出現件数、前後の文脈を機械的に列挙することです。Codexが得意なのは、列挙された定義と参照の関係を読み、変更範囲を判断し、修正後の確認方法まで組み立てることです。検索結果をそのまま答えと見なさず、「この結果から何が分かり、何はまだ未確認か」をCodexに説明させると、見落としを減らせます。

特に同名のクラスが複数ある構成、古い版のコードが残る構成、アプリ本体とテストが別フォルダーにある構成では、検索と判断を一度に任せると根拠が埋もれがちです。先に検索条件を固定し、次に結果を解釈し、最後に編集する三段階へ分ければ、途中で検索語や除外先を修正できます。

Codexからrgを使う基本手順

最初に確認したいのは、rgが現在の端末から呼び出せるか、どの場所を起点に検索するか、無視設定がどう効くかの三点です。Codexは現在の作業場所を基準にファイルを調べるため、起点が一段ずれるだけで結果が大きく変わります。以下では、インストール確認から安全に検索範囲を広げるまでを順に進めます。

Step 1: rgが使えるか確認する

Codexへ「rg --versionを実行し、利用可能か確認してください」と依頼します。バージョンが表示されれば準備完了です。見つからない場合は、ripgrep公式リポジトリのInstallationにあるOS別の案内を確認して導入し、端末を開き直してからもう一度確かめます。OSごとに配布経路が異なるため、古い記事のコマンドを無条件に貼り付けず、公式案内を起点にするのが安全です（出典: https://github.com/BurntSushi/ripgrep#installation ）。

このプロジェクトのルートで rg --version を実行してください。
使えない場合は編集せず、OSとエラー文だけを報告してください。

Step 2: ファイル候補を先に絞る

検索語を決める前に、rg --filesでripgrepから見えているファイルを把握します。すべてを表示すると多すぎる場合は、rg --files -g '*.php'のように拡張子を限定します。ここで目的のフォルダーが一件も出なければ、文字列検索へ進んでも見つかりません。Codexには件数と代表例だけを報告させ、長大な一覧を会話へ貼り付けないよう指示します。

rg --files -g '*.php' で検索対象を確認し、総数と代表的な10件を示してください。
vendorと生成物は対象に含めないでください。まだ編集はしないでください。

Step 3: 定義と参照を行番号付きで探す

候補が見えたら、rg -n -S 'PaymentStatus'のように行番号とsmart caseを付けて検索します。-Sは検索語に大文字が含まれると大文字小文字を区別し、すべて小文字なら区別しないため、名前の表記揺れを調べやすい指定です。単なる文字列を探すなら-F、単語単位なら-wを加えると、正規表現の記号や部分一致による余計な結果を減らせます。

rg -n -S -w 'PaymentStatus' を実行し、定義、利用箇所、テストに分類してください。
分類できない一致は「未分類」として残し、推測で除外しないでください。

Step 4: 前後の文脈を読んでから編集する

検索行だけでは、同名の識別子がどの処理に属するか判断できないことがあります。rg -n -C 3 'PaymentStatus'なら一致行の前後3行を確認できます。結果が多い場合は対象パスを末尾へ付け、調べるフォルダーを狭めます。Codexには、編集前に「変更候補」「変更しない一致」「判断保留」を分けて説明させると、誤った一括置換を避けやすくなります。

srcとtestsに限定して rg -n -C 3 -S 'PaymentStatus' を実行してください。
変更候補と変更しない一致を理由付きで整理し、私が確認するまでは編集しないでください。

よく使うrgオプションと使い分け

ripgrepは短いオプションを組み合わせられますが、多く付ければ精度が上がるわけではありません。目的が「場所を知る」「文脈を読む」「対象形式を限定する」のどれかを先に決めると、必要な指定だけを選べます。Codexへ渡す結果は少なすぎても判断できず、多すぎても重要な一致が埋もれるため、最初はファイル名と行番号が分かる粒度を基準にします。

正規表現が必要な場面と、文字列をそのまま探したい場面を混同しないことも重要です。たとえばconfig.value[0]を通常検索すると、角括弧が正規表現として解釈されます。構文を意識せず同じ文字列を探したいなら-Fを使います。反対に、error|failed|timeoutのいずれかを探すなら正規表現が便利です。Codexへ「この検索語は固定文字列か正規表現かを先に判断して」と頼むと、意図しない一致を減らせます。

ファイル形式の指定では、-g '*.php'のようなglobが分かりやすく、-tpyのような組み込み型も使えます。複数条件では-gを重ねられ、-g '!storage/**'のような否定条件も指定できます。除外先を依頼文へ明記しておけば、Codexが別の検索方法へ切り替えた場合にも、同じ境界を保ちやすくなります。

見つからないときの検索範囲の広げ方

目的の文字列がゼロ件でも、存在しないとは限りません。対象パスが違う、.gitignoreで外れている、隠しファイルにある、UTF-8以外で保存されている、別の表記になっている、といった可能性があります。重要なのは、最初からすべての除外を解除せず、一つずつ条件を変えて原因を特定することです。

Step 1: 検索語と起点を確認する

まずGet-Locationやpwdで現在地を確認し、rg --filesに目的の種類のファイルが含まれるかを見ます。次に検索語を短くし、-iで大文字小文字の差を外して試します。この段階では隠しファイルや無視対象をまだ含めません。表記違いだけが原因なら、余計な領域を読むことなく目的の場所へ到達できます。

Step 2: 隠しファイルだけを追加する

設定が隠しファイルにあると予想できる場合は、--hiddenを追加します。ただし.git配下まで読む必要は通常ありません。rg --hidden -g '!.git/**' '検索語'のようにリポジトリ管理情報を外すと、結果を抑えられます。Codexには、既定検索との差分だけを示させると、新たに見つかった場所を判断しやすくなります。

Step 3: 無視設定を限定的に解除する

無視対象にあると分かっている場合だけ--no-ignoreを検討します。-uuuは隠しファイル、無視対象、バイナリに対する自動除外をまとめて弱める強い指定なので、最初の手段には向きません。依存パッケージや生成物が大量に混ざれば、検索時間だけでなくCodexが読む情報量も増えます。対象パスとglobを先に限定し、解除の理由を記録してから使います。

Codexへの依頼文を正確にする

良い依頼文には、検索目的、起点、対象、除外先、報告形式、編集の可否が含まれます。コマンドだけを渡すと、Codexは結果を得られても「何の判断に使うか」を推測しなければなりません。反対に目的だけを伝えると、検索範囲が広がりすぎることがあります。両方を一つの依頼に入れると、途中結果を確認しながら次へ進められます。

Step 1: 調査だけを依頼する

最初の依頼では編集を許可せず、定義、参照、テスト、設定の所在を調べさせます。検索コマンドと対象パスを明記し、結果はファイル名、行番号、役割の三点でまとめてもらいます。ゼロ件の場合も、別の語を勝手に試し続けず、実行した条件を報告させると、次の検索を人が判断できます。

目的は決済状態の変更影響を把握することです。
src、config、testsを対象に、rg -n -S -w 'PaymentStatus'で調査してください。
vendorと生成物は除外し、ファイル名・行番号・役割を表で報告してください。
この段階では編集しないでください。

Step 2: 仮説と未確認点を説明させる

検索結果が出たら、変更が必要な理由と、まだ読めていない領域を説明させます。「一致したから直す」ではなく、呼び出し元、値の流れ、テストの期待値がつながっているかを確認します。文字列検索では動的な呼び出しや別名を見落とす場合があるため、Codex自身に検索の限界を言語化させることが大切です。

Step 3: 対象を固定して編集する

編集へ進むときは、確認済みのファイルを列挙し、範囲外へ触れる場合は止まって報告するよう指示します。修正後は同じrgを再度実行し、古い表記が意図どおり消えたか、残った一致に理由があるかを確かめます。検索前後を同じ条件で比べれば、修正漏れと過剰な置換の両方を見つけやすくなります。

ripgrep Codexで起きやすい失敗

最も多い失敗は、検索結果がゼロ件だったときに「対象は存在しない」と即断することです。ripgrepの既定の除外は便利ですが、調査対象が隠し設定や無視対象にある場合は結果へ出ません。逆に、除外をすべて解除して大量の一致を出すのも問題です。どの条件を変えた結果なのか分からなくなり、Codexが生成物を本体コードと誤認する可能性があります。

二つ目は、検索結果をそのまま一括置換へつなげることです。同じ文字列でも、実装、テスト用データ、説明文、移行用コードでは役割が違います。rg -lで候補を絞った後、rg -Cで周辺を読み、役割ごとに分類してから編集する必要があります。rg --replaceは置換後の表示を作れますが、ファイル自体を書き換える機能ではない点にも注意してください。

三つ目は、出力をすべてCodexへ読ませることです。一致が数千件あるなら、まずrg -lでファイル数を確認し、対象フォルダーや拡張子を狭めます。それでも多い場合は、定義らしいパターン、呼び出し、テストの順に検索を分けます。速い検索ツールを使っても、結果の選別がなければ判断は速くなりません。

まとめ

Codexとripgrepの組み合わせは、AIに速くコードを書かせるためだけの工夫ではありません。調査範囲と根拠を見える形にし、人が途中で修正できるようにするための方法です。rg --filesで対象を確かめ、rg -n -Sで定義と参照を探し、rg -C 3で文脈を読み、仮説を確認してから編集する流れを基本にすると、大規模なリポジトリでも判断が安定します。

ripgrep 15.2.0では複数ディレクトリ検索時の無視設定と大規模ツリーの走査が改善され、Codex側でも複数の関連フォルダーを扱えるようになりました。便利な範囲が広がったからこそ、検索条件を明示する価値が増しています。まずは一つの識別子を対象に、検索、分類、編集、再検索までを小さく試し、自分のリポジトリに合う絞り方を固めてください。