| description | Codex 任务设计方法，说明如何写清目标、背景、范围、约束、验证和交付格式，让执行结果更稳定，减少返工。 |
|---|
任务设计决定 Codex 的工作质量。一个好任务会同时说明目标、上下文、范围、约束、验证方式和最终交付。
| 要素 | 写法 | 示例 |
|---|---|---|
| 目标 | 一句话说明结果 | 修复登录页刷新后状态丢失的问题 |
| 背景 | 给出现象和上下文 | 用户刷新页面后需要重新登录 |
| 范围 | 限定文件或模块 | 只修改 auth 模块和相关测试 |
| 约束 | 写明禁止事项 | 不改数据库 schema，不引入新依赖 |
| 验证 | 给出命令或检查方式 | pnpm test auth |
| 交付 | 要求复盘格式 | 总结根因、改动、测试和风险 |
模糊写法：
帮我优化登录逻辑。
清晰写法：
请修复登录页刷新后状态丢失的问题。
背景：
- 用户登录后刷新页面，会回到未登录状态。
- 期望刷新后仍能恢复已登录状态。
范围：
- 优先检查 `src/auth` 和相关测试。
- 不改数据库和后端接口。
验证：
- 运行 `pnpm test auth`。
- 如果需要新增测试，请覆盖刷新恢复状态的场景。
交付：
- 说明根因、改动文件、验证结果和剩余风险。
::: info 截图占位
请补充“模糊任务 vs 清晰任务”的对比截图。建议文件：docs/.vuepress/public/screenshots/cli/03-task-design-comparison.png。
:::
大任务建议拆成三步：
- 只读分析：让 Codex 找影响面。
- 方案确认：让 Codex 给出切分和验证方式。
- 分步实施：每次只做一个可验证改动。
模板：
请先不要修改代码。阅读 [模块/目录]，分析 [目标] 会影响哪些文件、接口和测试。请输出：
1. 影响面
2. 推荐实施步骤
3. 每一步的验证方式
4. 第一阶段最小改动建议
可以加上：
如果你需要推测，请明确标注“推测”。如果官方文档、代码和测试之间有冲突，请先停下来说明冲突。
这句话适合文档更新、版本升级、依赖迁移和跨模块改动。