worktree

Worktree

デフォルトでは、リンクされた worktree による隔離を使用してください。 複数のセッションが同時に実行されることはよくあります。セットアップに約30秒かかりますが、何時間にも及ぶマージのトラブルを防げます。

有効なワークスペースの定義

• 重要な作業や自律的な作業で有効：Skill(worktree) create で作成したリンクされたチェックアウト（通常は .worktrees/<name>）
• デフォルトでは無効：リポジトリルートにあるプライマリチェックアウト
• 許可される例外：対話形式で単一エージェントによる小規模な変更は、意図的に選択した場合、プライマリチェックアウトで実行できます

すべての操作には noodle worktree を使用してください。CWD の安全性、正しい手順、stash／rebase の処理、依存関係の再インストールを適切に行います。

コマンド

事前確認

noodle worktree list

マージ状況とともにすべての worktree を表示します。セッション開始時に実行し、クラッシュしたセッションから残った古い worktree がないか確認してください。

作成

noodle worktree create <name>

.worktrees/<name> に worktree とブランチを作成し、.claude/settings.local.json のシンボリックリンクを設定して、パッケージマネージャーを自動検出し、依存関係をインストールします。

worktree 内でコマンドを実行する

noodle worktree exec <name> <command...>

cmd.Dir を使って worktree 内でコマンドを実行します。親シェルの CWD は変更されません。ビルド、テスト、または worktree を CWD として必要とするツールを実行する際の安全な方法です。

# Examples
noodle worktree exec my-feature go test ./...
noodle worktree exec my-feature go build ./...

Git 操作には git -C も使用できます。exec は不要です。

git -C <project-root>/.worktrees/<name> status
git -C <project-root>/.worktrees/<name> add -A
git -C <project-root>/.worktrees/<name> commit -m "message"

ファイルの読み取りや編集には、絶対パスを直接使用します。exec は不要です。

マージ

noodle worktree merge <name>
noodle worktree merge <name> --into <branch>

1つのコマンドで、CWD の安全性確認 -> worktree 内の不要な変更を stash -> 対象ブランチに rebase -> マージ -> worktree の削除 -> ブランチの削除 -> prune -> 依存関係の再インストールを実行します。CWD が worktree 内にある場合、またはルートチェックアウトが対象ブランチにない場合は、実行を拒否します。

デフォルトの対象は統合ブランチで、origin/HEAD から自動検出します（検出に失敗した場合は main にフォールバックします）。任意のブランチにマージするには --into を使用してください。コマンドの実行時に、ルートチェックアウトがそのブランチにある必要があります。

マージするコミットがない場合は早期終了し、作業を続けるかクリーンアップを実行するかを選べるよう、worktree とブランチをそのまま残します。

マージはロックファイル（.worktrees/.merge-lock）を使って直列化されます。別のマージが進行中の場合、コマンドは短い間隔で再試行しながら待機し（デフォルトのタイムアウトは5分）、その後自動的に続行します。クラッシュしたプロセスが残した古いロックは自動検出され、クリーンアップされます。

マージ済み／パッチ相当の worktree を prune する

noodle worktree prune

安全な worktree を自動でクリーンアップします。

• 統合ブランチより先行するコミットがない、またはパッチ相当のコミットのみである
• 作業ツリーがクリーンである（コミットされていない変更がない）
• 実際の worktree ではなくなった古い .worktrees/<name> ディレクトリを削除する

マージせずにクリーンアップする

noodle worktree cleanup <name>

マージされていないコミットがある場合は警告します。それらを破棄するには --force を使用してください。

重要な安全ルール

.worktrees/ に cd してはいけません。 削除時にシェルの CWD が worktree 内にあると、シェルが完全に終了します（終了コード 1、復旧不可、セッション終了）。次の操作が該当します。

• Bash ツールの呼び出しでの cd /path/to/worktree && ...
• 副作用として CWD を変更するあらゆるコマンド

Bash ツールは永続的なシェルを維持します。ある呼び出しでの cd は、今後のすべての呼び出しに引き継がれます。そのパスに対して後から rm -rf や git worktree remove を実行すると、シェルは即座に終了します。

代わりに、必ず次のいずれかを使用してください。

1. noodle worktree exec <name> <cmd> — CWD の安全性を考慮した設計です
2. サブシェル：(cd /path && cmd) — サブシェルの終了時に CWD がリセットされます
3. 絶対パス：go build /path/to/pkg/...
4. ツールのフラグ：git -C <path>、go -C <path>

並列エージェントチーム

1. リードがチームメイトごとにワークツリーを作成します：noodle worktree create phase-1
2. 各エージェントを mode: "acceptEdits" で起動します。ワークツリーは分離されたスクラッチ領域です
3. 各チームメイトはそれぞれのブランチでコミットします
4. リードがそれぞれをマージします：noodle worktree merge phase-1

サブエージェントの階層：自身のワークツリー（ブランチ lead-work）で作業するリードエージェントは、それぞれ独自のワークツリーを持つサブエージェントを起動できます。サブエージェントは main ではなく、リードのブランチにマージします：

# Root checkout must be on the target branch
git checkout lead-work
noodle worktree merge sub-work --into lead-work

基盤となる変更：後続フェーズで必要となる基盤を Phase 1 で構築する場合は、まず main で作業してコミットし、その後、並列ワークツリーを作成します。ブランチは作成時点のコミットから開始します。

使用しないケース：逐次的なタスク、読み取り専用の調査、並行作業によるリスクがない単一エージェントでの作業。

規約

• ディレクトリ：プロジェクトルートの .worktrees/（gitignore 対象）
• 命名：.worktrees/<branch-name>
• ブランチは一時的なものです — 作業が終わったら main にマージして削除します
• Brain vault は共有状態です — ブランチを作成しないでください。チームメイトは結果をリードに返します。

古いワークツリーのトリアージ

noodle worktree list で状態を確認し、次のように対応します：

1. マージ済み（「安全にクリーンアップできます」と表示） -> noodle worktree cleanup <name>
2. 未マージのコミットあり -> ユーザーに報告し、マージするか破棄するかを決めてもらいます
3. コミットなし -> セッションのクラッシュによる残骸 -> noodle worktree cleanup <name>