EGM 漂移检测协议(活文档与代码同步)¶
- 作者: Jim Quinn (@quinnjim)
- 状态: 当前
- 日期: 2026-06-07
概述¶
EGM 漂移检测技能(/egm-drift-report)对 docs/designs/ 下的已检入设计文档以及各包 README.md 层级结构进行审计,并与源代码对照,以识别并报告架构偏差。
它旨在作为实践 EGM 的团队的一项例行仪式纳入工作流程,以保持其设计文档与功能实现同步。
问题¶
文档漂移,尤其是在使用 AI 工具时,会带来以下问题:
-
过时上下文:如果没有系统让它们保持更新,快速的问题修复或未跟踪的重构会让设计文档过时。当人类或 AI 代理查阅过时的规格来设计新功能时,会做出有缺陷的假设,从而导致实现失败。
-
无声的架构腐化:没有自动化验证,预期设计与实际代码之间的差异(例如硬编码绕过而不是动态解析器)会在无人察觉的情况下不断累积,直到生产事故爆发。
-
人类疲劳:手动将多页设计文档与几十个实现文件交叉对照既繁琐,又很难始终如一地执行。
系统架构与工作流¶
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 处理器。 |
执行协议¶
- 输入与发现:识别目标设计文件夹(
docs/designs/)或包树(README.md)。 - 顺序处理:逐个审计文档,以防止工具缓冲区溢出和上下文退化。
- 源码锚定:通过代码搜索和文件查看工具解析被引用的类、端点和文件。如果文档引用了未链接的符号,报告会提示工程师添加显式链接,以便降低未来扫描的成本。
- 差异过滤:仅报告可操作的差异。如果实现与设计完全匹配,则输出
"No drift detected."。 -
产物输出:将所有结果格式化为
{YYYY-MM-DD}_DRIFT_REPORT.md,并使用严格的 Markdown 标题:
运维维护节奏¶
为了让文档保持鲜活且值得信赖,我们建议(但不强制)以下做法:
- 每周园丁轮值:运行 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 验证结构,但仓库内没有运行器执行该断言。 |
参考资料¶
- Dave Rensin, Elephants, Goldfish, and the New Golden Age of Software Engineering (Medium, 2026).
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model