Lesson 12 · 協調

複数の agent が同じツリーを取り合わないようにする

「Isolate by directory, coordinate by task ID.」二つの平面が互いに干渉しない。

⏱ 約 10 分 · 📝 3 つのインタラクティブ要素 · 🧑‍💻 出典 shareAI-lab · s12_worktree_task_isolation.py

並列 agent の一つの難題

s09〜s11 で複数の teammate を同時起動できるようになったが、一つ落とし穴がある:全員が同じ作業ディレクトリにいる。alice が auth.py を編集し、bob も同時に auth.py を編集する——git コンフリクト、ファイルの混乱、テストの相互汚染が起きる。

s12 の解決策は git worktree:同じリポジトリに対して git worktree add を使い、異なるディレクトリに異なるブランチを checkout できる。各 agent は自分の worktree を持ち、自分のディレクトリで作業し、互いに見えない。

my-repo/                           # メイン作業ディレクトリ(lead が使用)
.worktrees/
  alice-auth/                      # alice の隔離ディレクトリ
    (branch: wt/alice-auth)
  bob-api/                         # bob の隔離ディレクトリ
    (branch: wt/bob-api)
  index.json                       # worktree レジストリ
  events.jsonl                     # ライフサイクルイベントログ

二平面の役割分担

s12 ではシステムを明示的に二つの平面に分ける:

  • 制御面 (control plane).tasks/ 内の JSON ファイル。タスクは「何をするか」の抽象単位で、依存関係・owner・status を持つ。
  • 実行面 (execution plane).worktrees/ 内のディレクトリ。worktree は「どこでするか」の物理コンテナで、ディレクトリ一つ+ブランチ一つ。

両者は task.worktreeworktree.task_id によって双方向にバインドされる。

この疎結合により次のことが可能になる:タスク管理の仕組みを再利用しつつ実行環境を切り替える(例:git worktree の代わりに Docker コンテナ)。あるいは実行環境を再利用しつつタスクの仕組みを切り替える(例:JSON ファイルの代わりにデータベース)。

ライフサイクルデモ

create task → create worktree → run commands → keep または remove まで完全に流す。各ステップにはイベントログevents.jsonl)が記録され、本番環境ではオブザーバビリティに活用できる。

keep vs remove

worktree が役目を終えたとき、二つの終局がある:

  • remove: git worktree remove --force でディレクトリを削除する。ブランチも通常一緒に削除される。「この試みは不要」に相当する。
  • keep: .worktrees/index.jsonstatus: kept を記すだけで、物理ディレクトリは保持する。「この結果は使いたい、マージを待つ」に相当する。

よくあるパターン:subagent が実験的なリファクタリングを実行 → 結果が良好 → keep → 人間がレビュー → メインブランチにマージ → 手動で remove。結果が悪ければ?そのまま remove して破棄する。

Interactive

Widget 1 · Lifecycle · create task から keep/remove まで

ステップごとに 5 つのイベントをトリガーする。左でディスク状態(.tasks/ + .worktrees/)、右でイベントログ(events.jsonl)を確認できる。

ディスク状態
events.jsonl(追記専用)
Interactive

Widget 2 · Parallel Lanes · 3 つの agent が 3 つの worktree で並列実行

alice / bob / charlie が異なる worktree で同じファイルを同時に変更する。互いに見えるのか?コンフリクトは起きるのか?

📂 .worktrees/alice/
📂 .worktrees/bob/
📂 .worktrees/charlie/
Interactive

Widget 3 · Decision Flow · 各ステップで次の選択

本番環境で agent が worktree 内の作業を完了したとき、keep すべきか remove すべきか?5 つのシナリオ。

正解 0 / 5