从 PRD 到技术方案，过去主要依赖资深工程师阅读需求、翻代码、找历史 PR、问相关同事，再把判断沉淀为设计文档和任务列表。Agent 进入这个环节后，真正的价值不是“替人写一篇设计文档”，而是把仓库研究、代码搜索、依赖分析、历史 issue/PR、ADR、现有设计文档、验收标准、风险识别和任务拆解组织成一个可审阅、可追踪、可复用的工程工作流。

基于对 GitLab Developer Flow、GitHub Copilot coding/cloud agent、Atlassian Rovo Dev、腾讯 CodeBuddy Plan Mode、Qoder Quest/Agent Mode、通义灵码等资料的调研，可以看到一个共同方向：先进工具都在把“先研究、先计划、再执行”变成产品默认路径。它们并不鼓励 Agent 收到需求后直接改代码，而是强调仓库上下文、规则文件、隔离环境、会话/任务状态、草稿 PR、人类 review、验收标准和回滚能力。

本文给出一套企业可落地的流程：PRD 输入后，Agent 先做 repository research，形成证据包；再生成技术方案草案、ADR 草案和任务拆解；最后由负责人审阅风险、边界、验收标准与执行顺序。文章末尾提供技术方案模板、任务拆解样例、落地 checklist 和参考资料。

为什么这个问题现在重要

AI 编码 Agent 已经能在仓库中创建分支、修改多文件、运行测试、提交 PR。GitHub Copilot coding agent 可以从 issue、IDE、CLI、GitHub.com、MCP 等入口接收任务，在隔离的 GitHub Actions 环境中探索代码、修改代码并运行测试；GitLab Developer Flow 把 issue 到 MR 的开发流放进 Duo Agent Platform，并要求项目用 AGENTS.md 和环境配置文件提供约束；Rovo Dev 可以从 Jira work item 进入，选择仓库、补充 prompt，生成代码并创建 draft pull request；CodeBuddy Plan Mode 和 Qoder Quest Mode 都明确强调先澄清需求、生成方案和任务，再执行。

这意味着“技术方案”不再只是项目启动前的一份文档，而会成为 Agent 执行的控制面：

• 它决定 Agent 应该读取哪些仓库、文件、issue、PR、ADR 和运行日志。
• 它限定 Agent 可以改什么、不可以改什么。
• 它把需求转成可验证的验收标准，而不是只给出自然语言愿望。
• 它让任务拆解小到能被 Agent 独立执行、测试、回滚和 review。
• 它为后续代码评审、测试、上线审批和复盘提供基准。

如果没有这个环节，团队很容易把 Agent 变成“高速试错器”：代码生成很快，但方向偏差、架构不一致、隐性依赖破坏、review 成本上升，最后由人类工程师收拾残局。

产品与实践调研

下表区分“官方已发布能力”“官方预览/Beta 能力”“基于公开资料的工程推断”和“本文落地建议”。产品状态以 2026-05-24 联网调研为准。

产品/实践	已发布或官方文档明确能力	预览/Beta/限制	对本文的启发
GitLab Developer Flow / Duo Agent Platform	Duo Agent Platform 提供 flows；Developer Flow 可从 issue 进入开发任务，建议使用 AGENTS.md 记录项目约定，并可用 agent-config.yml 配置执行环境。	GitLab 文档显示部分能力随版本、feature flag、group 设置变化。	PRD 到技术方案前，应把项目约定、测试命令、lint 规则、提交格式、编码模式写入仓库规则文件。
GitHub Copilot coding/cloud agent	Agent 可在后台处理任务，使用临时开发环境探索代码、改代码、运行测试和 linter，并创建 PR；可从 issue、chat、CLI、MCP 等入口触发。	从 issue 指派 Copilot 等部分入口在文档中标注 public preview 或受组织策略控制。	Agent 适合承接拆好的、可验证的任务；技术方案应明确“完成后需要请求人类 review”。
GitHub Code Search / Dependency Graph / CODEOWNERS	Code Search 支持 repo:、path:、language:、symbol:、正则和布尔查询；Dependency Graph 解析 manifest/lock 文件并展示依赖、漏洞、许可证、传递依赖；CODEOWNERS 可自动请求责任人 review。	Code Search 的不同界面/API 能力可能不完全一致；Dependency Graph 依赖生态和 lock file 覆盖。	repository research 不应只靠自然语言问答，要把代码搜索、依赖图和 owner 信息变成证据。
Atlassian Rovo Dev in Jira	Rovo Dev 可从 Jira work item 生成代码，选择一个或多个仓库，为每个仓库创建 session，可补充代码标准、关键路径、类似变更等上下文，可生成 draft PR；可读写连接仓库，并在用户权限下操作 Jira/Confluence。	自动化场景存在 restricted mode；访问范围受站点、仓库连接、权限和 credit 限制。	PRD/work item 到技术方案的桥梁应包含 Jira/Confluence 中的业务背景和仓库中的技术背景。
腾讯 CodeBuddy Plan Mode	Plan Mode 在 IDE 内完成需求澄清、方案设计、任务拆解与执行协同；Plan 保存到 .codebuddy/plans；支持 MCP、Skill、SubAgent 编排；执行前可审阅和编辑方案。	具体能力受 IDE、插件版本和已配置扩展影响。	“计划”应成为研发流的一等产物，而不是聊天记录；计划要可保存、可复用、可审阅。
Qoder Quest / Agent Mode	Quest Mode 强调目标委派、需求澄清、方案规划、代码执行、结果验证；Agent Mode 支持 Spec-driven execution、Worktree 隔离、Revert、任务报告和迭代。	Qoder CN / Lingma IDE 的 Quest 自主编程在阿里云更新日志中标注 Beta 体验；不同地区产品形态可能不同。	对复杂需求，Spec/设计文档应先于代码；执行环境隔离和可回滚是 Agent 做大任务的底线。
通义灵码 Agent Mode / Project Rules / Hooks	智能体模式具备工程检索、文件编辑、终端等工具使用能力；支持 MCP；Project Rules 可放在 .lingma/rules；Hooks 可在工具调用前后等关键节点插入逻辑。	新增能力以产品更新日志为准，企业使用需关注版本和权限。	企业落地需要把规则、工具、Hook 和安全拦截机制工程化，而不是完全依赖模型自觉。
ADR / 设计文档实践	Google Cloud 建议用 ADR 记录架构选择的背景和历史；MADR 提供轻量 Markdown 模板。	ADR 不是替代完整设计文档的万能格式。	Agent 生成技术方案时，应同时识别既有 ADR，并在产生新架构选择时生成 ADR 草案。

核心工程机制：从 PRD 到技术方案的 Agent Workflow

一个可控的 Agent 工作流应当把“理解需求”和“理解仓库”分开，再把二者合并成可审阅的方案。

1. 输入不是“写个方案”，而是结构化 PRD

Agent 能否产出靠谱方案，首先取决于 PRD 是否包含足够的工程信号。最低输入应包括：

• 背景：用户问题、业务目标、数据证据、触发场景。
• 范围：本期必须做什么，不做什么。
• 验收标准：可测试、可观察、可复现。
• 约束：上线时间、兼容性、合规、安全、性能、成本、已有承诺。
• 相关对象：Jira/issue 链接、设计稿、API 文档、指标看板、历史问题、客户反馈。

对 Agent 来说，PRD 中最重要的是“验收标准”和“非目标”。没有验收标准，Agent 会倾向于交付看起来完整但不可验证的代码；没有非目标，Agent 容易扩大改动范围。

2. Repository Research：让 Agent 先成为“会查案的工程师”

repository research 是本文的核心。它不是简单让模型“读整个仓库”，而是要求 Agent 用工具构造一张现状地图。

建议把研究动作拆成六类：

研究对象	典型问题	工具与证据
入口与边界	这个需求从哪个 API、页面、job、消息、CLI 入口进入？	rg、GitHub Code Search、路由表、OpenAPI、GraphQL schema、controller/service 名称
数据模型	涉及哪些表、缓存 key、事件、消息 topic、对象存储路径？	migration、ORM model、schema、protobuf、Avro、DB 文档
同类实现	仓库里有没有相似功能、相似错误处理、相似权限判断？	symbol: 搜索、path: 限定、历史 PR、测试样例
依赖关系	新方案会碰到哪些包、服务、SDK、许可证、漏洞和传递依赖？	Dependency Graph、lock file、SBOM、服务调用图、package manager
历史上下文	以前为什么这么设计？哪些坑踩过？	issue、PR discussion、ADR、postmortem、release note、changelog
责任人和治理	谁应该 review？哪些目录需要特殊审批？	CODEOWNERS、团队边界、branch protection、合规策略

Agent 的输出不应是“我看了代码”，而应是证据包，例如：

## Repository Research Evidence

- 入口：`apps/web/src/routes/billing.tsx` 负责展示当前计费页；`api/billing/subscription.ts` 暴露订阅接口。
- 同类实现：`apps/web/src/routes/usage.tsx` 已有按团队维度过滤的 UI 模式，可复用 `TeamSelector`。
- 数据模型：`Subscription` 当前缺少 `trial_end_reason`；migration 最近一次变更在 PR #1842。
- 历史风险：issue #1729 提到 Stripe webhook 顺序乱序导致状态回滚；方案需要幂等处理。
- ADR：`docs/adr/0012-billing-provider.md` 决定继续使用 Stripe，不引入第二支付网关。
- Owner：`/api/billing/**` 由 `@platform-billing` review；`/apps/web/**` 由 `@frontend-core` review。

这类证据包能显著降低幻觉风险，因为评审者可以追问每个结论来自哪里。

3. 代码搜索：从关键词搜索升级到意图搜索

GitHub Code Search 官方支持正则、布尔查询、repo:、path:、language:、symbol: 等限定。企业内部也可以用 Sourcegraph、OpenGrok、ripgrep、AST 索引或自建代码知识图谱。无论工具如何，Agent 应遵循相同搜索策略：

1. 从 PRD 名词提取业务关键词：订单、结算、权限、通知、导出。
2. 从 API/事件/表名提取技术关键词：endpoint、topic、model、command、job。
3. 搜索同类变更：path:billing refund OR invoice、symbol:calculateUsage。
4. 搜索反例和防御逻辑：rate limit、idempotency、retry、rollback、permission denied。
5. 搜索测试样例：path:test、path:spec、describe("billing")。

技术方案里应保留关键查询，而不是只保留结论。对 Agent 来说，“查询语句”本身就是可复验的工程证据。

4. 依赖图：识别变更半径，而不是只看 import

依赖图至少要回答四个问题：

• 代码依赖：当前模块依赖谁，谁依赖当前模块。
• 运行依赖：调用哪些外部服务、队列、数据库、缓存、对象存储、第三方 API。
• 供应链依赖：新增或升级依赖是否带来漏洞、许可证、体积、兼容性风险。
• 组织依赖：哪些团队、审批人、SRE、数据、安全、法务需要参与。

GitHub Dependency Graph 可以解析 manifest 和 lock file，展示直接/传递依赖、版本、许可证和已知漏洞，并在 PR 中辅助 dependency review。对 Agent 来说，这类信息应该进入“风险识别”和“任务拆解”，例如把“升级 SDK”拆成独立任务，并要求兼容性测试和回滚方案。

5. 历史 issue/PR、ADR、设计文档：把“为什么”交给 Agent

代码只能告诉 Agent “现在怎么做”，历史 issue/PR、ADR 和设计文档才能解释“为什么这么做”。这部分上下文通常决定技术方案是否可信。

建议让 Agent 固定检查：

• 最近 6-12 个月与目标模块相关的 PR：看变更方向、review 关注点、回滚记录。
• 相关 issue 和 incident：看真实用户问题、线上故障、边界条件。
• ADR：看架构决策、状态、上下文、后果和被替代关系。
• 设计文档：看已承诺的接口、扩展点、非目标、迁移计划。
• 规则文件：AGENTS.md、.github/copilot-instructions.md、.cursor/rules、.lingma/rules、.codebuddy/plans 等。

ADR 尤其适合作为 Agent 的“架构护栏”。Google Cloud 对 ADR 的定义强调记录设计选择背后的原因和历史；MADR 提供 Markdown 化模板。落地时可以要求 Agent：

• 如果方案违反现有 ADR，必须显式列出冲突。
• 如果方案产生新的关键架构决策，必须生成 ADR 草案。
• 如果无法找到 ADR，必须把“缺少决策记录”列为风险，而不是假装不存在。

技术方案文档模板

下面模板适合由 Agent 生成初稿，再由 tech lead / 架构师 / 测试 / 安全共同审阅。对于小任务，可以压缩；对于跨团队项目，不建议省略“现状研究”和“风险”。

# 技术方案：{功能/项目名称}

## 1. 背景
- PRD / Jira / Issue：
- 用户问题：
- 业务目标：
- 本期范围：
- 非目标：

## 2. 验收标准
- 功能验收：
- 数据验收：
- 性能验收：
- 安全/权限验收：
- 可观测性验收：
- 回归验收：

## 3. Repository Research 证据包
### 3.1 入口与调用链
- 入口文件/接口：
- 上游调用：
- 下游依赖：

### 3.2 数据模型与状态流
- 表 / schema / model：
- 状态机：
- 迁移影响：

### 3.3 同类实现
- 可复用组件：
- 可复用测试：
- 不应复用的旧模式：

### 3.4 历史上下文
- 相关 issue：
- 相关 PR：
- ADR / 设计文档：
- incident / postmortem：

### 3.5 依赖与 owner
- 包依赖：
- 服务依赖：
- CODEOWNERS / review 人：

## 4. 方案选型
### 方案 A
- 描述：
- 优点：
- 缺点：
- 风险：

### 方案 B
- 描述：
- 优点：
- 缺点：
- 风险：

### 推荐方案
- 决策：
- 原因：
- 需要新增/更新的 ADR：

## 5. 详细设计
- API 设计：
- 数据模型：
- 状态流 / 时序：
- 权限与安全：
- 幂等、重试、降级：
- 兼容性与迁移：
- 可观测性：

## 6. 任务拆解
| 任务 | 说明 | 依赖 | 验收 | Owner | 适合 Agent |
| --- | --- | --- | --- | --- | --- |

## 7. 测试计划
- 单元测试：
- 集成测试：
- E2E：
- 回归范围：
- 手工验收：

## 8. 发布与回滚
- Feature flag：
- 灰度策略：
- 数据迁移：
- 回滚步骤：
- 监控指标：

## 9. 风险与开放问题
| 风险 | 影响 | 触发条件 | 缓解措施 | 决策人 |
| --- | --- | --- | --- | --- |

## 10. 附录
- 关键代码搜索查询：
- 参考链接：
- Agent 运行记录：

任务拆解样例

假设 PRD 是：“为企业账户增加试用到期前的续费提醒，支持邮件和站内信，管理员可配置提前 7/14/30 天提醒。”

Agent 不应直接改代码，而应先给出如下拆解：

阶段	任务	输入证据	验收标准	适合 Agent 执行程度
研究	定位订阅状态和到期时间来源	Subscription model、billing webhook、历史 PR	找到唯一可信 trial_end_at 来源；列出状态乱序风险	高
研究	查找现有通知框架	NotificationService、邮件模板、站内信组件、测试	明确是否复用现有队列和模板系统	高
设计	产出提醒状态流	PRD、现有状态机、incident	状态流覆盖已续费、取消、过期、重复提醒	中，需要人审
数据	增加提醒配置字段	migration、tenant settings、默认值策略	兼容老租户；可回滚；有 migration 测试	中
后端	实现 reminder scheduler	job 框架、幂等 key、队列	同一租户同一到期日不会重复发送；失败可重试	高
前端	管理员配置页	现有 settings UI、权限组件	只有管理员可见；保存后可读取；错误提示一致	高
测试	补齐单测/集成测试	同类通知测试	覆盖 7/14/30 天、取消试用、已续费、重复 job	高
发布	feature flag 与监控	发布策略、指标系统	可按租户灰度；有发送成功率和失败率指标	中，需要 SRE/业务确认
文档	更新 ADR/设计文档	方案决策	记录为什么复用现有通知框架，不新建服务	高

拆解要点是：每个任务都能被独立验证，且任务之间有明确依赖。适合 Agent 的任务可以交给 GitHub Copilot coding agent、GitLab Developer Flow、Rovo Dev、CodeBuddy、Qoder 或通义灵码执行；涉及产品取舍、架构决策、安全策略和发布风险的任务，必须有人类负责人审阅。

风险识别：Agent 最容易漏掉什么

技术方案中的风险不能只写“可能有兼容性问题”。建议强制 Agent 按以下维度扫描：

风险类型	常见遗漏	Agent 应检查的证据
需求边界	把非目标也做了，或遗漏异常场景	PRD 非目标、验收标准、历史 issue
架构一致性	新增一套和既有模式冲突的实现	ADR、同类实现、目录结构、owner 评论
数据迁移	老数据默认值、回滚、双写、幂等没设计	migration、历史回滚 PR、数据量
权限安全	只做前端限制，后端未校验	policy、middleware、审计日志、安全测试
依赖供应链	新增包有漏洞、许可证不兼容、体积过大	Dependency Graph、SBOM、lock file
并发与状态	重试导致重复操作，异步事件乱序	job、queue、webhook、incident
可观测性	上线后无法判断是否成功	metrics、logs、traces、dashboard
组织协同	没有找对 owner review	CODEOWNERS、团队边界、服务目录
Agent 执行风险	任务过大、上下文过宽、权限过高	任务粒度、sandbox、工具权限、diff 范围

管理者视角：流程、组织与指标

对 CTO、研发负责人和产品负责人来说，PRD 到技术方案的 Agent 化不应被理解为“少开几次技术评审会”，而应被设计为研发治理能力升级。

组织流程

• PRD 必须有验收标准和非目标，否则不进入 Agent 方案生成。
• 每个核心仓库维护规则文件：测试命令、lint 命令、提交规范、架构约束、安全边界。
• 技术方案必须带证据包：代码搜索结果、历史 PR/issue、ADR、依赖图、owner。
• 复杂方案要输出 ADR 草案；重大 ADR 必须由架构 owner 批准。
• Agent 生成的任务默认进入 draft PR 或计划状态，不能自动 merge。

指标

建议关注四类指标：

• 方案质量：一次评审通过率、开放问题数量、重大遗漏数量。
• 执行效率：PRD 到方案耗时、方案到任务耗时、任务平均粒度。
• 交付质量：返工率、回滚率、线上缺陷、测试覆盖有效性。
• 治理健康度：有 ADR 的关键决策比例、owner review 命中率、规则文件覆盖率。

不要用“Agent 写了多少行代码”衡量这一环节。更有价值的指标是：技术方案是否减少了后续返工和线上风险。

工程师与架构师视角：落地架构

企业内部可以把 PRD 到技术方案的 Agent 能力设计成一个“方案生成服务”，而不是散落在各 IDE 插件里的聊天记录。

关键组件包括：

• Context Gateway：统一控制 Agent 能读哪些仓库、文档、issue、PR 和指标，避免权限失控。
• Tool Registry：登记代码搜索、依赖图、CI、测试、文档、Jira、Confluence、GitHub/GitLab 等工具。
• Policy Engine：限制写权限、删除操作、密钥访问、生产环境操作和敏感目录修改。
• Evidence Store：保存 Agent 使用的查询、文件片段、结论和链接，便于评审和审计。
• Template Library：维护技术方案、ADR、测试计划、发布计划和风险表模板。
• Task Router：把拆好的任务分派给 GitHub Copilot、GitLab Duo、Rovo Dev、CodeBuddy、Qoder、通义灵码或内部 Agent。

落地 Checklist

第 0 阶段：准备上下文

• 核心仓库存在 README、开发环境说明、测试命令、lint 命令。
• 核心仓库存在 AGENTS.md 或等价规则文件。
• 关键目录有 CODEOWNERS 或服务 owner 映射。
• 重要架构决策有 ADR，至少覆盖数据、权限、外部依赖、部署形态。
• CI 能在隔离环境稳定运行。

第 1 阶段：规范 PRD 输入

• PRD 包含验收标准和非目标。
• PRD 关联用户反馈、指标、issue 或业务证据。
• PRD 标明安全、合规、性能、兼容性约束。
• PRD 标明必须复用或禁止触碰的系统边界。

第 2 阶段：让 Agent 做 Repository Research

• Agent 输出代码搜索查询和结果摘要。
• Agent 输出入口、调用链、数据模型、依赖图。
• Agent 检索历史 issue/PR/ADR/设计文档。
• Agent 列出 owner 和必要 review 人。
• Agent 把无法确认的信息列为开放问题。

第 3 阶段：生成并审阅技术方案

• 方案包含至少两个选型或明确说明为什么只有一个方案。
• 方案包含数据迁移、回滚、监控、测试计划。
• 方案明确新增或更新 ADR。
• 方案明确哪些任务适合 Agent，哪些必须人类决策。
• 方案评审记录保存在仓库或项目管理系统中。

第 4 阶段：任务拆解与执行

• 每个任务有输入、输出、依赖、验收标准。
• 单个 Agent 任务控制在可独立 review 的 diff 范围内。
• Agent 只能创建 draft PR 或等待 review，不自动 merge。
• 任务完成后自动触发测试、lint、依赖审查和 owner review。
• 失败任务保留日志、diff 和回滚点。

小结

从 PRD 到技术方案，是 AI 原生研发中最容易被低估的一环。编码 Agent 越强，越需要严肃的规划、证据和治理。GitHub、GitLab、Atlassian、CodeBuddy、Qoder、通义灵码等工具的共同趋势已经很清楚：Agent 不是绕过设计文档，而是把设计文档变成可执行、可审阅、可追踪的控制面。

企业真正要建设的不是“一个会写方案的聊天机器人”，而是一条工程化链路：PRD 结构化输入，Agent 做 repository research，生成证据包和技术方案，识别风险，拆成可验证任务，再交由 Agent 或工程师执行。这样，AI 才能从“更快写代码”进入“更可靠地交付软件”。