Learn Claude Code
s12

Worktree + Task Isolation

协作

Isolate by Directory

695 LOC16 个工具Composable worktree lifecycle + event stream over a shared task board
机制概览

同一项研究要并行维护几个稳健性方向时，每个方向需要独立的目录与独立的 git 分支，多个 agent 同时各做各的不互相干扰。Claude Code 用 git 提供的"多目录"机制让每个稳健性版本住在独立目录里，几个 agent 同时各跑各的回归互不冲突。

本节贯穿示例
研究项目
耐心资本对企业 ESG 表现的实证项目要并行维护三个版本——pc-esg/ 主目录跑华证 ESG 0-1 连续主测度（do6 baseline 用 esg_score）、pc-esg-discrete/ 跑华证 AAA-CCC 1-9 离散评级（替换被解释变量为 esg_grade_num
在这一节里做的事

β=0.0120* 显著、规模比 0-1 版大 30 倍）、pc-esg-subscores/ 跑 E/S/G 三分项（拆解被解释变量为 e_score01/s_score01/g_score01）。三个版本核心数据相同，只是 do6_baseline.do 里 LHS 替换或拆解。

看完整机制讲解

s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]

"各干各的目录, 互不干扰" -- 任务管目标, worktree 管目录, 按 ID 绑定。

Harness 层: 目录隔离 -- 永不碰撞的并行执行通道。

问题

到 s11, Agent 已经能自主认领和完成任务。但所有任务共享一个目录。两个 Agent 同时重构不同模块 -- A 改 config.py, B 也改 config.py, 未提交的改动互相污染, 谁也没法干净回滚。

任务板管 "做什么" 但不管 "在哪做"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。

解决方案

Control plane (.tasks/)             Execution plane (.worktrees/)
+------------------+                +------------------------+
| task_1.json      |                | auth-refactor/         |
|   status: in_progress  <------>   branch: wt/auth-refactor
|   worktree: "auth-refactor"   |   task_id: 1             |
+------------------+                +------------------------+
| task_2.json      |                | ui-login/              |
|   status: pending    <------>     branch: wt/ui-login
|   worktree: "ui-login"       |   task_id: 2             |
+------------------+                +------------------------+
                                    |
                          index.json (worktree registry)
                          events.jsonl (lifecycle log)

State machines:
  Task:     pending -> in_progress -> completed
  Worktree: absent  -> active      -> removed | kept

工作原理

  1. 创建任务。 先把目标持久化。
TASKS.create("Implement auth refactor")
# -> .tasks/task_1.json  status=pending  worktree=""
  1. 创建 worktree 并绑定任务。 传入 task_id 自动将任务推进到 in_progress。
WORKTREES.create("auth-refactor", task_id=1)
# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"

绑定同时写入两侧状态:

def bind_worktree(self, task_id, worktree):
    task = self._load(task_id)
    task["worktree"] = worktree
    if task["status"] == "pending":
        task["status"] = "in_progress"
    self._save(task)
  1. 在 worktree 中执行命令。 cwd 指向隔离目录。
subprocess.run(command, shell=True, cwd=worktree_path,
               capture_output=True, text=True, timeout=300)
  1. 收尾。 两种选择:
    • worktree_keep(name) -- 保留目录供后续使用。
    • worktree_remove(name, complete_task=True) -- 删除目录, 完成绑定任务, 发出事件。一个调用搞定拆除 + 完成。
def remove(self, name, force=False, complete_task=False):
    self._run_git(["worktree", "remove", wt["path"]])
    if complete_task and wt.get("task_id") is not None:
        self.tasks.update(wt["task_id"], status="completed")
        self.tasks.unbind_worktree(wt["task_id"])
        self.events.emit("task.completed", ...)
  1. 事件流。 每个生命周期步骤写入 .worktrees/events.jsonl:
{
  "event": "worktree.remove.after",
  "task": {"id": 1, "status": "completed"},
  "worktree": {"name": "auth-refactor", "status": "removed"},
  "ts": 1730000000
}

事件类型: worktree.create.before/after/failed, worktree.remove.before/after/failed, worktree.keep, task.completed。

崩溃后从 .tasks/ + .worktrees/index.json 重建现场。会话记忆是易失的; 磁盘状态是持久的。

相对 s11 的变更

组件之前 (s11)之后 (s12)
协调任务板 (owner/status)任务板 + worktree 显式绑定
执行范围共享目录每个任务独立目录
可恢复性仅任务状态任务状态 + worktree 索引
收尾任务完成任务完成 + 显式 keep/remove
生命周期可见性隐式日志.worktrees/events.jsonl 显式事件流

试一试

cd claude-code-for-researchers
python agents/s12_worktree_task_isolation.py

试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):

  1. Create tasks for "ESG-main 0-1 primary" and "ESG-discrete 1-9 robustness", then list tasks.
  2. Create worktree "pc-esg-main" for task 1, then bind task 2 to a new worktree "pc-esg-discrete".
  3. Run "stata-mcp do do6_baseline.do" in worktree "pc-esg-main".
  4. Keep worktree "pc-esg-discrete", then list worktrees and inspect events.
  5. Remove worktree "pc-esg-main" with complete_task=true, then list tasks/worktrees/events.