| name | worktree-parallel |
| description | worktree の使い分けと並列実行の運用方針。サブエージェントへの実装 fan-out、EnterWorktree / --worktree / isolation:worktree の利用、gwq への言及、複数セッション並列の相談があった時に必ず読む。ファイルを書くサブエージェントを起動する前にも読むこと。 |
worktree 運用方針
worktree の仕組みは2系統あるので混同しない。
- gwq (人間専用):
~/Work/... に永続配置。人間が複数の Claude セッションを別ターミナルで回す時だけ使う。Claude 自身は gwq を操作しない
- ハーネス worktree (Claude用):
.claude/worktrees/ に一時生成・自動掃除。claude --worktree、EnterWorktree ツール、サブエージェントの isolation: worktree がこれ
3層の使い分け
- L1 人間の並列 (複数 Claude を同時起動) → gwq。1機能=1worktree=1セッション。実用は3〜8並列 (レビュー帯域とトークンコストが上限)
- L2 セッション内並列 (1セッションが fan-out) → 探索/レビュー/調査 (読み取り専用) は cwd 共有。ファイルを書く実装サブエージェントは必ず
isolation: worktree で隔離。lead は main worktree で設計・監査・レビュー・統合を担当
- L3 通常 (単一セッション・単一ブランチ) → worktree なし
L2「常に隔離」の運用条件 (守らないと壊れる)
- baseRef: 隔離 worktree は既定で origin/HEAD から分岐し lead の未コミット作業が見えない。fan-out 前に lead が commit してから並列化する (または対象 repo の settings で
worktree.baseRef: "head")
- .worktreeinclude: fresh checkout なので repo 内の
.env 等 gitignore ファイルは worktree に無い。必要な repo は .worktreeinclude (.gitignore 構文) に列挙してコピーさせる (sops 鍵は ~/Library/... にあり worktree でも生存、repo 内 .env のみ要対応)
- 統合: 各サブエージェントは自分の worktree でコミット → lead が diff を取り込む。変更を残したまま放置すると worktree が掃除されず滞留する
