AI Agent 已经很会写代码了。 但当一个需求跨越前端、后端、数据结构、兼容性与多轮验收时，真正困难的往往不再是"这一段代码怎么写"，而是：下一次会话还能不能准确接住上一次的工作。

最近我把自己处理中大型需求时逐渐形成的一套协作方法，整理成了一个开源 Skill：large-feature-ai-coding。

它不负责教 Agent 使用某个框架，也不替代项目自身的开发规范。它解决的是另一类问题：

如何把一个中大型需求，变成一组能够被不同 AI Agent、跨多个会话持续推进的工程工作。

这篇文章记录这套方法为什么出现、它解决了什么、应该如何正确使用，以及一次看似"Agent 没有立刻开始编码"的场景，为什么反而说明流程正在发挥作用。

一、AI Coding 的真正瓶颈，开始从写代码转向管理上下文

1.1 小任务里，Agent 几乎天然表现良好

如果任务足够明确，例如：

• 给一个表单增加校验
• 修复一个确定的空指针
• 为现有接口增加单元测试
• 调整一个组件的样式

Agent 通常可以在一次会话内完成：

任务边界、上下文和完成标准都能同时放进一个会话里。Agent 即使没有额外的协作方法，也很容易做对。

1.2 中大型需求不是"更大的小任务"

当需求开始具备以下特征，情况会迅速变化：

• 横跨前端、后端、数据库或多个业务模块
• 存在多个候选方案，需要先做技术决策
• 一次会话无法完成全部实现
• 实施过程中可能发现设计假设不成立
• 需要人工验收，并在验收后继续修复
• 不同时间、不同 Agent 需要接力开发

这时，直接告诉 Agent：

1根据需求开始开发，分阶段一步步完成。

看起来已经说了"分阶段"，实际仍然把所有关键判断交给了当前会话：

• 当前到底处于设计、规划、开发，还是验收修复阶段？
• "分阶段"具体分成哪些工作包？
• 哪个工作包依赖哪个？
• 已经做完了什么？
• 哪些结论是经过验证的？
• 下一次会话应该从哪里继续？

如果这些状态只存在于聊天记录里，它们就很容易随着会话切换、上下文压缩或 Agent 更换而消失。

1.3 常见失败并不是代码写错，而是流程漂移

我观察到中大型 AI Coding 任务最常见的失败模式，往往是这些：

这些问题并不说明 Agent 不够聪明。恰恰相反，Agent 往往会非常积极地继续探索和编码。

问题在于：它缺少一套稳定的外部状态，用来判断此刻应该做什么、不应该做什么。

二、核心思路：把隐藏在聊天中的状态写进仓库

large-feature-ai-coding 的核心并不复杂：

把需求决策、执行顺序、进度状态、每次会话结果和验收变化，沉淀为与代码一起演进的文档集合。

它不是为了增加文档数量，而是为了让关键上下文脱离聊天记录，成为 Agent 可以重新读取的工程资产。

这套流程里，每类文档承担不同职责：

1docs/开发设计文档/
2  <feature_slug>_final_design.md
3  <feature_slug>_execution_plan.md
4  <feature_slug>_implementation_records/
5    YYYY-MM-DD_<work-package-id>_<short-title>.md
6  feat/
7    YYYY-MM-DD_<feature_slug>_<short-title>.md
8  fix/
9    YYYY-MM-DD_<feature_slug>_<short-title>.md

项目已经有自己的文档根目录或命名习惯时，应该遵循项目规范，不必强行使用上面的路径。

三、五类文档，分别解决五类上下文问题

3.1 Final Design：先固定"要做成什么"

最终设计文档负责定义稳定契约，而不是记录每一步如何施工。

它应该回答：

• 背景、目标与非目标是什么？
• 当前前后端代码链路如何运行？
• 最终用户行为是什么？
• 模块职责、接口和数据结构如何划分？
• 有哪些性能边界、兼容规则和明确排除项？
• 哪些约束在开发期间不能被悄悄改变？

如果存在多个候选方案，先在文档开头写评审结论：

• 每个方案解决了什么
• 风险在哪里
• 最终采用哪个方案
• 编码期间不能违反哪些约束

这样后续 Agent 不需要重新进行整轮方案讨论。

3.2 Execution Plan：把设计变成可认领的工作包

执行计划不是第二份设计文档。它是构建台账和多会话交接契约。

一份可用的执行计划至少需要包含：

• 工作包 ID、范围和依赖顺序
• 状态规则
• 进度台账
• 每个工作包的验证要求
• 关键工程约束
• 实施记录模板
• 下一次会话应该如何开始

推荐只使用少量明确状态：

一个典型的进度台账：

台账让 Agent 在会话开始时先定位状态，而不是再次漫游整个仓库。

3.3 Work Package：让一次会话有明确的停止位置

工作包应该足够小，能够在一次专注会话中完成实现、验证和记录。

好的工作包通常具备：

• 单一、清晰的目标
• 有限的代码影响范围
• 明确的输入依赖
• 可以独立验证的完成标准
• 完成后仓库仍处于可运行状态

不好的工作包则常常写成：

1完成前后端开发、测试、兼容处理和文档。

它看起来完整，实际上没有为 Agent 提供任何范围边界。

可以使用 PRE、BE、FE、QA、DOC、FIX 等前缀标识工作包，但前缀只是辅助。真正重要的是：一个工作包要有可以被验证的结束状态。

3.4 Implementation Record：让下一次会话知道"实际上发生了什么"

执行计划记录整体状态，实施记录记录某次会话的事实。

每次工作完成前，应该写下：

• 本次实现了什么
• 修改了哪些文件
• 接口或数据结构是否变化
• 执行了哪些验证命令
• 哪些内容还没有完成
• 下一次最适合继续哪个工作包

1# 工作包 <ID>：<标题>
2
3## 基本信息
4
5- 日期：
6- 状态：已完成 / 部分完成 / 阻塞
7- 对应执行计划工作包：
8
9## 本次实现内容
10
11-
12
13## 修改文件
14
15-
16
17## 接口或数据结构变化
18
19-
20
21## 验证结果
22
23执行命令：
24
25```plaintext
26
27```
28
29结果：
30
31-
32
33## 未完成事项
34
35-
36
37## 下一步建议
38
39-

实施记录的价值，不是写一篇漂亮总结，而是让下一位 Agent 不依赖隐藏聊天上下文也能继续工作。

3.5 Feat / Fix Docs：把验收阶段的新变化重新纳入契约

中大型需求很少在第一次实现后就完全结束。人工自测、QA 或用户验收通常会发现：

• 新增交互要求
• 数据口径差异
• 边界条件遗漏
• 视觉或格式问题
• 回归缺陷

如果这些变化只存在于聊天里，最终设计和真实系统就会逐渐分离。

因此，验收后发现的变化也需要分类记录：

• 新增需求或交互增强写入 feat/
• Bug、回归或数据不一致写入 fix/

如果变化修改了原始契约，还要同步更新最终设计和执行计划。

四、最关键的能力不是拆任务，而是先判断当前处于哪个阶段

large-feature-ai-coding 首先要求 Agent 根据用户请求和仓库状态选择入口：

这张表看起来朴素，却是整套方法中最重要的部分。

因为 AI Agent 很容易把"积极行动"理解成"立即改代码"。而在大型需求里，当前阶段如果判断错了，越积极，返工可能越多。

五、一个真实的误区：有设计文档，不等于可以直接认领工作包

我最近遇到过一个很典型的场景。

仓库中已经存在最终设计文档，用户给出的指令大意是：

1根据开发设计文档开始认领工作包，分阶段一步步开发。

Agent 检查后发现：设计文档已经存在，但执行计划尚不存在。

此时，它没有立刻修改代码，而是准备先把设计转换成执行计划和进度台账。

表面看，它似乎"没有按要求开始开发"。但按照这套工作流，它的判断是正确的：

问题出在原始提示把两个阶段混在了一起：

1. 创建执行计划、定义工作包。
2. 认领工作包、开始开发。

没有执行计划时，所谓"认领工作包"并没有正式台账可以落地。设计文档中的实施建议也不能替代执行计划，因为它通常不包含准确状态、完成日期、验证结果和实施记录路径。

5.1 正确提示：先创建执行计划

1使用 large-feature-ai-coding Skill。
2
3当前已有：
4- <feature_slug>_final_design.md
5
6当前没有 execution_plan。
7
8请根据最终设计创建：
9- <feature_slug>_execution_plan.md
10
11要求：
12- 本次只创建执行计划，不修改业务代码。
13- 将工作拆成单次会话可完成的小工作包。
14- 包含依赖顺序、进度台账、状态规则、验证要求和实施记录模板。

5.2 正确提示：下一次会话再认领工作包

1使用 large-feature-ai-coding Skill。
2
3请读取：
4- <feature_slug>_final_design.md
5- <feature_slug>_execution_plan.md
6
7检查进度台账，认领当前依赖已满足的最小工作包。
8
9本次要求：
10- 开始编辑前声明认领的工作包和预期产出。
11- 只完成一个工作包，或一组紧密耦合的小工作包。
12- 完成实现和相关验证。
13- 更新 execution_plan 进度台账。
14- 创建对应 implementation record。
15- 不继续认领下一个无关工作包。

这两个提示的区别很小，但会显著改变 Agent 的工作质量。

PS: 实际使用中只要能正确引用 large-feature-ai-coding Skill，是不需要将 Prompt 写得这么详细的。

六、一次完整的多会话开发应该如何推进

假设需求是"为现有箱图增加可选的小提琴图，并先升级 ECharts v6"，一个合理的会话序列可能是：

每次会话开始时，Agent 都做相同的几件事：

1. 读取最终设计和执行计划。
2. 检查进度台账。
3. 认领一个未完成且依赖已满足的工作包。
4. 声明本次范围和预期产出。
5. 检查相关代码与用户已有变更。

每次会话结束前，也做相同的收尾：

1. 执行相关验证，或准确记录无法验证的原因。
2. 更新执行计划状态。
3. 创建或更新实施记录。
4. 只有真正验证完成的工作才能标记为 已完成。
5. 写清下一次会话的最佳入口和未解决风险。

这种重复不是负担，而是稳定性来源。它让每次会话都具备清晰的开始和结束。

七、为什么它比"写一个超长 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 仓库中，可以通过以下命令安装：

1npx skills add https://github.com/qiuyedx/qiuye-skills.git --skill large-feature-ai-coding

开源仓库：

• qiuyedx/qiuye-skills

安装只是开始。真正决定效果的，是后续是否按阶段使用，以及给 Agent 的输入是否足够清楚。

10.2 阶段 0：先把需求讨论清楚，再让 Agent 进入工程设计

在正式使用 Skill 前，应该先和 AI、产品、设计或相关开发者把需求讨论到足够清楚。

这里的目标不是提前写出完整技术设计，而是形成一份可靠的需求输入包，至少包括：

这一步越清楚，后续 Agent 越少需要靠猜。

不确定的内容不必伪装成确定结论，可以明确标记：

1已确认：
2- 新功能由独立开关控制，默认关闭。
3- 历史保存配置必须兼容。
4
5待 Agent 结合代码确认：
6- 开关适合放在现有哪个设置分组。
7- 是否可以复用现有接口返回数据。
8
9本次不做：
10- 不新增独立图表类型。
11- 不改后端统计口径。

如果只有一句"给箱图加个小提琴图"，Agent 即使最终写出了代码，也很难保证行为、范围和技术路线符合真正需求。

10.3 阶段 1：让 Agent 梳理现状并产出 Final Design

需求输入包准备好后，才进入 large-feature-ai-coding 的第一个正式阶段。

此时不要让 Agent 直接编码，而是让它：

1. 读取项目规则、相关文档和参考资料。
2. 沿着真实代码链路梳理前端、后端、接口与数据流。
3. 验证需求讨论中的技术假设是否成立。
4. 比较候选方案并明确最终结论。
5. 输出可以约束后续开发的 Final Design。

可以使用下面的提示：

1使用 large-feature-ai-coding Skill。
2
3这是一个新的中大型需求，本次只进行现状梳理与开发设计，不修改业务代码。
4
5需求背景与已确认结论：
6- <背景与问题>
7- <用户行为与功能细节>
8- <范围与非目标>
9- <兼容、性能、安全等约束>
10- <已讨论清楚的大致技术方案>
11
12参考资料：
13- <原型 / Demo / 截图 / 历史方案>
14- <已知相关代码入口>
15
16请读取项目规范和相关代码，核实上述信息，梳理真实前后端链路，
17比较必要的候选方案，并产出 <feature_slug>_final_design.md。
18
19设计文档需要明确：
20- 当前实现与约束
21- 最终用户行为
22- 最终技术方案与模块职责
23- 接口、状态和数据流
24- 边界、风险、兼容与验证策略
25- 明确非目标和开发期间不可违反的约束

PS: 实际使用中只要能正确引用 large-feature-ai-coding Skill，并将必要信息描述清楚即可。

Final Design 不是把需求描述换一种格式抄写。它必须把需求放进真实仓库中验证，并回答"这套系统具体应该怎么改"。

10.4 阶段 2：人工评审 Final Design，确认后再进入规划

Agent 写完设计后，人需要认真评审，而不是把"生成了文档"当成设计已经完成。

重点检查：

• Agent 对需求的理解是否准确？
• 是否遗漏用户操作、默认值、异常和历史兼容？
• 是否误判了现有代码逻辑？
• 最终技术路线是否符合团队预期？
• 哪些内容应该开发处理，哪些应该由人工测试或其他团队处理？
• 风险、非目标和验收标准是否足够明确？

如果评审过程中改变了结论，直接要求 Agent 更新 Final Design。设计稳定到足以施工后，再进入执行计划阶段。

1使用 large-feature-ai-coding Skill。
2
3请根据以下评审结论更新 <feature_slug>_final_design.md，
4本次仍不修改业务代码，也不创建执行计划：
5
6- <需要修正的需求理解>
7- <确认采用或放弃的技术方案>
8- <新增的范围、边界或验收要求>
9
10更新后检查设计文档内部是否存在冲突，并总结最终不可违反的开发约束。

10.5 阶段 3：把稳定设计转换成 Execution Plan

设计确认后，再让 Agent 创建执行计划。

这个阶段的目标不是继续补充设计细节，而是把稳定方案拆成单次会话可以完成和验证的工作包。

1使用 large-feature-ai-coding Skill。
2
3当前已有并已确认：
4- <feature_slug>_final_design.md
5
6当前没有 execution_plan。
7
8请根据最终设计创建 <feature_slug>_execution_plan.md。
9
10要求：
11- 本次只创建执行计划，不修改业务代码。
12- 将工作拆成单次专注会话可完成的小工作包。
13- 明确工作包依赖顺序、并行关系和优先级。
14- 包含进度台账、状态规则、验证要求、关键文件和实施记录模板。
15- 区分开发阶段验证与人工验收，不要把无依赖关系的任务错误设为开发阻塞项。
16- 写清未来 Agent 每次会话应该如何读取文档、认领工作包和完成收尾。

执行计划完成后，人最好再快速检查一次：

• 工作包是否过大？
• 是否存在跨越多个模块但无法独立验证的工作包？
• 依赖关系是否真实？
• 是否把人工工作错误地塞进了 Agent 开发链路？
• 最小端到端能力是否优先闭环？

10.6 阶段 4：每次会话只认领一个清晰工作包

进入编码阶段后，不再重复输入完整需求，也不要笼统地说"继续完成剩余开发"。

每次新会话都让 Agent 重新读取 Final Design 和 Execution Plan，从进度台账中选择依赖已满足的最小工作包。

1使用 large-feature-ai-coding Skill。
2
3请读取：
4- <feature_slug>_final_design.md
5- <feature_slug>_execution_plan.md
6
7检查进度台账和现有代码变更，认领当前依赖已满足的最小工作包。
8
9本次要求：
10- 编辑前先声明认领的工作包、范围和预期产出。
11- 只完成该工作包，或一组不可拆分的紧密耦合工作包。
12- 保持 Final Design 中的约束，不静默改变设计契约。
13- 完成相关实现和约定验证。
14- 更新 execution_plan 进度台账。
15- 创建或更新对应 implementation record。
16- 结束时说明验证结果、未完成事项和下一次推荐工作包。
17- 不继续认领下一个无关工作包。

如果实现过程中发现设计假设错误，不应该让 Agent 自行换一套方案继续写。正确做法是暂停扩展范围，更新设计或增加后续工作包，再继续实施。

后续每个开发会话重复同一模式：

10.7 阶段 5：计划内开发完成后，进入人工验收

当计划内工作包完成，不代表需求已经真正结束。

此时由开发者、QA、产品或用户按项目实际流程进行：

• 人工自测
• 全量回归
• 视觉与交互验收
• 数据结果核对
• 性能或兼容性验证
• 真实环境验证

这些工作不一定都需要阻塞前面的开发，但必须在执行计划中明确责任、时机和状态。

验收结果应具体记录，而不是只告诉 Agent"有点问题，继续改一下"：

1验收场景：
2- 历史保存的箱图配置
3
4观察到的行为：
5- 打开旧配置后，小提琴开关显示为开启。
6
7预期行为：
8- 历史配置没有 showViolin 字段时，应默认关闭。
9
10影响范围：
11- 图表编辑页与报表页都需要兼容。

10.8 阶段 6：将验收变化转成 feat / fix，再继续开发

验收发现的问题，先判断属于哪类变化：

• 原需求之外的新增能力或交互增强：创建 feat 文档。
• Bug、回归、数据不一致或行为修正：创建 fix 文档。

1使用 large-feature-ai-coding Skill。
2
3当前需求已进入人工验收阶段，发现以下问题或新增要求：
4- <观察到的行为>
5- <预期行为>
6- <复现条件与影响范围>
7
8请先判断它属于 feat 还是 fix，并创建对应文档。
9如果它改变了原始设计契约，同步更新 Final Design；
10同时在 Execution Plan 中新增或更新对应工作包。
11
12完成文档对齐后，认领该修复工作包进行实现、验证，
13并更新进度台账与 implementation record。

这一步让验收阶段的变化重新进入同一套可追踪流程，而不是变成散落在聊天记录里的临时指令。

10.9 阶段 7：最终收口，确保下一位读者看到的就是真实系统

所有开发和验收问题完成后，最后进行一次文档与实现对齐：

• Final Design 是否仍然描述真实系统？
• Execution Plan 状态是否准确？
• 所有已完成工作包是否有验证结果和实施记录？
• feat / fix 是否已经同步回原始契约？
• 项目要求的 Release Note、模块文档或发布说明是否完成？
• 是否仍有未验证风险被错误标记为完成？

1使用 large-feature-ai-coding Skill。
2
3请对本需求进行最终收口检查：
4- 对比 Final Design、Execution Plan、implementation records、feat/fix 文档与实际代码。
5- 修正文档与实现之间的冲突。
6- 检查所有工作包状态和验证记录是否准确。
7- 执行项目要求的最终验证，或记录无法执行的原因。
8- 输出剩余风险、发布注意事项和最终交付摘要。
9
10本次不扩展新的需求范围。

完整流程里，人并没有退出。人的职责从"逐行告诉 Agent 怎么写代码"，转向：

• 在开始前讨论并确认需求
• 评审关键设计决策
• 确认工作包边界与优先级
• 执行需要人工判断的验收
• 对新增需求与修复结果做最终决策

Agent 则负责把这些明确的信息持续映射到代码、文档、计划和验证记录中。两者配合，才能真正发挥这套 Skill 的价值。

十一、结语：让 Agent 的能力沉淀在工程里

AI Coding Agent 的能力还会继续提高。未来的模型会更擅长理解代码、更擅长调用工具，也能在更长的上下文中工作。

但中大型软件开发的核心问题不会因此消失：

• 决策需要被记录
• 范围需要被控制
• 状态需要被验证
• 变化需要被追踪
• 工作需要能够交接

large-feature-ai-coding 想做的，并不是给 Agent 增加一套繁琐仪式，而是把这些原本依赖资深工程师记忆和项目管理直觉的能力，变成 Agent 可以稳定执行的协作流程。

当设计、计划、代码、验证和实施记录一起留在仓库里，一次会话就不再是一段随时会消失的聊天。

它会成为下一次工作的起点。