> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 02-计划开发与协作

> 以 TODO API v2 为例，演示计划模式、任务拆分、子代理、Worktree、并行协作、审批、阶段验收和回滚。

## 本页要完成什么

这一页用一个具体的 TODO API v2 项目，演示如何把跨模块需求变成可并行、可检查、可暂停、可恢复的交付流程。项目当前已经支持创建和列出待办，本次增加：

* `GET /todos` 的分页、`completed` 和 `tag` 筛选；
* `PATCH /todos/{id}` 对 `title`、`tag`、`completed` 做部分更新；
* 保留已有响应字段、认证方式和错误格式；
* 通过单元测试、接口测试、lint、类型检查和构建。

不在本次范围内：更换数据库、修改前端、重做认证、连接生产服务、删除历史迁移、无审批提交或发布。你可以把 TypeScript、Node.js 和下列路径换成实际项目的技术栈，但流程和边界应保持一致：

```text theme={null}
todo-api/
├── src/routes/todos.ts
├── src/services/todo-service.ts
├── src/repositories/todo-repository.ts
├── src/models/todo.ts
├── test/
├── package.json
└── AGENTS.md
```

完成定义：

| 编号 | 标准       | 证据                             |
| -- | -------- | ------------------------------ |
| D1 | API 契约确定 | 参数、响应、错误和兼容规则                  |
| D2 | 任务边界确定   | 文件范围、依赖、负责人                    |
| D3 | 功能完成     | GET/PATCH 路径可运行                |
| D4 | 测试通过     | 单测、接口测、lint、类型检查、构建            |
| D5 | 变更可审查    | diff 只有批准文件                    |
| D6 | 结果可恢复    | 基线、阶段提交或补丁、回滚方案                |
| D7 | 外部动作获批   | commit、push、merge、release 分开批准 |

具体命令和 Codex 界面会随版本变化。遇到差异时，以本机 `codex --help`、对应子命令的 `--help` 和官方文档为准。

## 01 开工检查：确认工作区和基线

先进入仓库根目录，确认路径、分支、HEAD、已有修改和工具版本。不要把别人的未提交修改当成自己的基线，也不要用 `git reset --hard` 清理不明来源的修改。

```bash theme={null}
pwd
git status --short --branch
git branch --show-current
git log -1 --oneline
codex --version
```

给主代理的第一条提示词：

```text theme={null}
现在只做只读开工检查，不要修改、安装、联网、写数据库、提交或推送。
确认仓库根目录、当前分支、HEAD、工作区未提交修改、README、AGENTS.md、运行命令和测试命令。
读取 todos 的路由、服务、仓储、模型、数据库适配器和现有测试。
输出：项目结构、已有 GET/PATCH 行为、错误格式、可复用测试约定、候选文件、风险和无法确认的假设。
每条结论都带文件路径和符号；完成后停止等待指令。
```

预期不是“可以开始”，而是可核对的事实：

```text theme={null}
基线：main @ 8f31c2a
运行：npm run dev；测试：npm test
已有 GET /todos 返回数组，错误为 { error: { code, message } }
候选文件：src/routes/todos.ts、src/services/todo-service.ts、test/todos.test.ts
风险：分页默认值和数据库稳定排序尚未确认
```

验收：代理没有产生 diff，`git status` 与开始时一致。如果它误改了文件，先保存并查看 `git diff`，不要将检查和实现混在一起。

## 02 计划模式：把不确定性暴露出来

在 CLI 或 App 中进入计划模式；不同版本可能使用按钮或 `/plan`。计划的目标是明确契约、依赖、并行机会和审批点，不是生成一篇漂亮长文。

```text theme={null}
进入计划模式，只读，不要改文件。
为 TODO API v2 制定实施计划：
- GET /todos 支持 page、page_size、completed、tag；
- 响应保留已有字段，并增加 page、page_size、total、items；
- PATCH /todos/{id} 支持 title、tag、completed 的部分更新；
- 非法参数、空标题、未知 ID 继续遵循现有错误格式；
- 不换数据库、不改认证、不改前端、不引入第三方依赖。
输出：
1. 当前与目标行为的差异；
2. 参数、响应和错误契约草案；
3. 按依赖拆分的任务清单；
4. 每项的文件范围、输出和验证命令；
5. 可并行与必须串行的任务；
6. 风险、需人工决定的事项和回滚方案；
7. 阶段性交付建议。等待批准，不要实现。
```

合格的任务图应类似：

| ID | 任务        | 依赖    | 文件范围             | 交付物   |
| -- | --------- | ----- | ---------------- | ----- |
| P0 | 读取现有行为    | 无     | 只读               | 事实报告  |
| P1 | 固化 API 契约 | P0    | 契约记录             | 示例和边界 |
| P2 | 数据层查询和更新  | P1    | model/repository | 数据层测试 |
| P3 | 路由、校验、服务  | P1、P2 | route/service    | 接口测试  |
| P4 | 独立审查      | P2、P3 | 只读               | 问题报告  |
| P5 | 集成验收      | P2-P4 | 集成区              | 完整检查  |

要求代理把“改一下接口”“优化数据库”改写成明确决定。例如：`page_size` 上限是多少？空 `tag` 是不筛选还是筛选空标签？旧客户端收到数组还是对象？如果这些问题没有答案，计划必须标记 `BLOCKED`，而不是让实现代理自行猜测。

计划审查提示词：

```text theme={null}
请把后续动作标记为 read、write、network、external 或 irreversible。
read 可以执行；write 只限批准文件；network、external、irreversible 必须再次请求批准。
列出所有会改变公共 API、数据库、锁文件、分支或远端的动作，等待“批准阶段 1”。
```

预期输出：`阶段 1 read`、`阶段 2 write`、`数据库迁移 external`、`commit/push/release irreversible`。验收：契约和任务依赖由人确认，未批准动作没有执行。

## 03 任务拆分：按结果和依赖分工

拆分不是按文件数量平均分配，而是让每项任务有一个主要结果、明确输入、有限文件范围和独立验证。建议采用四条工作流。

### A：只读探索

```text theme={null}
作为只读探索员，检查 todos API 的真实执行路径。
读取路由、服务、仓储、模型、数据库适配器和测试；不要修改文件或写数据。
输出不超过 30 行：GET/PATCH 调用链、分页和筛选插入点、参数校验和错误约定、文件与符号、兼容风险。
每条结论引用文件路径和符号名，只回摘要，不贴大段源码。
```

预期：证据索引，而不是修复建议。验收：每条结论都能回到文件或测试。

### B：API 契约

```text theme={null}
根据探索报告起草 TODO API v2 契约，不修改业务代码。
明确 page、page_size、completed、tag 的类型、默认值、上限、组合规则和错误。
明确 PATCH 的部分更新、空字符串、未知字段和未知 ID 语义。
保留现有字段和错误 envelope；若无法兼容，列出冲突并停止。
输出契约表及 5 个请求/响应示例，供实现和测试共同使用。
```

预期至少覆盖默认分页、超限、非数字、非法布尔值、空标签、无结果、空标题和旧客户端。验收：主代理、实现代理和测试代理使用同一份已批准契约。

### C：数据层实现

```text theme={null}
实现已批准的 TODO API v2 数据层契约。
只修改 src/models/todo.ts、src/repositories/todo-repository.ts 及直接数据层测试。
加入分页、completed/tag 筛选和 PATCH 部分更新；不要改路由、认证、迁移、依赖或错误格式。
先检查接口，再小步实现；完成后运行数据层测试并报告文件、命令、结果和未解决问题。
若需要新增依赖、迁移或公共类型变化，先停止并说明原因。
```

预期：稳定排序、明确分页边界、部分更新不覆盖未传字段，且 diff 不越界。

### D：路由和接口测试

```text theme={null}
数据层已按下列契约验收：[粘贴契约]
只修改 src/routes/todos.ts、src/services/todo-service.ts 和 test/ 中直接相关文件。
实现 GET 分页筛选和 PATCH 部分更新，保持认证、错误 envelope、状态码和旧客户端行为。
覆盖正常路径、默认值、非法 page/page_size、completed 非法值、tag 无结果、空标题、未知字段、未知 ID 和旧请求。
先展示计划再修改；完成后运行相关测试、完整测试、lint、类型检查和构建。
不要提交、推送或访问外部服务。
```

## 04 阶段 0 和阶段 1：基线与契约交付

阶段 0 先记录基线，不要顺手修历史失败：

```bash theme={null}
git status --short
git rev-parse HEAD
git diff --check
npm test
```

提示词：

```text theme={null}
只做基线验证，运行已有测试和必要静态检查，不改文件。
输出命令、退出码、失败测试、环境假设和基线提交。
失败统一标记为 BASELINE_FAILURE，不要顺手修复。
```

预期记录：`base=8f31c2a`、`npm test=PASS`，或列出已有失败。验收：没有新 diff。回滚：无需回滚；只清理项目明确允许的缓存。

阶段 1 执行只读探索、契约讨论和任务图审批。交付物：

```text theme={null}
contract：已批准的参数、响应、错误和兼容规则
files：每项任务的允许文件集合
dependencies：P0 -> P1 -> P2/P3 -> P4 -> P5
risks：响应形状、分页默认值、数据库排序、性能
approval_needed：是否允许数据层类型和查询变更
```

验收：歧义全部得到决定，或明确标记 `BLOCKED`。回滚：废弃错误的契约草稿，保留已批准版本；不要让代理以旧契约继续实现。

## 05 阶段 2：Worktree 中实现数据层

多个线程的上下文隔离不等于文件系统隔离。并行写入必须使用不同 Worktree，或严格串行使用同一工作区。推荐：

| Worktree          | 任务    | 允许触碰                   |
| ----------------- | ----- | ---------------------- |
| `todo-api-data`   | 数据层   | model、repository、数据层测试 |
| `todo-api-route`  | 路由    | route、service、接口测试     |
| `todo-api-review` | 审查    | 只读                     |
| 集成工作区             | 合并和验收 | 合并后的批准文件               |

在 App 中新线程选择 Worktree、选择起始分支，再发任务；Worktree 默认可能是 detached HEAD，需要提交时先创建分支。CLI 是否具备同样界面能力以本机版本为准，不要假设有通用 `--worktree` 参数。

启动提示词：

```text theme={null}
这是数据层 Worktree，只负责阶段 2。
先运行 git worktree list、git status --short、git branch --show-current，确认没有误入主工作区。
如果是 detached HEAD，报告当前提交，不要自行建分支。
只修改批准的模型、仓储和数据层测试文件；每个小步运行相关测试。
结束时输出 diff --stat、测试结果、未解决问题和回滚点。
```

审批提示词：

```text theme={null}
批准阶段 2 在 todo-api-data Worktree 修改：
- src/models/todo.ts
- src/repositories/todo-repository.ts
- test/repository/todo-repository.test.ts
允许运行既有本地测试和类型检查。
禁止安装依赖、联网、读取密钥、写共享数据库、修改其他文件、提交和推送。
超出范围立即暂停。
```

预期：

```text theme={null}
git diff --stat：仅 3 个批准文件
相关测试：12 passed
未验证：真实数据量下的查询性能
回滚点：commit 1ab42ef 或 phase-2.patch
```

验收提示词：

```text theme={null}
对照契约逐项验收；查看完整 diff；确认没有路由、认证、依赖、迁移或敏感文件变更。
运行数据层测试和类型检查。每项输出证据；不能证明的标记 UNVERIFIED，失败标记 BLOCKED。
```

回滚：先保存 `git diff > phase-2.patch`，确认目录没有他人改动后按文件恢复，或废弃整个临时 Worktree。不要用 `git restore .` 覆盖无关修改。

## 06 阶段 3：路由、服务和接口测试

阶段 2 通过后，才能基于它的提交创建或更新路由 Worktree。不能靠两个目录“看起来一样”判断依赖已满足，先核对提交哈希。

```text theme={null}
批准阶段 3。先确认数据层提交哈希和当前 Worktree 无未提交修改。
基于已批准契约实现路由、服务和接口测试，只修改批准文件。
遇到契约与现有代码冲突先停下报告。
测试断言真实响应体、状态码、错误格式和用户行为，不只断言没有抛异常。
运行相关测试、完整测试、lint、类型检查和构建；不要提交、推送或访问生产。
```

预期：接口测试覆盖分页、筛选、部分更新、非法输入、无结果、未知 ID 和旧请求；测试命令和退出码明确。验收：代码路径、测试和 diff 三者都与契约一致。

若失败：保留阶段 2 有效提交，不合并阶段 3；若根因是契约，回到阶段 1 重新审批，不在路由里偷偷同时支持矛盾的两种契约。

## 07 子代理：并行探索和独立审查

Codex 不会自动拆分，必须明说“派几个代理、各做什么、是否等待全部、返回什么摘要”。子代理最适合只读、可独立的工作：扫描不同模块、分别做正确性和兼容性审查、运行互不冲突的检查。不适合多个代理同时改同一类型、生成同一迁移或处理强顺序依赖。

阶段 4 审查提示词：

```text theme={null}
并行派出 3 个只读子代理审查当前 diff：
correctness：检查分页、筛选、PATCH 和错误处理；
compatibility：检查旧客户端、响应字段、状态码和数据库行为；
tests：检查边界覆盖、断言质量和回归缺口。
三个代理都只读、不改文件、不提交、不联网；等全部返回后按阻塞、应修、建议汇总。
每条发现带文件、符号、复现条件、证据和修复建议；不要贴大段源码。
```

预期：

```text theme={null}
阻塞：src/routes/todos.ts:parsePage，page_size=abc 被当成默认值。
应修：test/todos.test.ts 未断言空结果的 total。
建议：可抽出参数对象，但不属于本次范围。
```

审查验收：阻塞项必须修复并有回归测试；应修项要修复或由负责人批准延期；建议项不自动扩大范围。审查代理没有写文件，`git status` 不应多出未授权修改。

如需自定义只读代理，可放在项目 `.codex/agents/`：

```toml theme={null}
name = "api_reviewer"
description = "Read-only reviewer for TODO API correctness and compatibility."
sandbox_mode = "read-only"
model_reasoning_effort = "medium"
developer_instructions = """
只读审查 API 代码和测试，关注行为、边界、兼容性和安全性。
不要修改、提交、联网；输出带文件和符号的精炼发现。
"""
```

多个结果矛盾时，要求双方引用证据，用最小复现测试验证，仍不能判定则人工决定；不要用代理投票代替事实。

## 08 冲突处理：文件、契约和资源分开看

### 文件冲突

```text theme={null}
出现合并冲突。先不要编辑冲突文件。
读取双方 diff、共同祖先和已批准契约，说明冲突文件/符号、两边行为、必需与额外改动、最小合并方案和必须运行的测试。
等待批准后，在集成 Worktree 解决；不要自动选择 ours/theirs。
```

处理顺序：保存双方提交和 diff；对照契约；在集成 Worktree 做最小合并；运行受影响测试和完整测试。

### 契约冲突

如果一方按数组写路由、另一方按对象写测试，这是决策冲突，不是普通文本冲突。回到契约负责人，决定响应形状和兼容方案后，再同步改代码和测试。

### 资源冲突

共享测试数据库、端口或锁文件时，优先使用独立临时资源；不能隔离就串行。禁止为了“解决占用”杀别人的进程、删除锁文件、重置数据库或读取主工作区 `.env`。涉及外部资源重新请求审批。

## 09 Worktree 的边界和常见错误

检查独立性：

```bash theme={null}
git worktree list
git status --short
git branch --show-current
```

同一分支不能同时在两个 Worktree 检出。遇到：

```text theme={null}
fatal: 'feature/todo-api-v2' is already used by worktree at '...'
```

先找出占用目录，确认哪个线程继续使用；另建分支，或用 App 的 Handoff 转移线程。不要强行删除锁或目录。Worktree 中的 `.env`、缓存和 `node_modules` 不会因 Handoff 自动搬运。缺依赖时只能运行项目已有 setup 脚本，不要复制真实密钥或连接生产：

```text theme={null}
如果缺少 .env、数据库连接或依赖，不要猜值、不要读取其他工作区的密钥、不要连接生产。
列出缺失项和安全的测试环境方案，等待批准。
```

清理有改动的 Worktree 前先记录提交、补丁和状态；没有有效改动的临时 Worktree 才能在确认无人使用后清理。长期环境使用永久 Worktree，避免误删重要工作。

## 10 审批和集成验收

按影响分档：

| 动作                        | 处理            |
| ------------------------- | ------------- |
| 读取源码和测试                   | 自动允许          |
| 修改批准文件                    | 看 diff 后允许    |
| 安装依赖                      | 先确认，可能联网和改锁文件 |
| 迁移或写共享数据库                 | 明确批准          |
| 读取密钥、客户数据                 | 禁止            |
| 删除文件或 Worktree            | 明确批准          |
| commit、push、merge、release | 各自单独批准        |

所有 Worktree 完成后，在专用集成区执行：

```bash theme={null}
git status --short --branch
git worktree list
git log --oneline --decorate --all --max-count=20
```

集成提示词：

```text theme={null}
先只读检查阶段 2/3 提交哈希、文件范围、未提交修改、Worktree 分支占用和审查阻塞项。
输出集成顺序和冲突风险，不要 merge 或 rebase。
```

获批后：

```text theme={null}
批准在集成 Worktree 合并阶段 2 和阶段 3。
合并前后运行 git status；冲突立即停止，不自动选 ours/theirs。
合并后运行 npm test、npm run lint、npm run typecheck、npm run build。
```

最终验收：

* D1-D7 每项都有文件、命令、退出码或测试名称作为证据；
* `git diff --check` 通过，diff 只含批准文件；
* 分页、筛选、部分更新和旧行为都被测试；
* 错误状态、响应体和状态码符合契约；
* 没有 `.env`、令牌、日志、缓存、意外锁文件或生成目录；
* 没有未解决审查意见；
* 回滚到基线、阶段提交或补丁的路径清楚。

最终验收提示词：

```text theme={null}
请按 D1-D7 逐项验收，不要只说“完成”。每项提供证据；不能证明标记 UNVERIFIED，失败标记 BLOCKED。
检查未批准文件、敏感值、外部调用、数据库变更、临时产物和公共 API 兼容性。
最后给出交付、返工或回滚建议；不要 commit、push、merge 或 release。
```

## 11 回滚、恢复和阶段性交付

阶段记录应包含：

```text theme={null}
阶段：2 数据层
完成：分页、completed/tag 筛选、PATCH 部分更新
变更：3 个批准文件
验证：npm test -- repository，12 passed
未完成：真实数据量性能未验证
风险：page_size 上限仍需确认
回滚点：1ab42ef / phase-2.patch
下一步：阶段 3，等待批准
```

失败分三类：

1. **未提交 Worktree**：保存 `git status`、`git diff --stat` 和补丁；确认目录没有他人修改后按文件恢复或废弃临时 Worktree。
2. **已提交未合并分支**：保留提交哈希，不合并失败阶段；需要修复时创建新提交，不能改写共享历史。
3. **已进入共享分支或外部系统**：使用新的反向修复提交；数据库使用项目已有回退迁移、备份恢复或补偿迁移，Git 回滚不能撤销已经写入的数据。

测试失败也要分类：断言失败是代码或契约问题；缺依赖是 setup 问题；端口占用是资源冲突；网络超时不是循环重试理由；权限拒绝应检查审批，不要扩大权限。

阶段交付表：

| 阶段 | 交付物            | 是否可合并 |
| -- | -------------- | ----- |
| 0  | 基线命令和结果        | 否     |
| 1  | 契约、任务图、风险      | 否     |
| 2  | 数据层 diff、测试、提交 | 待审    |
| 3  | 路由、接口测试、构建     | 待审    |
| 4  | 正确性、兼容性、测试审查   | 否     |
| 5  | 集成 diff 和完整验收  | 待交付   |
| 6  | 获批的本地提交或 PR    | 是     |

## 12 最终交付提示词和速查

```text theme={null}
进入交付前审查，只读。检查当前 diff、提交历史、测试输出和契约：
范围是否准确，公共 API 是否兼容，测试是否验证用户行为，是否有敏感文件或构建产物，审查意见是否关闭，回滚点是否明确。
输出最终报告和 BLOCKED 项；不要 commit、push、merge 或 release。
```

人工查看：

```bash theme={null}
git status --short
git diff --stat
git diff --check
git diff -- src/routes/todos.ts src/services/todo-service.ts
git diff -- test/
```

本地提交也要单独批准：

```text theme={null}
批准创建一个本地提交。提交前列出暂存文件、提交信息和测试结果。
仅包含 TODO API v2 批准文件；暂不批准 push、merge、数据库迁移和生产发布。
```

全流程速查：

```text theme={null}
工作区检查
→ 计划模式
→ 契约审批
→ 只读探索
→ 任务拆分
→ Worktree 隔离
→ 阶段实现
→ 子代理审查
→ 集成
→ 完整验收
→ 人工批准
→ 提交/发布
```

每条实现提示词都应写出：背景目标、文件范围、不可变契约、允许/禁止动作、验证命令、停止条件、预期输出、验收证据和回滚点。每次并行前都确认任务独立、写入目录隔离、分支不重复检出、资源可隔离、主代理保留最终决策权。

## 小结

可靠的 TODO API 协作不是让更多代理同时工作，而是让每个代理拥有明确边界，让每个阶段都能被证明、暂停和恢复：计划模式负责暴露未知事项；契约负责统一实现和测试；只读子代理负责并行探索与审查；Worktree 负责隔离并行写入；审批负责拦住联网、数据库、删除、提交和发布；集成阶段负责最小解决冲突；阶段提交和补丁负责恢复。

迁移到其他项目时，只替换 API 契约、文件路径和验证命令，仍然遵循“先读后写、先契约后实现、先隔离后并行、先证据后交付”。

参考资料：`参考/codex/34-capstone.md`、`参考/codex/14-workflows.md`、`参考/codex/21-subagents.md`、`参考/codex/25-worktrees.md`。