games-development-ai/docs/agent-specs/_archive/2026-06-20-架构错误根因复盘-report.md

date, topic, status

date	topic	status
2026-06-20	架构错误根因复盘	复盘报告(trace 层) · 已落地修复见 AGENTS.md §6 条款 10/11 + engineering-conventions §10.7 + 生成主线架构演进路线 ★终态定调

架构错误根因复盘：为什么「结构化源项目」做成了「JSON 生成游戏」

写在前面

2026 年 6 月 20 日，创始人指出了一个一直没被正面承认的事实：生成主线的核心设计错了。设计文档白纸黑字要求生成的游戏是一个结构化、模块化、可维护的 src/ 源代码工程，方便 agent 定位和修改；可实际落地的实现，却把整段玩法逻辑塞进了一个 JSON 字符串字段（behavior.code），运行时用 new Function 解释执行。产出的是「机制上合法、但视觉上是几何色块、玩起来没人想玩」的玩具，而创始人最初要的「代码目录清晰、结构一致、好定位好探索」一条都没兑现。更糟的是，号称卖点的「点对点修改」——改一个 JSON 字段重新生成——在分辨率、尺寸、资产这些维度根本不成立。

这份文档不讨论「接下来怎么修这个设计」（那是另一件事），它只回答创始人提出的三个问题：为什么会出现这种错误？错误的根因是什么？以后怎么才能从过程上避免？ 这是一次过程复盘，不是技术方案。

复盘的方法本身也值得一提：根因不是一个人拍的，而是先列出二十多条候选原因，再派两个互相独立的对抗验证子代理（codex 与 opus）各自回到真实的 git 历史、设计评审文档、代码现场逐条核验——哪条是真根因、哪条只是症状、哪条夸大不成立——最后取两者都判「成立」的作为铁的结论，分歧处由主 agent 裁断。下面的结论，是这样筛出来的。

错误的两条根因轴

复盘下来，这次错误不是单点失误，而是两条彼此独立、又相互喂养的根因轴同时失效。

第一条：决策层——评审从不质疑前提

两个验证器各自独立地，把「最深的那一个根因」指向了同一个地方：从生成范式被定下来的那一刻起，所有的评审都只在这个范式内部审细节，从来没有任何一道工序的职责，是站到范式外面问一句「这个前提本身对吗」。

具体到这次：范式的出发点是「便宜模型脾性」——既然便宜模型自己发明不出可靠的代码结构，那就让强模型设计一个固定的脚手架、让便宜模型往槽里填。这个出发点本身是从「手段约束」出发的，不是从「用户想玩什么游戏」这个产品目标反推的。然后，决定范式的两份关键评审里，从没有摆出过两三个本质不同的方案（比如「真多文件代码工程」对「声明式 JSON 壳」对「OpenGame 式受控自由代码」）让创始人在优缺点和风险之间选；它直接把「JSON 填槽」作为唯一结论展开落地。再然后，这个范式的「正确性」，是用「双证地基成立」（便宜模型能产出连贯的 gameDefinition、产物能过九门）来证明的——而这恰恰是在用工程指标（可靠、可自动验收）证明一个产品命题（用户想玩）。

最致命的是：codex 和 opus 评审了两三轮，连「对抗验证」都挂上了，但所有这些评审的问题都是「这个 JSON 架构设计得好不好」，从来不是「它该不该是 JSON」。这个问题，直到 2026-06-20 才第一次被正式问出口——那时 gameDefinition 已经双证、十六节点的图已经合进主干。

为什么说这是「最深」的根因？因为其他所有根因——优化了错的目标、验证验了错的东西、AI 偏向可测量的——都能被「一次对的早期评审」捕获；唯独「没有人被指派去质疑前提」是结构性的缺失，意味着这个捕获机制从一开始就没被设计进流程。它是一台会把任何错误前提精致化、自洽化、并用自产证据加固的机器：设计能力越强、验证越密、蒸馏复利越快，跑偏得越远、还越自信。

第二条：知识层——设计写对了，实现却没兑现

第一条解释了「为什么定了个错范式」，但还有一个独立的问题：即便某一层的设计是对的（生命周期设计确实白纸黑字要了 src/ 模块化代码工程），这个正确的意图也没能传导到实现。 这是另一条轴，机制完全不同。

断点不是「实现者没读设计文档」。真实的机制是一次**「沉默的重解释」**：中间那份《固定游戏架构》文档，开头声称自己是生命周期设计的「具体落地」，却在文档中途把核心定义悄悄换掉了——把「src/ 多文件工程」重解释成了「gameDefinition JSON」，还自己补了一句「诚实边界：MVP 可以退化成单 behavior」。下游的 plan 把 canonical 指针指向了这份《固定架构》而不是生命周期设计，实现于是忠实地照着它做。实现是忠实的，只是忠实的对象在中途被掉包了——而没有任何一道门，去对账「这个重解释放弃了什么、还满不满足原始设计的可维护性要求」。引用链表面是连着的，核心定义却在中间断了，没人发现。

这种「文档写对、实现没兑现」在 AI 驱动开发里不是偶然事故，是这套范式不加治理时的默认输出，因为它叠加了四个放大器：AI agent 是无状态的，每次靠当下读进上下文窗口的那些文档片段重建认知；它会近乎百分之百信任它读到的那一份，不像人类工程师那样凭记忆和直觉嗅出「这文档好像过期了」；当它同时读到冲突的两份时，没有任何元信息告诉它哪份权威，只能掷硬币；而最致命的是，即便它读到了正确的设计，也没有任何一道门会在事后把实现产物和设计声明对照一遍。

这条轴底下还压着两个更结构性的问题。一个是整体一致性无人负责：这个项目的单一事实源维护、索引同步、收口退役，在文档里全都落在「主 agent」身上——而主 agent 是个无状态、每会话重建、用完即弃的主体。把「看护整体」的责任交给一个根本没有「整体」和「长期」概念的东西，等于交给了没有人。品牌名能半新半旧地散在几十份文档里、连 AGENTS.md 自己的标题都过期十天没人改、同一个生成主题散在三十多份文档里彼此矛盾，全都因为这些是「跨文档、跨任务、跨时间」的整体性问题，而体系里没有任何角色的职责是看护整体。另一个是规则没有被编译成机器门：项目其实有一整套相当完善的文档治理规则（命名、状态、退役、一题一活档、canonical），但这些规则全部依赖人——依赖 agent——自觉去读、自觉去执行，而无状态 agent 最不可靠的恰恰就是「自觉」。一条没有机器门把守、没有责任人认领、没有触发点强制运行的规则，对一个用完即弃的 agent 来说，约等于不存在。

更深的一层：AI 会系统性地优化「可测量的」而非「好的」

把两条轴往下再挖一层，会碰到一个更普遍的机制：用 AI 驱动开发，在没有人锚的情况下，系统会自然地偏向「可测量的目标」，而不是「好的目标」。 九门可以自动跑、可以当 reward 信号；「好玩」不能自动判、给不出 reward 信号；于是整个 build-verify 循环自然地把「可被 harness 验证的」置于中心，把「用户想不想玩」挤到边缘。这不是某个人的疏忽，是这套开发范式的引力方向。它也解释了为什么「工程沉淀在 harness、单次生成是消耗品」这种话听起来如此顺理成章——因为它正是这个偏误的产物。

这次复盘本身，就是机制价值的活证

有一件事必须写进来，因为它比任何论证都更有说服力：在这次复盘的过程里，创始人又连续做了四次「质疑前提」，每一次都揪出了真东西。

他先问「没考虑过 agent 的管理吗」——这是一个主 agent 和子代理都漏掉的真盲点，我们把可观测性框成了「看图、看日志」，漏了「agent 的创建、编排、管理」整个维度。接着他问「我们自己实现的 StateGraph 是 SAA 官方推荐的用法吗」——查实下来，这次前提是对的（裸图确实是官方背书的核心用法），但质疑的过程把「凭感觉对」变成了「源码加官方双证的对」、排除了「用错框架」的风险。再接着他问「SAA 到底有什么用，不能编排和写 if-else 有什么区别」——这一问切中了 SAA 对这种用法在「可管理性」维度上的真实局限。最后他指出「九门只是一个验证工具，不是绑死在 SAA 的控制流」——这一下戳破了一个一直没被意识到的伪矛盾：我们把一个验证工具神秘化成了「现成平台表达不了的特殊控制流」，并基于这个错误前提差点得出「必须自研」的错误结论。

这四次质疑，有的揪出盲点、有的确认前提、有的拆穿伪矛盾——但它们共同证明了一件事：前提证伪不是抽象的口号，它每一次都产出真东西。 这恰恰就是第一条根因要立的那道工序的实战示范，而且是创始人本人在一次次示范它。一个健康的流程，本该把这种「站到前提外面发问」的动作，制度化成不依赖某个人灵光一现的固定工序。

怎么避免：把每条教训编译成机制

复盘的落点不是「下次小心点」，而是把每条根因变成一个不依赖自觉的机制。这次会话里，已经落地了一部分：

给每个范式级决策强制一道「前提证伪」工序。 派一个独立的角色（人或 agent），它的职责不是「这个设计好不好」，而是「这个前提对吗、如果它是错的会怎样、我们是不是在测量正确的东西」。这次复盘就是这道工序迟到的样板。配套地，范式级决策必须并列至少两个本质不同的方案，从「产品要什么」反推，而不是从「模型能干什么」反推。

把「好玩 / 用户价值」操作化成一条早期门。 哪怕先粗——非退化、失败可达、有正反馈节奏——也要让它和九门并列、有否决权。只要「好的」那一端不再是空占位符，AI 偏向「可测量的」那股引力就失去了畅行的空间。

把文档治理规则编译成机器门。 这次已经把四道门写成了可执行规格并挂进收口流程：品牌不变量门、canonical 唯一性门、doc↔code 兑现门、入口卫生门（细则见 engineering-conventions §10.7）。其中 doc↔code 兑现门正是「沉默的重解释」那个根因的正解——它要求一份基石设计声称的关键产物约束，必须带一条机器可校验、且收口时真跑的断言；首批断言就是「生成产物必须是 src/ 多文件工程，逻辑不得只以 JSON 字符串或 new Function 的形态存在」。设计声称 X，代码就必须可验证地兑现 X，而不是只在文档里写了 X。

给整体一致性立一个有状态的主人。 那些机器门兜不住的灰度判断——哪份文档过期了、两份冲突的哪份胜出、一个补丁是不是其实是架构信号——显式归属给创始人加 6c6g 文档设计线这个有状态的主体，不再无主地压在无状态的主 agent 头上（已写进 AGENTS.md §6 条款 11）。

一句诚实的平衡话

最后必须说清楚，免得这份复盘自己滑向「全盘否定」：这次犯的不是「做了个没用的东西」的错。 那套 JSON 声明式生成，作为面向便宜模型加自动验收的 Tier0 超休闲产线，是聪明的、抗作弊的、该坚持的工程。真正的错，是把一个对的 Tier0 东西，当成了通用范式去对标漫威、拳皇那种富交互游戏，还用「能过九门」这种机制证明去加固「它是通用范式」的错觉。所以改过程要瞄准的是「别再用局部自洽冒充全局正确」，而不是推翻 Tier0 本身。

收束

把这一切收成一句话：这次错误根上不是「规则没写」，而是「规则没被编译成机制、也没有人被指派去质疑前提」。在一个由无状态 agent 驱动的开发体系里，任何依赖主体自觉的规则、任何无人负责的整体一致性、任何没人质疑的前提，都等于不存在。 修它的方向，不是把规则写得更严厉，而是在 agent 会犯错的每一个点上，都放一个不依赖 agent 自觉的机制——机器门、有状态的责任人、和一道制度化的前提证伪工序。