从 Issue 到实施计划：让 AI 先理解再动手
摘要
Issue 通常只描述问题或目标，不会直接告诉 AI 编程助手应该修改哪些文件、采用什么实现顺序以及怎样证明改动有效。直接让助手"处理这个 Issue"，很容易在没有理解调用链、数据约束和测试现状之前就开始编辑。
把 Issue 转换成实施计划，可以把一次代码变更拆成调查、设计、实现、验证和交付几个阶段。计划不是为了增加流程，而是为了让影响范围、技术决策、失败条件和完成证据在改代码之前变得可见。
一、背景与问题
一个典型 Issue 可能只有几句话：
text
订单列表接口太慢，请优化查询，并补充测试。这段描述至少缺少五类信息：慢在哪里、当前耗时是多少、哪些结果必须保持一致、允许修改数据库还是只能改应用层、测试需要覆盖什么。AI 编程助手如果直接执行，只能根据文件名和常见经验猜测。
猜测会在几个地方放大风险。它可能给查询加上不匹配的索引，改变分页顺序，删掉看起来无用的关联表，或者把测试改成更容易通过的断言。即使最终代码能编译，也不代表它解决了真实瓶颈。
实施计划的第一目标不是选出最复杂的方案，而是先把未知事实列出来，用代码、日志、配置和测试逐项确认。对需要业务决策的地方，计划应停下来等待确认，而不是让助手替你定案。
二、核心概念
1. Issue、调查结论和实施计划
| 内容 | 回答的问题 | 产生时间 |
|---|---|---|
| Issue | 为什么要改，用户看到了什么问题 | 任务开始前 |
| 调查结论 | 当前代码怎样运行，证据在哪里 | 只读调查阶段 |
| 实施计划 | 按什么顺序改哪些文件，怎样验收 | 动手前 |
| 变更 diff | 实际改了什么，是否超出计划 | 实施后 |
Issue 是目标输入，不是完整技术方案。调查结论必须区分事实、推断和待确认问题。实施计划则应把已确认的事实转成可执行步骤，每一步都能对应文件、测试或命令。
2. 计划的最小组成
一份可执行计划至少包含：
- 目标与非目标：这次要改变什么，明确不处理什么；
- 现状与调用链：入口、核心逻辑、数据来源和下游影响；
- 变更文件：每个文件为什么要改，预计增加或删除什么；
- 技术决策：方案选择、替代方案和选择理由；
- 风险与停止条件：遇到哪些情况必须暂停并报告；
- 验证矩阵：每项需求由什么测试、检查或观测结果证明；
- 交付边界：是否允许提交、推送、迁移数据库或部署。
"修改 OrderMapper.xml"只是文件名，不是计划步骤。更具体的写法是"删除无关投影和排序，保留分页语义；先用查询计划确认索引是否被使用，再运行订单列表的分页、权限和空结果测试"。
三、工作原理
让 AI 先理解再动手，可以使用下面的阶段门：
text
读取 Issue 和工作区状态
↓
只读调查：入口、调用链、数据、测试、运行命令
↓
列出已确认事实、假设、冲突与待确认问题
↓
形成最小实施计划与验收矩阵
↓ 人工确认高风险决策
分阶段修改 → 聚焦验证 → 完整回归 → 审查 diff第一道门阻止助手在错误目录或错误分支工作。第二道门要求它拿证据说明"为什么改这里"。第三道门把计划中的每个验收项变成可执行检查。计划确认后仍要根据实际代码调整，但任何超出范围的变化都要重新说明原因。
计划粒度要能支持红到绿：修改前应知道哪个测试或检查会失败，修改后应知道什么结果代表通过。对于性能问题，还应先记录基线和数据规模；没有基线，就无法证明优化是否带来收益。
四、实战示例
1. 从一个性能 Issue 开始
原始 Issue：
text
订单待处理数量接口经常超时，请优化 SQL。先要求助手只读调查：
text
请先不要编辑文件，也不要运行会写入数据的命令。
围绕"订单待处理数量接口经常超时"完成只读调查：
1. 找到 HTTP 路由、控制器、服务、Mapper 和前端调用位置；
2. 贴出当前 SQL 的表、条件、JOIN、排序和参数；
3. 找到最近一次可用的慢查询日志或调用耗时记录；
4. 列出相关索引和已有测试；
5. 检查当前工作区的未提交改动。
输出四部分：已确认事实、待确认问题、影响文件、建议验证命令。
如果没有生产 EXPLAIN 或真实数据量，请明确标记为未验证。调查结果不应只写"SQL 复杂、可能缺索引"。至少要说明请求入口、SQL 位置、条件字段、关联关系、测试现状和证据缺口。例如，若 SQL 为 COUNT(*)，却包含无关业务表的 JOIN、投影和 ORDER BY，可以把它列为优化假设；是否能删除 JOIN，仍需核对权限和业务过滤逻辑。
2. 形成实施计划
基于调查结果，可以要求助手生成如下计划：
text
目标：降低 /workflow/task/getTaskWaitCount 的数据库查询耗时，保持返回数值和权限语义不变。
已确认：
- 路由由 TaskController 调用 TaskService，再进入 ActTaskMapper.xml；
- 当前查询只返回 COUNT，但包含与待处理条件无关的关联和排序；
- 前端每 10 秒轮询一次；
- 没有生产 EXPLAIN ANALYZE，索引收益尚未验证。
非目标：
- 不改变待处理定义；
- 不修改任务状态表结构；
- 本次不引入缓存，不调整前端轮询周期。
计划：
P1. 在 Mapper XML 中保留必要过滤条件，移除不影响计数的投影、排序和关联；
P2. 检查 task status、assignee、tenant 等过滤字段的现有索引，提出索引候选但不直接执行生产 DDL；
P3. 为空结果、租户隔离、权限过滤和多条数据补充测试；
P4. 运行聚焦测试、完整测试和 git diff --check；
P5. 输出 SQL 差异、测试结果、未验证的 EXPLAIN 和剩余风险。
停止条件：
- 发现 JOIN 参与权限过滤；
- 现有测试与 Issue 中的待处理定义不一致；
- 需要修改数据库结构或生产配置；
- 预计改动超出 Controller、Service、Mapper 和测试文件。
交付边界：不提交、不推送、不执行生产数据库写入。计划中把"索引候选"和"执行索引 DDL"分开，是因为它们的风险不同。应用层可以在测试环境验证，生产 DDL 需要容量、锁影响、回滚和发布窗口等额外决策。
3. 用计划指导分阶段执行
确认计划后，不要把所有阶段重新压缩成一句"开始做"。可以逐阶段交办：
text
只执行 P1。编辑前先展示将修改的 SQL 片段和保留的过滤条件。
修改后运行 Mapper 对应测试，不要执行数据库迁移。
输出修改文件、SQL 变化和实际测试结果；如果测试环境缺失，停止并说明。第一阶段完成后，再交办测试和检查。这样可以在 SQL 语义发生偏移时及时停止，避免助手继续修改缓存、前端和数据库，把一个可控问题扩展成跨系统改造。
4. 计划模板
text
任务目标：
非目标：
当前基线：<分支、工作区、运行命令、耗时或失败现象>
真实入口：<路由/命令/任务消费者>
调用链：<入口 → 服务 → 数据/外部系统 → 响应>
已确认事实：
待确认问题：
影响文件：<文件 + 修改理由>
方案与取舍：
实施步骤：P1...Pn
每步验收：<测试/检查/预期结果>
风险与停止条件：
禁止动作：<提交、推送、部署、生产写入>
最终交付：<diff、命令、结果、未验证项>五、常见问题与实践建议
1. 计划看起来完整，但没有证据
"检查性能""补充测试"都不是可执行验收。写清检查对象、命令、数据规模和通过条件；无法获取生产数据时，明确写"未验证"，不要用本地小数据的结果代替生产结论。
2. AI 把推断写成事实
要求输出"证据位置"。没有日志就写没有日志，没有测试就写没有测试；不要因为计划中出现了一个文件名，就把它当成真实入口。
3. 计划过于详细，反而锁死实现
稳定的不变量和验收标准应写死，具体实现可以保留合理空间。例如目标是减少数据库往返，就不必提前指定必须使用某个缓存；除非已有架构约束，否则让调查结果决定实现方式。
4. 只列成功路径
计划至少覆盖空值、异常、权限、重复请求、超时和回归行为。数据写入、支付、权限和迁移类任务，还要增加幂等、回滚和并发场景。
5. 把计划当成授权书
计划写了"可能执行迁移"不等于已经获得生产授权。高风险动作应单独确认，并在执行前再次展示命令、目标环境、影响范围和回滚方式。
六、进阶思考
计划可以成为 Issue、PR 和自动化任务之间的追踪桥梁。Issue 提供目标，计划绑定实现文件，测试绑定验收项，PR diff 绑定实际结果。出现回归时，可以判断是目标理解错误、计划遗漏，还是实现偏离。
对于长期项目，可以把高频计划模板写入 Issue 模板，把"先只读调查"做成 AI 助手的默认工作习惯，再用 CI 和分支保护落实必须执行的检查。需要强制执行的安全规则不要只放在提示词里。
复杂任务还可以分成"探索分支"和"实现分支"。探索阶段只记录调用链、实验数据和方案比较；实现阶段只采纳已经确认的结论。这样既能让 AI 快速搜索，也不会把临时实验直接混入正式功能。
结论
从 Issue 到代码变更，中间需要一座可审查的实施计划。先确认入口、调用链、数据约束和验证缺口，再列出范围、步骤、停止条件与交付证据；高风险决策单独确认，未验证的结论明确标注。
下一篇将把这套计划用于一次跨控制器、服务、数据访问和测试文件的完整功能开发，展示 AI 如何在多文件修改中保持边界和节奏。