Codexで複数フォルダを1つのローカルプロジェクトにまとめるときは、普段のGit操作と指示ファイルを置くリポジトリをprimary folderにします。secondary folderも読み取り・編集・検索の対象になりますが、新規チャットの基準、Git操作、AGENTS.md・skills・config.tomlの探索はprimaryが基準です。
この機能は、フロントエンドとAPI、アプリと共通ライブラリ、テーマと設計資料のように、別フォルダだが同じ成果物を作る構成に向きます。同じリポジトリの並列作業を分けるWorktreeとは目的が異なります。
情報確認日：2026年7月27日（日本時間）
結論：primaryは作業の司令塔、secondaryは関連資料・依存コードとして追加する
この記事の結論
- commitやdiffを主に確認するリポジトリをprimaryにする
- AGENTS.md、skills、config.tomlはprimary側を基準に整える
- secondaryで変更を許可する範囲も依頼文に明記する
- 無関係なフォルダや秘密情報を含む場所は追加しない
- 同一Gitリポジトリの並列作業にはWorktreeを使い分ける
複数フォルダ・ローカルプロジェクトとは
Codexデスクトップアプリのローカルプロジェクトに、関連する複数のフォルダを登録する機能です。2026年7月23日の公式更新では、プロジェクトの編集画面からフォルダを追加し、1つをprimaryとして選択できるようになりました。
| 項目 | primary folder | secondary folder |
|---|---|---|
| 新規チャットの基準 | 基準になる | 関連フォルダとして参照 |
| Git操作 | 基準になる | 編集前に範囲を明示 |
| AGENTS.md・skills・config | 探索の基準 | 必要なら個別に参照を指示 |
| 読み取り・編集・検索 | 可能 | 可能 |
複数フォルダを追加する手順
- Codexデスクトップアプリでローカルプロジェクトを開く
- プロジェクトの編集画面を開く
- 関連するフォルダを追加する
- 作業の中心になるフォルダをprimaryに設定する
- 新しいチャットで各フォルダの役割と変更範囲を伝える
既存チャットは開始時の前提を持っている可能性があるため、フォルダ構成を変えた後は新しいチャットを開始すると役割が明確です。
primary folderの決め方
Gitの成果を残す場所で決める
通常の差分確認、テスト、commit候補の中心になるリポジトリをprimaryにします。たとえばWebアプリがAPI SDKを参照する構成で、今回の成果がWebアプリのUIならWeb側がprimaryです。
作業ルールを持つ場所で決める
Codexが守るテスト手順、編集禁止領域、コーディング規約を記したAGENTS.mdがあるフォルダを優先します。「AGENTS.mdの書き方」を参考に、複数リポジトリを扱う際の境界も明文化しておくと安定します。
実行環境の起点で決める
Docker Compose、package.json、Makefileなど、検証コマンドの起点になる場所をprimaryにすると、Codexがコマンドの実行場所を誤りにくくなります。
構成例1：フロントエンドとAPI
workspace/
├─ web-app/ ← primary
├─ api-server/ ← secondary
└─ api-contracts/ ← secondaryUIの実装が目的ならweb-appをprimaryにします。APIサーバーは仕様確認のために読み取り、変更が必要になったときだけ明示的に許可します。
web-appをprimaryとして、注文一覧のUIを修正してください。
api-serverとapi-contractsは仕様確認のため読み取り可能です。
secondary folderは変更せず、API変更が必要なら実装を止めて理由を報告してください。構成例2：アプリと共通コンポーネント
products/
├─ customer-app/ ← primary
└─ ui-library/ ← secondarycustomer-appの不具合がui-libraryに由来する場合、2リポジトリへ変更が広がる可能性があります。最初から「両方変更してよい」とせず、再現確認後に変更案と影響範囲を出してもらいます。
構成例3：WordPressテーマと仕様書
client-site/
├─ wordpress-theme/ ← primary
└─ design-spec/ ← secondaryテーマをprimary、画像や文書を含む仕様フォルダをsecondaryにします。仕様書は参照専用と明記し、WordPress本体、uploads、秘密情報を含むディレクトリは登録しません。
複数フォルダとWorktreeの違い
| 目的 | 使う機能 |
|---|---|
| 別リポジトリを横断して調査・実装する | 複数フォルダ・ローカルプロジェクト |
| 同じGitリポジトリの独立タスクを並列化する | Worktree |
| ルールや禁止事項をプロジェクトに伝える | AGENTS.md |
| 実行許可やネットワーク境界を管理する | Sandbox・approval設定 |
Worktreeの分離方法は「Codex Worktreeの使い方」、権限境界は「CodexのSandboxと承認設定」で確認できます。
安全に使うためのチェックリスト
- 追加する各フォルダの所有者と用途を確認した
- 秘密鍵、環境変数、顧客データを含むフォルダを除外した
- primaryを変更成果とGit操作の中心にした
- secondaryごとに「参照のみ」「変更可」を決めた
- 各リポジトリのテストコマンドを区別した
- 複数リポジトリの変更を一括commitしない運用にした
- pushやdeployの対象と影響を実行前に確認した
フォルダを追加できることと、変更してよいことは同じではありません。依頼文でリポジトリ単位の権限を狭く指定してください。
よくある質問
secondary folderもCodexが編集できますか？
公式案内では読み取り・編集・検索が可能です。ただし実際の権限設定と依頼範囲に従うため、参照専用にしたい場合は明記してください。
primary folderは後から変更できますか？
プロジェクト編集で構成を見直せます。変更後は新しいチャットで、各フォルダの役割を再提示するのが安全です。
モノレポでも複数フォルダを追加すべきですか？
1つのGitルートで完結するモノレポは、通常そのルートだけで十分です。別管理の資料や依存リポジトリが必要な場合に追加します。
複数フォルダを1回のcommitにできますか？
別Gitリポジトリならcommit履歴も別です。各リポジトリで差分・テスト・commitを分け、依存順を記録します。
まとめ
Codexの複数フォルダ・ローカルプロジェクトでは、Git操作と指示の基準になる場所をprimaryにし、secondaryは関連コードや仕様のために追加します。変更可能範囲はフォルダごとに伝え、無関係なディレクトリを含めないことが重要です。同じリポジトリの並列化はWorktreeへ分けると、目的が混ざりません。