Codexのworktreeとは？複数のコーディング作業を分ける方法と注意点

要約： worktreeを使うと同じGitプロジェクトの作業フォルダーを分け、複数の変更を進められます。フォルダーが分かれても、結果を統合するときは変更内容と検証を再確認する必要があります。

1. worktreeを理解する簡単な例

メモアプリで自分は画面の色を変更し、Codexには検索機能を修正させたいとします。両者が同じフォルダーを変更すると、誰の変更か区別しにくくなります。worktreeはこの状況で各作業が別のフォルダーを使うための方法です。

OpenAIの公式文書はworktreeをGitリポジトリの別のチェックアウトとし、ファイルコピーは別に置き、コミットやブランチなどのGit情報を共有すると説明します。Codexでは同じプロジェクトの独立作業の並列実行に使えます。単なるフォルダーコピーとGitが作業フォルダーを管理する方式は区別する必要があります。

2. ブランチとフォルダーの違いから理解する

ブランチはGit履歴で作業の継続地点を分け、worktreeは実際の編集場所を分離します。初回は「今見ているフォルダーはどの作業のコードか」の確認が重要です。同じファイル名でも別の作業フォルダーなら内容が異なる場合があります。

架空のメモアプリで主フォルダーは色変更、別のworktreeは検索修正と定めたら、ブラウザーがどのフォルダーの開発サーバーを表示するかも記録してください。画面が変わらないからと再修正する前に、実行サーバーが修正フォルダーを指すか確認できます。これはAIツールに関係なく複数のチェックアウトで必要な習慣です。

3. 分ける作業の境界を先に定める

フォルダーを分けただけで責任範囲は決まりません。検索修正と色変更が同じコンポーネントを大きく変えれば統合時の調整が必要です。独立性の高い作業から分け、共通修正があれば互いの要求を先に整理してください。

검색 결과가 없을 때 안내 문구를 표시하는 수정만 진행해 주세요.
작업은 별도 worktree에서 진행하고 시작 기준을 알려 주세요.
주 작업 폴더에서는 색상 변경을 진행 중입니다.
공통 스타일과 다른 작업자의 변경은 덮어쓰지 마세요.
완료 후 변경 파일, 관련 검증 결과, 합칠 때 확인할 점을 정리해 주세요.

これは特定ボタンのUI説明ではなく、作業境界を伝える依頼例です。アプリでworktreeを使えるか、どの基準から作られるかは実際の生成結果と現在の公式案内で確認してください。未保存の変更が別フォルダーにも自動で現れると仮定しない方がよいでしょう。

4. 生成直後と統合直前に確認する

生成直後は作業パス、開始したGit状態、必要な開発環境を確認します。新フォルダーにソースがあってもパッケージとローカル設定まで全て準備済みとは断定できません。環境ファイルが必要なら内容を会話に貼るより、プロジェクトの安全な設定方法に従ってください。

統合前に変更ファイルの差分を読みます。検索変更が色変更と同じ行に触れるか、公開関数の形式が変わるか、意図しない生成ファイルが含まれるか確認してください。各作業の検証は有用ですが、両変更を適用した状態でも必要確認を行います。各々が正常でも組み合わせで問題が生じ得るためです。

5. よくある混乱と解決の確認

• 画面が変わらない： 開発サーバーの作業パスと接続URLを確認します。
• 必要コマンドが失敗する： 新フォルダーの依存関係と設定の準備を確認します。
• 変更が混ざる： 差分を見て作業ごとの責任と共通修正を整理し直します。
• フォルダーの整理が必要： 保存するコミットとファイルを確認し、アプリの整理手順に従います。

未使用フォルダーをすぐ削除するより結果の保存場所を確認してください。OpenAIは作業の移動と整理も案内しています。アプリ管理のworktreeなら通常フォルダーのように任意で移動するより公式の管理手順を確認する方が現在の作業を見つけやすくなります。

6. 作業フォルダーとGit状態を目で区別する

架空のmemo-appで現在のフォルダーは色変更、別フォルダーは検索修正に使うと仮定します。開始時は記憶に頼らずパスとGit状態を読みます。下は現在フォルダー、リポジトリルート、変更ファイル、接続worktreeを照会する例です。PowerShellで実行でき、実際のパスは変更する必要があります。

Get-Location
git rev-parse --show-toplevel
git branch --show-current
git rev-parse --short HEAD
git status --short
git worktree list

git worktree listは複数の作業フォルダーと接続Git状態の確認に役立ちます。同じプロジェクト名でもパスが違えば別フォルダーです。branch --show-currentが空なら名前付きブランチをチェックアウトしていない可能性があるため、Git状態も読んでください。公式アプリ文書は管理worktreeが基本的にdetached HEADで開始すると説明します。ブランチ名がないだけで生成失敗と判断しません。

記録項目	架空の作業A	架空の作業B
作業目的	画面の色調整	空の検索結果の案内
フォルダー	C:\Projects\memo-app	別worktreeの実際のパス
開始状態	現在の変更を含むか記録	選択基準と開始コミットを記録
修正責任	共通の色	検索表示の条件

開始コミットとローカル変更の包含を残す理由は、後で差分を解釈するためです。最新作業のつもりでも古い基準から始めれば検索修正以外の差が混ざって見えます。アプリで開始ブランチとローカル変更を選んだ場合は選択を記録してください。直接Gitで作るworktreeとアプリ管理の生成・整理手順を同じと仮定しないことも重要です。

7. フォルダーが分かれても共有され得る実行環境

ソースフォルダーが分かれても、実行サーバーと外部データは自動分離されません。二つのサーバーが同じポートを使うと後のサーバーが失敗したり別ポートで起動したりします。同じテストDBへ接続すれば片方のデータ変更が他方の結果に影響し得ます。worktreeの分離範囲と共有資源を分けて記録する必要があります。

1. 各フォルダーのREADMEとlockファイルを見て同じパッケージマネージャーを使います。
2. 依存関係の準備を調べ、プロジェクトのインストール手順に従います。
3. サーバー開始時の出力URLを作業名と併記します。
4. 環境変数名と接続対象を確認し、テストサービスが共有されるか把握します。
5. ブラウザーのURLを修正フォルダーのサーバーと対応づけます。

例えば色作業のサーバーを5173、検索を5174と定めたら、各URLの画面を作業記録に書きます。これは架空の配置で、全ツールがこのポートを使う意味ではありません。サーバー設定と開始出力に合わせてください。画面が変わらないときはコード追加修正前にURLとサーバー実行フォルダーを比べると速く診断できます。

새 worktree의 실행 환경을 점검해 주세요.
현재 경로, 시작 커밋, 관련 실행·검증 명령을 알려 주세요.
의존성과 필요한 설정 파일이 준비되어 있는지 확인하세요.
주 작업 폴더와 개발 서버 포트·데이터 연결이 겹칠 수 있는지 설명하세요.
환경 변수의 실제 비밀값은 출력하지 말고 이름과 준비 상태만 보고하세요.

8. Gitから除外されたローカル設定の準備方法

新フォルダーにコードがあっても実行できない一般的な理由は、Git未追跡のローカル設定がないことです。まず環境変数の例ファイルや設定案内を確認し、その手順で準備してください。元フォルダーを丸ごとコピーすると不要な依存関係・キャッシュ・ビルド成果物も移るため、必要設定を区別するとよいでしょう。

現在の公式文書は、リポジトリルートに.worktreeincludeファイルを置き、ローカル管理worktreeの作成時にコピーするignoredファイルのパスやパターンを書く機能を案内しています。対象はアプリが作ったローカル管理worktreeです。直接Gitで作ったフォルダーやリモートにも自動適用されるとは考えないでください。追跡済みソースはcheckoutに含まれるため再度コピー一覧へ入れる必要はありません。

# .worktreeinclude의 가상 예시
.env.local
config/development.local.json

上のファイル名を無条件に追加しないでください。実際にGit除外で新環境に必要か先に判断します。運用サービスの設定を開発worktreeへコピーする方式が合うかも検討する必要があります。例ファイルで準備できれば優先できます。生成時のコピー設定を変更したら、実際の生成結果で必要ファイルが準備されたか確認してください。

設定が見つからないCodexが空ファイルを勝手に作ってコマンドだけ成功させないよう、必要環境が不明なら未実行と表示し、準備手順を説明させてください。準備問題と機能欠陥を分けると不要なソース変更を減らせます。

9. 二つの変更を統合する前後の確認例

検索と色の作業が各々検証済みとします。検索は0件の案内を追加し、色は共通メッセージ色を変更しました。行の衝突がなくても統合後の文言のコントラストが不足する可能性があります。Gitが統合できることと製品動作が正しいことは別の判断です。

時点	確認内容	問題があれば
統合前	各変更の目的・ファイル・検証結果	機能と無関係な変更を先に分ける
差分比較	共通コンポーネント・スタイル・API接点	同じ条件を異なる方法で変えたか調整
統合後	正常検索と空の結果画面	組み合わせの問題を別途再現
整理前	保存する結果とローカル設定の位置	不足ファイルを確保してから整理

검색 수정과 색상 변경을 함께 적용한 상태를 검토해 주세요.
각각의 의도는 유지하고 공통 메시지 표시 부분을 확인하세요.
정상 결과·결과 0개·로딩·오류 상태를 구분해 검증하세요.
충돌 해결 과정에서 빠진 기능과 관련 없는 변경이 있는지 살펴보세요.
개별 작업에서 통과한 검사와 조합 상태에서 실행한 검사를 나누어 보고하세요.

アプリでworktreeの作業をLocalへ移す際は公式Hand offを使えます。別checkoutで続けるための移動であり、独立二作業の変更が意図通り統合されたかの確認を代替しません。現在のローカル変更があれば状態を把握して移動結果を読んでください。管理worktreeはアプリの保存・復元の流れを使うと作業記録とフォルダーの接続を維持しやすくなります。

10. よくある質問

Gitを使わなくてもよいですか？ この記事のworktreeはGitリポジトリを前提とします。通常のプロジェクトフォルダーを分けることと同機能と考えないでください。

worktreeで衝突はなくなりますか？ 編集フォルダーは分かれますが同じコードの変更の統合には衝突や意味の調整が必要な場合があります。

必ず複数の作業を分ける方がよいですか？ 独立した作業に有用です。非常に小さな修正なら新環境の準備と整理の負担も考慮してください。作業数より各結果を理解・検証できるかが重要です。

公式の出典と確認日： OpenAI公式文書：ワークツリー。2026年10月3日確認。コマンドと機能は現在の環境・権限を確認して使ってください。