codex@macbookpro
·
2026-03-30
task-doc-template.md
1# 通用任务文档模板
2
3## 用途
4
5这个模板用于在任意代码仓里快速生成新的任务文档。
6
7适用场景：
8
9- 单仓开发任务
10- 多仓联动任务
11- 文档整理任务
12- 测试与回归任务
13- 重构或迁移任务
14
15目标：
16
17- 给新对话一条可以直接复制的提示词
18- 把边界、写入范围、验收标准写清楚
19- 每个任务强制使用独立分支和 worktree，避免代码冲突
20- AI 在执行过程中主动更新任务文档状态
21
22## 使用方式
23
24新对话如果是"帮我创建任务文档"，可以先读这个模板，再按当前需求生成新的任务 `md`。
25
26推荐提示词：
27
28- `读 </绝对路径/任务文档模板.md> 任务模板，按当前需求创建新的任务 md 文档。`
29
30如果是"按某个任务文档开始开发"，推荐提示词：
31
32- `读 /绝对路径/某个任务文档.md 任务文档，完成开发任务。`
33
34任务文档本身建议放在项目内固定位置，例如：
35
36- `<repo>/tasks/`
37- `<repo>/docs/tasks/`
38- `<repo>/.codex/tasks/`
39
40如果是多仓任务，也可以集中放在一个单独目录里统一管理。
41
42## 模板正文
43
44下面是可直接复制的结构。生成新任务时，把尖括号占位内容替换掉即可。
45
46```md
47# Task <编号>：<任务标题>
48
49## 状态
50
51- 当前状态：`待开始`
52- 规模预估：`S / M / L`
53- 依赖任务：无 / `<依赖的任务编号>`
54- 建议执行者：`Codex / Claude / 均可`（附简要原因）
55
56## 直接给对话的提示词
57
58读 `</绝对路径/当前任务文档.md>` 任务文档，完成开发任务。
59
60如需补背景，再读：
61
62- `</绝对路径/背景文档1.md>`
63- `</绝对路径/背景文档2.md>`
64
65## 当前基线
66
67- 仓库：`</绝对路径/仓库>`
68- 分支基线：`main`
69- 提交：`<当前 main 提交>`
70
71## 分支与 worktree（强制）
72
73每个任务必须使用独立的分支和 worktree，禁止直接在 main 上修改，禁止多个任务共用同一个 worktree。
74
75- 分支名：`<feat/short-branch-name 或 bug/short-branch-name>`
76- worktree 路径：`</绝对路径/仓库>-<short-branch-name>`
77
78开工步骤：
79
801. `cd </绝对路径/仓库>`
812. `git worktree add ../$(basename $(pwd))-<short-branch-name> -b <分支名> main`
823. `cd ../$(basename $(pwd))-<short-branch-name>`
834. 在这个 worktree 目录里开发，不要回到主仓库目录
84
85完成后提交与推送：
86
871. 在 worktree 里提交所有变更（包括更新后的任务文档）
882. `git push -u origin <分支名>`
89
90合并步骤（由合并者执行）：
91
921. `cd </绝对路径/仓库>`
932. `git fetch origin`
943. `git merge origin/<分支名>`
954. `git push`
965. `git worktree remove ../$(basename $(pwd))-<short-branch-name>`（如果 worktree 还在）
97
98合并冲突处理：
99
1001. 如果 `git merge` 报冲突，先 `git diff` 查看冲突文件
1012. 手动解决冲突后 `git add` 冲突文件
1023. `git merge --continue` 完成合并
1034. 不要用 `git merge --abort` 然后 force 覆盖
104
105命名规则：
106
107- 功能任务分支名以 `feat/` 开头
108- 缺陷任务以 `bug/` 开头
109
110## 目标
111
112<一句话说明这个任务要完成什么>
113
114## 背景
115
116<说明为什么要做这个任务，当前问题是什么>
117
118## 涉及仓库
119
120- `</绝对路径/仓库1>`
121- `</绝对路径/仓库2>`
122
123## 范围
124
125- <任务范围 1>
126- <任务范围 2>
127- <任务范围 3>
128
129## 路径约束
130
131<如果有固定新路径前缀、目录位置或接口命名约束，在这里写清楚>
132
133## 推荐实现边界
134
135建议新增：
136
137- `<service/controller/vo/...>`
138
139建议放到：
140
141- `</绝对路径/目录1/>`
142- `</绝对路径/目录2/>`
143
144## 允许修改的目录
145
146- `</绝对路径/目录1/>`
147- `</绝对路径/目录2/>`
148- `</绝对路径/目录3/>`
149
150## 尽量不要修改
151
152- `</绝对路径/目录或文件1>`
153- `</绝对路径/目录或文件2>`
154
155## 必须完成
156
157### 1. <子目标 1>
158
159- <要求 1>
160- <要求 2>
161
162### 2. <子目标 2>
163
164- <要求 1>
165- <要求 2>
166
167### 3. <子目标 3>
168
169- <要求 1>
170- <要求 2>
171
172## 需要特别注意
173
174- <兼容性约束>
175- <不要破坏的旧行为>
176- <本任务和其他并行任务的边界>
177- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
178
179## 验收标准
180
181- <可验证结果 1>
182- <可验证结果 2>
183- <可验证结果 3>
184
185## 推荐验证命令
186
187- `<命令 1>`
188- `<命令 2>`
189- `<命令 3>`
190
191## 执行记录
192
193> 以下内容由执行任务的 AI 填写，创建任务时留空。
194
195### 开始执行
196
197- 执行者：<AI 名称和模型，如 Claude Opus 4.6>
198- 开始时间：<ISO 时间>
199- 状态变更：`待开始` → `进行中`
200
201### 完成摘要
202
203- 完成时间：<ISO 时间>
204- 状态变更：`进行中` → `已完成`
205- 修改了哪些文件：
206 - <文件列表>
207- 核心实现思路：
208 - <简述>
209- 跑了哪些测试：
210 - <测试列表>
211
212### 执行过程中遇到的问题
213
214> 记录执行过程中遇到的阻塞、环境问题、临时绕过方案等。合并时由合并者判断是否需要修复或建新任务。
215
216- <问题描述> → <临时处理方式>
217
218### 剩余风险
219
220- <风险 1>
221- <风险 2>
222- 无已知风险
223```
224
225## AI 执行任务时的行为规范
226
227AI 收到任务文档后，必须按以下顺序操作：
228
229### 开工时
230
2311. 把任务文档的 `当前状态` 从 `待开始` 改为 `进行中`
2322. 在"执行记录 > 开始执行"区域填写：
233 - 执行者（AI 名称和模型）
234 - 开始时间（ISO 格式）
2353. 按"分支与 worktree"章节创建独立 worktree
2364. 开始开发
237
238### 完成时
239
2401. 把任务文档的 `当前状态` 从 `进行中` 改为 `已完成`
2412. 在"执行记录 > 完成摘要"区域填写：
242 - 完成时间
243 - 修改了哪些文件
244 - 核心实现思路
245 - 跑了哪些测试
2463. 在"执行记录 > 剩余风险"区域填写风险点，如果没有写"无已知风险"
2474. 提交所有变更（包括更新后的任务文档本身）
2485. 推送分支到 remote：`git push -u origin <分支名>`
249
250### 遇到阻塞或环境问题时
251
2521. 在"执行记录 > 执行过程中遇到的问题"区域记录：问题描述 + 临时处理方式
2532. 如果能绕过则继续开发，不要因为非核心问题停下来
2543. 提交时确保问题记录在任务文档中，合并者会判断是否需要修复或建新任务
255
256### 失败或中断时
257
2581. 把任务文档的 `当前状态` 改为 `阻塞` 或 `失败`
2592. 在"剩余风险"区域写明失败原因和卡点
2603. 在"执行过程中遇到的问题"区域记录所有已知问题
2614. 提交当前进度，不要丢弃已有工作