はじめに
AIでコードを書くツールはたくさんあるが、最近は「チャットで相談する」だけではなく、リポジトリを読んで、変更案を出し、テストやレビューまで一緒に進める AIコーディングエージェント が使われるようになってきた。
この記事では、OpenAIの Codex を初めて使う方向けに、次の内容を整理する。
- Codexとは何か
- Codex CLIで何ができるのか
- 最初に試すとよい使い方
- 安全に使うための注意点
-
AGENTS.mdでプロジェクトのルールを伝える方法
この記事は、まず CLIから触ってみる ことを目的にしている。
Codexとは
Codexは、コードの作成・調査・修正・レビューを支援するAIコーディングエージェントだ。
普通のチャットAIにコードを貼り付けて相談する場合、こちらが必要なファイルや前提を都度渡す必要がある。
一方でCodex CLIは、ローカルのターミナルから起動し、指定したディレクトリの中でリポジトリを読み取りながら作業できる。つまり、単に「関数を書いて」と依頼するだけでなく、次のような実際の開発作業に近い依頼ができる。
- このリポジトリの構成を説明して
- このエラーの原因を調べて
- テストが落ちている理由を特定して
- この処理をリファクタリングして
- 変更後にテストまで実行して
- 差分をレビューして
Codexで最初にやるとよいこと
いきなり大きな変更を任せるより、最初は「読む」「説明する」「小さく直す」から始めるのがおすすめだ。
たとえば、既存のリポジトリで次のように起動する。
codex
起動後、まずは次のように聞いてみる。
このリポジトリの構成を説明して。
主要なディレクトリ、エントリーポイント、テストの実行方法を整理して。
まだファイルは変更しないで。
最初のポイントは、いきなり変更させないこと だ。
まずCodexにプロジェクトを読ませて、どのように理解したかを確認する。ここで説明が的外れであれば、作業を任せる前に前提を補足できる。
インストールと起動
macOS/Linuxの場合、公式の案内ではスタンドアロンインストーラを使う方法が紹介されている。
curl -fsSL https://chatgpt.com/codex/install.sh | sh
インストール後、任意のリポジトリで次を実行する。
codex
初回起動時は、ChatGPTアカウントまたはAPIキーで認証する。
Windowsの場合も利用できるが、PowerShellでネイティブに使う方法や、Linux寄りの環境が必要な場合にWSL2を使う方法がある。実際のセットアップは利用環境によって変わるため、最新の公式ドキュメントを確認した方がよい。
はじめての依頼例
1. リポジトリを説明してもらう
このリポジトリの構成を説明して。
特に、アプリケーションの起動方法、テスト方法、主要な設定ファイルを整理して。
ファイル変更はしないで。
これは最初におすすめだ。
Codexがどこまでプロジェクトを読めているか確認できる。
2. エラー調査を依頼する
npm test が失敗している。
原因を調査して。
まずは失敗しているテストと原因候補を説明して。
修正はまだ行わないで。
最初から「直して」と言うより、まず原因を説明してもらう方が安全だ。
原因の説明に納得できたら、次に修正を依頼する。
原因の説明は理解した。
最小限の変更で修正して。
修正後に関連するテストを実行し、結果も説明して。
3. 小さなリファクタリングを依頼する
この関数を読みやすくリファクタリングして。
ただし、外部仕様は変えないで。
変更後に既存テストを実行して。
リファクタリングを依頼するときは、必ず 外部仕様を変えない と明示するとよい。
さらに、テスト実行まで依頼しておくと、変更後の確認がしやすくなる。
Codexにうまく依頼するコツ
Codexに依頼するときは、単に「直して」ではなく、次のように書くと安定しやすい。
目的:
ログイン処理で発生している500エラーを修正したい。
制約:
- 既存のAPIレスポンス形式は変えない。
- 新しい依存パッケージは追加しない。
- まず原因を説明してから修正する。
確認:
- 関連するテストを実行する。
- 変更差分の要約を最後に出す。
ポイントは、次の4つだ。
- 目的を書く
- 制約を書く
- 変更してよい範囲を書く
- 最後に確認してほしいことを書く
AIエージェントは、自由度が高いほど便利だが、自由度が高すぎると意図しない変更も起こりやすい。
そのため、最初は少し細かいくらいに条件を書くのがおすすめだ。
AGENTS.md でプロジェクトのルールを伝える
毎回プロンプトに同じ注意事項を書くのは大変だ。
そこで便利なのが AGENTS.md だ。
Codexでは、グローバル設定やリポジトリ内の AGENTS.md に、プロジェクト固有のルールを書いておける。
たとえば、リポジトリのルートに次のようなファイルを置く。
# AGENTS.md
## Repository rules
- 変更前に、必ず関連ファイルを読んでから作業すること。
- 新しい依存パッケージを追加する場合は、事前に理由を説明すること。
- TypeScriptを変更した場合は `npm run typecheck` を実行すること。
- JavaScript/TypeScriptを変更した場合は `npm test` を実行すること。
- public API のレスポンス形式を変える場合は、必ず事前に確認すること。
- 変更後は、差分の要約と実行した確認コマンドをまとめること。
このように書いておくと、Codexに毎回同じ前提を説明しなくても、プロジェクトの作法を伝えやすくなる。
チーム開発の場合は、レビュー観点やテスト方針を AGENTS.md にまとめておくと、属人化しにくくなる。
初心者が気をつけること
1. 最初から強い権限を与えすぎない
Codexはローカルのファイルを読んだり、変更したり、コマンドを実行したりできる。
そのため、最初はデフォルトの権限設定で使い、どのタイミングで確認が入るのかを理解してから設定を緩めるのがよい。
特に、重要なリポジトリや本番に近い環境では、いきなり広い権限を与えない方が安全だ。
2. Gitの状態をきれいにしてから使う
Codexに作業を依頼する前に、次のように作業ツリーを確認しておくと安心だ。
git status
未コミットの変更が多い状態でCodexに修正を依頼すると、自分の変更とCodexの変更が混ざって見えにくくなる。
可能であれば、作業ブランチを切ってから使う。
git switch -c try-codex
3. 差分は必ず自分で確認する
Codexが生成したコードは、そのまま信用するのではなく、必ず差分を確認する。
git diff
見るべきポイントは次のとおりだ。
- 依頼していないファイルを変更していないか
- 仕様が変わっていないか
- エラーハンドリングが雑になっていないか
- テストが追加・更新されているか
- セキュリティ上のリスクが増えていないか
- 不要な依存関係が追加されていないか
AIが書いたコードも、人間が書いたコードと同じようにレビューする必要がある。
4. 「テストして」と明示する
Codexに変更を依頼するときは、最後に必ず確認方法も指定する。
修正後、関連するテストを実行して。
テストを実行できない場合は、理由と代替確認方法を説明して。
テストがないプロジェクトでは、Codexにテストの追加を依頼するのも有効だ。
この変更に対するテストを追加して。
正常系と異常系を最低1つずつ含めて。
Codexに任せやすい作業
最初に任せやすい作業としては、次のようなものがある。
- 既存コードの説明
- エラー原因の調査
- 小さなバグ修正
- テスト追加
- 型エラーの修正
- Lintエラーの修正
- READMEの更新
- 影響範囲の調査
- 変更差分のレビュー
逆に、最初から任せすぎない方がよいのは次のような作業だ。
- 大規模な設計変更
- 認証・認可まわりの変更
- 決済処理の変更
- 本番データに影響する処理
- セキュリティ上重要な設定変更
- 仕様が曖昧な機能追加
このあたりは、Codexに丸投げするのではなく、設計方針を先に固めてから、部分的に作業を依頼する方が安全だ。
よく使う依頼テンプレート
コード調査
この機能の処理フローを説明して。
関係するファイルを特定し、どの順番で呼び出されているかを整理して。
まだファイルは変更しないで。
バグ修正
以下のバグを修正して。
現象:
〇〇すると△△になる。
期待値:
□□になる。
制約:
- 既存のAPI仕様は変えない。
- まず原因を説明する。
- 修正後に関連テストを実行する。
テスト追加
この関数に対するテストを追加して。
正常系、異常系、境界値を含めて。
既存のテストスタイルに合わせて。
レビュー
現在の未コミット差分をレビューして。
特に、バグ、仕様変更、テスト不足、セキュリティリスクの観点で確認して。
修正はまだ行わず、指摘だけ出して。
まとめ
Codexは、単にコードを書かせるツールというより、開発作業を一緒に進めるAIコーディングエージェントだ。
最初は、次の流れで使うのがおすすめだ。
- リポジトリを説明してもらう
- 小さな調査を依頼する
- 小さな修正を依頼する
- テスト実行まで依頼する
- 差分を自分で確認する
- よく使うルールは
AGENTS.mdにまとめる
AIエージェントは便利だが、最終的な責任は開発者側にある。
だからこそ、Codexには「作業を丸投げする」のではなく、「調査・実装・確認・レビューの相棒」として使うのがよい。