跳转至

EGM 架构与系统生命周期


概述

Elephant-Goldfish Model (EGM) 是规格驱动开发(SDD)的一种实现,基于 Elephants, Goldfish, and the New Golden Age of Software Engineering 一文。它强调协作式使用 AI 进行设计与评审,并维护已通过验证的技术规格,直接将其检入代码库。

本文档规定了 EGM 的整体系统架构:其组件模型、端到端数据流,以及其在各编码代理运行时中的生命周期。

问题

非结构化、对话式的 AI 代码生成存在四种系统性失效模式:

  1. 幻觉级联与上下文污染:当单个 LLM 线程负责访谈开发者、创建设计并编写代码时,会话上下文会累积推测性假设和对话偏差。模型会验证自身有缺陷的假设,而不是检测错误。
  2. 过早实现("杂草综合征"):编码代理默认会立即在就近文件中编写代码,绕过高层架构定位、简洁性检查(YAGNI)以及现有基础设施的复用。
  3. 聊天倾泻疲劳:直接在聊天窗口中呈现多页设计规格或冗长的评审反馈,会扰乱对话历史、降低 LLM 上下文性能,并造成糟糕的用户体验。
  4. 文档漂移:项目启动阶段编写的设计文档通常会随代码演进而逐渐腐化,破坏未来 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
  • 执行方式:执行一个五阶段评估流水线:
    1. 步骤 5:Zoom Out 审查:对照 zoom-out-standard.md 评估简洁性、YAGNI 与代码库复用。
    2. 步骤 6:理解测试:由隔离的朴素读者审计文档,检查其自包含性和缺失的背景知识。
    3. 步骤 7:Critic 审查:对照 feature-spec-standard.md 评估系统设计、规模瓶颈与故障模式。
    4. 步骤 8:中间 Zoom Out:对照 zoom-out-standard.md,对理解阶段和 Critic 阶段新增的内容进行重新审计。
    5. 步骤 9:实现就绪测试:对照 implementation-readiness-standard.md 验证文件路径、函数签名和测试用例。
  • 子代理扇出/扇入: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 协议:

  1. 聊天倾倒禁令:工具和技能绝不能将大型提案、草稿或审查日志倾倒到主聊天流中。
  2. 工件输出:所有内容必须直接写入专用的侧边栏工件(在 Antigravity 中带有 RequestFeedback: true)或持久化的工作区文件。
  3. 让出回合的检查点:当需要用户反馈或分诊时,调用技能以一条指向工件的简洁消息通知用户,并让出执行权。
  4. 队列清理:一旦用户完成某个检查点的审查,调用技能将清除待处理的反馈标记。

参考文献

已考虑的备选方案

  • 单体内联线程审查 vs. 多子代理流水线:
    • 备选方案:在同一聊天会话内顺序运行审查提示。
    • 否决原因:会导致严重的上下文退化和确认偏差;模型会自我确认自己的错误。
  • 直接写代码 vs. 规范驱动开发:
    • 备选方案:提示代理直接从功能请求生成代码。
    • 否决原因:导致每 kLOC 注释密度更高、工具函数实现重复,且已检入的架构记忆为零。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model