很多人第一次让Codex处理复杂工程任务时会发现一个明显变化问题已经不再局限于一个Repository。一个真实需求可能同时涉及frontend ↓ api ↓ service ↓ shared-sdk比如给支付系统增加一种新的退款状态。表面上只是一项Feature。实际上可能需要前端增加状态显示API增加字段Service修改业务逻辑SDK更新Type测试同步调整。这时候真正困难的已经不是Codex能不能修改4个Repository而是怎样让4个Repository的修改最终仍然属于同一个Task。Codex现在越来越强调长任务、多个项目、多个Agent以及独立Worktree等工程能力官方最佳实践同样强调面对大型或复杂Repository时最重要的是给Codex正确Context以及明确的任务结构。所以多Repository任务真正需要解决的是Goal ↓ Dependency Graph ↓ Repository Boundary ↓ Execution Order ↓ Cross-repo Verification ↓ Evidence如果没有这套结构Repo越多Agent越容易失控。一、第一种失控把4个Repository当成4个独立任务这是最常见的问题。假设一个需求支付接口新增refund_reason字段。涉及frontend api service sdk最简单的拆法是Agent A 修改frontendAgent B 修改apiAgent C 修改serviceAgent D 修改sdk看起来非常适合多Agent。但这里隐藏着一个问题四个Agent看到的是四个局部任务。它们可能分别完成得很好。最终却拼不起来。例如Service新增refundReasonAPI返回refund_reasonSDK定义reasonFrontend又按照旧字段refundMessage每个Repository内部都能Build。但整个系统Contract已经分裂。所以多仓库任务第一条原则应该是先定义全局Goal再拆Repository任务。而不是先拆Repo再让各自想Goal。二、真正应该先建立的是Dependency Graph一个任务跨多个Repository以后Repo之间通常不是并列关系。而是有依赖顺序。例如shared-sdk ↓ service ↓ api ↓ frontend如果SDK定义先变化后面的Repository才能基于新Contract继续修改。但另一类任务可能是database ↓ service ↓ api还有一些任务则可以并行backend test ↘ integration ↗ frontend test所以多Repository任务真正需要先回答谁依赖谁而不是有几个Repo可以给任务先画一个非常简单的Dependency Graphshared-contract ↓ backend-service ↓ api-gateway ↓ frontend然后再决定哪些串行哪些并行。三、第二种失控该串行的任务被强行并行多Agent最容易让人产生一种冲动既然能开多个Agent那就全部同时跑。但并行的前提是任务之间不存在强因果依赖。比如Agent A正在设计新的API字段。与此同时Agent B已经开始修改Frontend。问题是Frontend依赖的Contract还没有稳定。于是Agent B只能猜。最终常见结果就是Agent A 改变接口导致Agent B 重新修改然后Agent C 再重新适配表面上并行了。实际上产生了大量Rework。Codex App本身支持多个Agent并行运行并通过独立Thread和Worktree降低任务之间的相互干扰但这种能力解决的是执行隔离并不意味着所有存在依赖关系的任务都应该并发。所以多仓库调度应该区分Independent → ParallelDependent → Serial四、怎样判断两个Repo能不能并行可以问一个非常简单的问题Repo B开始工作之前是否需要等待Repo A产生新的Contract或状态如果不需要就适合并行。例如Frontend UI tests和Backend logging可能彼此独立。但如果Frontend必须等待新的SDK TypeAPI必须等待Service ContractMigration必须先于Application Code那么就应该串行。可以简单抽象成Can Start With Current State?如果答案是Yes可以并行。如果No等待上游结果。五、第三种失控Context开始跨Repo污染单Repository里已经存在Context Pollution。多Repository以后问题会放大。Agent可能同时读取frontend/README backend/README sdk/AGENTS.md service/docs不同Repository甚至可能拥有完全不同的编码规范测试命令目录结构发布流程。例如Repo A规定pnpmRepo B使用npmRepo C使用yarn如果所有信息进入同一个长ContextAgent非常容易开始混用规则。因此多Repository任务不能只有一份巨大的Global Context。更合理的是分成两层。六、第一层Global Task Context这一层只保存跨Repo都需要知道的内容。例如Goal最终要完成什么。Global Contract接口、字段、行为应该最终变成什么。Dependency GraphRepo之间的顺序关系。Acceptance Criteria整个任务什么情况下才算完成。例如Goal: 增加refund_reason Global Contract: refund_reason: string | null Acceptance: API返回正确字段 SDK类型更新 Frontend正常展示 Integration Test通过这一层不应该塞某个Repo具体怎么Build。七、第二层Repository Context每个Repository独立维护Repo Rules Build Command Test Command Directory Boundary Local Constraints例如frontendpnpm test pnpm lintservicemake test make integrationsdknpm test npm run build于是Context结构变成Global Task Context ↓ ┌──────┼──────┐ ↓ ↓ ↓ Repo A Repo B Repo C Context Context Context这样Agent不会因为看了太多不同工程规则而逐渐混乱。OpenAI目前关于Codex复杂工程任务的最佳实践也强调需要给Agent清晰的任务结构和正确范围的Context而不是无限扩大上下文。八、第四种失控一个Repo完成就误判整个Task Done这是多仓库任务最危险的问题之一。比如Service修改完成。测试通过。Agent输出Task completed successfully.从Service视角确实完成了。但全局Goal可能还有SDK 未修改Frontend 未适配Integration 未验证所以多Repository任务必须区分两个Done。Repo DoneRepository内部工作完成Goal Done所有Repository组合以后 满足最终业务目标两者不能混在一起。九、应该建立两级Completion State每个Repo都有自己的状态Repo A Implemented Tested ReadyRepo B Implemented Tested Ready但最上面还要有Global Task Waiting Cross-repo Verification完整流程更应该是Repo A Done Repo B Done Repo C Done ↓ Cross-repo Integration ↓ Verification ↓ Goal Done这也是为什么Agent真正进入复杂工程以后Task State Management会越来越重要。单纯看聊天窗口里的Done已经不够。十、第五种失控每个Repo都测试通过但系统还是坏的这是多Repository最经典的问题。比如SDKTests PassedServiceTests PassedAPITests PassedFrontendTests Passed看起来全部绿色。上线以后却报错。为什么因为所有测试验证的是Local Correctness。没有验证Cross-repo Contract。例如SDK认为字段refundReasonAPI返回refund_reason两边自己的Unit Test都能通过。但真正组合以后失败。十一、多仓库必须增加Cross-repo Verification至少应该有一层Integration Contract负责验证Repo之间接口是否匹配。例如SDK Type ↓ API Response ↓ Frontend Consumption或者Producer ↓ Message Schema ↓ Consumer所以完整验证应该分成Local Verification每个Repo自己的Test Lint Build然后Cross-repo Verification整个系统Contract Test Integration Test E2E最终Local Correctness Integration Correctness Goal VerificationCodex官方一直强调验证和可审查结果的重要性其Git工作流也把独立修改、Diff Review以及后续验证作为Agent工作的重要组成部分。十二、第六种失控Diff、Branch和Commit最后根本没法Review这是实际开发中非常容易被低估的问题。假设一个任务同时产生Repo A 8 filesRepo B 12 filesRepo C 6 files如果所有Agent各自随意创建Branch命名Commit修改额外文件做顺手重构最后Reviewer看到的就不是一个Feature。而是26个文件 多个不同方向的变化。这时候最大的成本已经不是生成代码。而是理解发生了什么。十三、多Repo任务一定要控制Diff Boundary每个Repository在开始执行之前都应该定义Expected Files大概会修改哪些区域。Allowed Scope哪些模块允许改变。Forbidden Scope哪些区域不能顺手重构。例如Repo: api Allowed: src/refund/ src/schema/ Avoid: auth/ payment-core/ global-config/这样Agent才能避免为了完成一个小Feature顺手改了半个Repository。Codex现在允许用户直接Review Agent产生的Diff并在Thread中继续评论和修改这种Review能力的价值在复杂任务里尤其明显。十四、Commit也应该围绕Goal组织不要出现fix stuffupdate fileschanges更合理的是sdk: add refund_reason typeservice: support refund_reason persistencefrontend: render refund reason这样Reviewer看到Commit就能立刻建立Global Goal ↓ Repo Contribution多Repository任务真正需要的是Traceability。也就是能回答这个Repository里的修改为整个Goal贡献了哪一部分十五、Worktree解决的是“执行隔离”不是“架构协调”多仓库和多Agent结合时Worktree非常有价值。Codex当前的Worktree机制可以让多个独立任务在同一个Git项目中运行而不直接影响开发者当前工作目录不同Thread可以拥有各自独立的代码状态。但一定要理解Worktree解决Agent A 不覆盖 Agent B它并不能解决Agent A 是否应该先于Agent B也不能自动解决Repo A Contract 是否和 Repo B Contract 一致所以Worktree State Isolation而不是Worktree Task Coordination这一点很关键。十六、多Repository任务更适合“主任务 子任务”如果任务比较复杂我更建议使用Root Goal ↓ Repo Tasks而不是4个平行Prompt例如Root Goal实现refund_reason端到端支持。然后拆Task A Update shared contractTask B Update service Depends on ATask C Update API Depends on BTask D Update frontend Depends on A C最后Task E Cross-repo Verification Depends on ABCD完整结构变成Goal ↓ Shared Contract ↓ ┌────┴────┐ ↓ ↓ Service SDK ↓ ↓ └────┬────┘ ↓ Frontend ↓ Integration Verify这时候Agent执行的是Dependency Graph。而不只是Task List。十七、什么时候应该使用多个Agent不是Repo数量达到2个就应该多Agent。如果任务强依赖A ↓ B ↓ C一个Agent顺序执行反而可能保持更稳定Context。但如果任务结构是Goal ↙ ↓ ↘ A B C三者基本独立就非常适合多个Agent并行。Codex目前支持多个Agent跨项目并行执行长任务但真正能从并行中获益的仍然是可以独立推进的工作单元。所以多Agent判断标准应该是Dependency Density。依赖越少越适合并行。依赖越强越应该串行。十八、什么时候应该开新Thread多仓库任务还有一个很实用的问题到底所有Repo都放在一个Thread里还是拆Thread可以用一个简单原则同一个决策链保留同Thread。例如API Contract ↓ Service Implementation两者Context强相关。独立执行任务可以拆Thread。例如Frontend visual test和Backend logging互相不依赖。拆Thread能够减少Context Pollution。Codex App本身就是通过独立Thread组织多个Agent任务让不同工作保持自己的Context和修改状态。十九、一套比较稳的多Repository执行流程真正开始任务之前第一步Define Goal写清最终用户行为应该发生什么变化不要先谈文件。第二步Build Dependency Graph列Repo A ↓ Repo B ↓ Repo C判断哪些串行哪些并行。第三步Define Global Contract例如API Schema Event Schema Shared Type Database Contract先固定跨Repository接口。第四步Create Repo Tasks每个Repo明确Input Scope Output Verification第五步Execute独立任务可以并行。依赖任务按顺序执行。第六步Local Verification每个RepoTest Lint Build第七步Cross-repo Verification再跑Integration Contract E2E第八步Evidence Review最后输出Repo Changed Files Tests Contract Remaining Risk最终才Goal Done二十、可以直接套用一个Multi-repo Task Contract以后碰到跨仓库任务可以先给Codex明确下面这些内容Goal: 实现什么最终行为 Repositories: 涉及哪些Repo Dependency: Repo之间谁依赖谁 Global Contract: 跨Repo接口是什么 Scope: 每个Repo允许修改什么 Verification: 每个Repo怎么验证 Integration: 最终怎样验证整个系统 Done: 什么情况下整个Goal才完成然后再执行。这比简单告诉Codex把这几个Repository一起改一下。稳定得多。最后一个任务跨多个Repository以后最大的风险不是Codex看不懂多个Repo。而是局部修改越来越容易整体一致性越来越难。单Repo时代Task ↓ Repo ↓ Test ↓ Done多Repo时代则变成Goal ↓ Dependency Graph ↓ Multiple Repositories ↓ Local Verification ↓ Cross-repo Verification ↓ Evidence ↓ Done这时候真正需要管理的已经不是Files。甚至也不只是Repositories。而是Dependency。因为一个大型Feature最终是否成功取决于谁先修改谁依赖谁Contract是否一致Context有没有污染每个Repo是否只修改自己的边界整个系统最终有没有重新被验证。所以多Repository Agent工程真正需要建立的思维不应该是开更多Agent。而应该是先建立一个能够被Agent执行的Dependency Graph。当这套结构清楚以后Codex才能真正从同时修改多个Repository进化到围绕一个Goal协调多个Repository完成工程任务。持续更新Codex、大模型开发相关技术内容。长期使用各类代码大模型整理了稳定的AI会员订阅渠道。