舰队简报
并行代理之所以失败，通常是因为 共享地面——两个通道同时编辑同一个文件。本简报的存在，就是为了在派发之前杜绝这种冲突。边界必须根据实际文件映射来推导，绝不能依靠假设。
按顺序构建简报
1. 先映射文件
在定义通道之前，列出每个拟议变更会涉及的文件。然后读取这些文件。一个没有读取其文件的通道定义，就是一场即将发生的冲突。
2. 分配独占归属
每个文件恰好属于一个通道。生成以下表格：
| 通道 | 拥有（写入） | 仅读取 |
|---|---|---|
| W1 — <名称> | path/a.ts, path/b.ts | path/shared.ts |
如果两个通道需要写入同一文件，你有三个选项——明确选择其中一个，绝不能含糊：
- 串行化（W2 等待 W1 合并）
- 合并成一个通道
- 拼接：一个通道添加扩展点，另一个通道消费它
3. 命名共享地面
列出每个被多个通道读取的文件，并说明谁可以写入该文件。
从你面前的代码库中推导此列表——不要把另一个项目的列表搬过来。值得检查的常见形态包括：
- 实时入站路径。凡是接收 webhook 或用户流量的地方。并发编辑在这里会在生产环境出问题，而不是在测试中。
- 引擎和调度模块，多个功能都会调用它们。
- 仅追加的清单——部署配置、路由表、函数列表。平台有上限（函数数量、文件大小）；两个通道独立追加可能会突破限制。
- 被广泛导入的导出。加法式扩展；一次重命名会波及所有调用者。
- 生成或供应商提供的文件，任何通道都不应手动编辑。
曾经引起冲突的文件，永久视为共享地面。记录在简报中，以便下一舰队继承经验。
4. 推导“禁止操作”列表
每条禁止操作都指明文件名或行为以及理由。单纯的禁止会被忽略；附有理由的才站得住脚。
适用于大多数代码库的条目：
- 冲突解决期间不要
git add -A——它会暂存冲突标记和其他通道的工作。 - 工作者不要在链接的工作树中提交；由协调者提交。
- 如果测试套件全局模拟数据库，绿色的单元测试并不能证明数据库的状态。明确说明。
- 添加依赖项时，必须附上一行理由。
- 不要在通道内部执行数据库迁移。延迟到一个单一的、经过审核的步骤。
- 注意静默失败的 CLI 调用——例如
gh pr create需要显式的--base，链式 heredoc 可能吞掉错误。
然后添加项目特有的条目。每个让你熬夜的事故，都应附上理由记录在这里。
5. 设定门禁
针对每个通道明确说明：“完成”意味着什么，什么证据能证明，以及合并前由谁审核。
值得保留的默认门禁是上线前审核——构建，然后独立行审核，然后必须修复的轮次，最后合并。绝不能仅凭通道作者的一面之词就合并。作者自己的代理是其差异最差的评审者。
6. 标记待定内容
一个“明确未完成——需要人类参与”的章节。为等待明确指示而保留的内容，是有意保留的。不要让某个通道仅仅因为看起来准备好了就去执行它。
隔离
构建应该在 git 工作树中进行，而不是在主检出目录——共享一个工作目录的舰队会交错编辑。如果尽管有文件映射，通道仍然修改重叠的文件，请为每个通道分配单独的工作树。
规模
通道应能独立合并。如果一个通道离开另一个通道的 PR 就无法合并，那它就不是一个通道——而是一个阶段。阶段串行化；通道并行化。
输出
将简报写入项目计划存放的地方，并附上“验证，不要假设”的警告。任何源文档中的状态行只是检查点，不是权威——在根据它们派发之前，重新检查实时提交、数据库状态、PR 检查和工作树头部。