EGM 架构与系统生命周期¶
- 作者: Jim Quinn (@quinnjim), Elise Ewing (@eewing314), Dave Rensin (@drensin)
- 状态: 当前
- 日期: 2026-06-06
概述¶
Elephant-Goldfish Model (EGM) 是规格驱动开发(SDD)的一种实现,基于 Elephants, Goldfish, and the New Golden Age of Software Engineering 一文。它强调协作式使用 AI 进行设计与评审,并维护已通过验证的技术规格,直接将其检入代码库。
本文档规定了 EGM 的整体系统架构:其组件模型、端到端数据流,以及其在各编码代理运行时中的生命周期。
问题¶
非结构化、对话式的 AI 代码生成存在四种系统性失效模式:
- 幻觉级联与上下文污染:当单个 LLM 线程负责访谈开发者、创建设计并编写代码时,会话上下文会累积推测性假设和对话偏差。模型会验证自身有缺陷的假设,而不是检测错误。
- 过早实现("杂草综合征"):编码代理默认会立即在就近文件中编写代码,绕过高层架构定位、简洁性检查(YAGNI)以及现有基础设施的复用。
- 聊天倾泻疲劳:直接在聊天窗口中呈现多页设计规格或冗长的评审反馈,会扰乱对话历史、降低 LLM 上下文性能,并造成糟糕的用户体验。
- 文档漂移:项目启动阶段编写的设计文档通常会随代码演进而逐渐腐化,破坏未来 AI 代理的接入体验。
设计原则¶
-
Elephant 与 Goldfish:
- Elephant:一个深上下文代理,加载系统历史、CUJ 和代码库地图,用于探索需求并起草设计。
- Goldfish:隔离的、零上下文子代理评审者,依据评审准则评估草案,不受上下文偏见影响。
-
人类负责制:AI 是用于探索和评审的工具;人类工程师负责架构决策与权衡,并对最终结果负责。
-
工件优先体验(Artifact-First UX):所有长篇交付物(草案、摘要、评审报告)都会被渲染到专用的侧边栏 Markdown 工件或工作区文件中,并设有交互式反馈检查点。
-
活规格(Living Specifications):设计文档是检入源码树(
docs/designs/)的工件,并被持续监控是否存在代码库漂移。
系统架构与组件模型¶
开源 EGM 框架由四个解耦的子系统组成:
1. 技能层(skills/)¶
可通过斜杠命令或直接调用执行的模块化代理能力:
egm-brainstorm:用于早期概念探索的 7 视角击落群体。egm-draft:逐节编译规格的规格编译器。egm-review:多阶段评审流水线的编排器。egm-review-loop:并发子代理评审调度器。egm-resolve:交互式决议与补丁应用。egm-drift-report:通过主机搜索和文件读取工具,将规格和 README 与代码进行比对的代理工作流。egm-bootstrap:递归自底向上的代码库文档生成器。
2. 角色层(agents/)¶
为隔离的 Goldfish 评审子代理提供的无状态系统提示词指令(Comprehension、Design Critic、Implementation Readiness、Codebase Auditor、Structural Validator、Style Editor、Inventive Catalyst 和 Synthesizer)。
3. 文档标准(resources/document_standards/)¶
Goldfish 评审者会加载 共享运行时资源 中列出的版本化评审准则。这些文件负责定义评估要求;本文档描述各层如何运用它们。
4. 活文档(docs/)¶
用户指南(getting_started.md、faq.md)与技术设计规格(docs/designs/)。
端到端生命周期与数据流¶
EGM 开发流水线将工件沿着五个严谨的阶段流转:
sequenceDiagram
autonumber
actor Human as Software Engineer
participant Elephant as Elephant (Brainstorm & Draft)
participant Artifact as Side-Panel Artifact / File
participant Reviewer as Goldfish Reviewers (Synthesizer)
participant VCS as Version Control (PR)
participant Coder as Implementation Agent
Human->>Elephant: /egm-brainstorm (Multi-Lens Ideation & Shootdown)
Elephant->>Artifact: Write concepts_brief.md
Human->>Elephant: /egm-draft
Elephant->>Artifact: Write docs/designs/FEATURE.md
Human->>Reviewer: /egm-review docs/designs/FEATURE.md
Note over Reviewer: Zoom Out -> Comprehension -> Critic -> Zoom Out -> Readiness
Reviewer->>Artifact: Write review reports & findings
Human->>Reviewer: Triage & resolve findings (/egm-resolve)
Human->>VCS: Open Pull Request with FEATURE.md
VCS-->>Human: Spec Approved & Merged
Human->>Coder: Implement against FEATURE.md阶段 1:上游构想与多视角击落(Elephant)¶
- 命令:
/egm-brainstorm - 机制:Elephant 访谈工程师以锚定核心假设,然后生成 7 视角 Goldfish 群体,击落有缺陷的假设。
- 输出:写入
concepts_brief.md的结构化简报。
阶段 2:规格编写与语义边界¶
- 命令:
/egm-draft - 机制:将概念简报(或讨论笔记)转换为符合 EGM 规范的技术设计文档,写入
docs/designs/<feature>.md。 - 语义边界发现:在高层架构(
FeatureRange)与详细实施计划(DetailedRange)之间建立清晰的边界,从而实现有针对性的子代理评审。
Phase 3:隔离验证(The Goldfish)¶
- 命令:
/egm-review - 执行方式:执行一个五阶段评估流水线:
- 步骤 5:Zoom Out 审查:对照
zoom-out-standard.md评估简洁性、YAGNI 与代码库复用。 - 步骤 6:理解测试:由隔离的朴素读者审计文档,检查其自包含性和缺失的背景知识。
- 步骤 7:Critic 审查:对照
feature-spec-standard.md评估系统设计、规模瓶颈与故障模式。 - 步骤 8:中间 Zoom Out:对照
zoom-out-standard.md,对理解阶段和 Critic 阶段新增的内容进行重新审计。 - 步骤 9:实现就绪测试:对照
implementation-readiness-standard.md验证文件路径、函数签名和测试用例。
- 步骤 5:Zoom Out 审查:对照
- 子代理扇出/扇入:
synthesizer角色并行生成隔离的审查者,汇总原始发现,去重重叠内容,并编写整合后的 Markdown 报告。
Phase 4:人工审查与提交¶
- 人类工程师使用
/egm-resolve解决或驳回 Goldfish 发现,更新设计文档,并通过 Pull Request 提交规范供人类同行评审。
Phase 5:实现与漂移监控¶
- 执行方式:编码代理严格遵循已批准的设计文档实现代码。(此处不需要 Skill.md,因为设计文档既完整又详细。)
- 阶段写入边界:阶段 1-4(
/egm-brainstorm、/egm-draft、/egm-review和/egm-resolve)应只写入规范和审查工件:concepts_brief.md、design_draft.md、审查报告、设计文档以及SITEMAP.md(如果存在)。它们不应更改生产源代码或依赖项。这只是一个约定,并没有任何机制强制实施。一旦第 9 步(实现就绪测试)通过,计划中的Target Scope & File Boundary列表就是阶段 5 实现可以写入的文件集合。 - 维护:定期(例如每周)运行
/egm-drift-report,以检测代码库实现与已检入设计文档之间的偏离。
工件优先的 UX 协议¶
为了维护对话健康并防止上下文退化,所有 EGM 技能都遵循以下 UX 协议:
- 聊天倾倒禁令:工具和技能绝不能将大型提案、草稿或审查日志倾倒到主聊天流中。
- 工件输出:所有内容必须直接写入专用的侧边栏工件(在 Antigravity 中带有
RequestFeedback: true)或持久化的工作区文件。 - 让出回合的检查点:当需要用户反馈或分诊时,调用技能以一条指向工件的简洁消息通知用户,并让出执行权。
- 队列清理:一旦用户完成某个检查点的审查,调用技能将清除待处理的反馈标记。
参考文献¶
- Dave Rensin,Elephants, Goldfish, and the New Golden Age of Software Engineering(Medium,2026)。
已考虑的备选方案¶
- 单体内联线程审查 vs. 多子代理流水线:
- 备选方案:在同一聊天会话内顺序运行审查提示。
- 否决原因:会导致严重的上下文退化和确认偏差;模型会自我确认自己的错误。
- 直接写代码 vs. 规范驱动开发:
- 备选方案:提示代理直接从功能请求生成代码。
- 否决原因:导致每 kLOC 注释密度更高、工具函数实现重复,且已检入的架构记忆为零。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model