前言

配套资源：AI 辅助开发检查清单资源包，里面包含任务 Brief、重构前风险评估、代码 Review、数据库改动和复盘模板。

上一篇文章里，我写到一个观点：快速 AI 迭代仍然需要操作纪律。

这篇文章想把其中最前置的一步单独展开：在让 AI 辅助开发之前，先写任务 Brief。

很多人使用 AI 写代码时，习惯从一句直接指令开始：

帮我重构这个模块。

或者：

帮我修一下这个 bug。

这类指令不是完全不能用。在小范围、低风险、上下文很清楚的任务里，它确实能让 AI 很快进入状态。

但一旦进入真实项目，尤其涉及业务逻辑、历史兼容、数据库、权限、缓存、接口行为时，这种指令就太薄了。

AI 可能很快开始改代码，但它并不知道哪些地方不能碰，也不知道这次任务到底只解决当前问题，还是可以顺手重构周边逻辑。

所以我现在更倾向于先写一份轻量的任务 Brief。

它不需要很长，但要把关键边界写清楚。

任务 Brief 解决的不是表达问题，而是协作问题

很多人会把 Brief 理解成“更长的提示词”。

我觉得这个理解不太准确。

任务 Brief 不是为了把 prompt 写得更复杂，而是为了让人和 AI 在开始之前对齐四件事：

1. 这次到底要解决什么问题。
2. 这次明确不解决什么问题。
3. 哪些改动有风险，哪些边界不能碰。
4. 最后用什么标准判断任务完成。

如果这些信息没有提前写出来，AI 会默认根据上下文和常见工程习惯自行补全。

问题在于，AI 补全出来的方案可能“技术上合理”，但不一定“工程上安全”。

比如你让 AI 重构一个支付相关模块，它可能会觉得抽象重复逻辑、统一异常处理、优化字段命名都是合理动作。但在真实项目里，这些动作可能牵涉历史数据、外部接口、审计日志、兼容旧客户端。

这些风险不写出来，AI 很难凭空知道。

所以任务 Brief 的价值不是让 AI 更聪明，而是减少它误判任务边界的空间。

没有 Brief 时，AI 容易出现的几类问题

1. 把小任务做成大重构

你原本只是想修一个 bug，AI 可能顺手调整了函数结构、变量命名、文件组织和公共工具函数。

这些改动单独看都不一定错，但它们会让 review 变得困难。

更麻烦的是，当测试失败或线上行为异常时，你很难判断问题来自 bug 修复本身，还是来自 AI 顺手做的重构。

2. 忽略历史兼容

真实系统里有很多看起来不优雅但暂时不能动的逻辑。

比如旧接口保留某个字段，某个状态值不能删除，某个异常分支是为了兼容历史数据。

AI 如果只从当前代码质量出发，很容易把这些东西当成“可以清理的坏味道”。

但工程里并不是所有坏味道都应该马上处理。

3. 先改代码，再反向解释

很多 AI 辅助开发会变成这样一个节奏：

1. 人给一个模糊目标。
2. AI 直接改代码。
3. 人发现问题。
4. AI 再解释为什么这么改。
5. 双方继续补丁。

这个流程的问题在于，关键判断发生得太晚。

更稳的方式应该是先让 AI 复述任务、识别风险、提出计划，再决定是否允许它动代码。

4. 验收标准不清楚

如果一开始没有定义验收标准，AI 很容易把“代码能跑”当成完成。

但真实开发里，完成不只是没有报错。

它还可能包括：

1. 原有接口行为不变。
2. 历史数据能兼容。
3. 权限逻辑没有绕开。
4. 关键测试通过。
5. 这次 diff 能被一次 review 看完。

这些标准如果不提前写出来，最后就会变成返工。

一个可复用的任务 Brief 结构

我现在会把 AI 辅助开发任务 Brief 控制在 7 个部分。

不需要每次都写得很正式，但这些问题最好在开始前过一遍。

1. 任务基本信息

先写清楚任务类型。

比如：

任务名称：修复订单列表筛选状态不准确的问题
任务类型：bug 修复
相关模块：订单列表、订单查询接口
相关代码路径：src/order/list、src/api/order

任务类型很重要。

因为新增功能、bug 修复、局部重构、大范围重构、数据库改动，对 AI 的使用方式不一样。

如果是 bug 修复，优先要求 AI 找复现路径和影响范围。

如果是重构，优先要求 AI 说明改动边界和回滚方式。

如果是数据库改动，就不应该让 AI 一次性把表结构和业务逻辑都改完。

2. 背景说明

背景说明回答的是：为什么现在要做这个任务。

这部分不用长，但要把隐性上下文说出来。

比如：

这个接口目前同时服务 Web 端和旧移动端。
旧移动端依赖 statusText 字段，短期不能删除。
本次问题只修复筛选条件错误，不调整返回结构。

这些信息对人来说可能是常识，但对 AI 不是。

尤其是“为什么不能顺手优化”，通常需要明确写出来。

3. 本次目标

目标要写成可以验收的结果。

不要只写：

优化订单查询。

更好的写法是：

1. 修复待支付状态下筛选结果包含已取消订单的问题。
2. 保持原有接口返回字段不变。
3. 补充或更新对应测试用例。

目标越具体，AI 越容易保持方向。

如果目标太抽象，AI 就会用自己的工程判断去扩展任务。

4. 明确不做什么

这一部分非常关键。

很多 AI 失控不是因为它没有完成目标，而是因为它完成目标时顺手做了太多额外事情。

所以 Brief 里应该写清楚本次不处理什么。

比如：

本次不重构订单模块整体结构。
本次不修改数据库字段。
本次不调整接口返回格式。
本次不处理优惠券相关逻辑。

“不做什么”可以显著降低改动面。

它也是后续 review 的依据：如果 diff 里出现了不该出现的修改，就可以直接要求回退或拆分。

5. 相关输入材料

AI 需要知道从哪里开始读。

不要只说“看一下项目”，而要给它更明确的入口。

可以包括：

1. 相关代码路径。
2. 错误日志。
3. 复现步骤。
4. issue 或需求说明。
5. 旧版本行为。
6. 已有测试用例。

这一步的目标是减少 AI 自己搜索上下文的随机性。

AI 当然可以读项目，但你给的入口越清楚，它越不容易绕远。

6. 风险边界

风险边界回答的是：哪些东西不能随便改。

常见边界包括：

1. 公共接口。
2. 数据库结构。
3. 历史兼容逻辑。
4. 权限判断。
5. 缓存逻辑。
6. 外部依赖。
7. 定时任务。

如果任务涉及这些内容，就不要让 AI 直接动手。

更稳的做法是先让它列出影响范围，然后再决定是否拆阶段处理。

7. 验收标准

最后要写清楚什么叫完成。

比如：

1. 指定复现步骤下问题不再出现。
2. 原有订单查询测试全部通过。
3. 接口返回字段保持兼容。
4. 本次 diff 只涉及订单查询相关文件。
5. AI 输出最终变更说明和验证结果。

验收标准不是形式主义。

它能防止开发过程变成“看起来改完了”。

给 AI 的起始提示词

有了 Brief 之后，我通常不会马上让 AI 写代码，而是先给它一个阅读和计划任务。

可以这样开始：

你现在要参与一个真实项目的开发任务。请先不要直接修改代码。

请先完成以下事情：
1. 阅读我提供的背景、目标、代码路径和风险边界。
2. 复述你对任务的理解。
3. 列出你认为还缺少的上下文。
4. 梳理可能影响的模块和风险点。
5. 给出分阶段实施计划。

只有在我确认计划后，才开始修改代码。

这个提示词的重点不是“措辞多高级”，而是先把 AI 从执行模式拉回分析模式。

在真实工程里，很多任务不应该一上来就改。

先读、先复述、先列风险，再动手，往往比直接生成代码更省时间。

一个简单例子

假设你要让 AI 修复一个筛选 bug。

不太稳的写法是：

帮我修复订单列表筛选 bug。

更稳的 Brief 可以是：

任务类型：bug 修复

背景：
订单列表的状态筛选在选择“待支付”时，会把部分“已取消”订单也查出来。
该接口同时服务 Web 管理端和旧移动端，返回字段不能调整。

目标：
1. 修复待支付筛选条件。
2. 保持接口返回结构不变。
3. 补充对应测试。

不做：
1. 不重构订单模块整体结构。
2. 不修改数据库字段。
3. 不调整权限逻辑。

输入材料：
1. 相关接口：GET /api/orders
2. 代码路径：src/order/query
3. 复现步骤：选择待支付状态，查询结果包含已取消订单。

风险边界：
1. statusText 字段旧移动端仍在使用，不能删除。
2. 缓存 key 规则不能调整。

请先不要修改代码。
先阅读相关代码，复述任务理解，列出影响范围和实施计划。

这段 Brief 看起来比一句 prompt 长，但它能节省后面的沟通成本。

AI 如果准备修改接口返回结构，你可以立刻拦住。

AI 如果准备重构整个查询模块，你也可以要求它缩小范围。

Brief 不需要写得很重

这里也要避免另一个极端：不是所有任务都要写成正式文档。

如果只是改一个文案、补一个简单测试、修一个局部样式问题，Brief 可以非常轻量。

比如只写四行：

目标：修复按钮 loading 状态下仍可重复点击的问题。
范围：只改 Button 组件和对应测试。
不做：不调整设计样式，不修改调用方。
验收：重复点击只触发一次提交，现有测试通过。

关键不在于篇幅，而在于有没有把边界写出来。

AI 辅助开发越快，越需要这种边界感。

任务 Brief 和提示词的关系

我现在更倾向于把两者分开看。

提示词解决的是“这一次怎么跟 AI 说”。

任务 Brief 解决的是“这件事本身有没有被定义清楚”。

如果任务本身没定义清楚，再好的提示词也只能让 AI 更流畅地跑偏。

反过来，如果 Brief 写得清楚，提示词反而可以很朴素。

你只要让 AI 先阅读 Brief、复述理解、列风险、给计划，后面的协作就会稳定很多。

这也是我前面说的：AI 工作流的下一步不是更多提示词，而是更清楚的任务模式。

这篇文章配套的资源包

我把这篇文章里的任务 Brief，以及前后相关的检查清单，整理成了一个资源包：

AI 辅助开发检查清单资源包

里面包括：

1. AI 辅助开发任务 Brief 模板
2. AI 重构前风险评估表
3. AI 代码变更 Review 检查清单
4. 数据库改动两阶段检查清单
5. AI 辅助开发复盘模板
6. CSV 表格版清单

如果你经常使用 Claude Code、Codex、Cursor、ChatGPT、Copilot 这类工具参与开发，可以把任务 Brief 当作每次开发前的入口模板。

它不保证 AI 一定不会犯错，但能显著减少任务边界不清带来的返工。

总结

AI 辅助开发前先写任务 Brief，本质上不是增加流程，而是把关键判断前置。

不要等 AI 改完一堆代码之后，再去解释哪些地方不能动。

更稳的方式是，在开始之前就写清楚：

1. 这次做什么。
2. 这次不做什么。
3. 哪些地方有风险。
4. 从哪里读取上下文。
5. 怎么判断完成。

我的当前结论是：

AI 写代码前，先让任务变得可控。

当任务边界清楚，AI 的速度才更容易变成工程收益；当任务边界模糊，AI 的速度只会更快地放大混乱。