egm-drift-report

检测设计与代码之间的偏差

在 Codex 或 ChatGPT Work 中运行时，请先阅读 Codex 集成。 在 Claude Code 或 Cowork 中运行时，请先阅读 ${CLAUDE_PLUGIN_ROOT}/docs/claude.md。

当用户要求检测所有设计或一组 README 中的偏差时，目标是找出代码库中所有偏离设计或未能实现设计或 README 所述规范的情况。

1. 检查输入：确认用户提供了包含设计文档或 README 的目录。如果没有提供，请要求用户指定目标目录。

2. 列出文档：列出设计目录中的所有文件。

3. 分析：对每份设计文档：

   • 明确上下文：阅读设计文档。确定其意图、拟议的变更，以及其中提及的具体文件名／符号。
   • 定位源代码：在源代码树中查找对应的源代码文件。如果未明确给出路径，请使用代码搜索或 grep 查找文档中提及的相关类、函数或 API 端点。提示用户在文档中补充缺失的链接，以降低今后的检测成本。
   • 核实：阅读这些源代码文件的当前内容。
   • 检测偏差：比较设计与实际情况。重点检查：
     • 缺失的功能：文档中描述但代码中不存在的逻辑。
     • 不完整的模型：数据类／类／结构体／Protos 缺少设计中指定的字段。
     • 逻辑简化：原计划采用动态逻辑，但实际使用了硬编码值。
     • 架构偏离：实现使用了与提议不同的模式／库。
   • 筛选：只报告差异。不要描述正常工作或与设计相符的部分。如果代码与设计完全一致，输出“No drift detected”。

4. 报告：生成一份报告，列出发现的所有差异。

   • 使用文件写入工具，将每个文件的分析追加到 {YYYY-MM-DD}_DRIFT_REPORT.md。

   • 严格遵循以下格式：

     ## <DESIGN_DOC_NAME>
     
     <发现的具体偏差项目列表>
     <或“No drift detected”>
     

5. 指导

   • 务必严谨。如果设计文档提及了某个具体对象、字段或文件名，但代码中没有，这就属于应报告的偏差。请再次检查覆盖情况。如果某部分逻辑未在设计或 README 中提及，这也属于应报告的偏差。
   • 广泛阅读文件，确保查看的是代码当前状态，而不是依赖记忆。
   • 按顺序处理文件，避免工具输出缓冲区溢出。