3行まとめ
このテーマをもう少し広げて見るなら、AI Coding Loop Engineering入門：Plan・Implement・Test・ReviewをAgent任せにしすぎない設計 と Codex Skillsをチームで入れる前に：サードパーティSkill・MCP依存・権限を監査する も合わせて確認してください。Worktreeへ作業を逃がす前に、Plan、Implement、Test、Reviewのどこを人間が確認するかを決められる
普段の作業。
独立作業。
移動する。
残す。
片付ける。
background作業を増やす前に、最後にどこで確認するかを決めます。
- Codex Worktreesは、同じproject内で独立した作業場所を作り、Localの作業を邪魔せずにbackground作業を進めるために使います。
- Worktreeで始める前に、開始branch、setup scripts、Handoff先、branch化する条件、消す前の確認を決めます。
- 「並列にできる」だけで進めると、branch制約、未追跡file、Localでの確認漏れで後から詰まります。
この記事では、OpenAI公式のCodex app Worktrees、Features、Local environments、Permissions、AGENTS.md docsを確認し、2026年6月1日時点の情報として整理しています。Codex appのWorktrees、Handoff、Local environments、Git連携は更新され得るため、導入前に最新docsと手元のGit運用を確認してください。
この記事でわかること
任せる範囲。
開始branch。
初期化。
戻し方。
worktreeは作業場所なので、開始条件と終了条件をセットで決めます。
- Codex appでLocalとWorktreeを分ける判断軸
- Worktreeを使う前に決める開始branchと作業範囲
- HandoffでWorktreeとLocalを行き来する時の注意点
- branch化、detached HEAD、同じbranchを複数場所で使えない制約
- setup scriptsとActionsを用意する理由
- Worktreeを消す前に残すべき情報
Codex appのWorktrees docsでは、Worktreeを使うと同じprojectで複数の独立taskを並べて進められると説明されています。Git repositoryでは、automationsも専用のbackground worktreeで動き、進行中のLocal作業と衝突しにくくなります。
一方で、Worktreeは魔法の隔離箱ではありません。Git worktreeを使う以上、branch、checkout、未追跡file、依存関係、実行環境の問題が残ります。Codexに任せる作業場所を増やすほど、最後にどこで確認し、どう残し、どう片付けるかを先に決める必要があります。
Codexで定期実行を作る場合のbackground作業は、公開済み記事のCodexで定期実行を作る前に決めることでも扱っています。この記事では、Worktreeそのものの運用に絞ります。
前提知識
| 項目 | 内容 | 見方 |
|---|---|---|
| Worktrees | 並列作業。 | |
| Features | app全体。 | |
| Local env | setup。 | |
| Permissions | 権限。 | |
| AGENTS.md | repo指示。 |
Worktreeだけでなく、setupと権限も一緒に見ます。
OpenAI公式のWorktrees docsでは、Codex appのWorktreeはGit repositoryで動くと説明されています。Git worktreeを使うため、repositoryの別checkoutを作り、複数branchや複数taskを並列に扱える仕組みです。
Features docsでは、Codex appが複数projectやthreadを扱い、built-in worktree supportを持つdesktop体験として説明されています。新しいthreadではLocalかWorktreeを選び、Localは普段のprojectで直接作業し、Worktreeは変更を通常projectから分離します。
Local environments docsでは、worktreeのためのsetup stepsやprojectのActionsを設定できることが説明されています。WorktreeはLocalと別directoryで動くため、依存関係やbuild済みfileが足りない場合があります。setup scriptsは、新しいworktree作成時に自動で走る初期化として使えます。
公式情報で確認する範囲
| 確認先 | 見ること |
|---|---|
| Codex app Worktrees | Worktree、Handoff、branch、削除後の扱い |
| Codex app Features | Local/Worktreeの位置づけ |
| Local environments | setup scripts、Actions |
| Permissions | filesystem、network、profile |
| AGENTS.md | repo固有の作業指示 |
注意点
この記事は、Git worktreeそのものの詳しい解説ではありません。Codex appでWorktreeを使う時に、作業を壊さないための判断を整理します。
また、WorktreeはGit repositoryで使う機能です。公式docsでは、version controlされていないprojectではautomationsがproject directoryで直接動くと説明されています。Gitがないprojectを同じ運用で扱わないようにします。
まずLocalとWorktreeを分ける
| 項目 | 内容 | 見方 |
|---|---|---|
| Local | すぐ確認。 | |
| Worktree | 独立変更。 | |
| Automations | background。 | |
| Non-git | 直接作業。 |
Git repositoryかどうかで、background作業の置き場所も変わります。
Codex appでは、新しいthreadでLocalかWorktreeを選びます。Localは普段のprojectで直接作業します。WorktreeはGit worktreeを作り、通常の作業場所から変更を分けます。
| 作業 | 向いている場所 | 理由 |
|---|---|---|
| いま開いている画面の小修正 | Local | すぐ確認しやすい |
| 大きめの調査 | Worktree | Localの差分を汚しにくい |
| 並列の実装案比較 | Worktree | 複数案を分けやすい |
| 起動中serverに触る確認 | Local | 普段の環境で見られる |
| 定期実行 | Worktree | backgroundで衝突しにくい |
Worktreeを使う理由は、Localの作業を邪魔しないことです。すでに別の修正をしている時、Codexに別taskを進めさせたいならWorktreeが向いています。
Localが向く作業
Localが向くのは、普段のIDE、dev server、database、browser、環境変数、未commitの変更と一緒に確認したい作業です。たとえばUIの見た目確認、手元のserverでしか再現しないbug、ユーザーが今触っているbranchの小修正はLocalのほうが扱いやすいです。
Localで進めるなら、Codexの変更が今の差分に混ざります。そのため、作業前に未committed changesを把握し、触ってよいfileを決めます。
Localに残すべき条件
次の条件があるなら、最初からLocalを選ぶか、Worktreeから早めにHandoffします。
| 条件 | 理由 |
|---|---|
| 1つしか起動できないserverを使う | Worktree側で再現しにくい |
| 手元のIDEで細かく読む | Handoffしたほうが自然 |
| 未追跡fileが必要 | Handoffで移らない可能性がある |
| local secretが必要 | Worktreeへ渡す範囲を絞る必要がある |
Worktreeが向く作業
Worktreeが向くのは、独立した調査、別案の実装、test追加、docs更新、Codex automationのようなbackground作業です。Localの差分を汚さずに試せるため、今の作業を止めずに進められます。
ただし、Worktreeを選ぶ時は開始branchを決めます。公式docsでは、main/master、feature branch、local changesを含むcurrent branchをbaseにできると説明されています。どの状態から始めたかを残さないと、後で差分の意味が分かりにくくなります。
Handoff前提で作業を設計する
- 1Start
Worktreeで開始。
- 2Inspect
差分を見る。
- 3Handoff
Localへ移す。
- 4Verify
普段の環境で確認。
Handoffする前提なら、Localで見る理由も最初に決めます。
Worktreeで作業を始めても、最後までWorktreeで終えるとは限りません。Codex appにはHandoffがあり、threadとcodeをWorktreeとLocalの間で移せます。
| 移動 | 使う場面 |
|---|---|
| WorktreeからLocal | 普段のIDE、server、手動QAで確認したい |
| LocalからWorktree | foregroundを空けてbackground作業に戻したい |
| Worktreeのままbranch化 | そのままcommit、push、PRへ進めたい |
Handoffを後から考えるのではなく、開始時に「最後はどこで確認するか」を決めます。Worktreeで完結するなら、setup scriptsとActionsを整えます。Localで確認するなら、Handoffする条件を決めます。
WorktreeからLocalへ戻す
WorktreeでCodexが差分を作った後、普段のIDEや既存dev serverで確認したい場合はLocalへHandoffします。公式docsでは、HandoffがGit operationsを扱い、threadとcodeを安全に移すと説明されています。
Localへ戻す前に見ることは、差分の範囲、未追跡file、test結果、branch状態です。特に .gitignore 対象のfileはHandoffで移らないため、生成物、local config、cache、sample dataを前提にしないほうが安全です。
LocalからWorktreeへ逃がす
Localで始めた作業を、後からWorktreeへ移すこともできます。これは、Codexに続きの作業をbackgroundで進めさせ、自分はLocalのforegroundへ戻りたい時に便利です。
ただし、LocalからWorktreeへ逃がす前に、いまのLocal差分をどこまで持っていくかを確認します。未整理の変更をそのまま渡すと、Worktree側の結果をreviewしにくくなります。
branch化とdetached HEADを理解する
初期状態。
残す時。
同じbranch不可。
pushして開く。
同じbranchをLocalとWorktreeで同時に使わない設計にします。
公式docsでは、Codexが作るworktreeは既定でdetached HEADの状態になると説明されています。これは、複数worktreeを作ってもbranchを汚しにくくするためです。
Worktree上の作業を残したいなら、Create branch hereでbranch化します。その後、commit、push、GitHub PRへ進めます。
| 状態 | 意味 | 判断 |
|---|---|---|
| detached HEAD | branchに紐づかない作業状態 | 試作や一時作業に向く |
| branch作成 | 作業を名前付きで残す | PRや共有へ進む |
| LocalへHandoff | 普段のcheckoutで続ける | 手動確認に向く |
| 破棄 | 作業を残さない | 明確に不要な時だけ |
branchを作るタイミング
branchを作るのは、差分を残す価値が見えた時です。最初からbranchを増やすより、Worktreeで試し、採用するものだけbranch化するほうがbranch一覧が散らかりにくくなります。
ただし、複数人で確認する、PRを作る、CIを走らせる、後で戻る必要があるなら、早めにbranch化します。名前を付けた瞬間に、作業の責任とreview経路がはっきりします。
branch化前の確認項目
branchを作る前に、次を確認します。
| 項目 | 見ること |
|---|---|
| 差分 | 依頼範囲を超えていないか |
| test | 最低限の確認が通っているか |
| base | どのbranchから始めたか |
| secrets | local fileが混ざっていないか |
| generated | 不要な生成物が入っていないか |
同じbranchを複数場所で使わない
Gitは同じbranchを複数worktreeで同時にcheckoutできません。公式docsでも、worktree上でbranchを作った後、そのbranchをLocal checkoutで使おうとするとエラーになる例が説明されています。
この制約を避けるには、Localで確認したい時にHandoffを使います。WorktreeとLocalで同じbranchを無理に共有するのではなく、threadごと移すほうが分かりやすいです。
setup scriptsとActionsを用意する
| 項目 | 内容 | 見方 |
|---|---|---|
| Install | 依存を入れる。 | |
| Build | 初期確認。 | |
| Test | 共通task。 | |
| Run | 起動command。 |
Worktreeで検証するなら、初期化と確認commandをproject設定へ寄せます。
WorktreeはLocalとは別directoryで動きます。そのため、依存関係、build結果、local生成物、環境設定が揃っていないことがあります。Local environmentsのsetup scriptsは、この差を埋めるために使えます。
| 準備 | 例 | 目的 |
|---|---|---|
| install | package install | 依存関係を揃える |
| build | initial build | 生成物や型を確認する |
| test | unit test | 最低限の動作確認 |
| run | dev server | 手動確認の入口 |
| docs | README確認 | setup手順を残す |
worktreeの初期化
setup scriptsには、新しいworktreeが作られた時に必要な初期化を入れます。公式docsでは、TypeScript projectの例として依存installとbuildが挙げられています。
ただし、setup scriptsに何でも入れると遅くなります。最初は、依存install、型生成、初期buildなど、Worktreeで作業を始めるために必要なものに絞ります。
確認command
Actionsには、よく使う確認commandを入れます。test suite、build、dev server起動などです。CodexがWorktreeで作った差分を、その場で確認できるようにします。
Local environmentsの詳しい整理は、公開済み記事のCodexのLocal environmentsをチームで使う前に決めることで扱っています。Worktree運用では、setup scriptsとActionsを「background作業を検証可能にするもの」として見ます。
消す前に残すものを決める
| 項目 | 内容 | 見方 |
|---|---|---|
| Diff | 変更内容。 | |
| Branch | 残す作業。 | |
| Untracked | 未追跡。 | |
| Snapshot | 復元。 |
使い捨てにする前に、残す変更と捨てる変更を明確にします。
Worktreeは軽く作れる分、片付けも雑になりがちです。消す前に、残すものと捨てるものを分けます。
| 確認 | 見ること |
|---|---|
| diff | 採用する変更があるか |
| branch | 名前を付けて残すか |
| test log | 後で見る必要があるか |
| untracked | 未追跡fileが必要か |
| thread summary | なぜ捨てるか残すか |
公式docsでは、Codex-managed worktreeは軽量で使い捨ての性格があり、threadに紐づくと説明されています。削除後もthread履歴が残る場合があり、Codex-managed worktreeでは削除前にsnapshotを保存し、再open時に復元を提示することがあると説明されています。
snapshotと復元
snapshotがあるから何も考えなくてよい、とは考えません。復元に頼るより、採用する差分はbranchやPRへ残し、不要な差分は理由を残して捨てるほうがreviewしやすいです。
Worktreeを消す判断は、差分の価値、再現性、未確認事項で決めます。良い案だが未検証ならbranch化します。不要なら削除します。判断不能ならLocalへHandoffして人間が確認します。
未追跡file
Handoffや削除で見落としやすいのが未追跡fileです。公式docsでは、.gitignore に含まれるfileはHandoffで移らないと説明されています。
生成された画像、local config、temporary data、test artifact、database dumpなどを成果物に含めるなら、Gitで追跡するのか、別の場所に置くのか、本文やPRにどう残すのかを決めます。
導入初週の進め方
- 1日目
read-only調査。
- 2日目
小さな修正。
- 3日目
Handoff確認。
- 5日目
setup整備。
- 7日目
cleanup基準。
最初は大きな実装より、戻し方と確認方法を試します。
Worktree導入の最初の1週間は、大きな実装を並列に投げるより、戻し方と確認方法を試します。
| 日 | やること | 見ること |
|---|---|---|
| 1日目 | read-only調査をWorktreeで試す | Localを汚さないか |
| 2日目 | 小さなdocs修正を試す | diffが分かりやすいか |
| 3日目 | Handoffを試す | Localへ戻せるか |
| 5日目 | setup scriptsを整える | 初期化が足りるか |
| 7日目 | cleanup基準を決める | 何を残すか |
初週の成功条件は、作業量ではありません。Worktreeで始めた作業を、Local確認、branch化、PR、削除のどれかへ迷わず進められることです。
小さく始める例
最初に試すなら、次のような作業が扱いやすいです。
| 作業 | 理由 |
|---|---|
| READMEの古い手順を直す | 影響範囲が狭い |
| test追加だけ任せる | 差分をreviewしやすい |
| issue調査を並列で進める | Localを汚さない |
| UI文言候補を比較する | 複数案を分けやすい |
| dependency updateの調査 | 実装前にriskを見られる |
大きなrefactor、migration、deploy、secretsを扱う作業は、Worktreeに慣れてからにします。
FAQ
普段の確認。
独立作業。
残す時。
確認後。
迷ったら、どこで最終確認するかへ戻ります。
WorktreeならLocalの変更は絶対に壊れませんか？
壊れにくくなりますが、完全に考えなくてよいわけではありません。開始branch、local changes、Handoff、branch化、未追跡fileの扱いで混乱することがあります。作業場所だけでなく、戻し方まで決めます。
WorktreeのままPRまで進めてよいですか？
はい。Worktree上でCreate branch hereを使ってbranchを作り、commit、push、PRへ進める流れができます。ただし、Localで同じbranchを同時にcheckoutしようとしないようにします。
LocalへHandoffするのはどんな時ですか？
普段のIDE、既存server、local database、手動QAで確認したい時です。Worktreeで検証できるならそのまま進めてもよいですが、環境差が大きいならLocalへ戻すほうが安全です。
Worktreeを消す前に何を見ますか？
diff、branch化の必要性、test結果、未追跡file、thread summaryを見ます。採用する変更はbranchやPRへ残し、不要な変更は削除理由を残します。
AutomationsとWorktreeはどう関係しますか？
Git repositoryでは、Codex appのautomationsは専用background worktreeで動くと説明されています。定期実行やbackground作業を増やすなら、Worktreeの初期化、権限、cleanupを先に決めておくと運用しやすくなります。
次に読むなら
参照した主な情報源
- Worktrees – Codex app – OpenAI Developers
- Codex app features – OpenAI Developers
- Local environments – Codex app – OpenAI Developers
- Permissions – Codex – OpenAI Developers
- Custom instructions with AGENTS.md – Codex – OpenAI Developers
更新履歴
- 2026年6月1日
OpenAI公式Codex docsを確認して初版を作成しました。
導入時には最新のCodex app docsとGit運用を確認してください。
- 2026年6月1日: OpenAI公式Codex docsを確認し、初版を作成しました。