Codex Worktreeを使うと、同じGitリポジトリの複数タスクを、別々の作業ディレクトリへ分離して進められます。ログイン画面の修正と依存更新を同時に依頼しても、未コミット差分やブランチ切り替えが衝突しにくくなります。
ただし、Worktreeが分離するのは主にGit管理下のファイルです。ポート、データベース、Docker名、キャッシュ、外部サービス、環境変数は自動で隔離されません。複数エージェントが同時に開発サーバーやマイグレーションを実行すると、別のWorktreeでも衝突する可能性があります。
この記事では、CodexアプリでWorktreeタスクを始める方法、detached HEADからブランチを作る方法、LocalへのHandoff、並列実行時のポート・DB・依存関係の分離、終了後の片付けまで解説します。
情報確認日：2026年7月11日（日本時間）
結論：コードはWorktree、共有資源はタスクごとの名前と接続先で分ける
この記事の結論
- 独立したGitタスクはWorktreeへ分ける
- 開始前に基準ブランチと未コミット差分を確認する
- 保持したい変更はWorktree内でブランチを作る
- ポート、DB、Docker Compose project、キャッシュは別途分離する
- 統合前に各Worktreeでテストし、最後に1つずつmergeする
Codex Worktreeとは？
GitのWorktreeは、1つのリポジトリから複数の作業ディレクトリを作る仕組みです。それぞれ別のブランチやコミットをチェックアウトでき、通常のgit cloneを複数作るよりGitオブジェクトを共有できます。
CodexアプリのWorktree機能は、この仕組みを使ってタスクを分離します。メインのローカル作業を残したまま、別ディレクトリでCodexへ調査や実装を任せられます。
Worktreeが向いているタスク
- 互いに依存しない2つ以上のIssue
- バグ修正とドキュメント更新を並行する
- 複数の実装案を別ブランチで試す
- 長時間のCodexタスク中に自分が別作業を続ける
- Scheduled Taskを専用の作業ディレクトリで動かす
- 大きなリファクタリングを通常開発から隔離する
Worktreeが向いていないタスク
- 同じファイルの同じ箇所を複数タスクが変更する
- タスクBがタスクAの未完成コードに依存する
- 1つのDBスキーマ変更を複数Worktreeで同時実行する
- 環境構築が重く、各ディレクトリで依存を持てない
- Git管理されていないプロジェクト
依存関係が強い仕事は並列にせず、「調査→設計→実装→検証」の順で進めた方が、統合コストを抑えられます。
CodexアプリでWorktreeを開始する
- ChatGPTデスクトップアプリのCodex画面で対象プロジェクトを開く
- 新しいタスクで実行環境として
Worktreeを選ぶ - 開始元のブランチを選ぶ
- タスクの目的、変更範囲、テスト、禁止事項を入力する
- Codexが作成したWorktreeで作業を開始する
依頼例です。
Issue #184のバグだけを修正してください。
範囲:
- apps/web/src/features/search/
- 関連するVitestテスト
しないこと:
- API仕様の変更
- 依存パッケージの追加
- 検索画面以外のリファクタリング
- push、deploy
完了条件:
- 再現テストを先に追加
- 修正後に関連テスト、typecheck、lintを実行
- 変更ファイルとテスト結果を報告開始前に確認すること
基準ブランチが最新か
古いmainから複数タスクを始めると、統合時の差分が大きくなります。作業開始前にリモート情報を取得し、チームのルールに従って最新状態を確認します。
git fetch origin
git status --short
git log --oneline --decorate -5未コミット差分がないか
Worktreeは新しい作業場所を作りますが、現在のローカル差分が自動で引き継がれるわけではありません。必要な差分はコミット、stash、パッチのいずれかで明示的に管理します。
AGENTS.mdが正しいか
Worktreeにもリポジトリ内のAGENTS.mdが含まれます。テストコマンド、変更禁止領域、環境構築が最新か確認します。
detached HEADとは？
CodexのWorktreeは、開始時にdetached HEADになる場合があります。これは、特定コミットを直接チェックアウトしていて、まだ通常のブランチ名へ紐付いていない状態です。
detached HEADでも編集やコミットはできますが、後で参照しやすくするため、保持する変更にはブランチを作ります。CodexアプリのCreate branch hereを使うか、ターミナルで作成します。
git status
git switch -c codex/fix-search-empty-stateブランチ作成前に現在のコミットと差分を確認してください。別のタスクと同じブランチ名を使わず、Issueや目的が分かる名前にします。
LocalへのHandoff
CodexアプリのHandoffを使うと、Worktreeで進めたタスクを通常のLocal作業へ引き継げます。自分のIDEで細かく修正したい場合や、ローカル専用ツールで検証したい場合に便利です。
Handoff前に次を確認します。
- Worktree内の変更がコミットまたは明確な差分として残っている
- 現在のLocal作業に未コミット差分がない
- 同じブランチを別のWorktreeが使用していない
- 必要な環境変数や依存がLocal側にもある
- Worktreeでのテスト結果を記録している
ターミナルでWorktreeを確認する
Gitのコマンドで、現在のリポジトリに紐づくWorktreeを確認できます。
git worktree list詳細を機械的に確認する場合です。
git worktree list --porcelainWorktreeの場所、HEAD、ブランチ、detached状態を確認できます。手動削除する前に、Codexアプリが管理している作業との関係を確認してください。
複数Worktreeでポートを分ける
2つのWorktreeでnpm run devを実行すると、どちらも3000番ポートを使おうとして衝突します。環境変数や起動引数でタスクごとに変更します。
# Worktree A
PORT=3101 npm run dev
# Worktree B
PORT=3102 npm run devViteの例です。
npm run dev -- --port 3101E2EテストのbaseURLも同じポートへ合わせます。固定値がコードに埋め込まれている場合は、Worktree並列実行前に環境変数化します。
データベースを分ける
Worktreeごとに同じ開発DBへマイグレーションやデータ更新を行うと、互いのテストが壊れます。
DB名を分ける
# Worktree A
DATABASE_URL=postgres://localhost/app_codex_184
# Worktree B
DATABASE_URL=postgres://localhost/app_codex_201一時DBを使う
テスト開始時にDBを作り、終了時に破棄する構成にします。並列テストではジョブIDをDB名へ含めます。
マイグレーション実行を1タスクへ限定する
同じスキーマ変更を複数Worktreeで作らせないでください。マイグレーション担当を1つに決め、他タスクはそのブランチへrebaseした後に続けます。
Docker Composeを分ける
Composeのプロジェクト名が同じだと、コンテナ名、ネットワーク、ボリュームが共有されます。-pで分けます。
# Worktree A
docker compose -p app-codex-184 up -d
# Worktree B
docker compose -p app-codex-201 up -dホスト側ポートも重複しないよう、環境変数で変更します。DBボリュームを共有するとデータが混ざるため、プロジェクト名とボリューム定義を確認してください。
node_modulesとビルドキャッシュ
Worktreeは別ディレクトリなので、通常は各Worktreeで依存を用意します。node_modulesを強引に共有すると、ブランチごとのlockfileやネイティブ依存と不整合になる場合があります。
npm ciなどlockfileに従うコマンドを使う- パッケージマネージャーのグローバルキャッシュは利用してよい
dist、.next、coverageはWorktreeごとに生成する- 共有キャッシュを使う場合はブランチやlockfileハッシュをキーに含める
環境変数と秘密情報
.envは通常Git管理外なので、新しいWorktreeへ自動で現れない場合があります。秘密をコピーするスクリプトを安易に作らず、開発用の安全な値を秘密管理ツールから注入します。
- 本番用キーをWorktreeへ配らない
- 読み取り専用または短期トークンを使う
- Worktree削除時に秘密ファイルも削除する
- Codexのログや差分へ値を出さない
- 外部サービスのテスト環境を使う
並列化してよいタスクを判断する
| 組み合わせ | 並列化 | 理由 |
|---|---|---|
| README更新 + UIバグ修正 | しやすい | 変更ファイルと検証が独立しやすい |
| API追加 + 同APIを使う画面 | 条件付き | 先に契約を固定し、モックや型を共有する必要がある |
| 同じ認証ミドルウェアの変更2件 | 避ける | 同じファイルと挙動を変更する |
| 依存更新 + 大規模リファクタ | 避ける | 差分とエラー原因を分離しにくい |
統合前の流れ
- 各Worktreeで関連テスト、Lint、型チェックを実行する
- 差分を確認し、不要な生成物や依存変更を除く
- ブランチへコミットする
- 基準ブランチの最新変更を取り込む
- 競合を解消し、再度テストする
- タスクを1つずつmergeする
- 統合後に全体の重要テストを実行する
git status --short
git diff --check
npm run lint
npm run typecheck
npm run test
git log --oneline --decorate -52つのWorktreeが個別にテスト成功しても、統合後に失敗する可能性があります。共有型、依存、ルーティング、DBスキーマなどは統合後の検証が必要です。
Scheduled TasksとWorktree
Gitリポジトリ内でCodexのScheduled Taskを実行すると、バックグラウンド用の専用Worktreeが使われる場合があります。通常作業と差分が混ざりにくい一方、次を確認してください。
- タスクがどのブランチ・コミットから始まるか
- 生成した変更をどのブランチへ残すか
- 実行環境に必要な依存と秘密があるか
- 同じ定期タスクが重複実行されないか
- 古いWorktreeやブランチをいつ削除するか
作業後にWorktreeを片付ける
Codexアプリから削除できる場合は、まずアプリ側でタスクとの関係を確認します。手動で行う場合のGitコマンドです。
git worktree list
git worktree remove /path/to/worktree
git worktree prune未コミット差分があるWorktreeを強制削除しないでください。必要な変更がブランチやパッチへ残っていることを確認します。
不要になったローカルブランチを削除する場合です。
git branch -d codex/fix-search-empty-stateよくあるトラブル
ブランチをチェックアウトできない
同じブランチが別Worktreeで使われていないか、git worktree listで確認します。
開発サーバーのポートが使われている
Worktreeごとにポートを変更し、E2EテストのbaseURLも合わせます。
DBのテストデータが互いに壊れる
DB名、スキーマ、コンテナ、テストトランザクションをタスクごとに分けます。
LocalへHandoffできない
Localの未コミット差分、同じブランチの使用、Worktreeのdetached状態を確認します。
Worktreeを削除したのに一覧へ残る
ディレクトリを手動削除した場合はgit worktree pruneで古い管理情報を整理します。
あわせて読みたい記事
よくある質問
Worktreeと別cloneの違いは？
Worktreeは同じGitリポジトリのオブジェクトを共有し、複数の作業ディレクトリを作ります。別cloneはGit管理情報も独立します。完全な隔離が必要なら別cloneやコンテナも選択肢です。
Codex WorktreeはGit以外のプロジェクトでも使えますか？
WorktreeはGitの機能を前提とします。Git管理されていないフォルダではLocal作業など別の方法を使います。
同じブランチを2つのWorktreeで開けますか？
通常、同じローカルブランチを複数Worktreeで同時にチェックアウトすることはできません。タスクごとに別ブランチを作ります。
WorktreeならDockerやDBも自動で分かれますか？
分かれません。Compose project名、ポート、DB名、ボリューム、キャッシュを別途設定してください。
並列タスクはいくつまで動かせますか？
固定の最適数はありません。CPU、メモリ、ディスク、API利用枠、テスト環境、統合コストを見ながら2〜3件から始めるのが安全です。
まとめ
Codex Worktreeは、同じリポジトリの独立タスクを別ディレクトリへ分離し、Codexと自分の作業や複数のCodexタスクが衝突するのを抑える機能です。保持する変更にはブランチを作り、統合前に各Worktreeと統合後の両方でテストします。
Worktreeだけではポート、DB、Docker、キャッシュ、秘密情報は隔離されません。タスクごとの名前・接続先・短期資格情報を用意し、独立性の低い仕事は無理に並列化しないことが重要です。