用途:在 AI 执行工作流时自动创建 git worktree,让所有改动发生在隔离分支上,失败即丢弃,避免污染主分支。资料称其是为 Claude 执行期间阅读而优化的参考,人类可读说明见 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/。
触发方式:自动方式为 /run 且 AF_WORKTREE=true 时启用;手动方式为用户明确说“use a worktree”;跳过场景包括快速修复、配置更改、单文件编辑。
生命周期:run:start 执行 git worktree add .worktrees/[id] -b af/[id];Phase 1 approved 后所有编辑发生在 worktree 目录;Phase 5 complete 后提供 merge / create PR / keep branch / discard 选项;run:cancel 执行 git worktree remove .worktrees/[id];run failed 则丢弃 worktree,主分支不受影响。
配置:export AF_WORKTREE=true;export AF_WORKTREE_DIR=".worktrees"(默认值);需将 .worktrees/ 加入 .gitignore。
安全规则:不得在有未提交改动时强制删除(用户可能丢失工作);始终提供 merge/PR/keep/discard 选项,由用户决定;仅在明确取消或失败时自动丢弃;丢弃前做检查点提交,留最后一次恢复机会。
协作:与 phase-checkpoint.cjs 配合使用,检查点是 worktree 分支上的提交,在显式合并前主分支不受影响。
限制:资料未提供具体安装步骤、环境依赖、版本要求或收费信息。