---
description: "Codex 任务设计方法，说明如何写清目标、背景、范围、约束、验证和交付格式，让执行结果更稳定，减少返工。"
---

::: tip 最后核对
官方资料最后核对日期：2026-06-29。本文是 Codex 任务设计方法总结，涉及上下文、指令、验证和安全边界时，请参考 [Codex 文档入口](https://developers.openai.com/codex/)、[AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) 与 [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)。
:::

# 任务设计

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

## 任务六要素

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

## 从模糊到清晰

模糊写法：

```text
帮我优化登录逻辑。
```

清晰写法：

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

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

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

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

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

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

## 大任务拆分

大任务建议拆成三步：

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

模板：

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

## 让 Codex 主动暴露不确定性

可以加上：

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

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

## 下一步

下一步：[任务执行与验证闭环](./08-task-execution.md)。