企业官网建设流程全解析

Claude-of-Duty架构全解：如何用1份架构契约协调11个AI Agent并行开发FPS引擎

【免费下载链接】Claude-of-DutyA Call of Duty-quality FPS in Three.js, built from a single prompt.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-of-Duty

Claude-of-Duty 是一个用 Three.js 打造的浏览器 FPS 游戏，约 5.5 万行代码、11 个渲染与玩法子系统全部由 AI Agent 并行开发完成，而让这支 Agent 队伍不互相踩脚的，只是一份不到 170 行的架构契约 ARCHITECTURE.md。本文为你完整拆解这套「一份契约 + 目录所有权 + 事件总线」的多 Agent 协作架构，以及它踩过的坑与拿到的成绩。

🎮 一、先看成果：无美术资源的浏览器 FPS

Claude-of-Duty 的起点只有一段提示词（见 prompt.md）：「做一个《使命召唤》级别的 FPS，用 Three.js，fan out 子 Agent 各自负责一个模块，另派苛刻的批评 Agent 做盲评对比，循环到无可挑剔为止」。

最终产物：

• 零美术资源——所有纹理、网格、动画、声音在加载时由代码程序化生成，唯一运行时依赖是three（见 package.json）
• 11 个子系统——渲染管线、物理、武器、AI、UI、音频等，各司其职（清单见 README.md）
• 完全离线可运行，npm install后npm run dev即可开玩

📜 二、核心机制：一份契约，唯一的协调手段

ARCHITECTURE.md 开头就写明：「每个 Agent 写代码前必须读完本文档，它是唯一的协调机制。」契约由四部分组成：

1. 七条铁律（Hard Rules）

写在 ARCHITECTURE.md，每一条都直接对应并行开发中的真实风险：

第 4 条背后的实现是自研确定性随机数生成器（xoshiro128**，见 src/core/rng.js）——它是后续「像素级像素门」能成立的前提。

2. 子系统接口：统一的「形状」

所有子系统都是同一形状的一个类：static id（唯一身份）、static deps（声明依赖谁）、init/update/lateUpdate/dispose生命周期钩子（契约见 ARCHITECTURE.md，实现注释见 src/core/registry.js）。

引擎（src/core/engine.js）不知道任何子系统在做什么，只按依赖拓扑序统一驱动：先跑 120Hz 定步长的fixedUpdate（物理与确定性玩法），再跑update、lateUpdate，最后交给render出画。这意味着每个 Agent 只需对自己的目录负责，全局时序由引擎保证。

3. 所有权地图：11 个目录 = 11 个 Agent 的工位

契约中的 Ownership Map（ARCHITECTURE.md）把每个目录划给一个id：

而src/core/、src/main.js、tools/归「领队」所有，任何 Agent 不得改动——公共基础设施被锁定，是并行开发不烂尾的关键。

4. 事件总线：跨系统的「普通话」

子系统之间不许直接调用，只许通过事件解耦（ARCHITECTURE.md）：weapon:fire由武器系统发出，fx监听后生成枪口火光，audio监听后播放合成枪声，physics命中后发bullet:impact……契约甚至规定了「需要新事件时，必须在同一提交里往事件表加一行」。

事件总线本身只有几十行：src/core/registry.js 里的EventBus。这种「发件人不负责消费」的约定，让 11 个 Agent 可以并行开工而互不等待。

🏗️ 三、注册顺序为什么可以随便写

在 src/main.js 里，11 个子系统的.add()注册顺序是随意排列的。真正的初始化顺序由 Registry.resolve() 对deps做拓扑排序得出，遇到环或缺失依赖直接抛错。配合运行时ctx.get(id)查找，依赖图永远是显式的——这正是契约注释里说的「让 Agent 可以孤立地拥有文件」的工程基础。

🚦 四、契约的另一半：像素门与可复现性

并行开发还有一层隐藏协调问题：怎么证明某个 Agent 的改动没破坏全局？Claude-of-Duty 的答案是工具链而非口头约定：

• tools/capture.mjs / tools/baseline.mjs：GPU 无头 Chromium 截图，每个镜头独立页面、固定帧预算，保证比特级可复现
• tools/imagediff.mjs：逐像素门，任何像素变动就以非零退出码失败——优化工作流（tools/workflows/perf.js）明确规定：改完必须重跑基线对比，「不许把差异辩解为『肉眼不可见』」
• src/core/prewarm.js：启动前预热全部着色器变体，消除 3 秒级卡顿，且必须「证明像素中立」后才允许默认开启
• 11 个固定机位镜头（src/dev/shots.js）供「批评 Agent」每轮盲评同一构图

这套机制让契约从「文档」变成了可执行的验收标准。

📊 五、实战复盘：并行不是银弹

README 的「Process note」和「Honest assessment」给出了难得的诚实数据（README.md）：

• 盲目并行会翻车：三轮「6 个 Agent 各管一个目录」的并行 fan-out 只把评分从 3.59 拉到 4.05，且画面缺陷数量反而从 60 升到 66——因为色调映射、天空、间接光是一个耦合系统，孤立 Agent 不断打破彼此的假设
• 顺序单 Owner 反而赢了：针对耦合关注点改成「一次一个 Owner 的顺序 pass」后，评分 +1.00，缺陷从 66 降到 26
• Agent 反驳自己任务的时刻最有价值：批评者连报三轮「武器无纹理」，实测其实是高光过强压制了漫反射，修复方向与要求完全相反
• 性能侧：着色器预热把最坏帧从 728–1236ms 压到 66–82ms，且被像素门证明零视觉变化

一句话总结：契约解决「谁拥有什么、如何通信」，顺序与验收门解决「耦合系统别乱拆」。

🚀 六、快速上手：本地运行 Claude-of-Duty

git clone https://gitcode.com/gh_mirrors/cl/Claude-of-Duty cd Claude-of-Duty npm install npm run dev # 打开 http://127.0.0.1:5173

点击画布锁定鼠标后：WASD 移动、鼠标瞄准、左键开火、右键 ADS、R 换弹、Shift 冲刺、Ctrl 蹲、Space 跳、Q/E 探头、Esc 释放。

想深入架构，建议按这个顺序阅读：ARCHITECTURE.md（契约全文）→ src/core/registry.js（注册表与事件总线）→ src/core/engine.js（帧循环）→ 任选一个子系统如 src/fx/index.js 看契约如何落地。

这套架构最值得借鉴的，不是 5.5 万行游戏代码，而是那份让 11 个 Agent 像 11 名纪律严明的工程师一样并行工作的 170 行契约。如果你正准备用多 Agent 方式开发中大型项目，它给出的模板非常清晰：先定所有权地图，再统一接口形状，最后用可执行的验收门把「契约」钉死在 CI 里。

【免费下载链接】Claude-of-DutyA Call of Duty-quality FPS in Three.js, built from a single prompt.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-of-Duty