让 AI Agent 接力开发中大型需求：一套可持续的多会话 Coding 工作流
AI Agent 已经很会写代码了。 但当一个需求跨越前端、后端、数据结构、兼容性与多轮验收时，真正困难的往往不再是"这一段代码怎么写"，而是：下一次会话还能不能准确接住上一次的工作。
最近我把自己处理中大型需求时逐渐形成的一套协作方法，整理成了一个开源 Skill：large-feature-ai-coding。
它不负责教 Agent 使用某个框架，也不替代项目自身的开发规范。它解决的是另一类问题：
如何把一个中大型需求，变成一组能够被不同 AI Agent、跨多个会话持续推进的工程工作。
这篇文章记录这套方法为什么出现、它解决了什么、应该如何正确使用，以及一次看似"Agent 没有立刻开始编码"的场景，为什么反而说明流程正在发挥作用。
一、AI Coding 的真正瓶颈，开始从写代码转向管理上下文
1.1 小任务里，Agent 几乎天然表现良好
如果任务足够明确，例如：
- 给一个表单增加校验
- 修复一个确定的空指针
- 为现有接口增加单元测试
- 调整一个组件的样式
Agent 通常可以在一次会话内完成：
任务边界、上下文和完成标准都能同时放进一个会话里。Agent 即使没有额外的协作方法，也很容易做对。
1.2 中大型需求不是"更大的小任务"
当需求开始具备以下特征，情况会迅速变化：
- 横跨前端、后端、数据库或多个业务模块
- 存在多个候选方案，需要先做技术决策
- 一次会话无法完成全部实现
- 实施过程中可能发现设计假设不成立
- 需要人工验收，并在验收后继续修复
- 不同时间、不同 Agent 需要接力开发
这时，直接告诉 Agent：
看起来已经说了"分阶段"，实际仍然把所有关键判断交给了当前会话：
- 当前到底处于设计、规划、开发，还是验收修复阶段？
- "分阶段"具体分成哪些工作包？
- 哪个工作包依赖哪个？
- 已经做完了什么？
- 哪些结论是经过验证的？
- 下一次会话应该从哪里继续？
如果这些状态只存在于聊天记录里，它们就很容易随着会话切换、上下文压缩或 Agent 更换而消失。
1.3 常见失败并不是代码写错，而是流程漂移
我观察到中大型 AI Coding 任务最常见的失败模式，往往是这些：
这些问题并不说明 Agent 不够聪明。恰恰相反，Agent 往往会非常积极地继续探索和编码。
问题在于：它缺少一套稳定的外部状态，用来判断此刻应该做什么、不应该做什么。
二、核心思路：把隐藏在聊天中的状态写进仓库
large-feature-ai-coding 的核心并不复杂：
把需求决策、执行顺序、进度状态、每次会话结果和验收变化，沉淀为与代码一起演进的文档集合。
它不是为了增加文档数量，而是为了让关键上下文脱离聊天记录，成为 Agent 可以重新读取的工程资产。
这套流程里，每类文档承担不同职责：
项目已经有自己的文档根目录或命名习惯时，应该遵循项目规范，不必强行使用上面的路径。
三、五类文档，分别解决五类上下文问题
3.1 Final Design：先固定"要做成什么"
最终设计文档负责定义稳定契约，而不是记录每一步如何施工。
它应该回答：
- 背景、目标与非目标是什么？
- 当前前后端代码链路如何运行？
- 最终用户行为是什么？
- 模块职责、接口和数据结构如何划分？
- 有哪些性能边界、兼容规则和明确排除项？
- 哪些约束在开发期间不能被悄悄改变？
如果存在多个候选方案，先在文档开头写评审结论：
- 每个方案解决了什么
- 风险在哪里
- 最终采用哪个方案
- 编码期间不能违反哪些约束
这样后续 Agent 不需要重新进行整轮方案讨论。
3.2 Execution Plan：把设计变成可认领的工作包
执行计划不是第二份设计文档。它是构建台账和多会话交接契约。
一份可用的执行计划至少需要包含：
- 工作包 ID、范围和依赖顺序
- 状态规则
- 进度台账
- 每个工作包的验证要求
- 关键工程约束
- 实施记录模板
- 下一次会话应该如何开始
推荐只使用少量明确状态：
一个典型的进度台账：
台账让 Agent 在会话开始时先定位状态，而不是再次漫游整个仓库。
3.3 Work Package：让一次会话有明确的停止位置
工作包应该足够小，能够在一次专注会话中完成实现、验证和记录。
好的工作包通常具备：
- 单一、清晰的目标
- 有限的代码影响范围
- 明确的输入依赖
- 可以独立验证的完成标准
- 完成后仓库仍处于可运行状态
不好的工作包则常常写成：
它看起来完整，实际上没有为 Agent 提供任何范围边界。
可以使用 PRE、BE、FE、QA、DOC、FIX 等前缀标识工作包，但前缀只是辅助。真正重要的是：一个工作包要有可以被验证的结束状态。
3.4 Implementation Record：让下一次会话知道"实际上发生了什么"
执行计划记录整体状态，实施记录记录某次会话的事实。
每次工作完成前，应该写下：
- 本次实现了什么
- 修改了哪些文件
- 接口或数据结构是否变化
- 执行了哪些验证命令
- 哪些内容还没有完成
- 下一次最适合继续哪个工作包
实施记录的价值，不是写一篇漂亮总结，而是让下一位 Agent 不依赖隐藏聊天上下文也能继续工作。
3.5 Feat / Fix Docs：把验收阶段的新变化重新纳入契约
中大型需求很少在第一次实现后就完全结束。人工自测、QA 或用户验收通常会发现：
- 新增交互要求
- 数据口径差异
- 边界条件遗漏
- 视觉或格式问题
- 回归缺陷
如果这些变化只存在于聊天里，最终设计和真实系统就会逐渐分离。
因此，验收后发现的变化也需要分类记录：
- 新增需求或交互增强写入
feat/ - Bug、回归或数据不一致写入
fix/
如果变化修改了原始契约，还要同步更新最终设计和执行计划。
四、最关键的能力不是拆任务，而是先判断当前处于哪个阶段
large-feature-ai-coding 首先要求 Agent 根据用户请求和仓库状态选择入口：
这张表看起来朴素，却是整套方法中最重要的部分。
因为 AI Agent 很容易把"积极行动"理解成"立即改代码"。而在大型需求里，当前阶段如果判断错了，越积极，返工可能越多。
五、一个真实的误区：有设计文档，不等于可以直接认领工作包
我最近遇到过一个很典型的场景。
仓库中已经存在最终设计文档，用户给出的指令大意是：
Agent 检查后发现：设计文档已经存在，但执行计划尚不存在。
此时，它没有立刻修改代码，而是准备先把设计转换成执行计划和进度台账。
表面看，它似乎"没有按要求开始开发"。但按照这套工作流，它的判断是正确的：
问题出在原始提示把两个阶段混在了一起：
- 创建执行计划、定义工作包。
- 认领工作包、开始开发。
没有执行计划时，所谓"认领工作包"并没有正式台账可以落地。设计文档中的实施建议也不能替代执行计划，因为它通常不包含准确状态、完成日期、验证结果和实施记录路径。
5.1 正确提示：先创建执行计划
5.2 正确提示：下一次会话再认领工作包
这两个提示的区别很小，但会显著改变 Agent 的工作质量。
PS: 实际使用中只要能正确引用 large-feature-ai-coding Skill，是不需要将 Prompt 写得这么详细的。
六、一次完整的多会话开发应该如何推进
假设需求是"为现有箱图增加可选的小提琴图，并先升级 ECharts v6"，一个合理的会话序列可能是：
每次会话开始时，Agent 都做相同的几件事：
- 读取最终设计和执行计划。
- 检查进度台账。
- 认领一个未完成且依赖已满足的工作包。
- 声明本次范围和预期产出。
- 检查相关代码与用户已有变更。
每次会话结束前，也做相同的收尾：
- 执行相关验证，或准确记录无法验证的原因。
- 更新执行计划状态。
- 创建或更新实施记录。
- 只有真正验证完成的工作才能标记为
已完成。 - 写清下一次会话的最佳入口和未解决风险。
这种重复不是负担，而是稳定性来源。它让每次会话都具备清晰的开始和结束。
七、为什么它比"写一个超长 Prompt"更可靠
面对大型需求，一个常见做法是把所有背景、要求和步骤塞进一个很长的 Prompt。
这种方式在第一次会话里可能有效，但它有几个天然局限：
- Prompt 很快过时，无法自动反映代码实际变化
- 无法准确表达哪些工作已经验证完成
- 多次会话之间容易出现不同版本
- 验收变化难以回写原始上下文
- Agent 仍然需要自己判断本次应做到哪里停止
large-feature-ai-coding 并不是消灭 Prompt，而是让 Prompt 只负责启动当前阶段，把长期状态交给仓库文档。
这样，Prompt 会变短，但 Agent 得到的上下文反而更稳定。
八、这套方法真正带来的收益
8.1 Agent 可以更换，会话可以中断
只要文档和代码保持同步，下一位 Agent 可以从仓库恢复状态，不需要完整阅读历史聊天记录。
8.2 设计不会在实施中无声漂移
如果代码证明设计假设有误，流程要求更新设计或创建后续文档，而不是悄悄改成另一种行为。
8.3 完成状态更诚实
执行计划要求记录验证命令和结果。代码写完但尚未验证时，状态应该是 进行中，而不是为了好看标记为 已完成。
8.4 大需求获得可审查的中间交付
每个工作包结束时都应该留下一个可运行、可验证的状态。即使整个需求尚未完成，也不会只剩一堆跨模块的半成品。
8.5 人和 Agent 的协作边界更清楚
不是所有事情都必须由 Agent 自动完成。例如全量视觉回归可以明确交给人工，并从 Agent 开发依赖链中移除。
方法论的价值不是把流程变得更重，而是让哪些事情应该阻塞、哪些事情可以并行，变得清楚。
九、使用时最容易犯的几个错误
9.1 有 Final Design 就直接开发
设计定义"做成什么"，但不负责记录工作包状态。缺少 Execution Plan 时，应该先创建计划。
9.2 一次让 Agent 连续完成所有工作包
工作包存在的意义，就是为会话建立边界。连续跨越多个大工作包，会重新回到"一次性完成整个需求"的旧模式。
9.3 把 Execution Plan 写成第二份设计文档
计划应该短、明确、可更新。设计细节留在 Final Design，计划只记录施工顺序、状态、验证和交接。
9.4 只更新代码，不更新台账与实施记录
这会让下一次会话重新猜测仓库状态。对多会话工作流而言，收尾记录本身就是交付的一部分。
9.5 把所有测试都变成开发阻塞项
验证要求应根据实际依赖关系设计。某些定向测试必须在工作包内完成；某些全量人工回归可以并行或后置。
重要的不是"测试越多越好"，而是准确记录：谁负责、何时执行、是否阻塞当前工作。
9.6 让文档和实现互相矛盾
一旦实现改变了原始契约，就应该同步更新设计和计划。否则文档越完整，下一位 Agent 反而越容易被误导。
十、如何正确使用：从需求讨论到验收收口的完整流程
large-feature-ai-coding 并不是从一句模糊需求开始，自动替你猜完所有产品细节，再一路写到代码交付。
它最适合介入的时机，是需求已经经过人与 AI 的充分讨论，目标、范围和关键约束基本清楚，准备从"想做什么"进入"如何在真实仓库中落地"的时候。
一套完整使用流程如下：
10.1 安装 Skill
large-feature-ai-coding 已经开源在我的 Skills 仓库中，可以通过以下命令安装：
开源仓库：
安装只是开始。真正决定效果的，是后续是否按阶段使用，以及给 Agent 的输入是否足够清楚。
10.2 阶段 0：先把需求讨论清楚，再让 Agent 进入工程设计
在正式使用 Skill 前，应该先和 AI、产品、设计或相关开发者把需求讨论到足够清楚。
这里的目标不是提前写出完整技术设计，而是形成一份可靠的需求输入包，至少包括：
这一步越清楚，后续 Agent 越少需要靠猜。
不确定的内容不必伪装成确定结论，可以明确标记：
如果只有一句"给箱图加个小提琴图"，Agent 即使最终写出了代码，也很难保证行为、范围和技术路线符合真正需求。
10.3 阶段 1：让 Agent 梳理现状并产出 Final Design
需求输入包准备好后，才进入 large-feature-ai-coding 的第一个正式阶段。
此时不要让 Agent 直接编码，而是让它：
- 读取项目规则、相关文档和参考资料。
- 沿着真实代码链路梳理前端、后端、接口与数据流。
- 验证需求讨论中的技术假设是否成立。
- 比较候选方案并明确最终结论。
- 输出可以约束后续开发的 Final Design。
可以使用下面的提示：
PS: 实际使用中只要能正确引用 large-feature-ai-coding Skill，并将必要信息描述清楚即可。
Final Design 不是把需求描述换一种格式抄写。它必须把需求放进真实仓库中验证，并回答"这套系统具体应该怎么改"。
10.4 阶段 2：人工评审 Final Design，确认后再进入规划
Agent 写完设计后，人需要认真评审，而不是把"生成了文档"当成设计已经完成。
重点检查：
- Agent 对需求的理解是否准确？
- 是否遗漏用户操作、默认值、异常和历史兼容？
- 是否误判了现有代码逻辑？
- 最终技术路线是否符合团队预期？
- 哪些内容应该开发处理，哪些应该由人工测试或其他团队处理？
- 风险、非目标和验收标准是否足够明确？
如果评审过程中改变了结论，直接要求 Agent 更新 Final Design。设计稳定到足以施工后，再进入执行计划阶段。
10.5 阶段 3：把稳定设计转换成 Execution Plan
设计确认后，再让 Agent 创建执行计划。
这个阶段的目标不是继续补充设计细节，而是把稳定方案拆成单次会话可以完成和验证的工作包。
执行计划完成后，人最好再快速检查一次：
- 工作包是否过大？
- 是否存在跨越多个模块但无法独立验证的工作包？
- 依赖关系是否真实？
- 是否把人工工作错误地塞进了 Agent 开发链路？
- 最小端到端能力是否优先闭环？
10.6 阶段 4：每次会话只认领一个清晰工作包
进入编码阶段后，不再重复输入完整需求，也不要笼统地说"继续完成剩余开发"。
每次新会话都让 Agent 重新读取 Final Design 和 Execution Plan，从进度台账中选择依赖已满足的最小工作包。
如果实现过程中发现设计假设错误，不应该让 Agent 自行换一套方案继续写。正确做法是暂停扩展范围，更新设计或增加后续工作包，再继续实施。
后续每个开发会话重复同一模式：
10.7 阶段 5：计划内开发完成后，进入人工验收
当计划内工作包完成，不代表需求已经真正结束。
此时由开发者、QA、产品或用户按项目实际流程进行：
- 人工自测
- 全量回归
- 视觉与交互验收
- 数据结果核对
- 性能或兼容性验证
- 真实环境验证
这些工作不一定都需要阻塞前面的开发，但必须在执行计划中明确责任、时机和状态。
验收结果应具体记录，而不是只告诉 Agent"有点问题，继续改一下"：
10.8 阶段 6：将验收变化转成 feat / fix，再继续开发
验收发现的问题，先判断属于哪类变化：
- 原需求之外的新增能力或交互增强：创建
feat文档。 - Bug、回归、数据不一致或行为修正：创建
fix文档。
这一步让验收阶段的变化重新进入同一套可追踪流程，而不是变成散落在聊天记录里的临时指令。
10.9 阶段 7：最终收口，确保下一位读者看到的就是真实系统
所有开发和验收问题完成后，最后进行一次文档与实现对齐：
- Final Design 是否仍然描述真实系统？
- Execution Plan 状态是否准确？
- 所有已完成工作包是否有验证结果和实施记录？
- feat / fix 是否已经同步回原始契约？
- 项目要求的 Release Note、模块文档或发布说明是否完成？
- 是否仍有未验证风险被错误标记为完成？
完整流程里，人并没有退出。人的职责从"逐行告诉 Agent 怎么写代码"，转向：
- 在开始前讨论并确认需求
- 评审关键设计决策
- 确认工作包边界与优先级
- 执行需要人工判断的验收
- 对新增需求与修复结果做最终决策
Agent 则负责把这些明确的信息持续映射到代码、文档、计划和验证记录中。两者配合，才能真正发挥这套 Skill 的价值。
十一、结语：让 Agent 的能力沉淀在工程里
AI Coding Agent 的能力还会继续提高。未来的模型会更擅长理解代码、更擅长调用工具，也能在更长的上下文中工作。
但中大型软件开发的核心问题不会因此消失：
- 决策需要被记录
- 范围需要被控制
- 状态需要被验证
- 变化需要被追踪
- 工作需要能够交接
large-feature-ai-coding 想做的，并不是给 Agent 增加一套繁琐仪式，而是把这些原本依赖资深工程师记忆和项目管理直觉的能力，变成 Agent 可以稳定执行的协作流程。
当设计、计划、代码、验证和实施记录一起留在仓库里，一次会话就不再是一段随时会消失的聊天。
它会成为下一次工作的起点。