Codex CLIマルチファイル編集＆ワークスペース管理術

📚 この記事は「OpenAI Codex CLI 完全攻略シリーズ」の Episode 8 です。

Codex CLIの真価は、単一ファイルの生成ではなくプロジェクト全体を俯瞰した編集にあります。実際のSES現場では、1つの機能追加やバグ修正で複数ファイルを同時に変更することが当たり前です。

本記事では、Codex CLIのマルチファイル対応機能とワークスペース管理のベストプラクティスを、SES案件での実践例とともに解説します。

Codex CLIのマルチファイル対応とは

Codex CLIのマルチファイル編集フロー：コード分析→変更計画→複数ファイル同時編集→レビュー→適用

単一ファイル生成からプロジェクト全体編集へ

Codex CLIはfull-autoモードでディレクトリ全体を認識し、関連ファイルを横断的に編集できます。例えば「ユーザー認証にJWTリフレッシュトークンを追加して」と指示すると：

auth/jwt.ts — トークン生成ロジックの修正
middleware/auth.ts — リフレッシュトークン検証の追加
routes/auth.ts — リフレッシュエンドポイントの追加
types/auth.ts — 型定義の更新
tests/auth.test.ts — テストケースの追加

これらを一度の指示で整合性を保ちながら変更できるのが、マルチファイル対応の強みです。

エージェント的ワークフローの仕組み

Codex CLIは以下のステップでマルチファイル編集を行います。

コンテキスト収集 — プロジェクト構造を走査し、関連ファイルを特定
変更計画の立案 — どのファイルにどのような変更が必要かを計画
一括編集の実行 — 変更をまとめて適用（Sandboxモードの場合はプレビュー）
整合性チェック — 型エラーやインポート漏れがないか確認

マルチファイル編集の実践テクニック

複数ファイル横断のリファクタリング

SES現場で頻繁に発生するリファクタリングタスクの例です。

# API全体のエラーハンドリングパターンを統一
codex "このプロジェクトのすべてのAPIハンドラで、try-catchブロックのエラーハンドリングパターンを統一してください。カスタムエラークラスAppErrorを使い、HTTPステータスコードとエラーメッセージを標準化してください"

Codex CLIは関連するすべてのAPIハンドラファイルを検出し、一貫したパターンに書き換えます。

# データベーススキーマの変更に伴う全ファイル更新
codex "usersテーブルにprofile_image_urlカラム（VARCHAR(500), nullable）を追加し、関連するモデル、DTO、バリデーション、APIレスポンスをすべて更新してください"

変更提案のレビューと適用フロー

suggestモードを使えば、変更内容をdiff形式で確認してから適用できます。

# suggestモードで変更をプレビュー
codex --approval-mode suggest "全コンポーネントのpropsにデフォルト値を設定して"

表示されるdiffを確認し、問題なければyで適用、修正が必要ならnで却下します。SES現場では、必ずsuggestモードでレビューしてから適用する運用がおすすめです。

ワークスペース管理のベストプラクティス

プロジェクト構造の認識と最適化

Codex CLIはディレクトリ構造を自動認識しますが、効率的に動作させるためのポイントがあります。

AGENTS.mdでプロジェクト構造を明示

# プロジェクト構造
- src/api/ — APIルートハンドラ
- src/models/ — データモデル（Prisma）
- src/middleware/ — Express ミドルウェア
- src/utils/ — ユーティリティ関数
- tests/ — テストファイル（Jest）

この情報があることで、Codex CLIは関連ファイルを高速に特定できます。

.codexignoreによるスコープ制御

.codexignore（.gitignoreと同じ構文）で、Codex CLIが読み取る範囲を制御できます。

# 生成されたファイルを除外
dist/
build/
node_modules/

# 大きなデータファイルを除外
*.csv
*.sql

# 機密設定を除外
.env*
secrets/

SES現場では、クライアント固有の設定ファイルや本番環境のシークレットを確実に除外することが重要です。

マルチエージェント並列実行

独立Git Worktreeで競合回避

大規模プロジェクトでは、複数のCodex CLIインスタンスを並列実行して作業時間を短縮できます。ただし、同じディレクトリで複数エージェントを走らせるとファイル競合が発生します。

Git Worktreeを使った並列実行

# メインブランチから作業用ワークツリーを作成
git worktree add ../project-agent1 -b feature/auth-refactor
git worktree add ../project-agent2 -b feature/api-optimization

# 各ワークツリーで独立したCodex CLIを実行
cd ../project-agent1 && codex "認証モジュールをリファクタリングして" &
cd ../project-agent2 && codex "APIレスポンスのパフォーマンスを最適化して" &
wait

# 完了後にメインブランチにマージ
cd ../project
git merge feature/auth-refactor
git merge feature/api-optimization

大規模リファクタリングへの応用

SES案件でのレガシーコード刷新など、大規模リファクタリングでの活用例です。

フェーズ1: 分析 — codex "このプロジェクトのコード品質レポートを作成して"
フェーズ2: 分割 — 改善タスクを独立したブランチに分割
フェーズ3: 並列実行 — 各ブランチでCodex CLIを並列実行
フェーズ4: 統合 — 結果をレビューしてメインにマージ

この手法により、従来なら数日かかるリファクタリングを数時間に短縮できます。

Claude Code / Gemini CLIとの比較

マルチファイル対応の観点での比較です。

機能	Codex CLI	Claude Code	Gemini CLI
ファイル横断編集	◎	◎	○
変更プレビュー	◎（diff表示）	○	○
並列エージェント	◎（Worktree）	○	△
スコープ制御	◎（.codexignore）	○（CLAUDE.md）	△
自動テスト連携	○	◎	△