跳转至

EGM 设计起草:规范编写与语义边界

  • 作者: Jim Quinn (@quinnjim), Elise Ewing (@eewing314)
  • 状态: 当前
  • 日期: 2026-06-06

概述

EGM 设计起草技能(/egm-draft)将构思产物(来自 /egm-brainstorm 的 concepts_brief.md 或讨论笔记)转换为 docs/designs/ 下正式、动态的设计文档。它逐节迭代地起草文档,并在保存到磁盘之前收集每个阶段的反馈。

至关重要的是,它在文档内建立了语义边界,以便下游多代理审查(/egm-review)和自动漂移审计(/egm-drift-report)能够顺利执行。

问题

直接要求 AI 模型在单个 Prompt 中编写一份全面的技术设计,会产生严重的质量问题:

  1. 整体性幻觉与文本墙输出:模型直接将大量、非结构化的 Markdown 文本块输出到聊天面板中,使审查变得困难,并削弱技术深度。
  2. 过早倾倒代码:模型不关注架构不变量、数据流和文件级理由,而是生成原始、难以维护的辅助代码。
  3. 下游工具缺乏语义结构:如果没有严格标准化的章节边界(例如区分高层目标与具体实施计划),自动审查者无法划分审计职责。

设计原则

  • 逐节迭代起草:草稿是增量撰写的(概述与目标 -> 架构与图表 -> 备选方案 -> 实施计划),并在各节之间请求用户反馈。
  • 工件优先交付:所有起草状态都渲染到侧边栏工件(design_draft.md)或持久化工作区文件中。严格禁止将大型草稿直接打印到聊天流中。
  • 按设计进行语义拆分:草稿被划分为高层概念部分(FeatureRange)和具体执行部分(DetailedRange),以便进行有针对性的下游 Goldfish 审查。
  • 详尽的文件与理由枚举:实施计划必须枚举要创建、修改或删除的每个文件,并附上架构理由,但不生成原始源代码。
  • 溯源水印:定稿文档会附加标准化的溯源水印页脚,用于追踪 AI 编写状态。

系统架构与工作流

sequenceDiagram
    autonumber
    actor Human as Software Engineer
    participant Draft as egm-draft Skill
    participant Summary as Artifact: concepts_brief.md / notes
    participant DraftArtifact as Artifact: design_draft.md
    participant Workspace as Workspace File: docs/designs/<FEATURE>.md
    participant Review as egm-review Skill

    Note over Human,Draft: Step 1: Predecessor Context Ingestion
    Human->>Draft: /egm-draft
    Draft->>Summary: Read concepts_brief.md & verify consensus

    Note over Human,Draft: Step 2, 3, 4: High-Level Sections (FeatureRange)
    Draft->>DraftArtifact: Draft Overview, Problem Statement & Goals
    Draft->>DraftArtifact: Append Architecture, Data Flow & Mermaid Diagrams
    Draft->>DraftArtifact: Append Alternatives Considered & Trade-offs
    Draft->>Human: Request Feedback on High-Level Sections

    Note over Human,Draft: Step 5: Detailed Implementation (DetailedRange)
    Draft->>DraftArtifact: Append Detailed Implementation Plan (Files & Rationales)
    Draft->>Human: Request Feedback on Implementation Checklist

    Note over Human,Draft: Step 6: Finalization, Watermark & Handoff
    Draft->>Summary: Reconcile draft against concepts_brief.md
    Draft->>Human: Report contradictions & architectural additions
    Draft->>DraftArtifact: Append Watermark Footer
    Draft->>Workspace: Write docs/designs/<FEATURE>.md
    Draft->>Human: Provide link to spec & recommend /egm-review
    Human->>Review: /egm-review docs/designs/<FEATURE>.md

起草协议(/egm-draft)

/egm-draft 工作流将构思产物转换为活的 Markdown 设计文档:

第 1 步:前置上下文摄取

从工件目录解析 concepts_brief.md(或 discussion_summary.md / 功能笔记)(必要时回退到临时目录或工作区根目录),并验证用户共识。

第 2 步:概述、问题与目标

在 design_draft.md 中起草面向用户的问题陈述、业务价值、目标和非目标。

第 3 步:技术计划与架构

附加组件图(Mermaid)、API 签名和数据流叙述。

第 4 步:已考虑的备选方案

从简报的 Alternatives Weighed 部分读取被否决的备选方案,并记录具体的权衡理由(延迟、复杂性、维护)。

第 5 步:详细实施计划

起草执行部分:

  • 要创建、修改或删除的每个文件的统一清单。
  • 每个文件变更的明确架构理由。
  • 不包含实现代码:仅包含模式、类型定义和伪代码。

第 6 步:定稿、格式化与注册

  • 将草稿与前置上下文进行核对,并要求用户决定每个矛盾点。它不会根据 Zoom Out 标准自行评分;/egm-review 第 5 阶段会在全新上下文中完成该评分。
  • 在末尾的开放问题之后,追加一个由水平线分隔符(--------------------------------------------------------------------------------)分隔的标准溯源水印页脚(*Drafted with EGM*)。
  • 将文档写入 docs/designs/<FEATURE>.md。
  • 如果存在,则在 docs/designs/SITEMAP.md 中注册该文档。本仓库使用 docs/designs/README.md;贡献者应根据 CONTRIBUTING.md 的要求更新它。
  • 使用标准 Markdown 格式化工具格式化 Markdown。
  • 输出可点击链接,并指示用户运行 /egm-review。

语义边界发现

EGM 设计文档经过有意设计,使下游 Goldfish 审查引擎能够将文档解析为两个语义区域:

  1. 功能范围(FeatureRange):从第 1 行到标题边界。 包含高层问题陈述、目标、架构和备选方案。由 设计评论家(egm-design)和 理解评审员(egm-comprehension)审计。
  2. 详细范围(DetailedRange):从 ## Detailed Implementation Plan 到 EOF。包含文件目标、schema 和测试计划。由 实现就绪性评审员(egm-implementation-readiness)和 代码库细节审计员(egm-codebase-details)审计。

统一采用 ## Detailed Implementation Plan 标题可实现自动边界发现,无需手动配置行范围。位于 EOF 的页脚水印(*Drafted with EGM*)被视为惰性结构元数据,在评审和漂移分析期间不参与需求审计。

溯源水印

为支持轻量级溯源追踪与人工检查,所有设计 /egm-draft 规格说明均包含页脚水印:

--------------------------------------------------------------------------------

*Drafted with EGM*
  • 分隔限定的 EOF 位置:附加在文档的绝对末尾, 与尾部章节(### Open Questions)之间以水平线分隔。
  • 尽力而为且前瞻:严格适用于今后新起草或 更新的规格说明;不会对遗留文档施加追溯性迁移清理或 阻塞性预提交检查。

标准对齐

阅读链接的标准以了解其要求。

撰写步骤 适用标准
架构大纲 Zoom-out 标准
文档结构 功能规格说明标准
详细计划 实现就绪性标准

实现文件

起草能力通过以下技能与参考文件实现:

文件路径 类型 用途与存在原因
skills/egm-draft/SKILL.md 技能定义 实现 /egm-draft 的逐章节 markdown 编译、站点地图注册和格式化。
skills/egm-draft/TEST.md 单元测试 验证起草和定稿工作流的测试场景。
skills/egm-draft/test_scenarios.yaml 评估基准 共置的行为评估套件,用于评估模型对起草协议的遵循程度。
skills/egm-draft/references/design_doc.md 文档模板 定义所需章节和布局的规范 markdown 设计文档模板。
resources/execution_instructions.md 执行指令 强制执行无代码护栏、静默合规和一次一问节奏的核心执行规则。

参考

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