# Codex App Worktree 操作清单

核验日期：2026-07-16

## 创建前

- [ ] 项目位于 Git 仓库中。
- [ ] 已查看 Local 的分支、commit 和未提交改动。
- [ ] 为任务选择正确起始分支。
- [ ] 任务与其他并行任务不会写同一文件或占用同一外部资源。
- [ ] 需要的依赖可由 local environment setup 准备。

## 创建时

1. 在新任务中选择 **Worktree**。
2. 选择起始分支。
3. 提交范围明确的任务。
4. 确认 Codex 创建的工作副本和起始 commit。

Codex-managed worktree 默认从所选分支 HEAD 开始并处于 detached HEAD。这适合临时并行工作，不代表改动已经进入一个可推送分支。

## 工作中

- [ ] 每个任务只在自己的 worktree 修改。
- [ ] 运行该 worktree 的安装和验证命令。
- [ ] 不假设 Local 的未跟踪依赖或环境会自动存在。
- [ ] 需要长期保留时使用 **Create branch here**。
- [ ] 分支名、commit 和测试记录与任务绑定。

## Local 与 Worktree 之间

想回到日常本地环境时使用 **Handoff**。不要强行在 Local 检出已被 worktree 占用的同一分支。

Git 的约束：同一可变分支一次只能在一个 worktree 检出。出现以下错误时，应切换其中一边的分支或使用 Handoff：

```text
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
```

## 忽略文件

Local managed worktree 只自动拥有 Git 跟踪文件。确需复制的忽略文件可在仓库根使用 `.worktreeinclude`：

```text
.env.local.example
config/local-development.json
```

不要把真实 secrets 加入该文件。复制忽略文件会把它们带入更多工作副本，必须重新评估泄漏风险。

## 完成与清理

- [ ] 阅读完整 diff。
- [ ] 运行 lint、类型检查、测试和必要手工 QA。
- [ ] 创建分支或 Handoff 后确认 commit 可达。
- [ ] 保存结果边界和未验证项。
- [ ] 归档任务前确认重要改动已有分支、commit、patch 或快照。
- [ ] 定期清理依赖与构建缓存，避免 worktree 占用过多空间。

## 并行任务验收

- [ ] 每个 worktree 有独立目标和所有者。
- [ ] 没有共享同一分支。
- [ ] 合并顺序明确。
- [ ] 每个分支单独测试，合并后再次集成测试。
- [ ] 冲突由人工理解语义后解决，不直接选择整边覆盖。

官方来源：

- https://learn.chatgpt.com/docs/environments/git-worktrees