从需求到 PR：Agent 端到端软件开发的架构设计

从需求到 PR：Agent 端到端软件开发的架构设计

一、端到端自动化的诱惑与难处

让 Agent 接收一个需求，直接吐出一个可合并的 PR。
这是研发效能的圣杯。
听起来一步到位，做起来步步惊心。

难点不在"写代码"，在"做对的事"。
需求有歧义，边界没说清，依赖没理清。
Agent 闷头实现，产出的 PR 往往跑偏。

端到端架构的核心，是把"理解"拆成显式环节。
让需求先被结构化，再驱动实现与验证。
本文探讨从需求到 PR 的完整 Agent 架构。

二、端到端流水线的机制

整条链路分四段：理解、规划、实现、验收。
理解段把自然语言需求转成结构化规格。
规划段拆任务并排依赖。
实现段写代码，验收段跑测试与审查。

每段都是独立 Agent 或步骤，靠结构化数据衔接。
这样任一段失败，能精准定位，而非全盘重来。

链路围绕"结构化规格"这个枢纽流转。
它既是规划的输入，也是验收的标尺。
没有它，实现与验收各说各话。

三、生产级架构实现

下面用代码描述规格与链路的衔接。

from dataclasses import dataclass, field from typing import Optional from enum import Enum class SpecStatus(Enum): DRAFT = "draft" PLANNED = "planned" IMPLEMENTED = "implemented" ACCEPTED = "accepted" @dataclass class RequirementSpec: """需求到 PR 之间的单一事实来源""" id: str goal: str acceptance: list[str] tasks: list[str] = field(default_factory=list) status: SpecStatus = SpecStatus.DRAFT pr_url: Optional[str] = None def plan(spec: RequirementSpec) -> RequirementSpec: if not spec.acceptance: # 没有验收标准，规划无从展开，退回补全 raise ValueError("需求缺少验收标准，无法规划") spec.tasks = [f"实现: {a}" for a in spec.acceptance] spec.status = SpecStatus.PLANNED return spec def accept(spec: RequirementSpec, passed: bool) -> RequirementSpec: spec.status = SpecStatus.ACCEPTED if passed else SpecStatus.IMPLEMENTED return spec if __name__ == "__main__": spec = RequirementSpec("R1", "导出报表为 PDF", ["含分页", "含页眉"]) plan(spec) print(f"已规划 {len(spec.tasks)} 个子任务")

真实系统会把 spec 落库，各 Agent 读写同一份。
链路可断点续跑，失败从断点恢复，而非重头。

四、边界分析与架构权衡

端到端自动化强大，但禁区明显。

需求歧义不可逆。规格转错，后面全错。
理解段必须有人确认或置信度门槛。
低置信需求应暂停，而非硬猜。

验收标准的完备性。验收写不全，PR 质量无保障。
应由人或强规则补全验收，再放行实现。
这是质量的第一道闸门。

上下文跨段丢失。各段独立，易失隐含意图。
解决方式：把"为什么"写进 spec 的 goal 与注释。
而非依赖 Agent 之间的默契。

权限与安全。自动开 PR 要限分支、限范围。
不能让它改 CI、删分支、碰密钥。
最小权限是底线。

需求到 PR 的"验收自动化"是可复现的关键。验收标准若只写在文档里，每次都要人判，慢且不一致。建议把验收标准结构化、可机器校验（如"接口返回字段包含 X"可用测试断言），让验收能自动跑。另一个实践是"小步合入"：不要等整个大需求做完才开 PR，而是拆成可独立验收的小块逐步合入，缩短反馈环、降低单次风险。最后，PR 描述要自动带出关联的规格与验收清单， reviewer 一眼看清"这次满足了什么"，减少来回确认的成本。

五、总结

从需求到 PR 的端到端 Agent，本质是"用结构化规格串起各段"。
机制上以 spec 为枢纽，理解、规划、实现、验收各管一段。
工程上靠人确认需求、最小权限兜底安全。

落地路线：先把需求转结构化规格并补验收；再拆任务规划；实现后接测试与审查；设权限上限与断点续跑。自动化的是流程，不放手的判断。