0025 联合需求：一个需求同时改几个仓库

• 状态：已采纳（扩展 0018：为其他仓库新建工作区；0023：质量门按仓库进行；落实 1.8 设计中"多代码库需求"的第三种形态）

背景

前后端分在两个仓库的需求很常见：后端加接口，前端加页面。1.8.0-beta.1 起其他仓库可以作为只读参考，但两边都要改时只能拆成两个互不知道的需求：接口由两边各自理解，联调问题要到人工测试时才暴露，两份报告也凑不成"这个需求做完了没有"的答案。

决定

• 主仓库协调，复用单仓库的步骤：发起需求的仓库是主仓库，它的运行就是协调者，状态只有一份（主仓库的 state.json）。不另起子流水线进程：同一套步骤、结果文件、续跑和用量统计都直接适用，只是某些步骤换一个仓库运行。
• spec 头部 - 联合开发：<名称> 指定还要改的仓库，名称来自 relatedRepos，最多两个（一共三个仓库）。启动前检查名称已登记、本机存在、是 git 仓库，否则不启动、不留运行记录。
• 工作区：每个联合仓库由 Paseo 新建一个工作区，分支 feature/<需求>，从那个仓库当前检出的分支切出；那份检出本身不切换分支、不提交（同 0018 的理由）。同名分支已存在时停下来请人处理，不覆盖。
• 步骤怎么分：
  • 方案设计、方案审核与修订、方案确认点、提测说明、功能验证、复验、完成报告都在主仓库。方案按仓库分开写，并写出接口约定 contract.md，方案审核通过后冻结。
  • 实现、代码评审 ⇄ 修复在每个仓库各自进行、同时进行：步骤 agent 的工作目录和 Paseo 工作区是那个仓库的，仍挂在发起的对话下；步骤键加仓库后缀（implement@backend），结果文件写在那个仓库的功能目录。联合需求不按切片实现（每个仓库一个实现步骤），避免切片与仓库交错。
  • 实现前，主仓库的需求说明、访谈记录、方案、接口约定、预览同步到各仓库的功能目录并提交，合并那个仓库的人能在代码旁边读到。
  • 功能验证前，各仓库 paseo.json 中的服务都由 Paseo 用当前代码启动。验证和复验的结果用 defect_repos 写明缺陷在哪个仓库，缺陷修复只在那些仓库进行；没写时每个仓库都看一遍。
• 质量门按仓库：每个仓库用它自己项目配置中的 checks、自己的基线和记录（joint[].codeBase、joint[].gate）；它自己的项目说明、验证方法和按步骤的说明用在它的步骤里。
• 失败与继续：同时进行的步骤中一个失败时，等其他的做完再中断，不让 agent 在没人看着的情况下继续改代码；继续时沿用已建的工作区和已完成的步骤。
• 安全边界不变：只做本地提交，不合并、不推送；各仓库的合并顺序写进提测说明和报告，由人决定。不克隆本机没有的仓库，不自动部署。

影响

• 状态文件新增可选字段 joint，结果文件新增可选字段 defect_repos，格式版本仍为 1。回滚到旧版本后，旧引擎忽略 joint，只在主仓库继续，已经在其他仓库做的改动留在它们的工作区里。
• 每个联合仓库多一次实现和一轮以上的代码评审，用量大约按仓库数增加；三个步骤同时运行时，本机同时运行的 agent 也更多。
• 一个需求的改动分散在几个分支上，合并需要人按顺序进行。

本页由仓库中的 docs/adr/0025-joint-requirements.md 生成。在 GitHub 上编辑