tasks.md 是从规划进入执行的导航图。proposal 已经确定范围，delta spec 已经定义行为，design 已经说明方案，tasks 再把这些信息转换成可以逐项实现、验证和勾选的工作。

它既不是简单待办清单，也不是项目进度表截图。每个任务都应该指向一个可交付结果，并能用代码、测试或命令证明完成。Codex 的 apply 流程会读取未完成项，按顺序推进，并在每项完成后立即更新复选框。

📷 [图片 token=VdJyb1xLsoqOAIxhOJAcVDcYnuc（未能下载，见飞书原文）]

典型组织结构

## 1. Embedding 批处理兼容

- [ ] 1.1 将默认客户端单批数量限制为 10
- [ ] 1.2 增加客户端批量行为单元测试

## 2. 文档索引回归覆盖

- [ ] 2.1 增加超过 10 个 chunk 的索引回归测试
- [ ] 2.2 运行 Ruff、Pyright、Pytest 和 OpenSpec 验证

一级分组按照纵向交付范围组织，而不是机械按“后端、前端、测试”分开。主案例第一组完成 Provider 兼容性，第二组证明整个索引流程没有丢数据。编号让讨论和更新更精确，复选框保存执行状态。

📷 [图片 token=XX1FbGg7UoeMXgxIDv9cyipwnye（未能下载，见飞书原文）]

任务粒度怎样才合适

过粗的任务，例如“完成 Embedding 修复”，无法判断包含哪些代码、测试和验收；过细的任务，例如“打开 provider.py”“输入一行常量”，又会把执行过程切得支离破碎。

合适的任务通常对应一个可以独立说明的结果：建立一项约束、同步一个契约、增加一组测试、完成一次迁移或运行一组门禁。它不一定等于一次 Git commit，但应该能够在完成后马上验证。

主案例的四项任务非常紧凑：实现批量上限；验证默认客户端的配置与行为；验证大文档索引完整；运行质量门禁。每一项都能与 proposal、design 和 spec 建立对应关系。

📷 [图片 token=RQvzboKGQo81k0xj1B9cxQw1nto（未能下载，见飞书原文）]

为什么测试和验证必须写进 tasks

如果 tasks 只列“写代码”，Codex 很容易在实现结束时提前宣布完成。把测试与验证写成显式任务，意味着交付定义从“文件已修改”提升为“行为已有证据”。

OncallAgent 的检查要按影响范围选择。Python 后端通常涉及 Ruff、strict Pyright 和 Pytest；前端涉及 TypeScript 类型检查、Vitest 和构建；API/SSE 变化至少还要检查共享契约和双方消费；数据库变化要验证 Alembic upgrade；OpenSpec 结构运行 openspec validate --all；WIKI 变化运行 npm run docs:build。

不能为了勾选任务而删除测试、弱化断言或跳过类型检查。没有环境或外部服务时，应把验证标为未执行并说明原因，而不是把计划命令写成通过结果。

📷 [图片 token=Ui6xbVvcvoA6ByxWYyKcH5Hen9g（未能下载，见飞书原文）]

apply 怎样使用 tasks

openspec-apply-change 先读取 openspec status 和 openspec instructions apply 返回的 contextFiles，再了解总任务数、已完成数和动态指令。它不能只读 tasks 而忽略 proposal、design 和 specs，因为同一句任务需要这些上游产物解释意图和边界。

执行循环是：选择一个 pending task；完成最小且聚焦的修改；运行相关验证；把 - [ ] 改为 - [x]；继续下一项。需求不清、实现暴露设计问题或验证失败时，应暂停并回到产物修正，而不是为了清空清单继续猜。

📷 [图片 token=LFItboLTQo57XnxdJRLcJhPYnJe（未能下载，见飞书原文）]

复选框能证明什么，不能证明什么

[x] 表示该 change 的历史记录声称任务已经完成。它有助于恢复进度和归档检查，但不能独立证明当前代码仍然通过测试。代码可能在后续 change 中演进，运行环境也可能改变。

主案例 tasks 的四项均已勾选，这是归档时的历史状态。本次教学整理没有重新运行 Ruff、Pyright、Pytest 和 OpenSpec CLI，所以不能把历史勾选表述成本轮验证结果。

📷 [图片 token=XWjAbtyyzo0ZMvxJ3lHc9ALVnJe（未能下载，见飞书原文）]

怎样从 spec 反推 tasks

可以逐个 Scenario 问：需要哪一层实现、哪一层测试、是否有配置或迁移、是否影响契约和 UI。主案例三个 Scenario 对应：

小输入单批与大输入 10+1 拆分，需要 Provider 行为测试；保持向量顺序，需要对输出顺序断言；大文档 succeeded 且全部 chunk 落库，需要索引服务回归测试；所有变化还要经过静态检查和 OpenSpec 验证。

这种映射能发现漏项。如果 spec 有越权拒绝场景，而 tasks 没有授权测试；或者 design 决定增加迁移，而 tasks 没有 upgrade 测试，说明任务清单还不完整。

📷 [图片 token=TWCTbh9ZEo3RXyxFUrsctT4enqc（未能下载，见飞书原文）]

常见错误

**先写 tasks，再补 spec 和 design。**任务会被当前直觉绑架，容易遗漏行为和边界。

**用“完成全部开发”作为单一任务。**无法追踪，也无法在中断后恢复。

**只勾框，不保存验证依据。**复选框是进度，不是测试日志。交付说明仍需列出实际运行命令和结果。

**把无关重构塞进任务。**tasks 必须受 proposal Impact 和 design Non-Goals 约束。

📷 [图片 token=HJkRbS6njoyaVzxY9bBcmvernWd（未能下载，见飞书原文）]

面试表达

tasks 不是把需求切成“后端一项、前端一项”，而是把规格与设计转换成可验收的纵向步骤。apply 每完成一项就验证并勾选，verify 再检查任务、Scenario 和实现证据。复选框保存历史进度，但我不会把它当成当前测试通过的替代品。