在研发管理这块摸爬滚打多年后我越来越确定一件事PRD产品需求文档到可执行工作项之间的这条链路是整个软件交付流程里最原始、最依赖人肉、也是最容易断裂的一环。产品经理花一周写出一份详尽的需求文档开发拿到后靠“感觉”把它拆成任务排期、估点、写状态。表面上看流程走完了但实际上需求文档里的某个隐藏假设、某条边界条件可能在拆解过程中被悄悄丢掉。等到开发到一半发现“这个字段哪来的”“这个异常分支没人提过”再回头翻文档已经是两个迭代之后的事了。这也是我做PingCraft的初衷用一个 Agent 把“需求文档 → 可追踪工作项”这条路自动化、结构化地走通让每一个工作项都能回溯到它对应的原文依据。这篇文章我会把整个项目的设计思路、核心链路、踩过的坑、以及最终的性能数据完整地摊开来讲希望能给同样在折腾 Agent 落地研发流程的朋友一些实际参考。1. 为什么做 PingCraft需求到工作项的“最后一公里”全是人肉劳动1.1 大多数研发团队的现状PRD写得勤落地全凭嘴先说说我观察到的普遍现状。大部分团队的需求流转是这样的产品写完 PRD组织评审会会上大家口头对齐一遍然后开发负责人会后手动把 PRD 里的内容“翻译”成一个个 Jira 或 Tapd 工作项。这个过程有几个天然缺陷信息损耗无感知口头对齐时大家都说“明白了”但每个人理解的重点不同。开发拆出的工作项往往只覆盖了 PRD 里的主流程异常分支、边界条件、非功能性需求经常被有意无意地忽略。追踪链路断裂工作项描述里通常只有一句“实现 XX 功能”压根不会标注它对应 PRD 的哪一节哪一段。等需求变更时你根本不知道这个工作项该不该改、影响面多大。拆解质量依赖个人经验同一个需求资深开发拆出来的任务颗粒度合理、依赖清晰初级开发可能拆成几个大块到了迭代末期才发现漏掉了数据埋点、日志上报这些“隐性工作”。这些问题的根源不是团队不认真而是“拆解”这个动作本身需要同时处理上下文理解、结构化输出、业务知识沉淀三件事人脑在做这件事时很容易疲劳一旦需求文档超过几十页漏项几乎是必然的。1.2 我踩过的痛点可追踪性在第一天就丢了我自己经历过一个非常典型的场景。当时的项目要做一个跨系统的数据同步功能PRD 写了大概 40 多页涉及三个后端服务、一个定时任务、外加前端展示。评审会开了两个小时大家都觉得聊得很透。结果到了开发后期新来的后端同事改一个字段映射逻辑时发现代码里有个分支他完全想不起来对应什么需求去问产品产品也忘了当时为什么加这个逻辑。最后查 git 历史、翻聊天记录折腾了半天才拼凑出完整背景。那一刻我意识到团队缺的不是流程规范而是从需求到代码之间的那个“可回溯索引”。如果有工具能在拆解工作项时自动保留“这个任务对应 PRD 第几节、哪句话、哪个验收标准”这样的映射关系后面所有的变更评估、代码走查、新人 onboarding效率都会完全不一样。1.3 PingCraft 的目标范围与不做的事基于上面的痛点我给 PingCraft 划定了清晰的能力边界。它要做的事情解析需求文档的结构化内容标题层级、段落、表格、列表。基于语义理解将需求拆解为粒度合理的工作项。为每个工作项自动生成类型、优先级、依赖关系、验收标准。建立工作项到原文的引用锚点实现双向追溯。它明确不做的事情不做自动排期和人力分配这是项目管理工具的职责。不替代人工评审Agent 的结果是草稿不是最终结论。不理解代码仓库只处理需求侧不碰实现侧。这个边界很重要。Agent 类工具最容易犯的错误是“什么都想干”最后什么都干不深。PingCraft 只专注“拆解 追踪”这一段其他环节留给专业工具。2. PingCraft 整体架构单 Agent 编排而非多 Agent 群聊的取舍2.1 核心工作流读取 → 理解 → 拆解 → 验证 → 生成PingCraft 的整体工作流可以用一条流水线来描述。读取接收 PRD 文档支持 Markdown、TXT、以及从 Confluence 或语雀导出的 HTML 格式。理解还原文档结构做标题层级树解析、段落分块、表格语义提取然后构建“全局摘要 局部片段”的双层上下文。拆解基于理解结果逐块生成工作项候选每个候选附带拆解理由和原文引用。验证对生成的工作项做一致性校验是否有重复、是否覆盖了原文所有关键内容、验收标准是否可测试。生成输出结构化结果通常是 JSON 或 Markdown直接导入 Jira、Tapd 等项目管理工具。这五步里最容易出问题的不是“生成”而是“理解”和“验证”。很多 Agent 项目栽跟头就是因为跳过了对原文结构的还原直接把整篇文档灌给大模型让它“看着办”。后面我会详细讲这一步。2.2 为什么选单 Agent 编排减少上下文漂移做 Agent 的朋友一定纠结过一个问题到底用单 Agent 一把梭还是搞多 Agent 协作比如一个读文档、一个拆任务、一个质检我在 PingCraft 早期确实尝试过多 Agent 方案结果不太理想。主要原因有三个上下文漂移多 Agent 之间互相传递的是“文本摘要”每次传递都是一次有损压缩。第一个 Agent 读文档时提取的要点到第三个 Agent 手里可能已经走样了。决策责任分散多 Agent 协作时某个质量问题很难定位是哪一环出的错。是理解错了还是拆解逻辑不对还是质检漏了排查成本很高。调用成本翻倍每个 Agent 都需要独立的上下文窗口Token 消耗是单 Agent 的好几倍但产出质量并没有成比例提升。所以最终我选择了单 Agent 强流程约束的架构让大模型在同一个上下文窗口里完成“理解-拆解-自检”全流程但通过结构化的中间产物分块结果、引用映射、检查清单来约束它的行为。这相当于给一个能力很强但容易飘的员工配了一张非常详细的作业指导书而不是给他配三个同事。2.3 关键模块拆解文档加载器、语义分块器、拆解引擎、追踪映射器PingCraft 的代码结构上核心模块有四个。文档加载器DocumentLoader负责不同格式文档的解析统一转成内部的 Document 对象。这里有个关键设计每一行文本都会带上它在原始文档中的位置信息章节路径、段落序号、行号。这个位置信息是后面建立引用锚点的地基。语义分块器SemanticChunker基于标题层级和段落边界把文档切成若干语义完整的块。块的大小直接决定拆解任务的粒度。我实测下来单块控制在 300-500 个字最合适太碎会让大模型失去全局视野太大则会输出泛泛而谈的任务。拆解引擎DecompositionEngine这是核心。它接收分块结果和全局摘要按预设的任务类型模板功能开发、bug修复、技术优化、数据处理等生成工作项候选。追踪映射器TraceabilityMapper负责把工作项里的每一条验收标准、描述要点映射回原始文本的引用锚点。这个模块最终产出的是一个双向索引表。模块之间的数据流是串行的但我在实现时特意做了“中途检查点”。比如分块完成后会把分块结果先输出一份给用户确认用户可以直接在界面上调整块边界再继续往下执行。让关键步骤可人工干预这是 Agent 落地到正式工作流里很重要的一点。3. 需求文档解析让 Agent 真正“读懂”PRD而不是切片喂给大模型3.1 文档结构还原标题层级是理解需求结构的免费午餐很多人做文档类 Agent上来就把 PDF 转成纯文本然后开切这是最大的误区。PRD 最值钱的信息结构占了很大一部分。一份标准的 PRD 通常是这么组织的一级标题需求背景、目标与非目标、术语说明二级标题功能总览、业务流程图、详细功能说明三级标题功能点 1、功能点 2……四级标题功能点 1 的前置条件、交互细节、异常处理……标题层级本身就是一棵树它告诉 Agent哪些内容属于同一个功能模块哪些是并列的哪些是附属说明。如果把这个结构丢了直接平铺成文本大模型就要靠猜来恢复这层关系出错概率大大增加。PingCraft 的文档加载器在解析时会专门构建一棵章节树Section Tree每个节点记录它的标题文本、层级深度、父节点、子节点列表、以及对应正文内容。这棵树在后面做需求块切分和引用锚点定位时是最重要的索引结构。3.2 分块策略“全局摘要 局部片段”双通道上下文大模型的上下文窗口毕竟是有限的。一份 40 页的 PRD 全部塞进去不仅 Token 消耗巨大而且注意力会被稀释拆出来的工作项质量反而不如只看局部。PingCraft 采用“双通道”策略全局通道把整篇文档压缩成一份 800-1000 字的全局摘要重点关注业务背景、核心用户路径、全局性约束如权限、性能、安全要求、与非目标。这份摘要随每个分块一起送入模型让 Agent 在拆解局部功能时始终记得整体目标是什么。局部通道当前要拆解的语义块原文通常 300-500 字保留完整的细节和上下文。这样做的好处是Agent 在拆解某个具体功能时既能看到树的全貌又能看清树叶的纹理。全局摘要负责提供方向感局部片段负责提供精确信息。3.3 表格、原型图、验收标准这些非纯文本内容怎么处理PRD 里的信息载体不仅有文字段落还有大量表格、原型图、时序图。如果只处理纯文本等于瞎了一只眼。我的处理方式如下表格转成 Markdown 表格结构保留行列表头。特别是“字段说明表”每一行往往对应一个接口字段或数据库字段这些是最容易拆成细致工作项的信息源。原型图说实话以当前大模型的能力直接理解多张原型图的视觉细节还很吃力。我的折中方案是要求产品在上传 PRD 时给每张原型图配一段“图注说明”。PingCraft 会优先读取图注文本并将其挂载到原型图所在章节的上下文中。验收标准很多 PRD 里验收标准是单独一个小节通常以“Given-When-Then”或列表形式出现。这些内容拆解时要原封不动地映射到工作项的验收标准字段不能转述一旦转述就会丢失精确性。另外还要提一个容易被忽略的点术语表。技术型 PRD 里常有专有名词缩写比如“DTS”“MQ”“要对账”。如果 Agent 不理解这些词在业务上下文里的含义拆出来的任务描述就会很怪异。PingCraft 在解析阶段会自动提取全文词汇和内置的业务术语表做匹配然后把术语解释作为额外上下文注入拆解引擎。4. 从理解到拆解工作项生成的核心链路与质量护栏4.1 拆解模板类型、优先级、依赖、验收标准一个都不能少工作项不是随便列几条待办就叫拆解。一个合格的工作项必须具备以下字段PingCraft 的拆解引擎就是按这个模板来约束输出的字段说明示例标题一句话描述任务动词开头“实现订单列表的分页加载功能”类型功能开发 / 缺陷修复 / 技术优化 / 数据处理 / 文档补充功能开发优先级高 / 中 / 低基于需求中的措辞强度高依赖关系该任务依赖哪些前置任务或被谁依赖依赖“订单服务接口开发”验收标准可测试的完成条件引用原文见 PRD 3.2.1 节Given 用户已登录When 访问个人订单页Then 每页显示 20 条订单预估复杂度S / M / LM原文引用关联的章节路径和原句§3.2.1 功能描述第 2 段这里我想强调一下优先级自动识别的逻辑这是很多人忽略的。PRD 里通常会有关键词线索比如“核心链路”“必须支持”“最差情况下”“如果时间不够可以”等。PingCraft 会做一个简单的情感/强度分析带“必须”“核心”“关键路径”的内容优先级标为高带“建议”“后续版本”“如果可行”的内容优先级标为低或中。这个规则不复杂但效果非常好。4.2 提示词策略角色设定 思维链 结构化输出拆解引擎的 prompt 设计我迭代了很多版最终稳定下来的框架是“三段式”。第一段是角色与任务说明。我会明确地告诉模型你是一名拥有 10 年经验的研发负责人擅长将产品需求文档拆解为可执行、可验收的开发工作项。你的任务是基于给定的需求文档片段生成结构化的工作项列表。注意你只能输出客观存在的需求内容不能编造需求不能跳过文档中的边界条件和异常分支。第二段是思维链引导。我不会让模型直接输出结果而是要求它分四步走提取该需求片段中的核心功能点和关键业务规则列出所有参与者用户、系统、第三方服务识别主流程、分支流程、异常场景、非功能性要求基于上述分析生成工作项。这个过程相当于让模型先“打草稿”再“出图”比直接生成要稳得多。核心原因在于这四步之间存在逻辑依赖强制分步可以把隐含的推理过程显式化降低漏项率。第三段是输出格式约束。我会在 prompt 里附上一个 JSON Schema 示例明确每个字段的取值枚举、格式要求。比如优先级字段只能是“高/中/低”类型字段只能是预设的几种枚举值。大模型输出一定要先给你定义好 Schema 再让它生成否则你会花大量时间在清洗和重试上。4.3 质量护栏一致性校验、覆盖率检查、循环反馈Prompt 写得再好模型偶尔还是会“放飞”。所以我在拆解引擎之后加了三道质量护栏。第一道叫一致性检查Consistency Check。把生成的工作项列表重新送回给模型让它对照原文检查有没有两个工作项描述的是同一件事有没有工作项的验收标准与原文表述不符有没有工作项涉及原文未提及的内容即模型幻觉第二道叫覆盖率检查Coverage Check。对每个语义块检查它包含的关键业务规则数量与拆出的工作项数量做一个对比。如果某个分块有 6 条业务规则但只拆出了 2 个工作项系统会标记“疑似漏项”要求模型补充。第三道是人工确认回路Human-in-the-loop。所有质量检查通过后结果会进入确认界面用户可以直接编辑、增删工作项然后再导出。Agent 系统的价值在于减少工作量而不是剥夺人的控制权。5. 可追踪性设计每个工作项都能回溯到原文依据5.1 引用锚点机制句子级定位而不是段落级前面提到文档加载器在解析时保留了每一行文本的章节路径和段落号这为引用锚点提供了基础。但实际开发中我发现段落级锚点太粗了。一个段落通常有 3-5 个不同的业务规则如果工作项只挂到段落级别后期评审时还是要整段重读效率并没有提升多少。所以 PingCraft 的锚点做到了句子级。具体做法是对每个段落内部再做一次语义切分把长段落拆成若干短句每句一个编号。工作项的验收标准引用到的是那个句子编号。比如阅读模式是这样展示的原句§3.2.1-03用户删除订单后若订单已支付需在 24 小时内自动发起退款至原支付渠道。对应的引用格式就是[3.2.1-03]工作项描述里直接写“实现已支付订单删除后的自动退款机制引用 §3.2.1-03”。5.2 溯源链的数据结构工作项与原文映射关系如何存储为了实现双向追溯我设计了一个简单的映射数据结构存储在 SQLite 里。核心表有两张work_items和trace_links。work_items表存储工作项本身包括标题、类型、优先级、复杂度、验收标准、依赖关系、状态。每条记录都有一个external_id字段用来关联 Jira 或 Tapd 里创建的任务 ID。trace_links表存储引用关系字段说明work_item_id工作项 IDdoc_id文档 IDsection_path章节路径如 3.2.1sentence_id句级编号如 03quote_text原文摘录方便快速预览link_type关联类型描述依据 / 验收依据 / 依赖依据这个结构非常简单但在实践中非常实用。项目经理在 Jira 里看到一个工作项点开详情页就能看到挂着三条引用分别指向 PRD 的某一句话。点引用就能直接跳到原文。5.3 变更场景下的追踪PRD 改了怎么知道哪些工作项受影响可追踪性的价值在需求变更时体现得最充分。以前需求改了一句话负责拆分需求的人要自己回忆“这句话当时拆成了哪些任务”回忆不出来就得全文检索。有了引用锚点后这个流程变成了产品在 PRD 里修改了§3.2.1-03句子的内容PingCraft 检测到该句子前后版本存在差异触发变更影响分析查trace_links表找出所有引用了该句的工作项输出“受影响工作项清单”标注哪些异常描述更新了哪些验收标准变了哪些依赖关系需要重新评估负责人把清单发给开发逐项确认是否需要调整。这套机制上线后我们团队的需求变更响应时间从半天到一天缩短到了 30 分钟以内。不是我夸张以前人肉找受影响任务真的要半小时起步还不一定找全。6. 落地实践性能数据、失败案例与经验教训6.1 真实业务数据准确率、覆盖率、时间节省PingCraft 在内部测试阶段处理了 47 份 PRD覆盖电商、金融、企业内部工具三个领域。这里给出几个关键数据指标数据说明拆解召回率92.3%人工预标注的关键业务规则Agent 拆出的比例人工修正率26.8%工作项需要人工微调的比例其中大部分是优先级调整平均耗时43 秒/份处理一份约 5000 字的中型 PRD 的时间漏项率7.7%主要集中在“非功能性需求”和“文档隐含假设”两类Token 消耗约 1.8 万/份基于当前模型的估算值全局摘要 局部片段双通道总开销说实话92.3% 的召回率单独看不错但距离“完全替代人工”还有距离。特别是隐含假设和非功能性需求这两块模型表现相对较弱。比如 PRD 里写“参考竞品 A 的交互方式”但没有具体描述交互细节这种信息模型无法凭空拆出任务需要产品补充说明。6.2 三个典型失败案例与根因案例一PRD 里有大量原型图但没有图注。PingCraft 拿到手后完全无法理解页面交互拆出来的工作项是“实现页面交互功能”这种废话。根因是过度依赖纯文本信息对图像理解能力不足。解决方法是强制要求图注并把这些图注作为拆解的必需上下文。案例二一份 PRD 里功能描述特别简略大量依赖“历史约定”和“见旧系统逻辑”这类表达。Agent 拆解时把这些模糊表述当成已知信息生成了看似合理、实则无依据的工作项。根因是模型在遇到信息缺失时倾向于“脑补”而不是“举手提问”。后续修复策略是当检测到文档中出现“已知”“默认”“沿用”“参照”等依赖外部信息的词汇时自动给文档打上“信息完整性风险”标签提示人工介入确认。案例三拆解结果在导入 Jira 时依赖关系全部丢失。原因是 Jira 创建任务的 API 要求先创建任务拿到 issue key才能建立依赖关系而 PingCraft 一开始是批量创建的没法在创建时引用到后续任务的 key。这个不是模型问题是工程实现问题后来改成“分批创建 延迟建立依赖”解决了。6.3 我最后悔没早点做的事如果让我重来一次我会把三件事提前做第一在项目一开始就定义好统一的输出 Schema。早期我花了很多时间在“清洗模型输出”上因为同一个字段今天叫priority明天叫level后天叫priority_level模型一换全部重来。后来自从把 JSON Schema 固定下来并且用结构化生成替代自由文本生成整个链路稳定了非常多。第二把人工修正的数据沉淀下来反哺 prompt。每一处人工修正都代表模型的一个“误判”。我后来建了一个简单的修正日志表定期把修正记录导出来分析高频修正点针对性地改进 prompt 或补充语法规则。这相当于给 Agent 做了持续性的“错题本”。第三更早引入“变更影响分析”。原本我计划做的是“拆解”追踪只是附带功能。但实际用下来变更场景才是这个工具最刚需的场景。需求的拆解频率远低于需求变更频率一次拆解带来的价值是间断的但每一次变更都能用上追踪链路这才是把工具用成“基础设施”的关键。PingCraft 从最初的命令行脚本到现在相对完整的 Agent 服务最大的体会是Agent 类工具能不能在团队里活下来关键不是模型选得多强、提示词写得多花哨而是它能不能嵌进现有的工作流并且解决一个极其具体的痛点。对我而言这个痛点就是“从需求到工作项的追踪断裂”。PingCraft 不敢说做得有多完善但在把 PRD 变成结构化、可溯源工作项这条路上它确实把以前靠人肉完成的脏活累活变成了一个可靠、可验证的流水线。 用 Agent 将 PRD 自动拆解为可追踪工作项：PingCraft 实践
在研发管理这块摸爬滚打多年后我越来越确定一件事PRD产品需求文档到可执行工作项之间的这条链路是整个软件交付流程里最原始、最依赖人肉、也是最容易断裂的一环。产品经理花一周写出一份详尽的需求文档开发拿到后靠“感觉”把它拆成任务排期、估点、写状态。表面上看流程走完了但实际上需求文档里的某个隐藏假设、某条边界条件可能在拆解过程中被悄悄丢掉。等到开发到一半发现“这个字段哪来的”“这个异常分支没人提过”再回头翻文档已经是两个迭代之后的事了。这也是我做PingCraft的初衷用一个 Agent 把“需求文档 → 可追踪工作项”这条路自动化、结构化地走通让每一个工作项都能回溯到它对应的原文依据。这篇文章我会把整个项目的设计思路、核心链路、踩过的坑、以及最终的性能数据完整地摊开来讲希望能给同样在折腾 Agent 落地研发流程的朋友一些实际参考。1. 为什么做 PingCraft需求到工作项的“最后一公里”全是人肉劳动1.1 大多数研发团队的现状PRD写得勤落地全凭嘴先说说我观察到的普遍现状。大部分团队的需求流转是这样的产品写完 PRD组织评审会会上大家口头对齐一遍然后开发负责人会后手动把 PRD 里的内容“翻译”成一个个 Jira 或 Tapd 工作项。这个过程有几个天然缺陷信息损耗无感知口头对齐时大家都说“明白了”但每个人理解的重点不同。开发拆出的工作项往往只覆盖了 PRD 里的主流程异常分支、边界条件、非功能性需求经常被有意无意地忽略。追踪链路断裂工作项描述里通常只有一句“实现 XX 功能”压根不会标注它对应 PRD 的哪一节哪一段。等需求变更时你根本不知道这个工作项该不该改、影响面多大。拆解质量依赖个人经验同一个需求资深开发拆出来的任务颗粒度合理、依赖清晰初级开发可能拆成几个大块到了迭代末期才发现漏掉了数据埋点、日志上报这些“隐性工作”。这些问题的根源不是团队不认真而是“拆解”这个动作本身需要同时处理上下文理解、结构化输出、业务知识沉淀三件事人脑在做这件事时很容易疲劳一旦需求文档超过几十页漏项几乎是必然的。1.2 我踩过的痛点可追踪性在第一天就丢了我自己经历过一个非常典型的场景。当时的项目要做一个跨系统的数据同步功能PRD 写了大概 40 多页涉及三个后端服务、一个定时任务、外加前端展示。评审会开了两个小时大家都觉得聊得很透。结果到了开发后期新来的后端同事改一个字段映射逻辑时发现代码里有个分支他完全想不起来对应什么需求去问产品产品也忘了当时为什么加这个逻辑。最后查 git 历史、翻聊天记录折腾了半天才拼凑出完整背景。那一刻我意识到团队缺的不是流程规范而是从需求到代码之间的那个“可回溯索引”。如果有工具能在拆解工作项时自动保留“这个任务对应 PRD 第几节、哪句话、哪个验收标准”这样的映射关系后面所有的变更评估、代码走查、新人 onboarding效率都会完全不一样。1.3 PingCraft 的目标范围与不做的事基于上面的痛点我给 PingCraft 划定了清晰的能力边界。它要做的事情解析需求文档的结构化内容标题层级、段落、表格、列表。基于语义理解将需求拆解为粒度合理的工作项。为每个工作项自动生成类型、优先级、依赖关系、验收标准。建立工作项到原文的引用锚点实现双向追溯。它明确不做的事情不做自动排期和人力分配这是项目管理工具的职责。不替代人工评审Agent 的结果是草稿不是最终结论。不理解代码仓库只处理需求侧不碰实现侧。这个边界很重要。Agent 类工具最容易犯的错误是“什么都想干”最后什么都干不深。PingCraft 只专注“拆解 追踪”这一段其他环节留给专业工具。2. PingCraft 整体架构单 Agent 编排而非多 Agent 群聊的取舍2.1 核心工作流读取 → 理解 → 拆解 → 验证 → 生成PingCraft 的整体工作流可以用一条流水线来描述。读取接收 PRD 文档支持 Markdown、TXT、以及从 Confluence 或语雀导出的 HTML 格式。理解还原文档结构做标题层级树解析、段落分块、表格语义提取然后构建“全局摘要 局部片段”的双层上下文。拆解基于理解结果逐块生成工作项候选每个候选附带拆解理由和原文引用。验证对生成的工作项做一致性校验是否有重复、是否覆盖了原文所有关键内容、验收标准是否可测试。生成输出结构化结果通常是 JSON 或 Markdown直接导入 Jira、Tapd 等项目管理工具。这五步里最容易出问题的不是“生成”而是“理解”和“验证”。很多 Agent 项目栽跟头就是因为跳过了对原文结构的还原直接把整篇文档灌给大模型让它“看着办”。后面我会详细讲这一步。2.2 为什么选单 Agent 编排减少上下文漂移做 Agent 的朋友一定纠结过一个问题到底用单 Agent 一把梭还是搞多 Agent 协作比如一个读文档、一个拆任务、一个质检我在 PingCraft 早期确实尝试过多 Agent 方案结果不太理想。主要原因有三个上下文漂移多 Agent 之间互相传递的是“文本摘要”每次传递都是一次有损压缩。第一个 Agent 读文档时提取的要点到第三个 Agent 手里可能已经走样了。决策责任分散多 Agent 协作时某个质量问题很难定位是哪一环出的错。是理解错了还是拆解逻辑不对还是质检漏了排查成本很高。调用成本翻倍每个 Agent 都需要独立的上下文窗口Token 消耗是单 Agent 的好几倍但产出质量并没有成比例提升。所以最终我选择了单 Agent 强流程约束的架构让大模型在同一个上下文窗口里完成“理解-拆解-自检”全流程但通过结构化的中间产物分块结果、引用映射、检查清单来约束它的行为。这相当于给一个能力很强但容易飘的员工配了一张非常详细的作业指导书而不是给他配三个同事。2.3 关键模块拆解文档加载器、语义分块器、拆解引擎、追踪映射器PingCraft 的代码结构上核心模块有四个。文档加载器DocumentLoader负责不同格式文档的解析统一转成内部的 Document 对象。这里有个关键设计每一行文本都会带上它在原始文档中的位置信息章节路径、段落序号、行号。这个位置信息是后面建立引用锚点的地基。语义分块器SemanticChunker基于标题层级和段落边界把文档切成若干语义完整的块。块的大小直接决定拆解任务的粒度。我实测下来单块控制在 300-500 个字最合适太碎会让大模型失去全局视野太大则会输出泛泛而谈的任务。拆解引擎DecompositionEngine这是核心。它接收分块结果和全局摘要按预设的任务类型模板功能开发、bug修复、技术优化、数据处理等生成工作项候选。追踪映射器TraceabilityMapper负责把工作项里的每一条验收标准、描述要点映射回原始文本的引用锚点。这个模块最终产出的是一个双向索引表。模块之间的数据流是串行的但我在实现时特意做了“中途检查点”。比如分块完成后会把分块结果先输出一份给用户确认用户可以直接在界面上调整块边界再继续往下执行。让关键步骤可人工干预这是 Agent 落地到正式工作流里很重要的一点。3. 需求文档解析让 Agent 真正“读懂”PRD而不是切片喂给大模型3.1 文档结构还原标题层级是理解需求结构的免费午餐很多人做文档类 Agent上来就把 PDF 转成纯文本然后开切这是最大的误区。PRD 最值钱的信息结构占了很大一部分。一份标准的 PRD 通常是这么组织的一级标题需求背景、目标与非目标、术语说明二级标题功能总览、业务流程图、详细功能说明三级标题功能点 1、功能点 2……四级标题功能点 1 的前置条件、交互细节、异常处理……标题层级本身就是一棵树它告诉 Agent哪些内容属于同一个功能模块哪些是并列的哪些是附属说明。如果把这个结构丢了直接平铺成文本大模型就要靠猜来恢复这层关系出错概率大大增加。PingCraft 的文档加载器在解析时会专门构建一棵章节树Section Tree每个节点记录它的标题文本、层级深度、父节点、子节点列表、以及对应正文内容。这棵树在后面做需求块切分和引用锚点定位时是最重要的索引结构。3.2 分块策略“全局摘要 局部片段”双通道上下文大模型的上下文窗口毕竟是有限的。一份 40 页的 PRD 全部塞进去不仅 Token 消耗巨大而且注意力会被稀释拆出来的工作项质量反而不如只看局部。PingCraft 采用“双通道”策略全局通道把整篇文档压缩成一份 800-1000 字的全局摘要重点关注业务背景、核心用户路径、全局性约束如权限、性能、安全要求、与非目标。这份摘要随每个分块一起送入模型让 Agent 在拆解局部功能时始终记得整体目标是什么。局部通道当前要拆解的语义块原文通常 300-500 字保留完整的细节和上下文。这样做的好处是Agent 在拆解某个具体功能时既能看到树的全貌又能看清树叶的纹理。全局摘要负责提供方向感局部片段负责提供精确信息。3.3 表格、原型图、验收标准这些非纯文本内容怎么处理PRD 里的信息载体不仅有文字段落还有大量表格、原型图、时序图。如果只处理纯文本等于瞎了一只眼。我的处理方式如下表格转成 Markdown 表格结构保留行列表头。特别是“字段说明表”每一行往往对应一个接口字段或数据库字段这些是最容易拆成细致工作项的信息源。原型图说实话以当前大模型的能力直接理解多张原型图的视觉细节还很吃力。我的折中方案是要求产品在上传 PRD 时给每张原型图配一段“图注说明”。PingCraft 会优先读取图注文本并将其挂载到原型图所在章节的上下文中。验收标准很多 PRD 里验收标准是单独一个小节通常以“Given-When-Then”或列表形式出现。这些内容拆解时要原封不动地映射到工作项的验收标准字段不能转述一旦转述就会丢失精确性。另外还要提一个容易被忽略的点术语表。技术型 PRD 里常有专有名词缩写比如“DTS”“MQ”“要对账”。如果 Agent 不理解这些词在业务上下文里的含义拆出来的任务描述就会很怪异。PingCraft 在解析阶段会自动提取全文词汇和内置的业务术语表做匹配然后把术语解释作为额外上下文注入拆解引擎。4. 从理解到拆解工作项生成的核心链路与质量护栏4.1 拆解模板类型、优先级、依赖、验收标准一个都不能少工作项不是随便列几条待办就叫拆解。一个合格的工作项必须具备以下字段PingCraft 的拆解引擎就是按这个模板来约束输出的字段说明示例标题一句话描述任务动词开头“实现订单列表的分页加载功能”类型功能开发 / 缺陷修复 / 技术优化 / 数据处理 / 文档补充功能开发优先级高 / 中 / 低基于需求中的措辞强度高依赖关系该任务依赖哪些前置任务或被谁依赖依赖“订单服务接口开发”验收标准可测试的完成条件引用原文见 PRD 3.2.1 节Given 用户已登录When 访问个人订单页Then 每页显示 20 条订单预估复杂度S / M / LM原文引用关联的章节路径和原句§3.2.1 功能描述第 2 段这里我想强调一下优先级自动识别的逻辑这是很多人忽略的。PRD 里通常会有关键词线索比如“核心链路”“必须支持”“最差情况下”“如果时间不够可以”等。PingCraft 会做一个简单的情感/强度分析带“必须”“核心”“关键路径”的内容优先级标为高带“建议”“后续版本”“如果可行”的内容优先级标为低或中。这个规则不复杂但效果非常好。4.2 提示词策略角色设定 思维链 结构化输出拆解引擎的 prompt 设计我迭代了很多版最终稳定下来的框架是“三段式”。第一段是角色与任务说明。我会明确地告诉模型你是一名拥有 10 年经验的研发负责人擅长将产品需求文档拆解为可执行、可验收的开发工作项。你的任务是基于给定的需求文档片段生成结构化的工作项列表。注意你只能输出客观存在的需求内容不能编造需求不能跳过文档中的边界条件和异常分支。第二段是思维链引导。我不会让模型直接输出结果而是要求它分四步走提取该需求片段中的核心功能点和关键业务规则列出所有参与者用户、系统、第三方服务识别主流程、分支流程、异常场景、非功能性要求基于上述分析生成工作项。这个过程相当于让模型先“打草稿”再“出图”比直接生成要稳得多。核心原因在于这四步之间存在逻辑依赖强制分步可以把隐含的推理过程显式化降低漏项率。第三段是输出格式约束。我会在 prompt 里附上一个 JSON Schema 示例明确每个字段的取值枚举、格式要求。比如优先级字段只能是“高/中/低”类型字段只能是预设的几种枚举值。大模型输出一定要先给你定义好 Schema 再让它生成否则你会花大量时间在清洗和重试上。4.3 质量护栏一致性校验、覆盖率检查、循环反馈Prompt 写得再好模型偶尔还是会“放飞”。所以我在拆解引擎之后加了三道质量护栏。第一道叫一致性检查Consistency Check。把生成的工作项列表重新送回给模型让它对照原文检查有没有两个工作项描述的是同一件事有没有工作项的验收标准与原文表述不符有没有工作项涉及原文未提及的内容即模型幻觉第二道叫覆盖率检查Coverage Check。对每个语义块检查它包含的关键业务规则数量与拆出的工作项数量做一个对比。如果某个分块有 6 条业务规则但只拆出了 2 个工作项系统会标记“疑似漏项”要求模型补充。第三道是人工确认回路Human-in-the-loop。所有质量检查通过后结果会进入确认界面用户可以直接编辑、增删工作项然后再导出。Agent 系统的价值在于减少工作量而不是剥夺人的控制权。5. 可追踪性设计每个工作项都能回溯到原文依据5.1 引用锚点机制句子级定位而不是段落级前面提到文档加载器在解析时保留了每一行文本的章节路径和段落号这为引用锚点提供了基础。但实际开发中我发现段落级锚点太粗了。一个段落通常有 3-5 个不同的业务规则如果工作项只挂到段落级别后期评审时还是要整段重读效率并没有提升多少。所以 PingCraft 的锚点做到了句子级。具体做法是对每个段落内部再做一次语义切分把长段落拆成若干短句每句一个编号。工作项的验收标准引用到的是那个句子编号。比如阅读模式是这样展示的原句§3.2.1-03用户删除订单后若订单已支付需在 24 小时内自动发起退款至原支付渠道。对应的引用格式就是[3.2.1-03]工作项描述里直接写“实现已支付订单删除后的自动退款机制引用 §3.2.1-03”。5.2 溯源链的数据结构工作项与原文映射关系如何存储为了实现双向追溯我设计了一个简单的映射数据结构存储在 SQLite 里。核心表有两张work_items和trace_links。work_items表存储工作项本身包括标题、类型、优先级、复杂度、验收标准、依赖关系、状态。每条记录都有一个external_id字段用来关联 Jira 或 Tapd 里创建的任务 ID。trace_links表存储引用关系字段说明work_item_id工作项 IDdoc_id文档 IDsection_path章节路径如 3.2.1sentence_id句级编号如 03quote_text原文摘录方便快速预览link_type关联类型描述依据 / 验收依据 / 依赖依据这个结构非常简单但在实践中非常实用。项目经理在 Jira 里看到一个工作项点开详情页就能看到挂着三条引用分别指向 PRD 的某一句话。点引用就能直接跳到原文。5.3 变更场景下的追踪PRD 改了怎么知道哪些工作项受影响可追踪性的价值在需求变更时体现得最充分。以前需求改了一句话负责拆分需求的人要自己回忆“这句话当时拆成了哪些任务”回忆不出来就得全文检索。有了引用锚点后这个流程变成了产品在 PRD 里修改了§3.2.1-03句子的内容PingCraft 检测到该句子前后版本存在差异触发变更影响分析查trace_links表找出所有引用了该句的工作项输出“受影响工作项清单”标注哪些异常描述更新了哪些验收标准变了哪些依赖关系需要重新评估负责人把清单发给开发逐项确认是否需要调整。这套机制上线后我们团队的需求变更响应时间从半天到一天缩短到了 30 分钟以内。不是我夸张以前人肉找受影响任务真的要半小时起步还不一定找全。6. 落地实践性能数据、失败案例与经验教训6.1 真实业务数据准确率、覆盖率、时间节省PingCraft 在内部测试阶段处理了 47 份 PRD覆盖电商、金融、企业内部工具三个领域。这里给出几个关键数据指标数据说明拆解召回率92.3%人工预标注的关键业务规则Agent 拆出的比例人工修正率26.8%工作项需要人工微调的比例其中大部分是优先级调整平均耗时43 秒/份处理一份约 5000 字的中型 PRD 的时间漏项率7.7%主要集中在“非功能性需求”和“文档隐含假设”两类Token 消耗约 1.8 万/份基于当前模型的估算值全局摘要 局部片段双通道总开销说实话92.3% 的召回率单独看不错但距离“完全替代人工”还有距离。特别是隐含假设和非功能性需求这两块模型表现相对较弱。比如 PRD 里写“参考竞品 A 的交互方式”但没有具体描述交互细节这种信息模型无法凭空拆出任务需要产品补充说明。6.2 三个典型失败案例与根因案例一PRD 里有大量原型图但没有图注。PingCraft 拿到手后完全无法理解页面交互拆出来的工作项是“实现页面交互功能”这种废话。根因是过度依赖纯文本信息对图像理解能力不足。解决方法是强制要求图注并把这些图注作为拆解的必需上下文。案例二一份 PRD 里功能描述特别简略大量依赖“历史约定”和“见旧系统逻辑”这类表达。Agent 拆解时把这些模糊表述当成已知信息生成了看似合理、实则无依据的工作项。根因是模型在遇到信息缺失时倾向于“脑补”而不是“举手提问”。后续修复策略是当检测到文档中出现“已知”“默认”“沿用”“参照”等依赖外部信息的词汇时自动给文档打上“信息完整性风险”标签提示人工介入确认。案例三拆解结果在导入 Jira 时依赖关系全部丢失。原因是 Jira 创建任务的 API 要求先创建任务拿到 issue key才能建立依赖关系而 PingCraft 一开始是批量创建的没法在创建时引用到后续任务的 key。这个不是模型问题是工程实现问题后来改成“分批创建 延迟建立依赖”解决了。6.3 我最后悔没早点做的事如果让我重来一次我会把三件事提前做第一在项目一开始就定义好统一的输出 Schema。早期我花了很多时间在“清洗模型输出”上因为同一个字段今天叫priority明天叫level后天叫priority_level模型一换全部重来。后来自从把 JSON Schema 固定下来并且用结构化生成替代自由文本生成整个链路稳定了非常多。第二把人工修正的数据沉淀下来反哺 prompt。每一处人工修正都代表模型的一个“误判”。我后来建了一个简单的修正日志表定期把修正记录导出来分析高频修正点针对性地改进 prompt 或补充语法规则。这相当于给 Agent 做了持续性的“错题本”。第三更早引入“变更影响分析”。原本我计划做的是“拆解”追踪只是附带功能。但实际用下来变更场景才是这个工具最刚需的场景。需求的拆解频率远低于需求变更频率一次拆解带来的价值是间断的但每一次变更都能用上追踪链路这才是把工具用成“基础设施”的关键。PingCraft 从最初的命令行脚本到现在相对完整的 Agent 服务最大的体会是Agent 类工具能不能在团队里活下来关键不是模型选得多强、提示词写得多花哨而是它能不能嵌进现有的工作流并且解决一个极其具体的痛点。对我而言这个痛点就是“从需求到工作项的追踪断裂”。PingCraft 不敢说做得有多完善但在把 PRD 变成结构化、可溯源工作项这条路上它确实把以前靠人肉完成的脏活累活变成了一个可靠、可验证的流水线。