深入解析 EGM Codebase Details Goldfish:让文档与代码库逐项对齐的只读审计员

原创2026-11-14 12:36:302,142 阅读
文章标签:AI 技能代码评审文档Agent 工作流

深入解析 EGM Codebase Details Goldfish:让文档与代码库逐项对齐的只读审计员

在 Elephant-Goldfish Model(EGM)中,agents/codebase_details.md 定义了一位以"挑剔"为职业操守的 Goldfish 角色——Codebase Details Auditor。它不写代码、不改文档,只在新开的空上下文中逐条比对"文档声称的内容"与"代码实际的实现"。本文以该 persona 文件为骨架,结合它在 /egm-review 五阶段流水线中的调用位置、各 harness 的适配器配置与单元测试约束,说明如何正确理解、配置并运行这一审查角色。

一、角色定位:为什么需要一个"逐项对齐"的审查员

agents/codebase_details.md 的 frontmatter 给出了这个角色的正式身份与授权范围:

---
name: egm-codebase-details
description: Pedantic Technical Quality Auditor verifying that documentation accurately and exhaustively matches actual codebase implementation and existing library reuse opportunities.
license: Apache-2.0
---

三个要点值得拆开看:

  1. Pedantic(吹毛求疵):文件正文把自己描述为"a strict compliance officer who does not accept hand-waving explanations, unstated assumptions, or missing details"。这是一种刻意的角色设定——它不接受"大致如此"的描述。
  2. accurately and exhaustively:目标不是抽样检查,而是对照映射出的每一个源文件,检查公开 API、核心算法、配置开关、关键逻辑分支是否都被文档覆盖。
  3. existing library reuse opportunities:除"文档与代码是否一致"外,还要求发现"本可复用现有库却重复造轮子"的位置。这一点在审计向量中体现为"Contradicts the Code"条目里提到的 "existing library reuse opportunity discovered via code search"。

从源码结构看,egm-codebase-details 属于 personea 层(agents/),本身不含任何可执行逻辑,只是被派发的系统提示词;真正的执行者是各 harness 派生的子代理。这一点在 架构设计 的 "Personas Layer" 一节中有明确说明。

二、三条通用铁律:只读、无状态、不寒暄

该文件开篇的 "Core Mandates (Universal Goldfish Context)" 被所有 Goldfish persona(如 style.md、implementation_readiness.md)共享,包含三条硬约束:

铁律 原文要点 实际含义
Strict Read-Only Protocol "You have NO tools to modify the workspace, write files, or compile code" 发现缺陷也不得顺手修复;修复权归主上下文中的 Elephant
Stateless Mindset (Goldfish Isolation) "zero conversational history or external assumptions" 以"刚加入项目的新人"视角阅读,防止被前序讨论带偏
No Chitchat "Do not narrate your tool usage" 输出只留技术判断与证据,不写"我将先读取…"这类过程叙述

这三条并非仅靠提示词自觉,仓库在适配器层做了工具级强制。以 Claude Code 适配器 .claude-plugin/agents/codebase_details.md 为例,其 frontmatter 为:

tools: [Read, Grep, Glob]
model: inherit
color: yellow
omitClaudeMd: true

工具白名单只有 Read、Grep、Glob——没有 Write、Edit、Bash、Agent,因此"只读"与"不得再委派"在运行时即被剥夺能力,而非依赖模型自律。omitClaudeMd: true 则对应"无状态"要求:不注入项目级 CLAUDE.md,避免外部假设污染判断。

Cursor 适配器 .cursor-plugin/agents/codebase_details.md 使用另一套表达:

readonly: true
permissionMode: readonly
is_background: false

并明确要求 EGM_ROOT 必须是任务传入的绝对路径,而非环境变量展开。Copilot CLI 适配器 com.github.copilot/agents/egm-codebase-details.agent.md 同样声明 tools: [read, search] 与 include-custom-instructions: false,并补充一条关键纪律:

The caller writes reports. Do not claim independent verification from self-report.

也就是说,这位 Goldfish 只能"返回发现与它实际读过的路径",报告成文由调用方完成;它不得声称"我独立验证过",因为自证不构成验证。

这些约束有测试兜底。在 tests/unit/test_harnesses.py 中,codebase_details 被列入 8 个 reviewer 名单;test_claude_reviewers_are_read_only_with_fresh_context 断言每个适配器的工具集合严格等于 {Read, Grep, Glob}、model: inherit、omitClaudeMd: True,且不得出现 memory 字段。任何试图给审查员开写权限的改动都会直接让测试失败。

三、REVIEW 模式的四步审计流程

文件的 Instructions 段先读取调用方传来的 Mode 参数,再分流到两个完全不同的工作模式。REVIEW 分支面向"已有文档的实际审计",包含四个顺序步骤。

步骤 1:Map the Scope(映射范围)

Parse the active target scope to identify which source files (from the provided codebase context) it describes.

这一步把"目标行范围"翻译成"需要读哪些源文件"。EGM 的设计文档被刻意分隔为两个语义区:FeatureRange(高层设计)与 DetailedRange(从 ## Detailed Implementation Plan 到文件末尾的实现计划)。这一点在 docs/designs/draft.md 中定义,并明确指出 DetailedRange 由 Implementation Readiness Reviewer 与 Codebase Details Auditor 共同审计。因此 Codebase Details 的典型输入不是整篇文档,而是实现计划那一段。

步骤 2:Verify Code vs. Doc(逐文件核对)

For each mapped source file, read the code and verify that all key implementation details (including public APIs, core algorithms, configuration flags, and critical logic paths) are documented in the target scope.

四类必须覆盖的对象是判断基准:公开 API、核心算法、配置开关、关键逻辑路径。这也解释了它为什么需要 Grep 与 Glob——面对"文档只写了 AuthService"这种描述,它得自己去定位符号定义,而不是接受文档给出的路径为真。

步骤 3:Audit against the Standard(按标准打分)

Compare the depth and accuracy of the descriptions in the target scope against the requirements defined in the Target Standard.

Codebase Details 不带自己的评分表,它加载调用方指定的标准文件。在 /egm-review 的 Stage 9 中,映射关系被硬编码为:

standards: {"egm-implementation-readiness": "implementation-readiness-standard",
            "egm-codebase-details": "implementation-readiness-standard"}

见 skills/egm-review/SKILL.md。对应标准文件是 resources/document_standards/implementation-readiness-standard.md,其核心是 Zero-Decision Rule:计划必须让实现者"零设计决策"。该标准还要求 Target Scope & File Boundary 给出精确的仓库相对路径清单,而非"更新认证服务"这类模糊动作——这恰好是 Codebase Details 最容易抓到的问题类型:文档写了文件,但该文件里根本没有对应结构;或文档承诺了参数,源码里该参数硬编码成了常量。

步骤 4:Filter Test Files(测试文件的取舍)

Ignore simple unit test files, but strictly audit test infrastructure (mocks, helpers, base classes).

这条规则常被误读。它不是"测试不用管",而是:单个用例的断言内容不进入审查范围,但共享的 mock、helper、基类必须与生产代码同等严格地核对。理由是——测试基础设施一旦与生产接口脱节,后续所有用例都会产生虚假通过;而单条用例的覆盖偏好属于测试策略问题,不属于"文档与代码是否一致"。

四、六类审计向量与严重度分级

文件列出的 Audit Vectors 构成了这位审查员的检查清单。它们的共同特征是"可举证"——每一条都必须落到文件路径、API 名或行号。

审计向量 判定标准 典型场景
Missing Logic Detail 代码中存在但目标范围未提及的函数、校验规则或算法 源码有失败重试上限,计划未写重试策略
Unstated Assumptions 未写入文档的硬编码常量、环境变量、系统依赖 代码依赖本机可写的临时目录,计划未说明
Undocumented Edge Cases catch 分支、空值判断、重试上限、失败模式缺失 计划只描述成功路径
Test Infrastructure Neglect 共享 mock 与测试 helper 的文档详尽度不足 测试基类已改签名,计划仍按旧签名描述
Contradicts the Code 文档描述的行为与源码实际行为不符 按此执行会得到错误结果
Non-Existent References 文档声称"当前存在"的文件、函数、端点或表实际不存在 计划引用了不存在的 resources/... 路径

其中 Contradicts the Code 被特别升级为 🔴 Blocker,理由是原文那句判断:"every later reader inherits the false statement." 即错误陈述具有传染性:一旦设计文档被批准,后续实现者、评审者、drift 检查都会以它为基线,错误会被复制而非被发现。

关于 "Proposed files are not findings" 的关键澄清

文件用一整段专门处理一个高频误报:

Proposed files are not findings. An implementation plan lists files it will create. Their absence is not a defect. Apply Non-Existent References only to items the document says exist now. If the plan lists files without marking each Create, Modify, or Delete, report that once as 🟡 Major, and do not flag each path.

这条规则把时间维度引入审查:

  • 若文档说"这里已经有 AuthService.refresh()"→ 而代码里没有,这是 Non-Existent Reference,属缺陷。
  • 若文档说"将新建 AuthService.refresh()"→ 文件不存在是预期状态,不是缺陷。
  • 若文档列了一批文件却未标注 Create/Modify/Delete → 报一次 🟡 Major,而不是逐个路径重复报错。

对 /egm-draft 生成的实现计划而言,显式标注文件动作因此不是风格问题,而是能否通过 Stage 9 的结构性问题。这与 resources/document_standards/implementation-readiness-standard.md 中"明确列出将被创建、修改或删除的仓库相对路径"的要求直接对应。

五、BRAINSTORM 模式:把可观测性前置到概念阶段

当 Mode: BRAINSTORM 时,这位审查员不再看文档,而是在概念阶段回答两个非常具体的问题:

  1. Telemetry & Tracing:关键操作能否在分布式追踪中被串起来?产出的指标是否可据以采取行动(actionable)?
  2. Operational Debuggability:凌晨三点的生产事故中,oncall 工程师靠什么把问题收敛到具体组件?

它在 /egm-brainstorm 的 7 视角会审中被调用,与 design_critic、zoom_out、comprehension、implementation_readiness、structural、inventive_catalyst 并行工作,见 skills/egm-brainstorm/SKILL.md。这个模式的价值在于:可观测性缺口若留到设计评审阶段,往往已经绑定了具体的架构选择,修复成本显著上升。

BRAINSTORM 模式的输出字段与 REVIEW 模式刻意区分,避免把"文档缺陷"与"运营风险"混在一张表里:

字段 含义
Severity `[Blocker
Dimension Observability & Operational SRE Debuggability
Operational Risk 缺失的 trace context、未监控的指标、或排障摩擦点
Mitigation Requirement 必须写入 Concepts Brief/PRD 的强制遥测要求

注意 Mitigation Requirement 的措辞是 "Mandatory"——它输出的不是建议清单,而是"必须进入概念文档"的约束项。这使得 concepts_brief.md 在成文阶段就带有可验证的运维前提。

六、输出格式:两种模式,两种交付物

文件末尾的 Output Format 段规定,发现必须以"平实自然语言"回报给编排器,并给出各自必填字段。

REVIEW 模式的发现结构

1. Severity: [Blocker | Major | Nit]
2. Affected Scope: 文件路径、API 名或行号
3. Discrepancy Description & Rationale: 代码漂移说明,或通过代码搜索发现的库复用机会

三点设计意图值得说明:

  • Severity 用文本三档,而编排层用 emoji(🔴/🟡/🟢)聚合,映射发生在 agents/synthesizer.md 的 triage 步骤。个人差异化的 emoji 会破坏去重与统计,因此 persona 层坚持文本枚举。
  • Affected Scope 强制可定位:没有路径或行号的发现会被 Synthesizer 归并时丢弃。
  • Rationale 与 Description 合并为一条:要求"说明为什么这是漂移",而不只是"这里不一致"。对复用机会类发现,理由必须包含"通过代码搜索发现已有实现"这一证据链。

BRAINSTORM 模式的发现结构

如上节四项表格所示。编排器会把 7 位 Goldfish 的原始结论去重、按严重度分组,最终写入 concepts_brief.md;在 REVIEW 路径下则写入 goldfish_review_report.md 或调用方指定的报告名。

七、在五阶段流水线中的实际调用点

理解配置与参数,才算真正会用这位审查员。它在 /egm-review 中出现两次,位置不同、作用不同。

出现点一:Stage 9(Implementation Readiness Test)

Stage 9 的 reviewer 组是 [egm-implementation-readiness, egm-codebase-details, egm-style],目标为 DetailedRange。三者构成互补视角:Implementation Readiness 判断"够不够照着写",Codebase Details 判断"写的与代码是否一致",Style 判断"表述是否客观可测"。

同一段逻辑在 egm-review 中表达了两次——一次用于 uninterrupted 全流程,一次用于交互式 Stage 9 子流程调用 egm-review-loop,两处 reviewer 与 standards 映射保持一致:

Reviewers: [egm-implementation-readiness, egm-codebase-details, egm-style]
Standards: {"egm-implementation-readiness": "implementation-readiness-standard",
            "egm-codebase-details": "implementation-readiness-standard"}
Target:    DetailedRange

Stage 9 之后的终局检查点提供四个选项:结束评审并定稿、交由 agent 解析并修复、人工改文档后重跑、暂停退出。由于 Goldfish 是只读的,"修复"必然发生在主上下文的 egm-resolve 中,并由人来批准每一处改动。

出现点二:egm-review-loop 的短名解析

在 skills/egm-review-loop/SKILL.md 中,短名解析规则把 codebase_details 映射到 agents/codebase_details.md:

Reviewer Shortnames: design_critic, structural, style,
                     implementation_readiness, codebase_details,
                     comprehension, zoom_out
                     → agents/{name}.md

同一文件的 Inputs 推荐段落把 codebase_details 与 implementation_readiness 并列为 Implementation Plans 场景的推荐组合(对应标准为 implementation-readiness-standard),而 Feature Specs 场景推荐 design_critic 与 structural。这解释了为什么在纯设计评审阶段(Preset 2: Feature spec only)看不到它——该 preset 在 Stage 8 后干净停止,不进入 Stage 9。

如果跳过标准编排、直接手写调用,最小参数集是:

TargetFile:      docs/designs/<feature>.md
SemanticTarget:  "Target the H2 block 'Detailed Implementation Plan'"
Reviewers:       [codebase_details]
Standards:       {codebase_details: implementation-readiness-standard}
GoldfishContext: [目标文档引用的源文件列表]

SemanticTarget 使用稳定的标题字符串而非固定行号,因为 egm-review-loop 在每轮迭代前会无条件重读目标文件并重算行区间,以免上一轮的修复导致范围漂移。

八、实操:跑一次针对实现计划的代码对齐审查

以下操作在已安装 EGM 插件、且当前会话支持派生子代理的 harness 中执行。若 harness 无法创建新的子代理上下文,评审会被直接中止——README 对此有明确说明,同上下文评审不算 Goldfish 评审。

第一步:准备目标文档与阅读清单。 目标文档应包含 ## Detailed Implementation Plan 段落。文档内部链接的本地文件会被自动加入 GoldfishContext,但指向工作目录外的路径或 URL 需要人工确认;URL 需先落盘为本地文件供审查员读取。

第二步:选择执行模式。 若只关心实现计划的就绪性,选择 "Implementation plan only",流水线会跳过语义切分,直接进入 Stage 9。若要跑完整流程,选择 "Consolidated report with all review rubrics",五阶段不中断,最终产出 consolidated_review_report.md。

第三步:读取报告。 Stage 9 的产出文件是 implementation_readiness_report.md。报告中每位 reviewer 的状态只有 completed 与 not run 两种,不存在"零发现"的模糊态——超时、崩溃或未返回报告的审查员必须先重试一次,仍失败则记为 not run,且该轮不计为 clean round。这条规则防止"审查员没跑起来"被误读成"文档没问题"。

第四步:处置发现。 对每条 finding 做出判断:接受并修改文档、标记为已接受风险、或提出反驳(CONTEST)。修复完成后重读目标文件重算行边界;同一阶段的重审最多允许 1 次,超过上限则残余发现作为 accepted trade-off 记录,流程继续推进。

九、使用边界与常见误区

它不能替代测试,也不能替代人的判断。 README 对此有一句明确表述:评审不替代测试或人工判断。Codebase Details 检查的是"文档声明与代码现状的一致性",不是"代码是否正确"。一个实现完全错误的函数,只要文档如实描述了它,就不会被这位审查员报为缺陷。

它不负责修复,因此不要期待 patch。 只读协议在三层被强制:persona 文本、适配器工具白名单、单元测试断言。任何"顺手改一下"的期待都会落空,这是设计意图而非能力缺失。

不要把它当成通用代码评审员。 它的输入是"文档 + 目标行范围 + 标准 + 阅读清单",输出是"文档相对代码的漂移"。若目标是发现代码本身的缺陷,那属于实现阶段的代码评审,不在该 persona 的职责范围内。

注意"未读标准即无效结论"的规则。 Claude 与 Copilot 适配器都要求"在返回发现前,必须读目标文档与每一份提供的标准;若必需文件不可读,返回 incomplete review 而不是通过性结论"。因此在配置时漏传 standards 路径,得到的不应是"无发现",而应是"审查不完整"。

版本与兼容性以仓库现状为准。 各 harness 的适配器能力并不等价:Claude 侧通过 tools 白名单限制,Cursor 侧通过 permissionMode: readonly,Copilot 侧通过 tools: <a href="https://link.gitcode.com/i/a2b04ae34d0568fb78bd1a9a64193c44" target="_blank">read, search] 与 include-custom-instructions: false,且 [docs/copilot.md 明确指出该适配器的部分行为(如本地路径安装、设置项的实际强制效果)在本仓库中标注为未验证。跨 harness 复现同一结论前,需要先确认该 harness 的适配器是否真的能隔离上下文。

十、相关文件速查

路径 作用
agents/codebase_details.md 权威 persona 定义:职责、双模式指令、审计向量、输出格式
agents/synthesizer.md 汇总 8 位 Goldfish 的发现,去重、分级、成文
skills/egm-review/SKILL.md 五阶段流水线编排,Stage 9 的 reviewer 与 standards 映射
skills/egm-review-loop/SKILL.md 短名解析、迭代轮次、收敛与上限规则
skills/egm-brainstorm/SKILL.md 7 视角概念会审,BRAINSTORM 模式的调用方
resources/document_standards/implementation-readiness-standard.md Zero-Decision Rule 与目标文件边界要求
docs/designs/draft.md FeatureRange / DetailedRange 语义切分的定义来源
.claude-plugin/agents/codebase_details.md Claude Code 适配器:只读工具白名单与上下文隔离
.cursor-plugin/agents/codebase_details.md Cursor 适配器:permissionMode: readonly
com.github.copilot/agents/egm-codebase-details.agent.md Copilot CLI 适配器:tools: [read, search]
tests/unit/test_harnesses.py 断言 reviewer 工具集为只读、禁用 memory、强制 fresh context
tests/unit/test_frontmatter.py 断言 agents/*.md 的 name 与 description 字段合法且非空

把这十一个文件串起来,就是这位审查员的完整行为链路:frontmatter 声明身份 → 编排器按短名解析到 persona → 适配器限制工具与上下文 → persona 按模式执行审计 → 发现回传 Synthesizer 归一化 → 报告落盘后由 Elephant 与人共同决定如何修改。理解这条链,比记住任何单条审计规则都更能保证评审结果可信。

登录后查看全文
elephant-goldfish-model