AI 编程 Agent 使用 Git Worktree 的坑：vendor 符号链接

dev.to · AI#AI编程#Git#调试

Editor brief · 编辑速览

AI Agent 在 worktree 中运行时，node_modules/vendor 符号链接会导致路径解析到主分支代码，而非当前分支，表现为「代码和预期不符」的玄学 bug。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

我花了一整个上午调试一个实际上并不存在于我所阅读代码中的行为。

Agent 运行在一个 worktree 中，其 vendor 文件夹是指向主项目的符号链接。它悄无声息地从另一个分支加载类。

命令及其作用

git worktree add -b agent/task ../project-task
cd ../project-task

这会创建一个新文件夹，其中包含每个已跟踪的文件，位于一个新分支上，共享相同的历史记录。它不是克隆：仓库是同一个，所以提交对所有人都可见，不涉及上传或下载。完成后，git worktree remove ../project-task。

哪些不会一起带过来（卡住的部分）

只有已跟踪的文件会被复制。.gitignore 排除的所有内容都留在后面，而这恰恰是项目运行所需的东西：

依赖（node_modules、vendor）：必须在 worktree 中安装。一个常见的快捷方式是符号链接到主目录，对于 node_modules 通常可行。但对于使用文件路径解析的语言（如 PHP 的自动加载器），符号链接会导致 AI Agent 在不发出任何警告的情况下从其他分支加载代码，最终你调试的代码行为根本不在你所阅读的代码中。
环境文件（.env）：符号链接没问题，因为它是一个只读一次的文本文件。
前端构建：如果框架查找生成的 manifest，新 worktree 中不存在该文件，页面会报一个从不提及 worktree 的错误。

数据库是共享的，这是一个陷阱

worktree 不会隔离数据库。如果 AI Agent 运行了一个破坏性迁移，它会影响你和其他所有正在使用的 Agent。值得在项目说明中明确声明这一点，也值得让测试使用内存数据库而不是开发数据库。

什么时候不值得用

一次只用一个 AI Agent 时，不值得：你要支付设置成本却得不到隔离，因为根本没有东西可以冲突。对于只读工作（如调查或解释代码，不写入任何内容）也同样毫无意义。隔离是为了并发写操作而存在的，只有在三个或四个以上同时进行的前端任务时才值得。

Worktree 还是容器？

Worktree 更轻量、更快速：文件在同一磁盘上，Agent 仍然能使用你机器上的工具。容器隔离得更深入，包括进程和网络，如果你打算让 Agent 无人监管地运行，容器才是你想要的。对于在自己 Mac 上监督的工作，worktree 就足够了。

如何查看谁在哪个 worktree 里

git worktree list

显示所有 worktree 及其各自的分支。当你打开了五个 AI Agent 并且数不过来时，这个命令能回答"谁在动什么"。