跳转至

EGM 漂移检测协议(活文档与代码同步)

  • 作者: Jim Quinn (@quinnjim)
  • 状态: 当前
  • 日期: 2026-06-07

概述

EGM 漂移检测技能(/egm-drift-report)对 docs/designs/ 下的已检入设计文档以及各包 README.md 层级结构进行审计,并与源代码对照,以识别并报告架构偏差。

它旨在作为实践 EGM 的团队的一项例行仪式纳入工作流程,以保持其设计文档与功能实现同步。

问题

文档漂移,尤其是在使用 AI 工具时,会带来以下问题:

  1. 过时上下文:如果没有系统让它们保持更新,快速的问题修复或未跟踪的重构会让设计文档过时。当人类或 AI 代理查阅过时的规格来设计新功能时,会做出有缺陷的假设,从而导致实现失败。

  2. 无声的架构腐化:没有自动化验证,预期设计与实际代码之间的差异(例如硬编码绕过而不是动态解析器)会在无人察觉的情况下不断累积,直到生产事故爆发。

  3. 人类疲劳:手动将多页设计文档与几十个实现文件交叉对照既繁琐,又很难始终如一地执行。

系统架构与工作流

sequenceDiagram
    autonumber
    actor Human as Software Engineer / Gardener
    participant DriftSkill as egm-drift-report Skill
    participant DesignDir as docs/designs/ Directory
    participant Codebase as Live Codebase
    participant Artifact as Artifact: {YYYY-MM-DD}_DRIFT_REPORT.md

    Human->>DriftSkill: /egm-drift-report [path/to/designs]
    DriftSkill->>DesignDir: List all design specifications
    loop For Each Design Document (Sequential)
        DriftSkill->>DesignDir: Read doc & extract symbols, files, APIs
        DriftSkill->>Codebase: Locate source files & inspect current state
        DriftSkill->>DriftSkill: Compare design vs reality (Detect divergence)
        DriftSkill->>Artifact: Append findings under ## <DOC_NAME>
    end
    DriftSkill->>Human: Deliver consolidated drift report artifact
    Human->>Codebase: Reconcile drift (Update code OR update doc)

漂移检测启发式规则

该漂移检测技能依据四个核心偏差类别对代码进行审计:

偏差类别 描述 可报告偏差示例
缺失功能 设计中描述的逻辑或组件在源代码中完全不存在。 设计文档中指定的定时清理任务从未在服务二进制文件中实现。
不完整模型 结构体、模式、数据类或类缺少设计中所指定的字段。 设计中的模型模式定义了 5 个字段,但代码实现只有 3 个。
逻辑捷径 在设计为动态逻辑的位置使用了硬编码值、模拟回退或绕过方案。 设计采用动态配额查找,但代码使用了硬编码常量 DEFAULT_QUOTA = 100。
架构偏差 代码使用的设计模式、框架或依赖与计划不一致。 设计指定使用 gRPC 服务端点,但实现使用了自定义 HTTP 处理器。

执行协议

  1. 输入与发现:识别目标设计文件夹(docs/designs/)或包树(README.md)。
  2. 顺序处理:逐个审计文档,以防止工具缓冲区溢出和上下文退化。
  3. 源码锚定:通过代码搜索和文件查看工具解析被引用的类、端点和文件。如果文档引用了未链接的符号,报告会提示工程师添加显式链接,以便降低未来扫描的成本。
  4. 差异过滤:仅报告可操作的差异。如果实现与设计完全匹配,则输出 "No drift detected."。
  5. 产物输出:将所有结果格式化为 {YYYY-MM-DD}_DRIFT_REPORT.md,并使用严格的 Markdown 标题:

    ## <DESIGN_DOC_NAME>
    
    * [Divergence item 1 with file:line reference]
    * [Divergence item 2]
    <!-- Or "No drift detected." -->
    

运维维护节奏

为了让文档保持鲜活且值得信赖,我们建议(但不强制)以下做法:

  • 每周园丁轮值:运行 EGM 的团队将 /egm-drift-report 纳入每周构建园丁或值班检查清单。
  • 双向对账:检测到的每项漂移都是可操作的:
    • 如果代码变更是有意的:更新设计文档以反映实际情况。
    • 如果设计被违反:提交 issue 或提示代理完成缺失的实现。

实现文件

漂移检测技能由以下文件实现:

文件路径 类型 目的与存在原因
skills/egm-drift-report/SKILL.md 技能定义 实现 /egm-drift-report 的顺序文档扫描器、偏差启发式分析器和报告生成器。
skills/egm-drift-report/TEST.md 测试计划 指向 pytest tests/unit 和 TESTING.md(frontmatter 与链接检查);没有针对漂移的测试。
skills/egm-drift-report/test_scenarios.yaml 评估场景 单个 detect_all_drift 场景,带有宽泛的 required_pattern 断言;tests/unit/test_scenario_coverage.py 验证结构,但仓库内没有运行器执行该断言。

参考资料

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