摆脱模糊需求，用结构化任务卡让 AI 编程效率翻倍

---

一、为什么你的 AI 总是“猜错”？

很多开发者用 AI 编程时，常常遇到这些情况：

• AI 顺手重构了无关代码
• 改动了不该动的组件或配置
• 忽略了边界条件，交互状态混乱
• 代码能跑，但业务逻辑不对

问题的根源不是 AI 不会写代码，而是它不知道：

• 哪些文件可以改？哪些绝对不能动？
• 数据从哪来？交互状态如何流转？
• 什么结果才算完成？

当你只给一句模糊的需求时，AI 只能靠猜。猜错，就成了必然。

任务卡 就是解决这个问题的钥匙。

---

二、什么是任务卡？

任务卡不是普通需求文档，也不是一句 Prompt，它是一种面向 AI 执行的结构化任务说明。

比如，需求是“修改明信片区域并增加点击放大”，普通描述可能只有一句话，而任务卡则会明确：

# 任务目标
修改 10 周年报告页明信片区域，给 PageHeader 增加 BGM 控制

# 修改范围
允许修改：ReportScreen.tsx、PageHeader.tsx
禁止修改：路由、其他页面、全局样式、无关组件

# 交互规则
点击明信片→进入预览状态
预览状态下隐藏背景滚动明信片
点击预览区域→关闭预览
……

# 验收标准
- 第一行 5 张、第二行 5 张、第三行 6 张
- 横版和竖版预览样式不同
- PageHeader 自动播放音乐，可暂停/继续

任务卡的核心思想是：让 AI 少猜，按结构执行。你从“写一段自然语言作文”变成了“填写一张执行卡片”。

---

三、任务卡的标准结构

一张高质量的任务卡通常包含 10 个部分，你可以根据任务复杂度灵活选用：

1. 任务目标 — 一句话描述要做什么
2. 修改范围 — 明确允许和禁止修改的文件/模块
3. 背景上下文 — 当前功能状态、为什么要改
4. 输入资料 — 设计稿、接口文档、资源文件、参考代码
5. 数据结构 — 用代码形式给出接口字段、配置数组等
6. 业务规则/交互规则 — 用户操作如何影响状态
7. 边界情况 — 空数据、重复点击、加载失败等
8. 技术要求 — TypeScript、最小改动、不引入新依赖等
9. 禁止事项 — 明确告诉 AI 不要做什么
10. 验收标准 — 可勾选的完成清单

小任务可以简化，大任务尽量完整。 像“改个按钮文案”直接指定文件和内容即可，而新增支付、重构模块等复杂任务则必须完整覆盖以上要素。

---

四、写好任务卡的五大原则

1. 写结果，不要只写过程

❌ 差：“用 useState 控制弹窗”
✅ 好：“点击按钮打开弹窗，关闭后页面恢复原状态，刷新页面后弹窗不保留打开状态”

2. 写边界，不要只写正常路径

不仅描述“用户点击提交创建订单”，还要补充：未登录跳转、库存不足提示、重复点击防重、接口失败恢复按钮等。

3. 明确禁止事项

AI 热爱“主动优化”，必须明确告知：“不要重构无关代码”“不要修改接口协议”“不要引入新依赖”。这会大幅降低 review 成本。

4. 资源用结构化数据表达

❌ “第一张图是 xxx，第二张图是 xxx”
✅ 直接给数组或对象配置：

const tabs = [
  { key: 'all', label: '全部' },
  { key: 'pending', label: '待付款' }
]

AI 对结构化数据的执行稳定性远高于自然语言。

5. 要求 AI 自检

任务卡末尾必须包含：“改完后请输出修改文件列表、实现说明、验收清单、运行过的检查命令、未解决风险”。这能极大减轻你的验收压力。

---

五、三大实用模板（直接套用）

模板一：前端 UI / 交互任务卡

# 任务目标
给订单详情页增加“复制订单号”按钮

# 修改范围
允许：src/pages/OrderDetail/index.tsx
禁止：接口、其他区域

# 交互规则
- 点击按钮复制 orderNo
- 复制成功后 toast 提示“复制成功”
- orderNo 为空时不显示按钮

# 边界情况
- 剪贴板 API 不可用时降级处理
- 短时间内多次点击只触发一次

# 技术要求
最小改动，不引入新依赖

# 验收标准
- [ ] 有订单号时显示按钮
- [ ] 点击后复制成功
- [ ] 无订单号时不显示
- [ ] 原有功能不受影响

模板二：后端接口任务卡

# 任务目标
新增用户申请退款接口 POST /api/refunds/apply

# 业务规则
- 只有已支付订单可退款，已发货订单需人工审核
- 同一订单只能有一个进行中的退款申请
- 退款金额 ≤ 实付金额

# 幂等与事务
- 重复提交不创建多条记录，利用数据库唯一索引防重
- 创建退款记录和更新订单状态在同一事务中

# 权限
- 用户只能操作自己的订单，管理员可操作所有
- 未登录 401，无权限 403

# 验收标准
- [ ] 正常申请成功
- [ ] 订单不存在/未支付/已退款等错误码正确
- [ ] 并发请求不会重复创建
- [ ] 事务回滚验证

模板三：Bug 修复任务卡

# Bug 描述
订单列表快速切换筛选条件，偶现显示上一次结果

# 复现步骤
1. 打开订单列表
2. 快速点击“全部”→“待支付”
3. 列表可能仍然显示“全部”数据

# 初步判断
请求竞态问题

# 修复要求
- 只处理竞态，不重构列表页
- 可使用 AbortController 或请求 ID

# 执行方式
先分析当前请求流程、可能原因及修复方案，确认后再改代码

# 验收标准
- [ ] 快速切换后列表始终与当前 tab 一致
- [ ] loading/空状态正常
- [ ] 不影响分页和下拉刷新

---

六、执行方式：先方案，再编码

很多人在任务卡里只写需求，然后让 AI 直接改代码，结果反复返工。推荐加入“执行方式”控制节奏：

# 执行方式
先不要改代码，请先输出：
1. 你对需求的理解
2. 当前代码结构分析
3. 计划修改的文件及具体方法
4. 可能的风险点
5. 需要我确认的问题

等我确认后再开始修改。

对于小任务可让 AI 直接改，但中大型任务务必先出方案。这会把 AI 从“直接生成代码”提升为“可管理的执行者”。

---

七、建立你的任务卡库

建议在项目里建立 docs/ai-task-cards/ 目录，存放常用模板：

• frontend-ui-task.md
• backend-api-task.md
• bugfix-task.md
• refactor-task.md

以后每次派任务，复制模板填充，效率远胜从零手写。

---

八、派任务前的自我检查清单

每次给 AI 任务前，问自己 8 个问题：

1. 这次到底要改什么？
2. 哪些文件允许改？
3. 哪些文件绝对不能改？
4. 输入资料有哪些？
5. 数据结构是什么？
6. 状态如何变化？
7. 有哪些边界情况？
8. 什么结果算完成？

如果答不上来，先别让 AI 写代码。 因为你都没想清楚的事，AI 大概率会猜错。

---

九、总结：做“任务设计者”，而非“代码保姆”

低效模式：你写模糊需求 → AI 乱改 → 你逐行检查 → 手动修 → 再让 AI 改
高效模式：你写结构化任务卡 → AI 先出方案 → 你确认边界 → AI 实现并自检 → 你只验收关键结果

任务卡的真正价值，是把你的思考前置，用明确的边界和标准指导 AI，从而减少返工，让 AI 从一个“猜谜式的代码生成器”，变成一个可预测、可管理的高效执行者。

一张好任务卡，应让 AI 明确知道：

• 我要做什么
• 能改哪里，不能改哪里
• 输入资料与数据结构
• 业务规则和状态流转
• 边界情况
• 完成标准与自检要求

当你稳定写出这样的任务卡，AI 编程才能从“玩具”变成“工具”，真正融入你的开发工作流。