高质量任务描述模板:从模糊意图到结构化指令
为什么需要模板?
先看一组对比——同一个需求,模糊描述 vs 模板化描述的 Codex 输出差异:
| 输入方式 | 示例 | Codex 典型反应 | 结果 |
|---|---|---|---|
| 模糊描述 | "优化一下这个页面" | 追问"优化什么?性能?UI?可访问性?" | 来回 3 轮才开始干活 |
| 半结构化 | "首页加载太慢,看看能不能优化" | 会分析性能,但不确定范围 | 可能改了你不想改的地方 |
| 模板化 | 目标 + 背景 + 范围 + 约束 + 验证 | 直接分析 LCP/CLS,输出优化方案 | 第一轮就在正确方向上 |
警告
提示词不是越详细越好,而是信息密度要高。模板的目的是确保关键信息不遗漏,不是让你写小作文。一个字段一句话就够了。
三个框架对比与选择
| 维度 | CRISPE | 六要素 | SCQA |
|---|---|---|---|
| 全称 | Capacity / Role / Insight / Statement / Personality / Experiment | 目标 / 背景 / 范围 / 约束 / 验证 / 交付 | Situation / Complication / Question / Answer |
| 字段数 | 6 | 6 | 4 |
| 适合场景 | 需要角色设定 + 实验性任务 | 工程任务(有明确交付物) | 问题分析 + 方案设计 |
| 复杂度 | 中等 | 中等 | 低 |
| 学习成本 | 需记住每个字段含义 | 直觉友好,和工程思维对齐 | 最简单,适合快速上手 |
按任务复杂度选框架:
| 任务复杂度 | 推荐框架 | 理由 |
|---|---|---|
| 简单(改个文案、修个小 Bug) | 不需要模板,直接描述 | 模板 overhead 不值得 |
| 中等(功能开发、Bug 修复) | SCQA 或 六要素 | 快速结构化,不过度 |
| 复杂(多文件重构、架构决策) | 六要素完整版 | 字段完整,不容易遗漏关键约束 |
| 探索性(调研、方案设计) | CRISPE | 角色设定 + 实验性输出更合适 |
说明
不必三个全背。选一个最顺手的先用起来,用熟了再根据场景切换。团队协作时建议统一一个框架,减少沟通成本。
六要素框架详解
六要素最适合工程任务,因为它和开发思维天然对齐:
| 要素 | 要回答的问题 | 写法要点 |
|---|---|---|
| 目标 | 要达成什么结果? | 一句话,可验证 |
| 背景 | 为什么做这个?现状是什么? | 给出上下文,帮 Codex 理解动机 |
| 范围 | 改哪些文件/模块?不改哪些? | 明确边界,防止"顺手改了一堆" |
| 约束 | 有哪些限制? | 技术栈、兼容性、性能、不能动的地方 |
| 验证 | 怎么判断做完了? | 可执行的命令、测试、截图对比 |
| 交付 | 产出什么? | 代码、文档、测试、还是方案? |
完整示例——前端功能开发:
目标:在用户设置页新增"通知偏好"表单,支持邮件和站内通知的开关切换。
背景:当前用户只能在全局设置中开关所有通知,粒度过粗。产品要求支持按通知类型单独配置。设计稿见 @figma-notification-prefs。
范围:
- 改:apps/src/features/settings/components/NotificationPreferences.tsx(新建)
- 改:apps/src/features/settings/api/notification.ts(新增 API)
- 不改:全局通知组件、邮件发送服务
约束:
- 使用现有 @packages/ui 的 Switch 组件
- 兼容现有通知类型枚举(email / push / inApp)
- 表单需要响应式,移动端优先
验证:
- pnpm test -- --filter=settings 全部通过
- 在 375px / 768px / 1440px 三个断点检查布局
- 开关切换后立即生效,不需要刷新页面
交付:组件代码 + API 接口 + 单元测试
CRISPE 框架详解
CRISPE 适合需要角色设定或探索性的任务:
| 字段 | 含义 | 示例 |
|---|---|---|
| Capacity | 以什么角色/能力来执行 | "作为熟悉 Next.js App Router 的高级前端工程师" |
| Role | 具体职责 | "负责重构认证模块" |
| Insight | 背景信息和已知条件 | "当前使用 next-auth v4,计划迁移到 v5" |
| Statement | 具体要做什么 | "迁移 OAuth 提供商配置到新的 auth.ts" |
| Personality | 输出风格和偏好 | "代码注释用中文,遵循现有文件命名规范" |
| Experiment | 期望的输出格式 | "先给出迁移计划,确认后再实现" |
SCQA 框架详解
SCQA 适合问题分析和方案设计,结构最简洁:
| 字段 | 含义 | 示例 |
|---|---|---|
| Situation | 当前情况 | "首页 LCP 3.2s,超出 2.5s 目标" |
| Complication | 问题/挑战 | "主要瓶颈是 Hero 区域的未优化大图和阻塞渲染的 CSS" |
| Question | 需要解决什么 | "如何将 LCP 降到 2.5s 以下?" |
| Answer | 期望的输出 | "分析瓶颈并给出 3 个优化方案,标注预期效果和实现成本" |
按任务类型选模板
| 任务类型 | 推荐框架 | 模板编号 |
|---|---|---|
| Bug 修复 | 六要素(精简版) | A |
| 新功能开发 | 六要素(完整版) | B |
| 代码重构 | 六要素 + 影响面分析 | C |
| 文档编写 | SCQA | D |
| 探索性调研 | CRISPE | E |
模板 A:Bug 修复
目标:修复 [问题简述],使 [期望行为]。
背景:在 [环境/条件] 下,执行 [操作步骤] 时出现 [实际行为]。预期行为是 [期望行为]。
范围:
- 涉及文件/模块:[文件路径]
- 不涉及:[明确排除的范围]
验证:
- 复现步骤不再触发问题
- [相关测试] 通过
- 边界条件 [具体描述] 表现正确
模板 B:新功能开发
目标:实现 [功能名称],支持 [核心能力]。
背景:[为什么需要这个功能,当前痛点是什么]
范围:
- 新建:[文件/组件列表]
- 修改:[现有文件列表]
- 不涉及:[排除范围]
约束:
- 技术栈:[框架/库版本要求]
- 兼容性:[浏览器/设备/分辨率]
- 规范:[项目规范引用]
验证:
- [测试命令] 全部通过
- [视觉/交互检查点]
- [性能指标要求]
交付:[代码 / 测试 / 文档 / 截图]
模板 C:代码重构
目标:将 [模块/文件] 从 [当前状态] 重构为 [目标状态]。
背景:[为什么要重构——代码异味、性能瓶颈、可维护性问题]
范围:
- 重构目标:[具体文件/模块]
- 影响面分析:[列出依赖这个模块的其他模块]
- 不改:[明确排除]
约束:
- 公共 API 不变(或变更范围:[具体说明])
- 现有测试必须继续通过
- 不引入新依赖(或允许引入:[具体说明])
验证:
- 现有测试全部通过
- 新增测试覆盖重构引入的新逻辑
- [性能对比数据]
交付:重构代码 + 影响面报告 + 测试更新
模板 D:文档编写
S:[项目/模块] 目前缺少 [什么文档],导致 [什么影响]。
C:需要在 [时间/条件] 前完成,读者是 [目标受众]。
Q:如何编写一份 [文档类型],让 [目标受众] 能够 [达成什么]?
A:输出一份 [文档类型],包含 [章节列表],遵循 [风格指南]。
模板 E:探索性调研
Capacity:作为熟悉 [技术领域] 的工程师。
Insight:当前项目使用 [技术栈],面临 [决策问题]。
Statement:调研 [候选方案 A] vs [候选方案 B],对比 [维度列表]。
Personality:给出结论和推荐理由,不要只罗列信息。
Experiment:先输出对比表格,再给出你的推荐和理由。
模板的边界与反模式
| 反模式 | 问题 | 改进 |
|---|---|---|
| 复制模板不改 | 字段里留着占位符,Codex 困惑 | 哪怕一句话也比空字段好 |
| 过度约束 | 约束比目标还长,Codex 束手束脚 | 只写真正重要的约束 |
| 验证不可执行 | "代码要写好" | 改成具体命令或可观测行为 |
| 模板依赖症 | 简单任务也用完整模板 | 简单任务直接说,别套模板 |
警告
模板是起跑线,不是终点线。根据 Codex 的实际输出迭代你的模板——如果某个字段 Codex 从来不参考,就精简它;如果它总是追问某个信息,就把它加进模板。
验证清单
- 你的任务描述有明确的目标(一句话说清楚要做什么)
- 范围字段指定了改什么和不改什么
- 验证字段包含可执行的命令或可观测的行为
- 约束字段只写了真正重要的限制
- 简单任务没有过度模板化
FAQ
Q:每次都要写这么长吗?
不需要。简单任务(改个文案、修个样式)直接一句话描述就够了。模板主要用在中等复杂度以上的任务——当你发现 Codex 开始追问或偏离方向时,下次就用模板。
Q:三个框架之间选哪个?
团队统一用一个最好。如果只选一个,推荐六要素——它和工程思维最对齐,字段直觉友好,覆盖了大多数开发场景。CRISPE 适合探索性任务,SCQA 适合快速分析。
Q:Codex 不遵循模板结构怎么办?
先检查验证字段是否可执行——如果验证标准模糊,Codex 就没有"锚点"。然后在提示词开头加一句"请按以下结构回复",或在 AGENTS.md 中配置输出格式偏好。
说明
平台能力、套餐限制以 OpenAI Codex 官方文档为准;本文写于 2026-06-24。
选读建议:学会了任务模板,下一步是定义"做完了"——→ 验收标准。如果你的任务很简单、不需要多轮迭代,也可以直接跳到 实战案例库 看模板在真实场景中怎么用。