Superpowers Worktree Rototill 设计解析：Detect-and-Defer 如何让 Agent 技能与平台原生 Worktree 机制和平共处

Superpowers 的 using-git-worktrees 技能原本对 worktree 管理"很有主见"：固定路径 .worktrees/<branch>、固定命令 git worktree add、固定清理 git worktree remove。而 Claude Code、Codex App、Gemini CLI、Cursor 各自又提供了原生 worktree 支持。本文基于设计规格 2026-04-06-worktree-rototill-design.md（工单 PRI-974，并吞并 PRI-823 "Codex App compatibility"）详解 detect-and-defer 方案：如何用一条稳定的 git 原语检测"是否已在隔离工作区"、如何让 Agent 优先使用宿主平台的原生工具、以及如何按"谁创建谁清理"的原则归属 worktree 所有权。读完后，你既能理解这套技能体系的设计取舍，也能掌握一套可迁移到任何 Agent 框架的"能力探测—原生优先—降级兜底"工程模式。

一、问题定义：三种失效模式

Superpowers 的技能假设 Agent 运行在一个"裸"环境里，自己用 git 命令管理隔离工作区。但现实是各宿主平台（harness）已经内置了 worktree 生命周期管理，且各有各的路径与清理逻辑。设计文档将其归纳为三种失效模式：

1. 重复（Duplication）：在 Claude Code 上，技能做的正是 EnterWorktree/ExitWorktree 已经在做的事；
2. 冲突（Conflict）：在 Codex App 上，技能试图在一个已被平台管理的 worktree 内部再创建 worktree；
3. 幽灵状态（Phantom state）：技能在 .worktrees/ 下创建的 worktree 对宿主平台不可见；平台在 .claude/worktrees/ 下创建的 worktree 对技能也不可见。两边互相看不见，清理与检测全部失效。

但技能不能简单删除：对于没有原生 worktree 支持的宿主（Codex CLI、OpenCode、Copilot standalone），Superpowers 填补的是真实空白。因此设计目标是"当原生支持存在时，技能让路（get out of the way）"，而不是消失。

二、目标与非目标

目标（对应文档 Goals 一节）：

目标	说明
让位于原生 worktree 系统	宿主平台有原生工具时，技能检测并直接复用
继续为无原生支持的宿主兜底	Codex CLI、OpenCode 等场景下继续提供 git 手动创建路径
修复 finishing-a-development-branch 的三个已知 bug	#940、#999、#238
worktree 创建改为 opt-in	修复 #991（此前 subagent-driven-development 会未经同意自动创建）
平台中立化	硬编码的 CLAUDE.md 引用替换为通用表述（#1049）

非目标（Non-Goals） 同样值得学习——明确写出"这一版不做什么"，把争议项推到 Phase 4：

• 每个 worktree 的环境约定（.worktree-env.sh、端口偏移）；
• 用 PreToolUse hook 强制路径；
• 多仓库 worktree 文档；
• brainstorming 检查表的 worktree 步骤（#574 明确延期）；
• .superpowers-session.json 元数据跟踪（PR #997 的思路，v1 不需要）；
• hooks 向 worktree 内做符号链接（PR #965，独立议题）。

三、三条设计原则

3.1 检测状态，而不是检测平台（Detect state, not platform）

判断"我是否已经在一个 worktree 里"不靠嗅探环境变量去识别宿主平台，而是用 git 原语：

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

• 普通仓库检出中，GIT_DIR == GIT_COMMON；
• 在任何 linked worktree 中，GIT_DIR != GIT_COMMON。

这是一个自 git 2.5（2015 年）起就稳定的原语，对所有宿主通用，且新宿主出现时零维护成本——不需要维护一张"平台识别表"。这正是 detect-and-defer 中 "detect" 的核心。

3.2 声明式意图 + 处方式兜底（Declarative intent, prescriptive fallback）

技能描述的是目标（"确保工作发生在隔离工作区中"），而不是强制某个命令。有原生工具时让位；没有原生工具时才给出具体的 git 命令作为兜底。

文档特别记录了这条原则在 TDD 验证中的修正过程：最初 Step 1a 是抽象措辞（"You know your own toolkit"），结果 Agent 会锚定到 Step 1b 那些具体可抄的 git 命令上而忽略抽象指引，通过率只有 2/6。三处修正把它救回来（GREEN + PRESSURE 测试 50/50 通过）：

1. 显式命名工具——直接列出 EnterWorktree、WorktreeCreate、/worktree、--worktree，把"我是否有原生工具？"这个解释性问题变成"我的工具列表里有没有 EnterWorktree？"这个事实查表问题；
2. 同意桥接（consent bridge）——写明"用户对创建 worktree 的同意，就是你现在使用原生工具的授权"，直接对应 EnterWorktree 工具级护栏（"ONLY when user explicitly asks"）。由于工具描述会覆盖技能指令，技能必须把用户同意包装成工具要求的授权形式；
3. Red Flag 条目——把反模式点名："当你有原生 worktree 工具时还用 git worktree add，这是第一大错误"。

另有一个反直觉结论：把 Step 1b 拆成独立技能文件的方案被测试否决了。锚定问题靠 Step 1a 文本质量解决，而非物理隔离 git 命令——在完整 240 行技能（所有 git 命令可见）的对照测试中依然 20/20 通过。

3.3 基于来源的所有权（Provenance-based ownership）

谁创建 worktree，谁负责清理：

• 宿主平台创建的，Superpowers 不碰；
• Superpowers 通过 git 兜底创建的，Superpowers 自己清理；
• 判定启发式：worktree 位于 .worktrees/ 或 worktrees/ 之下 → Superpowers 所有；其余（.claude/worktrees/、~/.codex/worktrees/、.gemini/worktrees/、或旧版用户全局 Superpowers 路径）一律视为宿主/用户所有，只读旁观。

四、创建侧重写：using-git-worktrees 技能

对应仓库中的 skills/using-git-worktrees/SKILL.md。设计稿的完整步骤如下（Step 0、0.5、1a、1b、3、4；旧 Step 2 被 1a/1b 结构拆分取代，文档注明编号重整交由实现者选择）。

4.1 Step 0：检测既有隔离

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

三种结果：

条件	含义	动作
GIT_DIR == GIT_COMMON	普通仓库检出	进入 Step 0.5
GIT_DIR != GIT_COMMON，命名分支	已在 linked worktree 中	跳到项目设置步。报告："Already in isolated workspace at <path> on branch <name>."
GIT_DIR != GIT_COMMON，detached HEAD	外部托管的 worktree（如 Codex App 沙箱）	跳到项目设置步。报告："Already in isolated workspace at <path> (detached HEAD, externally managed)."

Step 0 不关心 worktree 是谁创建的、哪个宿主在运行——worktree 就是 worktree。

子模块护栏：GIT_DIR != GIT_COMMON 在 git 子模块内同样成立。下结论前必须先排除子模块：

# 如果这行返回一个路径，你在子模块里，不是在 worktree 里
git rev-parse --show-superproject-working-tree 2>/dev/null

若处于子模块，按 GIT_DIR == GIT_COMMON 处理（进入 Step 0.5）。这一护栏后来原样落进了技能文件（见 SKILL.md 的 Submodule guard 段）。

4.2 Step 0.5：用户同意（Consent）

仅当 Step 0 未检测到既有隔离时触发：

"Would you like me to set up an isolated worktree? This protects your current branch from changes. (y/n)"

同意则进入 Step 1；拒绝则原地工作，直接跳到项目设置步。若 Step 0 已检测到既有隔离，此步整体跳过——没意义为已存在的东西再问一遍。这直接修复了 #991（技能不再隐式创建 worktree）。

4.3 Step 1a：原生工具（首选）

用户已经要求隔离工作区（Step 0 的同意）。检查你的可用工具——你有 EnterWorktree、WorktreeCreate、/worktree 命令或 --worktree 标志吗？如果有：用户对创建 worktree 的同意就是你使用它的授权。现在使用它，然后跳到项目设置步。

使用原生工具后跳到项目设置步，不再做任何 worktree 层面的操作。理由如前：原生工具负责目录放置、分支创建与清理，绕过它会制造宿主看不见的幽灵状态。

4.4 Step 1b：Git Worktree 兜底

仅当 Step 1a 不适用时使用。

目录选择（优先级从高到低）：

1. 检查项目的 agent 指令文件（CLAUDE.md、GEMINI.md、AGENTS.md、.cursorrules 或等价物）中声明的 worktree 目录偏好；
2. 检查已存在的 .worktrees/ 或 worktrees/ 目录——两者都在则 .worktrees/ 胜出；
3. 默认使用 .worktrees/。

不弹交互式目录选择；旧版用户全局 Superpowers worktree 路径不被探测也不提供——新的手动 worktree 默认项目本地。

安全校验（仅项目本地目录）：

git check-ignore -q .worktrees 2>/dev/null

若未被 gitignore，先把目录加入 .gitignore 并提交，再继续——防止把 worktree 内容误提交进仓库。

创建：

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Hooks 感知：git worktree 不继承父仓库的 hooks 目录。设计稿要求在 1b 创建后，若主仓库有 hooks 目录则做符号链接：

if [ -d "$MAIN_ROOT/.git/hooks" ]; then
    ln -sf "$MAIN_ROOT/.git/hooks" "$path/.git/hooks"
fi

这避免 pre-commit 检查、linter 等 hooks 在 work 移入 worktree 后静默失效（思路来自 PR #965）。需要说明的是：从源码结构看，最终落地的 skills/using-git-worktrees/SKILL.md 并未包含这段 symlink 指令——它与"hooks 向 worktree 内链接"同属设计稿 Non-Goals 中 PR #965 议题的一部分，v1 实现选择了更保守的取舍。

沙箱兜底：若 git worktree add 因权限错误失败，视为受限环境（沙箱），跳过创建、在当前目录工作并继续。这一点对 Codex App 的 Seatbelt 沙箱场景尤为关键，配套的 Codex App 兼容性设计（2026-03-23-codex-app-compatibility-design.md）还专门定义了"Local thread 沙箱拒绝"的验收用例。

编号重整：设计稿保留 0、0.5、1a、1b、3、4 的编号，注明"没有 Step 2"，并给出重整建议（0 → "Step 0: Detect"，0.5 并入 Step 0 流程，1a/1b → "Step 1"，3 → "Step 2"，4 → "Step 3"）。当前技能文件采用了重整后的 Step 0–3 结构。

4.5 Step 3–4：项目设置与基线测试（不变）

无论工作区由哪条路径产生（Step 0 检测到既有、1a 原生工具、1b git 兜底、甚至无 worktree），执行收敛到同两步：

• 项目设置：自动探测并执行 npm install、cargo build、pip install、go mod download 等；
• 基线测试：跑测试套件。失败则报告失败并询问是否继续。

当前技能文件 中这两步对应"Step 2: Project Setup"与"Step 3: Verify Clean Baseline"，并附统一的汇报模板（worktree 路径、测试数、就绪声明）。

五、收尾侧重写：finishing-a-development-branch 技能

对应仓库中的 skills/finishing-a-development-branch/SKILL.md。核心流程：验证测试 → 检测环境 → 呈现选项 → 执行选择 → 清理。

5.1 新增环境检测步

重新执行与创建侧 Step 0 相同的检测（GIT_DIR vs GIT_COMMON），并趁还在工作区内部时捕获 WORKTREE_PATH=$(git rev-parse --show-toplevel)——因为后续清理前会先切换目录，必须提前取值。三种状态对应不同菜单与清理策略：

状态	菜单	清理
GIT_DIR == GIT_COMMON（普通仓库）	标准选项	无 worktree 可清理
GIT_DIR != GIT_COMMON，命名分支	标准选项	按来源归属清理（provenance）
GIT_DIR != GIT_COMMON，detached HEAD	缩减菜单：推为新分支 + PR、保持原样、丢弃	无合并选项（detached HEAD 无法直接合并）

5.2 选项与执行顺序（三个 bug 修复的关键）

选项 1（本地合并）：

# 取主仓库根以保证 CWD 安全（Bug #238 修复）
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先合并，验证成功之后再移除任何东西
git checkout <base-branch>
git pull
git merge <feature-branch>
<run tests>

# 仅在合并成功后：先移除 worktree，再删除分支（Bug #999 修复）
git worktree remove "$WORKTREE_PATH"  # 仅在 superpowers 拥有它时
git branch -d <feature-branch>

顺序至关重要：merge → verify → remove worktree → delete branch。旧技能先删分支再删 worktree，会失败（worktree 仍引用该分支）；而"先删 worktree"的朴素修法同样错误——若合并随后失败，工作目录已消失、变更丢失。

选项 2（创建 PR）：推分支、创建 PR，不清理 worktree——用户后续要在其中迭代 PR 反馈。（Bug #940 修复：删除矛盾的"Then: Cleanup worktree"文案。）

选项 3（保持原样）：无动作。

选项 4（丢弃，设计稿版本）：要求键入 discard 确认，然后移除 worktree（若 superpowers 拥有）、强删分支。

清理步（Step 5，设计稿编号）：

if GIT_DIR == GIT_COMMON:
    # 普通仓库，无 worktree 可清理
    done

if worktree path 位于 .worktrees/ 或 worktrees/ 之下:
    # Superpowers 创建的——我们拥有清理权
    cd 到主仓库根        # Bug #238 修复
    git worktree remove <path>
else:
    # 宿主创建的——不碰
    # 若平台提供工作区退出工具则使用它
    # 否则把 worktree 原样留在原地

清理只在选项 1 和 4 后执行；选项 2 和 3 永远保留 worktree（Bug #940 修复）。

陈旧 worktree 修剪：任何 git worktree remove 之后执行 git worktree prune 作为自愈步骤。worktree 目录可能被带外删除（宿主清理、手工 rm、.claude/ 清理），留下陈旧注册项并造成莫名其妙的报错。一行命令，防止静默腐烂（思路来自 PR #1072）。

实现落地差异：从源码结构看，最终 finishing-a-development-branch 技能 做了两处演进——标准菜单从 4 项收缩为 3 项，"Discard"不再作为主动菜单项，改为仅当用户明确要求丢弃时才走的确认路径（需键入 discard）；清理步重编号为 Step 6，且 git worktree prune 与 git worktree remove 写在同一代码块中。这属于规格之后的指令风格重设计，核心语义（来源归属、顺序约束、CWD 守卫）与本文所述一致。

六、集成更新与平台中立化

• subagent-driven-development 与 executing-plans：两者此前把 using-git-worktrees 列为 REQUIRED（"Set up isolated workspace before starting"）。设计稿要求改为：

  using-git-worktrees — Ensures isolated workspace (creates one or verifies existing)

  因为同意（Step 0.5）与检测（Step 0）已内聚进技能本身，调用方无需再设门控或提问。对照当前仓库可确认该措辞已落地：executing-plans 与 subagent-driven-development 均写"use superpowers:using-git-worktrees to create one or verify the existing one"。

• writing-plans：删除过时声明"应在专用 worktree 中运行（由 brainstorming 技能创建）"——brainstorming 是设计技能，不创建 worktree；worktree 的询问发生在执行期，由 using-git-worktrees 负责。当前 writing-plans 的表述已改为"若工作在隔离 worktree 中，它应在执行期通过 superpowers:using-git-worktrees 技能创建"。

• 平台中立引用：所有 worktree 相关技能中硬编码的 CLAUDE.md 替换为"your project's agent instruction file (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent)"，应用于 Step 1b 的目录偏好检查。

七、捆绑的 Bug 修复与 Issue 清单

Bug	问题	修复	位置
#940	选项 2 的文案说"Then: Cleanup worktree (Step 5)"，但快速参考说保留；Step 5 说"选项 1、2、4"，Common Mistakes 又说"仅选项 1 和 4"	从选项 2 移除清理；Step 5 仅适用于选项 1 和 4	finishing SKILL.md
#999	选项 1 先删分支再删 worktree；worktree 仍引用分支时 git branch -d 会失败	重排为：merge → 验证测试 → 移除 worktree → 删分支；合并成功前不删除任何东西	finishing SKILL.md
#238	CWD 位于被移除的 worktree 内部时，git worktree remove 静默失败	加 CWD 守卫：git worktree remove 前 cd 到主仓库根	finishing SKILL.md

文档还给出完整的 Issue 解决矩阵：#940、#999、#238 为直接修复；#991 由 Step 0.5 的 opt-in 同意解决；#918 由创建侧 Step 0 检测 + 收尾侧环境检测解决；#1009 依赖 Step 1a 生效（Agent 改用原生工具、worktree 落在宿主原生路径）；#1049 由平台中立引用解决；#279 由 detect-and-defer 本身解决（不覆盖原生路径）；#574 明确延期——本规格不触碰 bug 所在的 brainstorming 技能，完整修复（给 brainstorming 检查表加 worktree 步骤）属于 Phase 4。

八、风险与跨平台验证

8.1 Step 1a 是承重假设——已解决

"Agent 在有原生工具时选择原生工具而非 git 兜底"是整个设计的地基；若 Agent 无视 Step 1a，detect-and-defer 全面失效。文档如实记录了这个风险在实现中真实发生过：抽象版 Step 1a 在 Claude Code 上 2/6 通过，TDD 门禁按设计在改动任何技能文件之前拦下了这次失败（避免了坏版本发布）。经三轮 REFACTOR 定位根因（Agent 锚定具体命令、工具描述护栏覆盖技能指令），最终 GREEN + PRESSURE 共 50/50 通过。

仓库中的配套证据：实现计划 2026-04-06-worktree-rototill.md 把"Task 1: GATE — TDD Validation of Step 1a"设为第一道闸门——"若 GREEN 阶段在 2 次 REFACTOR 迭代后仍失败，STOP，不要进入 Task 2"；行为测试脚本 tests/claude-code/test-worktree-native-preference.sh 实现了 RED / GREEN / PRESSURE 三阶段：RED 断言旧技能下 Agent 使用 git worktree add；GREEN 断言新技能下 Agent 输出含 EnterWorktree 且不含 git worktree add；PRESSURE 阶段注入多重压力（"Production is down""Do NOT ask questions — just act"、已存在且已 gitignore 的 .worktrees/ 目录）验证原生工具偏好在压力下不退化。发布说明 RELEASE-NOTES.md 亦确认该重写"经 TDD 验证并跨五个 harness 完成交叉平台检查（PRI-974, PR #1121）"。

8.2 各宿主 worktree 模型对照表

截至设计日期（2026-04-06），Claude Code 是唯一提供会话中可调用（agent-callable）worktree 工具的宿主；其余宿主要么在 Agent 启动前创建 worktree（Codex App、Gemini CLI、Cursor），要么完全没有原生支持（Codex CLI、OpenCode）。Step 1a 是前向兼容的：未来宿主加入 agent-callable worktree 工具时，Agent 会把新工具名与列出的示例比对并直接使用，技能无需改动。

Harness	当前 worktree 模型	技能机制	测试结果
Claude Code	Agent 可调用的 EnterWorktree	Step 1a	50/50（GREEN + PRESSURE）
Codex CLI	无原生工具（仅 shell）	Step 1b git 兜底	6/6（codex exec）
Gemini CLI	启动期 --worktree 标志，无 Agent 工具	带标志启动走 Step 0，否则 Step 1b	Step 0: 1/1，Step 1b: 1/1（gemini -p）
Cursor Agent	用户侧 /worktree，无 Agent 工具	用户激活走 Step 0，否则 Step 1b	Step 0: 1/1，Step 1b: 1/1（cursor-agent -p）
Codex App	平台托管、detached HEAD、无 Agent 工具	Step 0 检测既有	1/1（模拟）
OpenCode	仅检测（ctx.worktree），无 Agent 工具	Step 1b git 兜底	未测试（无 CLI 访问）

残余风险：

1. 若 EnterWorktree 的工具描述变得更严格（例如"不得基于技能指令使用"），consent bridge 即失效——值得向平台方提 issue，要求工具描述兼容技能驱动的调用；
2. 未来宿主加入的工具名可能不在 Step 1a 清单里，清单需随新工具出现而更新；泛化措辞（"a worktree or workspace-isolation tool"）提供部分前向覆盖。

8.3 其他风险

• 来源启发式：".worktrees/ 或 worktrees/ = 我们所有，其余不碰"对当前所有宿主成立。若未来宿主恰好采用这些项目本地目录作为约定，会产生误判（Superpowers 尝试清理宿主 worktree）；用户手工执行 git worktree add .worktrees/experiment 时同理。两者均低风险——现有宿主都用品牌化路径——但值得记录。
• Detached HEAD 收尾：缩减菜单对 Codex App 的沙箱模型是正确的；即便用户因其他原因处于 detached HEAD，缩减菜单依然合理——不先建分支就无法从 detached HEAD 合并。

九、实现备注与后续工作

规格描述"改什么"，实现计划（2026-04-06-worktree-rototill.md）描述"怎么改"。设计稿的实现备注指出两个技能文件除核心步骤外还有若干次级章节需同步更新：

• Frontmatter（name、description）：反映 detect-and-defer 行为；
• Quick Reference 表：按新步骤结构与 bug 修复重写；
• Common Mistakes：更新或删除引用旧行为的条目（如"Skip CLAUDE.md check"已不再成立）；
• Red Flags：反映新优先级（如"Step 0 检测到既有隔离时绝不创建 worktree"）；
• Integration 段：更新技能间交叉引用。

对照当前 skills/using-git-worktrees/SKILL.md 可见这些次级章节均已重写：frontmatter description 明确"ensures an isolated workspace exists via native tools or git worktree fallback"，Quick Reference 覆盖"已在 worktree / 子模块 / 有原生工具 / 无原生工具 / 目录未被 ignore / 权限错误"等全部情形，Common Rationalizations 表把"git worktree add 更快"斥为第一大错误。

Future Work（明确不属于本规格）：

• Phase 3 余项：$TMPDIR 目录选项（#666）、缓存与环境继承的 setup 文档（#299）；
• Phase 4：PreToolUse hook 强制路径（#1040）、每 worktree 环境约定（#597）、brainstorming 检查表 worktree 步骤（#574）、多仓库文档（#710）。

十、小结：一套可复用的能力探测模式

Worktree Rototill 的价值不止于修好一个技能：它示范了 Agent 技能在多宿主生态中的通用写法——用稳定的底层原语（GIT_DIR != GIT_COMMON）检测状态而非嗅探平台；把用户同意转化为工具级授权；显式命名工具把解释题变查表题；用"谁创建谁清理"的路径启发式界定所有权边界；并在动手改任何文件之前，先为承重假设设置 TDD 行为闸门。仓库中 tests/claude-code 下的行为测试脚本与 docs/superpowers/specs、docs/superpowers/plans 下的"规格—计划"双文档配对，为这套方法提供了完整的可验证证据链。