workspace-isolation

工作区隔离

Git 工作树是在独立分支上的第二个工作目录，共享同一仓库的历史记录。在一个工作树中的操作不会影响另一个工作树的文件，因此可以安全地运行计划，而不影响用户的检出内容；并行 Agent 也不会互相覆盖文件。

核心原则：先检测是否已有隔离，优先使用运行环境自带的工作树机制，其次才使用普通 git；绝不要在未经测试的基线上开始工作。 在运行环境不知情的情况下创建的工作树属于它无法查看或清理的状态；在测试未通过的基线上启动工作树，会让之后出现的每个故障都难以判断。

首要准则

NO IMPLEMENTATION WITHOUT AN ISOLATED WORKSPACE AND A KNOWN BASELINE

没有例外。不要绕过。不要走捷径。

何时使用

必须使用：

• 在 godmode:delegated-execution 或 godmode:inline-execution 开始 Task 1 之前。
• 在会写入文件的并行 Agent（godmode:parallel-execution）启动之前。
• 用户的检出内容中有未提交的工作，且你不得影响这些工作时。

跳过：

• 只读调查或审查。
• 用户已明确要求在当前目录中工作；在记录簿中注明这一点，并仍然运行基线测试。
• 当前目录不是 git 仓库：说明这一点，并询问用户是要运行 git init 还是在当前目录中工作。

流程

1. 检测现有隔离

git_dir=$(cd "$(git rev-parse --git-dir)" && pwd -P)
git_common=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
super=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
branch=$(git branch --show-current)

• git_dir 与 git_common 不同且 super 为空：你已经位于一个关联工作树中。不要再创建一个。转到步骤 4。
• super 不为空：你位于子模块中，而不是工作树中。将其视为普通检出。
• 如果位于关联工作树中且处于分离 HEAD 状态：由宿主管理该工作树。请注意，必须在结束时创建分支。

2. 征得同意并选择名称

如果用户的指示已说明对工作树的偏好，请遵照执行。否则，用一句话说明你将创建工作树以保护用户的检出内容，然后继续，除非用户已要求在当前目录中工作。根据工作内容选择一个简短的分支名称（feature/csv-export、fix/login-race）。

3. 创建工作树

3a. 优先使用运行环境自带的机制。 如果运行环境本身可以创建工作树（内置操作、命令行标志或每个子 Agent 的隔离选项），请使用该机制：它负责放置工作树、创建分支、清理，并执行自身的隔离检查。运行环境参考资料中会列出相应操作。关于 Claude Code，需要了解以下信息：

• 会话工作树位于 .claude/worktrees/<name>/，分支名为 worktree-<name>；请将 .claude/worktrees/ 添加到 .gitignore。
• 除非项目的工作树基准设置另有规定，否则新工作树会从仓库的默认分支创建，而不是从当前 HEAD 创建。如果工作必须基于尚未推送的提交或某个功能分支，请先检查基准分支。
• .env 等被 git 忽略的文件不会被复制，除非项目有一个列出这些文件的 .worktreeinclude 文件。
• 使用工作树隔离运行的子 Agent 会获得一个临时工作树；如果它没有做出任何更改，该工作树会自动移除。

3b. 否则使用普通 git。 按以下顺序选择目录；用户明确指定的偏好始终优先于磁盘上的现有内容：

1. 用户指示中指定的工作树目录。
2. 仓库根目录下已有的 .worktrees/。
3. 仓库根目录下已有的 worktrees/（如果两者都存在，优先使用 .worktrees/）。
4. 默认：创建 .worktrees/。

在项目内的目录中创建任何内容之前，确认该目录已被忽略：

git check-ignore -q .worktrees || echo "NOT IGNORED"

如果该目录未被忽略，将其添加到 .gitignore，并在当前分支上提交这一行更改，然后告知用户。未被忽略的工作树目录会被整体提交到仓库中。

base=$(git rev-parse HEAD)           # or the branch the plan says to start from
git worktree add ".worktrees/$name" -b "$branch" "$base"
cd ".worktrees/$name"

如果创建失败并出现权限或沙盒错误，告知用户，然后在当前检出内容中创建新分支并继续工作。

4. 设置项目

检测并运行项目自身的设置流程；优先遵循项目 README 或贡献指南中的说明，不要凭猜测：

标记	设置
package-lock.json / pnpm-lock.yaml / yarn.lock	npm ci / pnpm install --frozen-lockfile / yarn install --frozen-lockfile
pyproject.toml / requirements.txt	在虚拟环境中使用项目的工具（uv sync、poetry install、pip install -r requirements.txt）
Cargo.toml	cargo build
go.mod	go mod download

仅当项目文档有说明时，才复制测试所需的本地配置（例如，将 .env.example 复制为 .env）。切勿将密钥复制到已跟踪的文件中。godmode:environment-awareness 涵盖 shell 和包管理器的差异。

5. 运行基线测试

运行项目的完整测试命令并查看输出。

• **通过：**记录数量。
• **失败：**报告失败情况，并询问用户是要继续还是先调查。如果用户选择继续，则在记录中写入 Baseline: <n> failing before any change: <names>，以便区分后续的失败。

6. 报告

Worktree: <absolute path>  (branch <name>, from <base sha>, created by <harness | git>)
Setup: <command> ok
Baseline: <command> -> <n> passed, <m> failed

此内容也要写入计划记录，以及消息中。

清理

清理工作由 godmode:merge-protocol 负责。此技能的规则是：仅移除本次运行在 .worktrees/ 或 worktrees/ 下创建的工作树；由 harness 管理的工作树应留给 harness 处理；如工作树中有未提交或未跟踪文件，切勿在未征求用户同意的情况下强制移除。

认知陷阱

合理化说法	事实
“我显然不在工作树中”	harness 创建的隔离环境和子模块都容易让人看走眼。运行检测命令。
“git worktree add 比 harness 的方式更快”	harness 无法查看或清理它没有创建的工作树，其隔离检查也不会覆盖该工作树。
“这个目录肯定已被忽略”	运行 git check-ignore。一次疏忽就可能提交整个目录树。
“新工作树包含我分支上的提交”	有些 harness 会从默认分支创建分支。在工作树中检查 git log -1。
“这是全新检出，基线测试可以稍后再跑”	基线测试失败会让之后的每个失败都变得难以判断。现在就运行。
“依赖和主检出中的一样”	工作树是全新检出。安装依赖。

防护规则

切勿：

• 在现有的关联工作树内创建工作树。
• 创建未被 git 忽略的项目本地工作树目录。
• 在尚未运行基线测试的情况下开始实现。
• 将密钥复制到已跟踪的文件中。
• 移除并非由你创建的工作树。

务必：

• 如果 harness 有自己的工作树机制，优先使用该机制。
• 确认工作树的基准提交就是此项工作所需的提交。
• 报告路径、分支、基准、设置情况和基线测试数量。

关联项

• godmode:delegated-execution、godmode:inline-execution：在任务 1 之前调用此项。
• godmode:parallel-execution：每个写入 Agent 使用一个工作树。
• godmode:environment-awareness：设置期间的 shell、包管理器和 Windows 路径。
• godmode:merge-protocol：合并分支并拆除工作树。