高质量任务描述模板:从模糊意图到结构化指令

为什么需要模板?

先看一组对比——同一个需求,模糊描述 vs 模板化描述的 Codex 输出差异:

输入方式示例Codex 典型反应结果
模糊描述"优化一下这个页面"追问"优化什么?性能?UI?可访问性?"来回 3 轮才开始干活
半结构化"首页加载太慢,看看能不能优化"会分析性能,但不确定范围可能改了你不想改的地方
模板化目标 + 背景 + 范围 + 约束 + 验证直接分析 LCP/CLS,输出优化方案第一轮就在正确方向上
警告

提示词不是越详细越好,而是信息密度要高。模板的目的是确保关键信息不遗漏,不是让你写小作文。一个字段一句话就够了。

三个框架对比与选择

维度CRISPE六要素SCQA
全称Capacity / Role / Insight / Statement / Personality / Experiment目标 / 背景 / 范围 / 约束 / 验证 / 交付Situation / Complication / Question / Answer
字段数664
适合场景需要角色设定 + 实验性任务工程任务(有明确交付物)问题分析 + 方案设计
复杂度中等中等
学习成本需记住每个字段含义直觉友好,和工程思维对齐最简单,适合快速上手

按任务复杂度选框架:

任务复杂度推荐框架理由
简单(改个文案、修个小 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
文档编写SCQAD
探索性调研CRISPEE

模板 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。

选读建议:学会了任务模板,下一步是定义"做完了"——→ 验收标准。如果你的任务很简单、不需要多轮迭代,也可以直接跳到 实战案例库 看模板在真实场景中怎么用。