CodexのWorktreeが3分でわかる：ローカル・Git・ブランチ・PR・デプロイの使い分け

「LocalとWorktreeは何が違うの？」「ブランチを作ったら保存されたの？」「コミットしたら公開されたの？」。

Codexで仕事を始めると、似た言葉が一度に出てきます。難しいのは操作より、それぞれが何を分けているのかです。

このページでは、町のパン屋さんにたとえて、作業開始から本番公開までを一本につなげます。

町のパン屋さんで、役割の違いをつかむ

新しいパンを作る仕事で考えてみます。

最後に、採用したレシピを本店のメニューへ入れるのがMerge、実際に店頭へ並べるのがDeployです。

つまり、コミットしても、プッシュしても、Pull Requestを作っても、まだお客様には見えていません。

利用図：Codexの作業開始から本番公開まで

この図の重要点は、LocalとWorktreeは最初に選ぶ作業場所で、その後のGitの流れは同じということです。

似ている言葉を、何を分ける機能かで整理する

一番混同しやすい4組

1. LocalとSandboxは別

Localは「どのフォルダで作業するか」です。Sandboxは「その作業中にどこまで触ってよいか」です。

LocalでもWorktreeでも、Sandboxは使われます。たとえば「このプロジェクト内は編集できるが、別事業のフォルダや外部ネットワークは確認が必要」という安全枠を作れます。

2. WorktreeとBranchは別

Worktreeは実際の別フォルダです。Branchは変更履歴につける名前です。

Codexが作るWorktreeは、最初はBranchへつながっていない detached HEAD の状態になることがあります。作業を残してPushやPull Requestへ進むなら、Codex画面の「Create branch here」などでBranchを作ります。

同じBranchをLocalとWorktreeの両方で同時に開くことはできません。Gitが「どちらの作業場が正しいBranchなのか」を決められなくなるためです。

3. CommitとPushは別

Commitは自分のPC内の履歴です。Pushは、その履歴をGitHubへ送る操作です。

たとえるなら、Commitは厨房の試作ノートへ記録すること。Pushは、そのノートの写しを本部へ送ることです。

4. MergeとDeployは別

MergeはGitの履歴をmainへ採用すること。Deployは採用した成果物を実際のWeb環境へ置くことです。

VercelなどとGitHubを連携している場合は、mainへのMergeをきっかけに自動Deployされます。ただし、処理の失敗や古いキャッシュもあるため、最後は本番URLで確認します。

LocalかWorktreeかを、5問と3つの実例で決める

迷った時の標準は、小さくてきれいな作業場ならLocal、混ざりそうならWorktreeです。

状態表示は「ローカル・プレビュー・本番」の3つに分ける

「ビルド成功」「コミット済み」「Push済み」「プレビュー確認済み」は、すべて本番確認前の状態です。

完了報告では、次のように言い分けます。

• ローカル：ビルドと画面確認まで完了
• プレビュー：Pull Requestの確認用URLで動作確認済み
• 本番：Merge・Deploy後、正式URLで画面と主要機能を確認済み

実例1：案内文の誤字を1か所直す

Localに別作業の未コミット変更があるなら、誤字修正でもWorktreeへ分けたほうが安全です。変更の大きさだけでなく、今の作業場がきれいかで判断します。

実例2：トップページを別案で作り直す

別案が不採用でも、いつものLocalはそのままです。これがWorktreeの大きな利点です。

実例3：AI相談の資料を追加する

このAI相談サイトでは、GitHubの main とVercel本番がつながっています。資料追加の安全な流れは次の通りです。

最新の origin/main
  ↓
資料追加専用 Worktree
  ↓
codex/add-codex-worktree-guide Branch
  ↓
content/blog に原稿を追加
  ↓
ローカルビルド・リンク・PC/スマホ確認
  ↓
Commit → Push → Pull Request
  ↓
Preview URLで確認
  ↓ CEO承認
Merge
  ↓
VercelへProduction Deploy
  ↓
https://ai-hub-jp.vercel.app の対象ページを確認

ここで大切なのは、Pull Requestを作った時点では「公開候補」、Preview URLは「確認用」、本番URLを確認して初めて「公開完了」と言うことです。

CodexとGitの基本操作を、一本道で覚える

Codex画面での基本操作

Worktreeで始める

1. 新しいCodexタスクを作る
2. 入力欄の下で Worktree を選ぶ
3. 開始元のBranchを選ぶ。通常は最新の main
4. 作業を依頼する
5. 残す変更なら Create branch here でBranchを作る
6. 差分とテスト結果を確認する
7. Commit、Push、Pull Requestへ進む

いつものIDEや開発サーバーで確認したい時は、Hand off でWorktreeからLocalへ移します。

Localで始める

1. 最初に git status で作業中の変更を確認する
2. 今回の変更と混ざらないことを確かめる
3. 必要なら専用Branchを作る
4. 小さく変更し、差分・テスト・画面を確認する
5. Stage、Commit、Push、Pull Requestへ進む

コマンドで見るとこうなる

Codex画面だけでも操作できます。裏側を知りたい人向けの最小例です。

# 今の状態を見る
git status

# 最新のmainを開始点に、別の作業場とBranchを作る
git fetch origin main
git worktree add -b codex/new-guide C:\tmp\new-guide origin/main

# 今回の変更だけ選び、履歴に残す
git add content/blog/new-guide.md
git commit -m "docs: add Codex worktree guide"

# GitHubへ送り、Pull Requestを作る
git push -u origin codex/new-guide
gh pr create

Deployの方法はプロジェクトごとに違います。GitHubとVercelが連携していれば、BranchのPushでPreview、mainへのMergeでProduction Deployとなる構成が一般的です。

そのまま使えるCodex依頼文

安全な作業場所を選ばせる

このリポジトリのGit状態を最初に確認してください。
今回の作業と関係ない未コミット変更がある場合は、触らずに、
最新のorigin/mainを開始点とする専用Worktreeと専用Branchで進めてください。

完了時は次を分けて報告してください。
1. ローカルで確認したこと
2. プレビューで確認したこと
3. 本番で確認したこと

Commit、Push、Pull Request、Deployは同じ意味として扱わないでください。
外部公開や本番変更の前には確認を求めてください。

Pull Requestまで頼む

この変更を専用Branchで実装し、差分、テスト、PC幅、スマホ幅を確認してください。
関係ない変更は含めないでください。
確認後にCommitとPushを行い、変更内容と確認方法が分かるPull Requestを作ってください。
本番へのMergeとDeployはまだ行わないでください。

本番公開まで頼む

承認済みのPull Requestを本番へ反映してください。
Merge、Deploy、正式な本番URLでの確認まで進めてください。
完了報告には、推測ではない本番URL、確認したページまたはAPI、
未完了があれば理由と次の1手を書いてください。

勘違いを避け、人に説明して本番確認する

よくある勘違い

人に説明する60秒台本

最低限の確認リスト

• [ ] 今のLocalに、別作業の未コミット変更がないか見た
• [ ] 小さな作業はLocal、混ざりそうな作業はWorktreeにした
• [ ] 今回専用のBranch名を付けた
• [ ] Stageへ関係ない変更を入れていない
• [ ] Commitメッセージで「何を変えたか」が分かる
• [ ] Push、Pull Request、Merge、Deployを別々に確認した
• [ ] ローカル・プレビュー・本番を言い分けた
• [ ] 本番では正式URLと主要機能を実際に確認した
• [ ] 公開・課金・DB変更・外部送信は承認後に行った

公式情報

• Codex Worktrees
• Codex Sandbox
• Codex environments
• Git worktree公式ドキュメント
• GitHub: Pull Requestとは
• Vercel: Preview Deploymentの共有