任务设计

任务设计决定 Codex 的工作质量。一个好任务会同时说明目标、上下文、范围、约束、验证方式和最终交付。

任务六要素

要素	写法	示例
目标	一句话说明结果	修复登录页刷新后状态丢失的问题
背景	给出现象和上下文	用户刷新页面后需要重新登录
范围	限定文件或模块	只修改 auth 模块和相关测试
约束	写明禁止事项	不改数据库 schema，不引入新依赖
验证	给出命令或检查方式	pnpm test auth
交付	要求复盘格式	总结根因、改动、测试和风险

从模糊到清晰

模糊写法：

帮我优化登录逻辑。

清晰写法：

请修复登录页刷新后状态丢失的问题。

背景：
- 用户登录后刷新页面，会回到未登录状态。
- 期望刷新后仍能恢复已登录状态。

范围：
- 优先检查 `src/auth` 和相关测试。
- 不改数据库和后端接口。

验证：
- 运行 `pnpm test auth`。
- 如果需要新增测试，请覆盖刷新恢复状态的场景。

交付：
- 说明根因、改动文件、验证结果和剩余风险。

截图占位

请补充“模糊任务 vs 清晰任务”的对比截图。建议文件：docs/.vuepress/public/screenshots/cli/03-task-design-comparison.png。

大任务拆分

大任务建议拆成三步：

1. 只读分析：让 Codex 找影响面。
2. 方案确认：让 Codex 给出切分和验证方式。
3. 分步实施：每次只做一个可验证改动。

模板：

请先不要修改代码。阅读 [模块/目录]，分析 [目标] 会影响哪些文件、接口和测试。请输出：
1. 影响面
2. 推荐实施步骤
3. 每一步的验证方式
4. 第一阶段最小改动建议

让 Codex 主动暴露不确定性

可以加上：

如果你需要推测，请明确标注“推测”。如果官方文档、代码和测试之间有冲突，请先停下来说明冲突。

这句话适合文档更新、版本升级、依赖迁移和跨模块改动。