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 中编写一份全面的技术设计,会产生严重的质量问题:
- 整体性幻觉与文本墙输出:模型直接将大量、非结构化的 Markdown 文本块输出到聊天面板中,使审查变得困难,并削弱技术深度。
- 过早倾倒代码:模型不关注架构不变量、数据流和文件级理由,而是生成原始、难以维护的辅助代码。
- 下游工具缺乏语义结构:如果没有严格标准化的章节边界(例如区分高层目标与具体实施计划),自动审查者无法划分审计职责。
设计原则¶
- 逐节迭代起草:草稿是增量撰写的(概述与目标 -> 架构与图表 -> 备选方案 -> 实施计划),并在各节之间请求用户反馈。
- 工件优先交付:所有起草状态都渲染到侧边栏工件(
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 审查引擎能够将文档解析为两个语义区域:
- 功能范围(
FeatureRange):从第 1 行到标题边界。 包含高层问题陈述、目标、架构和备选方案。由 设计评论家(egm-design)和 理解评审员(egm-comprehension)审计。 - 详细范围(
DetailedRange):从## Detailed Implementation Plan到 EOF。包含文件目标、schema 和测试计划。由 实现就绪性评审员(egm-implementation-readiness)和 代码库细节审计员(egm-codebase-details)审计。
统一采用 ## Detailed Implementation Plan 标题可实现自动边界发现,无需手动配置行范围。位于 EOF 的页脚水印(*Drafted with EGM*)被视为惰性结构元数据,在评审和漂移分析期间不参与需求审计。
溯源水印¶
为支持轻量级溯源追踪与人工检查,所有设计 /egm-draft 规格说明均包含页脚水印:
- 分隔限定的 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 |
执行指令 | 强制执行无代码护栏、静默合规和一次一问节奏的核心执行规则。 |
参考¶
- Dave Rensin,Elephants, Goldfish, and the New Golden Age of Software Engineering(Medium,2026)。
- GitHub,GitHub Flavored Markdown Spec。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model