什么是Codex工作树？拆分多个编码任务的方法与注意事项

摘要： 使用工作树可以分开同一Git项目的工作文件夹，开展多个修改。即使文件夹已分开，合并结果时仍需重新检查变更与验证。

1. 理解工作树的简单示例

假设自己在笔记应用修改界面颜色，同时希望Codex修复搜索功能。两个任务修改同一文件夹，可能难以区分谁创建了哪些变更。工作树让各任务使用独立工作文件夹。

OpenAI官方文档说明，工作树是Git仓库的独立检出，文件副本分开，但共享提交与分支等Git信息。在Codex中，可用于并行开展同一项目的独立任务。应区分简单复制文件夹，与Git管理工作文件夹的方式。

2. 先理解分支与文件夹的区别

分支区分Git历史中工作延续的位置，工作树则分开实际编辑文件的位置。初次使用应确认“当前看到的文件夹属于哪项工作的代码”。即使文件名相同，不同工作文件夹的内容也可能不同。

假想笔记应用中，主工作文件夹用于颜色变更，独立工作树用于搜索修复，应记录浏览器正在查看哪个文件夹的开发服务器。界面没变化时，先确认运行服务器是否指向修改文件夹，再重新改代码。这是使用多个检出时的必要习惯，与AI工具无关。

3. 先确定拆分任务的边界

仅分开文件夹，不会自动确定任务责任。如果搜索修复与颜色修改都大幅改变同一组件，后续合并需要协调。宜先拆分独立性较高的工作，共同修改部分应先整理双方要求。

검색 결과가 없을 때 안내 문구를 표시하는 수정만 진행해 주세요.
작업은 별도 worktree에서 진행하고 시작 기준을 알려 주세요.
주 작업 폴더에서는 색상 변경을 진행 중입니다.
공통 스타일과 다른 작업자의 변경은 덮어쓰지 마세요.
완료 후 변경 파일, 관련 검증 결과, 합칠 때 확인할 점을 정리해 주세요.

此示例是传递任务边界的请求，并非介绍点击某按钮的界面。应通过实际创建结果与当前官方指南，确认应用能否使用工作树、按什么基准生成。不要假设进行中未保存的修改会自动出现在其他文件夹。

4. 创建后与合并前的确认

创建后应确认工作路径、起始Git状态与必要开发环境。新文件夹有源代码，并不能证明软件包与本地配置都已准备。需要环境文件时，宜遵循项目安全配置方法，而不是将内容粘贴到对话。

合并任务前，应阅读修改文件差异。检查搜索修改是否与颜色修改涉及同一行、公开函数格式是否变化，以及是否包含意外生成文件。各任务的验证结果有用，但共同应用两种变更后仍需检查，因为分别正常的修改组合后也可能有问题。

5. 常见混淆与解决检查

• 界面未变化： 检查开发服务器工作路径与当前访问地址。
• 必要命令失败： 确认新工作文件夹的依赖与配置是否准备好。
• 变更混在一起： 阅读差异，重新整理各任务责任与共同修改部分。
• 需要清理文件夹： 确认要保留的提交与文件，再遵循所用应用的清理流程。

应先确认成果保存在哪里，而不是立即删除未使用的工作文件夹。OpenAI文档也介绍Codex任务移动与清理流程。应用管理的工作树宜采用官方管理流程，而不是像普通文件夹一样任意移动，这样更容易找到当前任务。

6. 直观区分工作文件夹与Git状态

假设memo-app当前文件夹用于颜色变更，独立文件夹用于搜索修复。开始时应读取路径与Git状态，而不是依赖记忆。下方命令在Git仓库查询当前文件夹、仓库根目录、修改文件与关联工作树。可在PowerShell执行，实际路径需替换。

Get-Location
git rev-parse --show-toplevel
git branch --show-current
git rev-parse --short HEAD
git status --short
git worktree list

git worktree list适合同时查看多个工作文件夹与关联Git状态。项目名相同但路径不同，就属于独立工作文件夹。branch --show-current为空，可能未检出命名分支，应同时读取Git状态。官方应用文档说明，管理工作树默认从detached HEAD开始。不能仅凭没有分支名判断创建失败。

记录项目	假想任务A	假想任务B
工作目的	调整界面颜色	空搜索结果提示
文件夹	C:\Projects\memo-app	独立工作树的实际路径
起始状态	记录是否包含当前修改	记录选定基准与起始提交
修改责任	公共颜色	搜索显示条件

记录起始提交与是否包含本地修改，是为了后续解释差异。如果以为是最新任务却从旧基准开始，可能看到搜索修复之外的差异。应用中选择了起始分支与本地修改时，应记录选择。也不能假设直接用Git创建的工作树，与应用管理的工作树采用相同创建和清理流程。

7. 文件夹分开后仍可能共享的运行环境

源代码文件夹分开，并不会自动分开运行服务器与外部数据。两个开发服务器使用同一端口，后启动者可能失败或改用其他端口。两文件夹连接同一测试数据库，一侧数据修改可能影响另一侧结果。应分别记录工作树隔离范围与项目共享资源。

1. 查看各文件夹README与锁文件，使用相同包管理器。
2. 检查依赖是否准备，并遵循项目安装流程。
3. 启动开发服务器时，将输出地址与任务名一起记录。
4. 确认环境变量名称与连接目标，了解是否共享测试服务。
5. 将浏览器当前地址对应到修改文件夹的服务器。

例如颜色任务服务器使用5173，搜索任务使用5174，应在任务记录写明各地址检查哪种界面。此数字是假想部署示例，并不代表所有工具都使用这些端口，应按项目配置与启动输出调整。界面未变化时，先比较访问地址与服务器启动文件夹，再修改代码，是快速诊断方法。

새 worktree의 실행 환경을 점검해 주세요.
현재 경로, 시작 커밋, 관련 실행·검증 명령을 알려 주세요.
의존성과 필요한 설정 파일이 준비되어 있는지 확인하세요.
주 작업 폴더와 개발 서버 포트·데이터 연결이 겹칠 수 있는지 설명하세요.
환경 변수의 실제 비밀값은 출력하지 말고 이름과 준비 상태만 보고하세요.

8. 如何准备Git排除的本地配置？

新文件夹有代码却无法运行，常因缺少Git未追踪的本地配置。先确认项目是否有环境变量示例文件或配置指南，并依流程准备。完整复制旧文件夹，可能也搬移无关依赖、缓存与构建产物，因此宜区分必要配置。

当前官方文档介绍了在仓库根目录放置.worktreeinclude文件，记录创建本地管理工作树时要复制的ignored文件路径或模式的功能。它适用于应用创建的本地管理工作树，不应认为直接Git创建的文件夹或远程环境也会自动应用。追踪中的源代码已包含在检出中，无需再次写入复制清单。

# .worktreeinclude의 가상 예시
.env.local
config/development.local.json

不要直接添加上方所有文件名，应先判断文件是否实际被Git排除，以及新环境是否需要。也需审查将生产服务配置复制到开发工作树是否合适。能用示例文件准备时，可优先使用该方法。改变新工作树创建时的复制设置后，应在实际创建结果确认必要文件已准备。

为避免Codex找不到配置时擅自创建空文件，只让命令通过，可要求无法了解必要环境时标为未执行，并说明准备流程。区分配置准备与功能缺陷，可减少不必要源代码修改。

9. 合并两种变更时的前后确认案例

假设搜索与颜色任务分别通过验证。搜索添加0条结果提示，颜色改变公共消息颜色。即使没有行级冲突，合并后提示文字也可能对比度不足。Git能合并，与产品行为正确，是不同判断。

时点	确认内容	发现问题时
合并前	各变更目的、文件与验证结果	先分离与功能无关的变更
比较差异	公共组件、样式与API接点	协调是否将同一条件改为不同方式
合并后	正常搜索与空结果界面	单独复现组合产生的问题
清理前	保留成果与本地配置位置	取得遗漏文件后再清理

검색 수정과 색상 변경을 함께 적용한 상태를 검토해 주세요.
각각의 의도는 유지하고 공통 메시지 표시 부분을 확인하세요.
정상 결과·결과 0개·로딩·오류 상태를 구분해 검증하세요.
충돌 해결 과정에서 빠진 기능과 관련 없는 변경이 있는지 살펴보세요.
개별 작업에서 통과한 검사와 조합 상태에서 실행한 검사를 나누어 보고하세요.

在应用中将工作树任务移至Local时，可使用官方Hand off流程。它用于把任务移至另一检出继续，不能代替确认两个独立任务的变更是否按意图组合。当前有本地变更时，应先了解状态，再读取移动结果。管理工作树采用应用归档与恢复流程，更容易保持任务记录与文件夹的关联。

10. 常见问题

不使用Git也可以吗？ 本文章的工作树以Git仓库为前提，不应视为与拆分普通项目文件夹相同功能。

使用工作树就没有冲突吗？ 编辑文件夹已分离，但合并相同代码的修改时，仍可能需要处理冲突或语义协调。

多个任务都应该拆开吗？ 它适合互相独立的工作。单个极小修改，应考虑准备与清理新环境的负担。相比任务数量，更重要的是能否理解并验证各成果。

官方来源与确认日期： OpenAI官方文档：工作树。2026年10月3日确认。使用命令与功能前，请确认当前环境与权限。