AI Agent 多角色协作总是重复问需求？用单一事实源串起文档、代码和测试

多角色 Agent 最容易出现一个看似荒谬的现象：产品 Agent 刚解释完需求，技术 Agent 又问一遍；代码写完后，测试 Agent 再从聊天记录里猜验收条件；上线时，发布人员仍不知道改了什么。

根源不是 Agent 不会聊天，而是聊天记录不适合承担正式项目依据。它会被截断、被改写、难检索，也无法区分“已确认结论”和“随口讨论”。

什么是单一事实源

单一事实源不是把所有材料塞进一个大文档，而是让同一个需求编号贯穿关键交接物，并明确每类事实该去哪里找。

一个轻量但完整的链路通常包括：

材料	回答的问题
需求说明	为什么做、范围与验收是什么
技术方案	影响哪里、如何实现、有什么风险
代码评审单	实际改了什么、发现了什么问题
测试说明	测什么、异常路径是什么
发布清单	如何上线、如何观察、如何回滚

它们不必冗长，但必须能互相定位。例如每份材料都写 REQ-202607-001，测试就能从需求编号找到方案与评审结论，而不是重新问模型。

每份交接物至少写什么

以技术方案为例，最低字段可以控制在七项：目标、范围与非目标、影响模块、实现思路、风险与待确认项、测试重点、发布与回滚。AI 可以帮助生成初稿，但不确定的内容必须显式标出，不能伪装成已确认事实。

更重要的是“逆向回填”。实施过程中如果发现原方案漏了一个接口、字段或异常分支，不能只在代码里悄悄修正；应回写到方案或评审记录中。否则下一位接手的 Agent 仍会依据旧结论工作。

交接包不要一视同仁

低风险文案修改可能只需目标、文件位置和截图验证；状态机、资金或跨系统改动则需要完整影响分析、数据策略和回滚预案。交接物应随风险增重，而不是每次都复制一份巨大的模板。

一个判断标准是：换一个不了解上下文的人或 Agent，只看交接包，能否知道做什么、为什么这样做、怎样验证、哪里不能碰？能回答这四件事，交接才算够用。

聊天记录为什么不能做正式依据

聊天记录可以保留探索过程，却不适合直接作为交付依据。它至少有四个问题：

• 同一问题可能在不同轮对话中出现互相矛盾的结论。
• 关键决定混在讨论、猜测和临时补充里，难以检索。
• 新参与者通常拿不到完整历史，或者无法判断哪一版已失效。
• 代码实际发生偏离时，没有明确位置要求回写原因。

因此，正确做法不是禁用聊天，而是把已经确认的结论“沉淀”到有编号、有负责人、有更新时间的交接物中。聊天用于探索，项目资产用于协作和审计；两者角色不同。

用一次接口字段变更跑通交接链

假设接口新增一个 channel_note 字段。需求说明需要写明字段语义、谁可见、是否必填和验收示例；技术方案记录涉及的接口版本、数据库迁移、前端页面、导出与调用方；代码评审单记录实际改动与偏差；测试说明覆盖空值、超长、权限和历史数据；发布清单写清灰度顺序、监控指标和回滚策略。

实施中如果发现某个旧客户端无法识别字段，不能只在代码里加兼容分支。应把“兼容策略”回填到方案和评审单，并更新测试场景。这样，下次 Agent 查询该需求时，读到的是最终事实，而不是最初设想。

交接包的责任人和状态

一份文档即使存在，也可能没人知道是否还能使用。建议为关键交接物加入三个轻量字段：

状态：草稿 / 待确认 / 已通过 / 已废弃
负责人：
最后更新时间与依据：

涉及高风险结论时，还应记录批准人和关联评审。这样可以避免 AI 引用一份看起来很完整、实际上已被替代的旧方案。

落地时常见的误区

第一，要求每个需求都填满长模板，结果团队把模板当负担；应随风险调整重量。第二，把“单一事实源”误解为“只能有一个文件”；事实上它是一组有明确关联和优先级的资产。第三，只在需求开始时创建文档，实施偏差却从不回填；这会让真相源很快变成新的历史包袱。

对多数团队而言，先让一个需求编号真正贯穿方案、评审、测试和发布，就比建立一个庞大的知识库更有价值。

项目资产统一，调用配置也应统一

项目事实要有统一入口，团队工具配置也要避免四处散落。Codex、Claude Code 和脚本分别保存不同 API 地址或 Key，会让一次异常很难追查来源。

云舒 API 以 OpenAI 兼容方式提供统一接入，可按成员或项目使用独立 Key，并集中查看模型配置、用量和调用记录。它不是项目文档的真相源，不能代替需求、方案和评审；它的价值是让模型调用层也具备可管理、可排查的入口。具体模型、权限和价格以后台实际展示为准。

可复制的最小模板

需求编号：
目标与验收：
范围 / 非目标：
事实来源：
影响模块：
方案与待确认项：
测试重点：
发布 / 回滚：
实际偏差与回填：

先让一个真实需求用这套模板跑一遍。只要后续角色不再反复追问已确认信息，单一事实源就开始产生价值了。

云舒实践：项目资料统一后，也统一模型调用入口

单一事实源解决“项目结论到哪里找”，云舒 API 解决“模型请求到哪里查”。两者不能互相替代，但一起使用时，团队更容易复盘一个需求的完整过程：文档中有需求、方案和评审事实；云舒后台有对应工具或 Key 的调用记录、模型使用情况和额度信息。

建议按项目或成员创建独立 Key，并在交接包中只记录 Key 的用途或别名，不记录真实密钥。Codex、Claude Code、Cherry Studio 和脚本等 OpenAI 兼容工具，可统一使用：

接口地址：https://yunshuapi.cn/v1
模型名称：以云舒后台模型列表为准

如果 Agent 在某次任务中输出异常，先检查交接物中的事实是否完整，再在云舒后台查看调用记录与模型权限；不要仅凭一次模型回答判断问题一定来自“模型不够强”。这能把项目资料、工具配置和调用证据分层管理，排查也更高效。

云舒后台展示的模型、Key 权限、分组和额度以实际账号配置为准，请勿在公开文章或仓库提交真实 API Key。

关注与下篇预告

本文是《让 AI 负责项目：研发篇》系列第 5 篇，共 9 篇。关注「小陈日常笔记」，接下来进入方案阶段的质量门禁。

下一篇：《AI 生成的技术方案能直接开工吗？一套方案门禁与逆向评审清单》，讲清如何让 AI 的“完整答案”接受独立质疑。