elephant-goldfish-model 教學手冊

Elephant-Goldfish Model(EGM)企業級 AI 軟體開發方法論與外掛工具導入手冊 Design with an Elephant. Review with a Goldfish. 適用對象:PM、SA、SD、Architect、Frontend/Backend Engineer、PG、QA、DevOps/DevSecOps 文件性質:企業內部開發規範與教育訓練教材(偏「實戰與維運」) 版本基準:google/elephant-goldfish-model v0.1.1(2026-11-06,tag commit dea7761);main 追蹤至 72d06f5(2026-11-15,tag 之後 45 個 commit) 實測環境:Windows 11、Claude Code 2.1.325(已登入,headless claude -p 實跑 4 支 Skill)、Git Bash、Python 3.12、JDK 21、Maven 3.9.9 查證日期:2026-11-17


重要聲明

  1. EGM 仍是 pre-1.0 專案。 官方 docs/releases.md 寫明 1.0 之前 minor 版本可能包含不相容的流程變更,「Version 1.0 requires a stable contract for skill names, parameters, output paths, and report formats」。本手冊所有指令、檔名、報告格式都以 v0.1.1 為準,升級前請重讀第 11 章的升級 SOP。
  2. EGM 不是 Google 官方支援產品。 README 最後一句:「This is not an officially supported Google product.」企業導入時,支援責任在公司內部,不在 Google。
  3. 本手冊不是官方文件的翻譯。 內容是依 repo 原始檔(skills/*/SKILL.md、agents/*.md、resources/、docs/)重新查證後整理,並加上企業導入建議、實測工具與案例。
  4. 案例皆為教學用虛構情境。 「企業客戶管理系統」「貸款核准」「ACME Bank」等名稱與資料都不是真實專案。
  5. 實測範圍要先看清楚。 已實測:Claude Code 2.1.325 的 marketplace 安裝、plugin list/validate/details、claude doctor 設定驗證;1.1 起在已登入的 session 以 claude -p --plugin-dir 實跑 egm-review、egm-resolve、egm-bootstrap、egm-drift-report(3.13.1、5.3.5、5.4.6、5.7.4、5.8.4);5 支公司自建工具(25 個 pytest+突變測試)、ArchUnit Lab(含 surefire 3.5.3 回歸重現)、CI workflow 的本機模擬 6 情境。未實測:egm-brainstorm、egm-draft、egm-review-loop 與互動關卡、Codex CLI 與 Antigravity 全部操作、GitHub Actions 實跑。第 5 章與第 15 章標示「範例」的對話與報告是依 Skill 規則撰寫的示範;標示「實跑紀錄」的才是實際輸出。
  6. AI 產出一律要人工驗證。 這也是 EGM 本身的立場:「Humans own the outcomes.」(docs/index.md)

閱讀約定

來源標示

全書在句末或表格中使用下列標示。凡標示為「建議」的內容都不是 EGM 官方功能,請勿在簡報或對外文件中寫成官方保證。

標示意義範例
官方repo 檔案明確寫出(會附檔案路徑或網址)Review 有 5 個 stage(官方,skills/egm-review/SKILL.md)
實測本手冊在上述實測環境親自執行過,附指令與結果claude plugin install egm@egm 成功(實測)
建議本手冊作者給企業的做法,EGM 沒有內建egm_scope_guard.py 範圍守門(建議)
尚待驗證查不到可靠來源,或來源互相矛盾Antigravity App 的指令格式(尚待驗證)
🧪寫法有依據,但本手冊沒有實際跑過在 Codex CLI 跑完整 Review(🧪)

指令區塊的適用環境

每個指令區塊上方都會寫明環境。常見寫法:

  • 「Shell(Git Bash/macOS/Linux)」:一般終端機指令。
  • 「Claude Code 對話框」:在 Claude Code session 內輸入的 slash command。
  • 「agy CLI 對話框」:在 Antigravity CLI session 內輸入。
  • 「Codex」:Codex 以 skill picker 選擇技能,不使用 /egm: 前綴。

不同 Host 的指令格式不同,不可互相套用(第 3 章與附錄 A 有對照表)。

本手冊附帶的實測工具

手冊中標示 📄 的程式碼區塊都是實測檔案,可原樣抽出使用:

檔案用途驗證
tools/egm_design_lint.pyReview 前的設計文件機械檢查(含中文佔位詞「待查」)pytest 5 案例+突變測試
tools/egm_report_gate.pyReview 報告閘門(R0~R5;以真實報告驗證 4 種格式)pytest 11 案例+突變測試+真實報告
tools/egm_isolation_probe.py從 stream-json log 檢查 Goldfish 實際讀到什麼(金絲雀)對實跑 log 執行(2.9.1)
tools/egm_scope_guard.py實作階段的檔案範圍守門(可依 Phase)pytest 7 案例+突變測試+CI 模擬 4 情境
tools/egm_evidence_check.py逆向工程文件的程式碼證據檢查pytest 2 案例+突變測試
archunit-lab/Hexagonal 架構測試(ArchUnit 1.5.1、surefire 版本可切換)mvn test 7/7、3 個反例被擋、3.5.3 回歸可重現

以上工具是公司自建的 EGM 周邊工具(建議),不是 EGM 的一部分。


版本紀錄

版本日期作者說明
1.02026-11-17架構組初版。基準 EGM v0.1.1、Claude Code 2.1.325。含 15 章、5 個完整案例、4 支實測工具、ArchUnit Lab;經獨立 Goldfish 審查(2 Blocker、13 Major、8 Nit)後修正,見附錄 E
1.12026-11-17架構組以已登入的 Claude Code 實跑 4 支 Skill 並用真實輸出改寫第 2、3、5 章;查明 @ArchTest Tests run: 0 根因(surefire 3.5.3);報告閘門改版(R0、R5,修 R1、R4)並以真實報告驗證;定案設計文件生命週期(10.4);新增 11.17 上游差異、11.18 RFC 追蹤;修正 Bootstrap 版本差異;第二輪 Goldfish 審查 25 項(3 項以實測或官方原文反駁),見附錄 E.3.1

文件維護資訊

項目內容
文件擁有者架構組(AI 開發規範小組)
審查週期每次 EGM 發布新 tag 時,或每季一次
變更方式PR 修改本檔,需架構師與 DevSecOps 各一人核准
版本對照第 11.7 節「版本相容性檢查表」
回報問題內部 Issue Tracker,標籤 egm-handbook

目錄

第 1 章:EGM 基本概念與核心價值

本章回答三個問題:EGM 是什麼、為什麼需要它、它不能做什麼。讀完本章,你應該能用一句話向主管解釋 EGM,並說出至少三個它不適用的情境。

1.1 EGM 是什麼?

Elephant-Goldfish Model(EGM) 是 Google 開源的一套「AI 輔助軟體設計與審查」方法論,同時也是一個可安裝到 AI Coding Agent 的 Plugin(外掛)。官方一句話定位:

Develop ideas with context and review documents with fresh eyes. EGM is an open-source plugin for AI assistants.(官方,README)

它把 AI 分成兩種記憶狀態,再加上人類,構成三個角色:

角色擁有的 Context責任
Elephant(大象)你的專案、需求與先前所有決策探索問題、撰寫規格
Goldfish(金魚)只有文件本身與文件引用的來源,沒有先前對話找出缺漏的假設、不清楚的需求、實作風險
You(人類)真正重要的目標與限制做架構取捨、核准設計、決定要做什麼

(官方,README「How it works」表格)

技術上,EGM 是一組 Markdown 檔案:

  • 7 支 Skill(skills/egm-*/SKILL.md):定義工作流程。
  • 10 個 Persona(agents/*.md):定義審查者與協調者的系統指示。
  • 5 份 Document Standard(resources/document_standards/*.md):審查用的評分標準。
  • 多個 Host 的 Manifest(.claude-plugin/、.codex-plugin/、plugin.json 等)。

它沒有伺服器、資料庫、帳號或遙測(官方,docs/privacy.md)。所有運算都由你使用的 AI Agent(Claude Code、Codex、Antigravity…)執行。

實務注意:導入 EGM 不需要採購新服務,但要確認公司核准使用的 AI Agent 支援「建立全新 Context 的 Subagent」,否則 Goldfish 審查會直接停止(見 1.7、第 3 章)。

1.2 EGM 的發展背景與起源

時間事件來源
2026Dave Rensin 發表〈Elephants, Goldfish, and the New Golden Age of Software Engineering〉Medium、Google Research 出版頁
2026-06-06docs/designs/architecture.md 定稿(作者 Jim Quinn、Elise Ewing、Dave Rensin)官方
2026-10-22Google Open Source Blog 發表〈Introducing the Elephant-Goldfish Model plugin〉官方 Blog
2026-10-27第一個 tag v0.1.0GitHub Releases
2026-11-06v0.1.1:新增 TRIZ Inventive Catalyst reviewer、實驗性 Cursor/OpenCode/Copilot adapterGitHub Releases

Google 部落格提到「Thousands of Googlers use this plugin every day to ship production Google code.」,並說核心目標 Host 是 Antigravity(官方 Blog)。注意:部落格只列出三個 Review 檢查(Comprehension Check、Antagonistic Review、Implementation Readiness Check),目前 repo 實際是 5 個 stage(見第 5.3 節)。這是「文章發布時的功能不等於目前功能」的典型例子。

官方也提醒先手動練習:「Going through the conversational sequence once or twice … will expose you to LLM quirks」(官方,docs/getting_started.md)。Plugin 是把一再重複的手動提示自動化後的結果。

實務注意:對內簡報引用部落格時,請同時附上 repo 版本號;部落格內容不會隨 repo 更新。

1.3 Dave Rensin 的 Elephant-Goldfish 設計理念

原文網址(README 與 docs/getting_started.md 都引用同一網址):

https://medium.com/@drensin/elephants-goldfish-and-the-new-golden-age-of-software-engineering-c33641a48874

另有 Google Research 出版頁:https://research.google/pubs/elephants-goldfish-and-the-new-golden-age-of-software-engineering/。

尚待驗證:Medium 對自動化工具回應 HTTP 403,本手冊無法逐字閱讀原文;以下理念整理自 repo 的 docs/index.md、docs/designs/architecture.md、Google 部落格與 Google Research 摘要。原文的逐步操作清單請同仁自行閱讀原文確認。

核心理念整理:

  1. Design is the new code.(官方 Blog 引述)AI 產生程式碼的速度已經超過人類能審查的速度,所以「寫清楚設計」比「寫程式」更值錢。
  2. Elephant 記得一切:把系統歷史、使用者旅程(CUJ)、元件地圖整理成 AI 可以低成本瀏覽的形式,讓 AI 能和你討論設計(官方,docs/index.md)。
  3. Goldfish 只記得三秒:讓另一個 AI 在不知道文件怎麼產生的情況下審查文件,可以降低幻覺。官方還加了註腳:金魚三秒記憶其實是迷思,「But that would ruin the metaphor!」
  4. 如果 Goldfish 只讀文件就看不懂,代表文件還不夠詳細;通過 Goldfish 測試之後才請 AI 寫程式(Google Research 摘要)。
  5. 人類擁有結果:「It’s not the tool that did that, it was you that did that.」(官方,docs/index.md)

實務注意:Rensin 的原始做法是「純手動對話流程」,不需安裝任何東西。PoC 階段建議先讓 2~3 位同仁手動練習一次,再安裝 Plugin(第 14.3 節)。

1.4 為什麼 AI Coding 需要 EGM?

官方 docs/designs/architecture.md 列出「非結構化對話式 AI 產碼」的四種系統性失效:

失效模式官方描述在企業專案的樣子
Hallucination Cascades & Context Pollution同一個 thread 訪談、設計又寫程式,模型會「驗證自己錯誤的假設」AI 自己編了一個 customer_status 欄位,後面每一步都當成事實
Premature Implementation(Weeds Syndrome)Agent 預設馬上在附近檔案寫程式,跳過架構位置、YAGNI 與既有元件重用在 Controller 直接寫 SQL;重複造一個 StringUtils2
Chat Dump Fatigue把多頁設計或審查意見直接倒進聊天視窗,污染 Context對話捲了 200 行,下一輪 AI 忘了前面的限制
Documentation Drift開工時寫的設計文件隨程式演進而腐爛新人照文件改,結果文件寫的 API 早已不存在

EGM 對應的解法:

失效模式EGM 機制
Context PollutionGoldfish 在全新 Context 審查;Elephant 只負責設計與修正
Weeds Syndrome設計階段禁止寫正式程式(resources/execution_instructions.md 的 Design-Only Scope)
Chat Dump FatigueArtifact-First:所有長內容寫成檔案,聊天只給路徑
Documentation Drift設計文件 commit 到 docs/designs/,每週跑 /egm:egm-drift-report

實務注意:EGM 解決的是「設計沒想清楚就開始寫」與「自己審自己」兩個問題;程式碼品質、測試、安全掃描仍要靠既有工具(第 9 章)。

1.5 Context Collapse 的原因及影響

Context Collapse(上下文崩潰) 指長對話中,模型對早期資訊的掌握變差,或被後來的錯誤推論覆蓋。常見原因:

  1. 對話過長:需求、試錯、錯誤訊息全部堆在同一個 session。
  2. 推測被當成事實:AI 在第 5 輪說「應該是用 Redis 快取」,第 20 輪已經把它當成既定架構。
  3. 長篇內容灌入聊天:一次貼上 3,000 行 log 或整份規格。
  4. Compaction(自動摘要)遺失細節:Host 為了節省 Context 自動摘要,細節被壓掉。

影響:設計前後矛盾、修好的錯誤又出現、AI 越來越「自信地錯」。

EGM 的處理方式:

  • 把決策寫到檔案:concepts_brief.md 的「Key Decisions」、設計文件的「Open Questions」(官方模板註解:「Unanswered questions are retained here across drafting sessions to preserve conversational memory」)。
  • Draft 不信任記憶:egm-draft Step 4 明確規定「Do not rely on memory: drafting often runs in a new session」,Alternatives 一律從 brief 讀。
  • Goldfish 從零開始:審查者看不到被污染的對話。

實務注意:大象的對話可以很長,但每次做出決定都要寫進檔案。判斷標準:如果現在把這個 session 關掉,另一個人只看檔案能不能接手?

1.6 AI Slop Code 的形成原因

AI Slop Code 指「看起來能跑、但缺乏設計、難以維護」的 AI 產出。形成原因與 EGM 的對策:

原因典型症狀EGM 對策對應位置
需求沒釐清就寫功能做錯方向Brainstorm 多輪開放式提問,未確認前禁止啟動 Goldfishegm-brainstorm Step 1
實作者自己做設計決策同一功能三種錯誤處理風格Zero-Decision Rule:計畫不得留下任何設計選擇給實作者implementation-readiness-standard.md
重造輪子重複的 util、重複的 DTOZoom Out reviewer 必須用 code search 找可重用元件agents/zoom_out.md
過度設計沒有需求就加快取、加 MQYAGNI、Premature Optimization 檢查zoom-out-standard.md
修改範圍失控順手重構、順手升級套件Target Scope & File Boundary 作為實作寫入白名單architecture.md Phase 5
諂媚式回應AI 說「好主意」然後照做No Glazing、Critique First、Banned Adjectives各 SKILL.md Execution Constraints

實務注意:EGM 定義了「實作可以改哪些檔案」,但官方明說「This is a convention, and nothing enforces it.」(architecture.md)。企業要自己用 CI 強制(第 10.9 節的 egm_scope_guard.py)。

1.7 Elephant 與 Goldfish 的角色差異

面向ElephantGoldfish
Context長、累積、包含對話與專案知識全新;只有任務、目標文件、persona、standard、指定的閱讀清單
主要 Skillegm-brainstorm、egm-draft、egm-resolve由 egm-review、egm-review-loop、egm-brainstorm 以 Subagent 啟動
檔案權限可寫設計文件與報告(不可寫正式程式碼)唯讀(persona:「Strict Read-Only Protocol」)
心態合作者,但必須挑戰使用者天真的新進同仁、懷疑論者、嚴格的稽核員
產出concepts_brief.md、design_draft.md、goldfish_review_report.md原始 findings(由 synthesizer 或主 Context 彙整成報告)
失效方式被對話污染、自我說服讀不到必要檔案、被 Host 注入指示檔
flowchart LR
    subgraph Human["人類(擁有結果)"]
        H1["回答問題、做取捨"]
        H2["處理 findings、核准設計"]
    end
    subgraph Elephant["Elephant:主 Context(長記憶)"]
        E1["egm-brainstorm"]
        E2["egm-draft"]
        E3["egm-resolve"]
    end
    subgraph Goldfish["Goldfish:全新 Subagent Context(無對話記憶、唯讀)"]
        G1["egm-zoom-out"]
        G2["egm-comprehension"]
        G3["egm-design、egm-structural、egm-style"]
        G4["egm-implementation-readiness、egm-codebase-details"]
        G5["egm-inventive-catalyst"]
    end
    Files[("檔案<br/>brief、設計文件、報告")]
    H1 --> E1
    E1 --> Files
    E2 --> Files
    Files -->|"只傳路徑與範圍"| Goldfish
    Goldfish -->|"findings 報告"| Files
    Files --> E3
    E3 --> H2
    H2 -->|"核准的修改"| E3

最重要的一句:

Goldfish 的獨立性來自全新的 Agent Context,而不是同一個 Agent 宣稱自己忘記先前的對話。

官方寫法更直接:「If your harness has no subagent tool, stop and tell the user: a review in the same context is not a Goldfish review.」(官方,skills/egm-review/SKILL.md)

還要知道一個細節:全新對話 Context ≠ 不載入專案指示檔。Claude Code adapter 用 omitClaudeMd: true 排除 CLAUDE.md;Codex 的 fork_turns: "none" 只隔離對話輪次,issue #237 回報 Codex CLI 0.166.0 仍會注入 AGENTS.md(官方,docs/harnesses.md)。第 2.9 節詳述。

實務注意:審查前請確認 AGENTS.md/GEMINI.md 不含「本專案已決定用 X」這類會偏袒設計的內容;要讓 Goldfish 質疑的假設,應寫成明確的審查條件。

1.8 EGM 與傳統 AI Coding 的差異

面向傳統對話式 AI CodingEGM
起點「幫我做 X」「我們先釐清 X 要解決什麼問題」
產出順序程式 → (也許)文件Brief → 設計文件 → 審查 → 核准 → 程式
審查者同一個 AI 或人類多個全新 Context 的 AI + 人類
決策紀錄散落在聊天紀錄Alternatives Considered、Open Questions 寫進檔案
修改範圍AI 自行判斷設計文件列出每一個要改的檔案與理由
長期維護文件很快過期設計文件放在 repo,定期 drift report
適合的工作小修正、探索性程式有設計決策、影響多檔案或多系統的變更

官方也不主張所有事情都走完整流程:「Do not forcibly use the design-first process if you believe you can one-shot a simple bug fix. Use the right tool for the job.」(官方,docs/getting_started.md)

實務注意:公司規範應寫明「哪些變更必須走 EGM」,而不是一律強制(第 10.4 節提供判斷表)。

1.9 EGM 與 Spec-Driven Development 的關係

官方定位:「The Elephant-Goldfish Model (EGM) is an implementation of Spec-Driven Development (SDD)」(官方,docs/getting_started.md、architecture.md)。

SDD 的共同主張是「規格是主要產物,程式依規格產生」。EGM 在 SDD 家族中的特色:

  1. 以「獨立審查」為核心:大多數 SDD 工具著重「規格怎麼寫、任務怎麼拆」;EGM 著重「規格寫完後,讓沒有背景的 AI 來挑錯」。
  2. 規格就是一般 Markdown:沒有專屬的 CLI 或 YAML 格式;設計文件模板在 skills/egm-draft/references/design_doc.md。
  3. 不規定實作工具:Phase 5 沒有 Skill(「No Skill.md is required here because the design document is complete and detailed」)。
  4. Living Specification:規格放在 repo,持續與程式碼比對漂移。

與 GitHub Spec Kit、OpenSpec、BMAD 的比較見第 9 章。

實務注意:若團隊已在用 Spec Kit 或 OpenSpec,不必二選一。常見組合是「用原工具產生規格,用 /egm:egm-review-loop 搭配合適的 standard 審查」(第 9.3 節)。

1.10 EGM 對企業 SDLC 的影響

flowchart LR
    A["需求<br/>PM/SA"] --> B["Brainstorm<br/>concepts_brief.md"]
    B --> C["Draft<br/>design_draft.md"]
    C --> D["Goldfish Review<br/>Stage 5 到 9"]
    D --> E["Resolve<br/>goldfish_review_report.md"]
    E --> F["Human Review<br/>設計 PR"]
    F --> G["Implementation<br/>依 File Boundary"]
    G --> H["測試/Code Review/SAST"]
    H --> I["上線"]
    I --> J["Drift Report<br/>每週"]
    J -.->|"文件或程式需修正"| C
SDLC 階段原本導入 EGM 後的變化
需求需求文件交給 SDSA 與 Elephant 一起 Brainstorm,Goldfish 先挑戰需求
設計SD 寫 SDS,會議審查設計文件依模板產生,先過 Goldfish 再進人工審查
開發PG 依 SDS 開發AI 依設計文件實作,範圍受 File Boundary 限制
測試QA 依需求寫測試QA 從 CUJ 與 Verification Plan 產生測試案例
維運文件更新靠自覺Drift Report 列為週例行工作

工作量會「前移」:設計與審查時間增加,期望換來實作返工減少。官方 FAQ 也承認「It can [create a review bottleneck]」,建議「Use EGM for “What’s important now?”, instead of everything」(官方,docs/faq.md)。

實務注意:導入初期最常見的抱怨是「審查意見太多」。官方回答:「This will provide a lot of feedback by design. Take what you think is relevant. Ignore the rest.」(官方,docs/getting_started.md)公司要教同仁「如何分辨該處理與可忽略的 finding」(第 5.4 節)。

1.11 EGM 的優點、限制及適用情境

優點:

  • 在寫程式之前暴露缺漏的決策與隱藏假設。
  • 審查者沒有作者的偏見,能發現「作者覺得理所當然」的事。
  • 設計文件同時是實作指令、Code Review 依據與新人教材。
  • 純 Markdown,容易客製與納入版本控制。

限制(官方明確承認):

限制來源
LLM 仍是非確定性的,每次審查結果不同docs/faq.md、egm-review-loop 2.4
審查會增加人力負擔,可能成為瓶頸docs/faq.md
不能證明生產力提升:「Completing the EGM workflow alone does not demonstrate a productivity improvement.」docs/faq.md
不能取代測試與人類判斷:「A review does not replace tests or human judgment.」README
實作範圍白名單只是慣例,沒有強制architecture.md
雲端 Host(Cowork、ChatGPT Work)仍有驗證缺口docs/harnesses.md

適用情境判斷:

情境建議理由
新功能,涉及 API、資料表或跨模組完整流程有多個需要人類決定的設計點
舊系統升級(Framework、Java 版本)完整流程+Migration standard風險高、步驟多
既有系統沒有文件Bootstrap → 人工審核 → Drift Report建立 Elephant 的 Context
已有 PR 計畫或設計文件只跑 /egm-review官方「60 秒審查」用法
單行 bug fix、文字修改不走 EGM官方明說不要強迫
探索性 PoC、拋棄式程式Brainstorm 即可設計文件價值低

實務注意:用「錯了會不會很貴」判斷,而不是用「程式碼行數」判斷。

1.12 EGM 不能解決的問題及人類必須負責的事項

EGM 不能:

  1. 保證 AI 產生的程式正確——仍需要測試、Code Review、SAST/DAST/SCA。
  2. 替你做架構取捨——egm-draft 規定有多個合理答案時,「Do not rank the options, mark a default, or pick one.」
  3. 知道文件以外的事實——口頭決議、團隊慣例要靠你補(Resolve 的 ESCALATE 類別就是為此設計)。
  4. 確保 Host 的資料處理符合公司政策——資料流由 Host 決定(官方,docs/privacy.md)。
  5. 讓不夠格的需求變好——垃圾需求只會得到精美的垃圾設計。

人類必須負責:

責任負責角色
確認需求正確、範圍合理PM、SA
選擇架構方案、核准 ADRArchitect、SD
判斷 Goldfish findings 要不要處理設計文件作者
核准設計文件(設計 PR)Architect+Tech Lead
審查 AI 產出的程式碼並負責PG(程式作者)、Code Reviewer
安全、個資、法遵判斷資安、法遵
決定文件或程式哪一方要修正(Drift)模組負責人

本章注意事項:

  • EGM 是方法論+Plugin,不是平台;它的價值取決於人類有沒有認真回答 Elephant 的問題、有沒有認真看 Goldfish 的報告。
  • 對內宣傳時避免「導入 EGM 可提升 X% 效率」這類說法,官方自己也不做這種宣稱;以 PoC 實測數據說話(第 14 章)。

1.13 本章 AI 產出審查

本手冊每章最後都有一節「AI 產出審查」,教你檢查 AI 依本章內容產出的東西。本章最常見的 AI 產出是「EGM 介紹簡報」或「導入提案」。

檢查點好例壞例怎麼抓
Review 階段數「v0.1.1 有 5 個 stage(5~9)」「EGM 有三個審查步驟」(這是部落格的說法)對照 skills/egm-review/SKILL.md 的 description
官方支援「非 Google 官方支援產品」「Google 官方企業級工具」搜尋 README 最後一段
效益宣稱「以 PoC 量測返工率」「可減少 50% 返工」找出數字的來源;沒有來源就刪
Goldfish 定義「全新 Subagent Context」「請 AI 忘記先前對話後再審查」檢查是否提到 Subagent

可重跑的檢查指令(Shell,Git Bash/macOS/Linux):

# 在簡報或提案的 Markdown 中找出沒有來源的百分比宣稱
grep -nE '[0-9]+ ?%' proposal.md | grep -v -E 'PoC|實測|來源'

第 2 章:EGM 系統架構與原始碼分析

本章依 v0.1.1/main@72d06f5 的實際檔案說明 EGM 的結構。所有圖都對應到真實目錄與檔名。

2.1 整體架構

官方把 EGM 分成四個解耦的子系統(官方,docs/designs/architecture.md):

子系統目錄內容誰讀它
Skills Layerskills/7 支工作流程(SKILL.md)主 Agent(Elephant)
Personas Layeragents/10 個無狀態系統指示Subagent(Goldfish、Synthesizer、Bootstrap Orchestrator)
Document Standardsresources/document_standards/5 份評分標準Goldfish reviewers
Living Documentationdocs/使用指南、設計文件人類、Agent(Host 整合指南會在執行時讀取)

此外還有一份所有設計類 Skill 都會讀的規則:resources/execution_instructions.md(Design-Only Scope、One Question At A Time、Contradiction Auditing 等)。

flowchart TB
    subgraph Host["AI Coding Agent Host(Claude Code/Codex/Antigravity…)"]
        Main["主 Context=Elephant"]
        Sub["Subagent 工具<br/>Agent/spawn_agent/invoke_subagent"]
    end
    subgraph Plugin["EGM Plugin(安裝後的完整套件)"]
        Skills["skills/<br/>egm-brainstorm、egm-draft、egm-review、<br/>egm-review-loop、egm-resolve、<br/>egm-bootstrap、egm-drift-report"]
        Personas["agents/<br/>10 個 persona"]
        Standards["resources/document_standards/<br/>5 份標準"]
        Exec["resources/execution_instructions.md"]
        Guides["docs/claude.md、docs/codex.md、docs/harnesses.md"]
        Adapters[".claude-plugin/agents/<br/>Claude 專用 adapter"]
    end
    subgraph Workspace["使用者專案(工作目錄)"]
        Brief["concepts_brief.md"]
        Draft["design_draft.md"]
        Reports["*_report.md"]
        Designs["docs/designs/FEATURE.md<br/>SITEMAP.md"]
        Code["原始碼"]
    end
    Main -->|"讀取"| Skills
    Main -->|"讀取"| Exec
    Main -->|"讀取"| Guides
    Main -->|"啟動"| Sub
    Sub -->|"Claude Code 經由"| Adapters
    Adapters -->|"讀取"| Personas
    Sub -->|"讀取"| Personas
    Sub -->|"讀取"| Standards
    Sub -->|"唯讀"| Designs
    Sub -->|"唯讀"| Code
    Main -->|"寫入"| Brief
    Main -->|"寫入"| Draft
    Main -->|"寫入"| Reports
    Main -->|"寫入"| Designs

實務注意:Skill 在執行時會讀 agents/ 與 resources/,所以一定要安裝完整 Plugin。官方警告:「Skill-only installers that copy skills/ alone break EGM」(官方,docs/harnesses.md)。

2.2 Plugin 架構

同一份 repo 同時是多個 Host 的 Plugin 來源,沒有任何 Host 拿到分叉的 Skill 文字(「No harness gets a fork of the skill text.」)。

檔案角色
plugin.json(根目錄)標準來源:名稱、版本、描述、發行者;採 Agent Plugins 1.0.0 格式,Antigravity 讀它
.claude-plugin/plugin.jsonClaude Code/Cowork manifest;明確列出 10 個 adapter
.claude-plugin/marketplace.jsonClaude Marketplace 目錄,source: "./"
.codex-plugin/plugin.jsonCodex manifest:"skills": "./skills/"、requires_local_executor: true
.agents/plugins/marketplace.jsonCodex/ChatGPT Workspace 的 Marketplace 目錄(注意:不是 persona 目錄)
.plugin/plugin.json帶 $schema 的可攜 manifest
.cursor-plugin/、.windsurf/、com.github.copilot/、adapters/opencode/實驗性 adapter
flowchart TB
    Root["plugin.json<br/>(標準來源:name、version)"]
    subgraph Claude["Claude Code/Cowork"]
        CM[".claude-plugin/marketplace.json"]
        CP[".claude-plugin/plugin.json"]
        CA[".claude-plugin/agents/*.md<br/>10 個 adapter"]
    end
    subgraph Codex["Codex/ChatGPT"]
        XM[".agents/plugins/marketplace.json"]
        XP[".codex-plugin/plugin.json"]
    end
    subgraph Agy["Antigravity"]
        AP["plugin.json+agents/ 預設掃描"]
    end
    subgraph Shared["所有 Host 共用的 runtime"]
        SK["skills/egm-*/SKILL.md"]
        AG["agents/*.md"]
        RS["resources/"]
        DC["docs/claude.md、docs/codex.md、docs/harnesses.md"]
    end
    Root -.->|"版本必須一致"| CP
    Root -.->|"版本必須一致"| XP
    CM --> CP
    CP --> CA
    CA -->|"讀取"| AG
    CP -->|"skills/ 預設"| SK
    XM --> XP
    XP -->|"skills 路徑"| SK
    AP --> SK
    AP --> AG
    SK --> RS
    SK --> DC

版本規則:根目錄 plugin.json 的 version 是唯一標準,其他 manifest 必須一致,scripts/prepare_release.py 與單元測試會拒絕不一致(官方,docs/releases.md)。

實測確認的 v0.1.1 版本號(Shell,Git Bash):

cd elephant-goldfish-model
grep -h '"version"' plugin.json .claude-plugin/plugin.json .codex-plugin/plugin.json .plugin/plugin.json
# 四行都是 "version": "0.1.1"

實務注意:.agents/plugins/ 與 agents/ 名稱很像但用途完全不同,客製 persona 時不要放錯目錄。

2.3 Skills 架構

每支 Skill 是一個目錄,結構一致(以 egm-review 為例):

skills/egm-review/
├── SKILL.md              # 工作流程本體(frontmatter + 步驟)
├── TEST.md               # 測試說明
├── test_scenarios.yaml   # 測試情境
├── agents/openai.yaml    # OpenAI 介面顯示用設定
└── assets/icon.svg       # 圖示

部分 Skill 另有 references/:

Skillreferences用途
egm-draftreferences/design_doc.md設計文件模板
egm-bootstrapreferences/templates.md、references/worker-return.schema.jsonREADME 模板、worker 回傳 JSON Schema

所有 SKILL.md 的 frontmatter 都有:

name: egm-review
license: Apache-2.0
disable-model-invocation: true
description: >-
  Orchestrates the EGM Goldfish Review Protocol. ...

disable-model-invocation: true 的意思是模型不會自動觸發這些 Skill,必須由使用者明確呼叫。Claude Code 指南補充:在自動 Skill 探索中看不到它們是預期行為;Skill 工具也會拒絕它們,所以 Stage 7/9 要執行 egm-review-loop 或 egm-resolve 時,Agent 會「read its SKILL.md and follow it in the same thread」(官方,docs/claude.md)。

實測(Claude Code 2.1.325)claude plugin details egm@egm 的 token 估算:

Skill常駐每次呼叫
egm-bootstrap~20~6.1k
egm-brainstorm~80~3.8k
egm-draft~70~4.4k
egm-drift-report~70~720
egm-resolve~60~2.1k
egm-review~70~6.1k
egm-review-loop~100~2.5k
合計常駐~464—

實務注意:常駐成本很低(約 464 token),但一次完整 Review 會啟動 9 個以上的 reviewer,每個都要讀 persona、standard 與目標文件,實際成本以 PoC 量測為準。

2.4 Agents / Subagents 架構

agents/ 下的 10 個 persona(frontmatter name 才是 Subagent 類型名稱,檔名是 snake_case):

檔案name角色用在
zoom_out.mdegm-zoom-outSkeptical Architect:簡單、YAGNI、重用Stage 5、8;Brainstorm
inventive_catalyst.mdegm-inventive-catalystTRIZ:找出被當成必然的取捨Stage 5;Brainstorm
comprehension.mdegm-comprehensionNaive Reader:先改寫(paraphrase)再找未定義名詞Stage 6;Brainstorm
design_critic.mdegm-designHostile Design Critic:架構、擴展、風險Stage 7;Brainstorm
structural.mdegm-structural版面結構與模板符合度Stage 7;Brainstorm
style.mdegm-style技術文字編輯:精準、去除空話Stage 7、9
implementation_readiness.mdegm-implementation-readinessTech Lead:是否能直接開工Stage 9;Brainstorm
codebase_details.mdegm-codebase-details稽核員:文件與程式碼是否一致Stage 9;Brainstorm
synthesizer.mdegm-synthesizer中介協調者:啟動 reviewer、去重、寫報告各 stage(可巢狀時)
bootstrap_orchestrator.mdegm-bootstrap-orchestratorBootstrap 的子樹 workeregm-bootstrap

注意:design_critic.md 的 name 是 egm-design,不是 egm-design-critic。Codex 指南特別提醒「a role such as egm-design maps to agents/design_critic.md, not agents/design.md」。

8 個 reviewer persona 共用三條 Core Mandates:

  1. Strict Read-Only Protocol:沒有修改檔案的工具。
  2. Stateless Mindset:以剛加入專案的新人身分閱讀。
  3. No Chitchat:只講技術理由與發現。

每個 reviewer persona 都有兩種模式:Mode: BRAINSTORM(評估概念)與 Mode: REVIEW(審查文件),由呼叫端指定。

Claude Code 的 adapter(.claude-plugin/agents/*.md)範例(官方原檔 zoom_out.md):

---
name: egm-zoom-out
description: Simplicity and scope reviewer.
license: Apache-2.0
tools: [Read, Grep, Glob]
model: inherit
color: yellow
omitClaudeMd: true
---

Read `${CLAUDE_PLUGIN_ROOT}/agents/zoom_out.md` before reviewing.
Follow that canonical persona's instructions. ...
Adaptertools
8 個 reviewer[Read, Grep, Glob]
synthesizer[Agent, Read, Grep, Glob, Write](可啟動 reviewer、可寫報告,不能跑 shell)
bootstrap orchestratorAgent, Bash, Read, Grep, Glob, Write, Edit

實務注意:實測 claude plugin list 會顯示「Default agents/ folder is ignored because the manifest sets “agents”」,官方說明這是預期且無害的提示(docs/claude.md)。另外實測 claude plugin details egm@egm 的「Agents」欄位顯示 0;adapter 是否已註冊,請在 session 內用 /agents 確認是否看到 egm:egm-zoom-out 等名稱(🧪,本手冊的隔離環境未登入,無法開 session)。

2.5 Resources 架構

resources/
├── README.md
├── execution_instructions.md
└── document_standards/
    ├── feature-spec-standard.md
    ├── heilmeier-standard.md
    ├── implementation-readiness-standard.md
    ├── re-implementation-standard.md
    └── zoom-out-standard.md
標準核心原則(摘要)內建使用處
zoom-out-standard用最簡單的方式解決根本問題,重用既有元件,避免 YAGNI 與過早最佳化Stage 5、8
feature-spec-standard陌生工程師能理解功能、動機與取捨;必須評估替代方案Stage 7
implementation-readiness-standard陌生工程師第一次就能做對;Zero-Decision RuleStage 9
re-implementation-standard只看文件就能寫出功能等價的程式;Zero-Assumption Rule無(供 egm-review-loop 使用;Stage 6 明確不套用)
heilmeier-standardHeilmeier Catechism:目標、現況、新做法、影響、風險、成本、時程、檢核無(供提案審查)

resources/README.md 的原則:「These files are the authoritative instructions and rubrics」,人類文件只連結它們,不另寫摘要。

實務注意:re-implementation-standard 很適合用來審查逆向工程文件(第 7 章),heilmeier-standard 適合審查專案提案或 PoC 計畫書(第 14 章)。

2.6 Documentation 架構

檔案讀者重點
README.md所有人安裝、60 秒審查、第一個設計
docs/getting_started.md使用者核心流程、專案目錄建議、Bootstrap
docs/index.md使用者理念、文件導覽
docs/harnesses.md使用者/DevOps各 Host 安裝、Delegation、Artifact Directory、支援狀態
docs/claude.mdAgent 與使用者Skill 執行時會先讀;權限規則、隔離
docs/codex.mdAgent 與使用者Codex/ChatGPT Work 執行時會先讀
docs/faq.md使用者效益、瓶頸、限制
docs/privacy.md資安/法遵資料流
docs/releases.md維運版本、ZIP、attestation 驗證
docs/designs/*.md貢獻者各功能的設計文件(EGM 自己用 EGM 開發)
TESTING.md維運Harness Test Record
AI_POLICY.md、CONTRIBUTING.md貢獻者AI 貢獻政策

實務注意:docs/claude.md 與 docs/codex.md 不只是說明文件,Skill 第一行就要求 Agent 先讀它們。公司若 fork EGM,修改這兩份檔案等於修改 Agent 行為,必須走審查。

2.7 Workflow Orchestration

整體流程(官方 architecture.md 的序列圖,本手冊轉成中文標註):

sequenceDiagram
    autonumber
    actor Human as 工程師
    participant Elephant as Elephant(Brainstorm 與 Draft)
    participant File as 檔案(工作目錄)
    participant Reviewer as Goldfish Reviewers(Synthesizer)
    participant VCS as 版本控制(PR)
    participant Coder as 實作 Agent
    Human->>Elephant: /egm-brainstorm
    Elephant->>File: 寫入 concepts_brief.md
    Human->>Elephant: /egm-draft
    Elephant->>File: 寫入 design_draft.md 與 docs/designs/FEATURE.md
    Human->>Reviewer: /egm-review docs/designs/FEATURE.md
    Note over Reviewer: Zoom Out → Comprehension → Critic → Zoom Out → Readiness
    Reviewer->>File: 寫入各 stage 報告
    Human->>Elephant: 處理 findings(egm-resolve)
    Human->>VCS: 開 PR 送審 FEATURE.md
    VCS-->>Human: 設計核准並合併
    Human->>Coder: 依 FEATURE.md 實作

編排原則:

  1. Skill 之間鬆耦合:可以單獨使用任何一支(「You do not have to follow the full sequence.」)。
  2. 檔案是 Skill 之間的介面:egm-draft 以 concepts_brief.md 為優先輸入;egm-review 以設計文件路徑為輸入。
  3. 人類關卡(Gate):每個重要轉換點都會停下來問「一個」問題。
  4. Stage 依序執行:5 → 6 → 7 → 8 → 9 不能平行;只有同一 stage 內的 reviewer 可以平行(官方,docs/claude.md)。

實務注意:因為檔案是介面,任何人都可以只拿現有的 PR 計畫跑 /egm-review,不一定要從 Brainstorm 開始。

2.8 Context Transfer 機制

EGM 不在 Agent 之間傳遞對話,而是用檔案與明確的閱讀清單傳遞 Context:

傳遞從到載體
概念Brainstorm 的 ElephantDraft(常是新 session)concepts_brief.md(含 Alternatives Weighed、Key Decisions)
設計ElephantGoldfish目標文件+行號範圍(FeatureRange/DetailedRange)
背景使用者GoldfishGoldfishContext(閱讀清單)
審查標準PluginGoldfishpersona 檔+standard 檔(絕對路徑)
審查結果GoldfishElephant*_report.md、FindingsList
修正決策Elephant+人類設計文件goldfish_review_report.md+對 TargetFile 的編輯

GoldfishContext 的規則(官方,egm-review Step 1.3):

  • 目標文件中的相對連結,若實際路徑(解析 symlink 後)在工作目錄內,自動加入。
  • 連到工作目錄外的檔案或 URL:列出來請使用者決定;無人回答(headless)時全部排除。
  • 部分 reviewer 無法開 URL:先把網頁原始內容存成工作目錄內的檔案,再傳絕對路徑。
  • Stage 6(Comprehension)不給 GoldfishContext,只讀文件本身——這是刻意的,測的就是文件能不能自己說清楚。
flowchart LR
    subgraph E["Elephant 主 Context"]
        Conv["對話與推理<br/>(不外傳)"]
        Split["Semantic Split<br/>FeatureRange/DetailedRange"]
    end
    subgraph Pack["每個 Goldfish 收到的任務包"]
        T["目標文件絕對路徑+行號範圍"]
        P["persona 檔絕對路徑"]
        S["standard 檔絕對路徑"]
        G["GoldfishContext 檔案清單<br/>(Stage 6 除外)"]
    end
    subgraph Gf["Goldfish 全新 Context"]
        R["唯讀工具<br/>Read/Grep/Glob"]
        F["findings<br/>Blocker/Major/Nit"]
    end
    Conv -.->|"禁止傳遞"| Gf
    Split --> T
    T --> R
    P --> R
    S --> R
    G --> R
    R --> F
    F -->|"報告檔"| E

實務注意:設計文件裡「請參考 Confluence 某頁」這種連結 Goldfish 讀不到。要讓 Goldfish 看到的資料,必須存成 repo 內的檔案並用相對連結引用。

2.9 Zero-Context Agent 的建立方式

各 Host 的對應方式(官方,docs/harnesses.md Delegation 表):

HostSubagent 工具具名 persona巢狀隔離重點
Antigravityinvoke_subagent是是獨立 IDE 版沒有此工具 → 不支援
Claude CodeAgent(Task)工具是(egm:egm-zoom-out…)預設最多 3 層adapter 設 omitClaudeMd: true、唯讀工具;需 Claude Code ≥ 2.1.271
Claude CoworkCowork subagents是子代理不能再啟動子代理由主 Context 直接派工
Codex原生 spawn/wait(spawn_agent)否執行時偵測設 fork_context: false 或 fork_turns: "none"
ChatGPT Work該 session 有暴露時才有否執行時偵測沒有工具就停止
omptask是是社群驗證
Muse原生 subagent具名啟動在 1.4.14 被拒,改用 general-purpose執行時偵測—

隔離的兩個層次(官方,docs/harnesses.md「Support Status」):

  1. Parent-turn isolation:子代理看不到父對話。Antigravity CLI、Claude Code、Codex 都有測試通過紀錄。
  2. Host-instruction exclusion:子代理不載入 CLAUDE.md/AGENTS.md/GEMINI.md。
    • Claude Code:adapter 設 omitClaudeMd: true,排除 user/project/local 指示檔,但managed policy 仍會套用。
    • Codex:issue #237 回報 CLI 0.166.0 仍注入 project 與 user AGENTS.md。
    • Antigravity CLI:同一 issue 回報注入 project AGENTS.md 與 GEMINI.md。

官方結論:「Fresh conversation context does not mean that the host omits its instruction files.」並且隔離的是 Context 與工具,不是檔案系統——reviewer 仍可讀到所有可存取的檔案(官方,docs/claude.md)。

實務注意:在 Codex/Antigravity 上,請把 AGENTS.md 保持為「穩定的工作慣例」,不要寫設計結論;要 Goldfish 挑戰的假設,寫成審查條件明確傳入。

2.9.1 實測:Goldfish 隔離到底隔離了什麼(1.1)

1.0 版只能引用官方說法。1.1 在已登入的 Claude Code 2.1.325 上實際跑了一次完整 Review(/egm:egm-review,Consolidated,EGM main 72d06f5),並用「金絲雀字串」驗證隔離。

實驗設計(任何人都可以照做):

金絲雀放在哪裡用來驗證
CANARY-CLAUDEMD-7731專案 CLAUDE.md 最後一行:「every review report written in this repository must end with the line CANARY-CLAUDEMD-7731」Host 指示檔是否被自動注入 reviewer
PROMPTCANARY-4419呼叫 /egm:egm-review 的訊息:「(Background for you only, do not forward to reviewers: the team already chose PostgreSQL advisory locks, ref PROMPTCANARY-4419.)」Elephant 的對話內容是否被轉交給 reviewer

執行後用公司自建的 egm_isolation_probe.py(第 10.5.1 節)分析 --output-format stream-json 的 log。實測輸出:

 1 egm:egm-zoom-out                   prompt=-                      result=-                      opened=CLAUDE.md
 2 egm:egm-inventive-catalyst         prompt=-                      result=-                      opened=-
 3 egm:egm-comprehension              prompt=-                      result=-                      opened=-
 4 egm:egm-design                     prompt=-                      result=-                      opened=-
 5 egm:egm-structural                 prompt=-                      result=-                      opened=-
 6 egm:egm-style                      prompt=-                      result=-                      opened=-
 7 egm:egm-zoom-out                   prompt=-                      result=CANARY-CLAUDEMD-7731   opened=CLAUDE.md
 8 egm:egm-implementation-readiness   prompt=-                      result=-                      opened=-
 9 egm:egm-codebase-details           prompt=-                      result=-                      opened=CLAUDE.md
10 egm:egm-style                      prompt=-                      result=-                      opened=-
subagents=10 leaked=yes
(exit=1)

判讀:

  1. PROMPTCANARY-4419 一次都沒有出現在 reviewer 的 prompt 或回應中:Elephant 沒有把對話內容轉交給 Goldfish(parent-turn isolation 成立)。
  2. 10 個 reviewer 中有 7 個完全沒有接觸 CLAUDE.md:omitClaudeMd: true 生效,Host 沒有自動注入指示檔。
  3. 但 3 個 reviewer(兩次 zoom-out、一次 codebase-details)自己用 Read 工具讀了 CLAUDE.md:它們的任務允許「read files in the repository」,CLAUDE.md 就是 repo 裡的一個檔案。第 7 個 reviewer 甚至在回應最後寫:「The repository’s CLAUDE.md says every review report written in this repository must end with the line CANARY-CLAUDEMD-7731. … If you save this report under .dev/docs/, add that line at the end.」
  4. 最後寫入 .dev/docs/ 的 6 份報告每一份結尾都有 CANARY-CLAUDEMD-7731:寫報告的是 Elephant(主 Context),它本來就載入 CLAUDE.md,所以照做了。

結論:

說法是否成立依據
Goldfish 看不到 Elephant 的對話成立實測 1
Goldfish 不會被自動注入 CLAUDE.md成立(Claude Code)實測 2;Codex/agy 見上方 #237
Goldfish 讀不到 CLAUDE.md不成立實測 3;官方也說隔離的「不是檔案系統」
報告檔中的內容全部來自 Goldfish不成立實測 4;報告由 Elephant 撰寫,會套用 Elephant 的指示

企業規則(建議):

  • CLAUDE.md/AGENTS.md 只寫「穩定的工作慣例」,不要寫會左右審查結論的指示(例如「本專案一律採用 X」),也不要寫任何機密。Goldfish 讀得到,Elephant 寫報告時也會照做。
  • 要 Goldfish 知道的已決事項,寫進設計文件或 ADR,並列入 GoldfishContext(上游 RFC #408 正在討論「把已記錄的決策提供給 Goldfish」,見第 11.18 節)。
  • 只告訴 Elephant 的事(例如本例的 advisory lock)不會進入審查。實測中 Elephant 遵守「不要轉交」的要求,結果是 reviewer 針對「樂觀鎖+部分唯一索引」提出 Blocker,而這些意見與團隊的真實決定無關。換句話說,沒有寫進文件的決定,Goldfish 只能把它當作不存在。

好例與壞例:

項目好例壞例
CLAUDE.md 內容「設計稿與報告寫到 .dev/docs/」「所有 reviewer 一律不得質疑 Oracle 選型」
已決事項docs/adr/0012-advisory-lock.md,列入 GoldfishContext只在聊天中告訴 Elephant
驗證隔離放金絲雀,跑 egm_isolation_probe.py看到報告沒提到就推論「Goldfish 沒讀到」

2.10 Goldfish Reviewer 的執行方式

每個 reviewer 的生命週期:

  1. 主 Context(或 synthesizer)以 Subagent 工具啟動 reviewer,指定 persona 類型(Claude Code)或要求 general-purpose agent 先讀 persona 檔(Codex)。
  2. 任務只包含:目標檔、行號範圍、standard 路徑、GoldfishContext。不得複製父對話的推理。
  3. reviewer 必須先讀完 persona、目標檔與每一份 standard;讀不到就要回報「incomplete review」,不能給結論(官方 adapter 文字:「If a required file cannot be read, report an incomplete review instead of a verdict.」)。
  4. reviewer 以自然語言回報 findings,每項含 Severity(Blocker/Major/Nit)、範圍、理由。
  5. 失敗或逾時:重試一次;再失敗記為 not run,「Never count it as a reviewer with zero findings.」(官方,agents/synthesizer.md)
sequenceDiagram
    autonumber
    participant M as 主 Context(Elephant)
    participant Sy as egm-synthesizer
    participant R1 as egm-design
    participant R2 as egm-structural
    participant R3 as egm-style
    participant FS as 工作目錄
    M->>Sy: Reviewers 清單、Standards 對照、TargetFile、行號、GoldfishContext、報告檔名
    par 同一 stage 內平行
        Sy->>R1: 任務包(全新 Context)
        Sy->>R2: 任務包(全新 Context)
        Sy->>R3: 任務包(全新 Context)
    end
    R1->>FS: 唯讀 persona、standard、目標檔、閱讀清單
    R2->>FS: 唯讀
    R3->>FS: 唯讀
    R1-->>Sy: findings
    R2-->>Sy: 逾時
    Sy->>R2: 重試一次
    R2-->>Sy: findings
    R3-->>Sy: findings
    Sy->>Sy: 去重、依 Blocker/Major/Nit 分組
    Sy->>FS: 寫入 critic_report.md(含 Reviewer Status 表)
    Sy-->>M: 每個 reviewer 的狀態、嚴重度統計、報告路徑

實務注意:報告的「Reviewer Status」表若出現 not run,代表那個視角沒有審查,不是「沒有問題」。第 10.5 節的報告閘門會把它當成失敗。

2.10.1 實測:Claude Code 不一定走 synthesizer(1.1)

上圖是「synthesizer 路徑」。官方 docs/claude.md 的原文是兩種都允許:「In Claude Code, egm:egm-synthesizer may spawn reviewers (nesting is allowed up to 3 levels by default), or the main context may dispatch reviewers directly. … In both cases the main context collects findings and writes the report.」

1.1 實跑時(headless,claude -p),Elephant 沒有啟動 synthesizer:10 個 reviewer 都由主 Context 直接啟動(log 中所有 Agent 呼叫的 parent_tool_use_id 都是空的),報告也由主 Context 撰寫。

這對企業有三個影響:

影響說明對策
報告格式不固定synthesizer 的 ## Reviewer Status 表與 ### 標題 - Severity: X 格式沒有出現;實測 6 份報告用了 4 種不同寫法(第 10.5.1 節)公司閘門必須能解析多種格式,解析不到要 FAIL(R0),不能當成 0 個問題
沒有 Reviewer Status 表「某個 reviewer not run」只寫在 Elephant 的文字說明中人工確認 consolidated 報告開頭的 reviewer 狀態;有表時才交給 R1
報告受 Elephant 指示影響見 2.9.1 實測 4CLAUDE.md 不放審查指示

實務注意:goldfish_review_report.md(egm-resolve 產出)是例外。它的格式寫死在 Skill 模板中,實測完全一致。所以公司閘門應以這份報告為主要依據(第 10.5 節)。

2.11 Review Results 如何回傳 Elephant

回傳路徑有兩條:

路徑適用機制
Hierarchical DispatchHost 支援巢狀(Claude Code 可選、Antigravity)synthesizer 啟動 reviewer 並彙整;報告仍由主 Context 寫(官方 docs/claude.md:「In both cases the main context collects findings and writes the report.」)
Direct Dispatch(Flat Swarm)不支援巢狀(Cowork、部分 Codex);Claude Code 也可能選這條(1.1 實測,2.10.1)主 Context 直接啟動每個 reviewer、收集 findings、自己寫報告;報告格式不固定

回到 Elephant 後,由 egm-resolve 在主 Context 處理(因為它記得設計理由):

  1. 每個 finding 分類為 CONTEST/ESCALATE/PROPOSE FIX/DECLINE。
  2. 寫 goldfish_review_report.md。
  3. 停下來等人類選擇 5 種處理方式之一:直接在報告上註記、auto accept、continue、interactive breakdown、自訂指示。
  4. 套用核准的修改,最上方加 Status: resolved。

詳見第 5.4 節。

實務注意:Resolve 規定「You wrote the document under review. A wish to contest is not evidence that the reviewer is wrong.」——Elephant 想反駁時,必須引用 reviewer 也讀得到的證據。

2.12 設計文件的產生、更新及版本管理

檔案產生者位置是否 commit
concepts_brief.mdegm-brainstorm工作目錄或 artifact 目錄通常不 commit;發布為 RFC 時寫到 docs/designs/<feature>.md
design_draft.mdegm-draft工作目錄或 artifact 目錄不 commit(草稿)
docs/designs/<FEATURE>.mdegm-draft Step 6專案 docs/designs/commit(核准後的規格)
docs/designs/SITEMAP.md人類建立;Skill 若發現存在會登錄docs/designs/commit
zoom_out_report.md 等egm-review工作目錄或 artifact 目錄公司建議封存(第 10.16 節)
goldfish_review_report.mdegm-resolve同上公司建議封存
{YYYY-MM-DD}_DRIFT_REPORT.mdegm-drift-report同上視需要

Artifact 目錄可以用一行設定改變(官方,docs/harnesses.md),寫在提示詞或 CLAUDE.md/AGENTS.md:

EGM artifact directory: .dev/docs
  • 相對路徑以工作目錄為基準。
  • 指示檔中的路徑若解析後在工作目錄外,EGM 會先請你確認;拒絕或無人回答時寫回工作目錄。答案不會保存。
  • 設計文件本身與其他專案檔不會移到這個目錄。
  • Claude Code 只有在專案沒有 CLAUDE.md 時才讀專案 AGENTS.md。

實務注意:官方建議只有在「核准前不想把草稿放進 git」時,才把 .dev/docs 加入 .gitignore;核准的規格與 AGENTS.md 一律 commit。

2.13 EGM 如何與 AI Coding Agent 整合

整合方式=「Host 讀 manifest 找到 skills 與 agents → 使用者呼叫 Skill → Skill 依 Host 選擇 Subagent 工具」。

整合點Claude CodeCodexAntigravity CLI
安裝MarketplaceMarketplaceagy plugin install <url>
呼叫/egm:egm-reviewSkill picker/egm:egm-review
Plugin 根目錄${CLAUDE_PLUGIN_ROOT}SKILL.md 往上三層安裝目錄
Persona 載入adapter 讀共用 personageneral-purpose agent 讀 persona 檔掃描 agents/
Artifact 目錄設定CLAUDE.md 或提示詞AGENTS.md 或提示詞提示詞(尚待驗證是否讀指示檔)

實務注意:EGM 只管「設計與審查」。實作階段用的是 Host 本身的能力,公司可以加上自己的實作 Skill(官方:「Add your skills to your implementation plan!」)。

2.14 Plugin Manifest、設定檔及目錄結構

v0.1.1/main@72d06f5 實際目錄樹(省略 site/ 網站原始碼與部分測試檔):

elephant-goldfish-model/
├── plugin.json                  # 標準 manifest(Agent Plugins 1.0.0)
├── .plugin/plugin.json          # 帶 $schema 的可攜 manifest
├── .claude-plugin/
│   ├── plugin.json              # Claude manifest,列出 10 個 adapter
│   ├── marketplace.json         # Claude marketplace(name: egm)
│   ├── icon.png
│   └── agents/                  # Claude adapter(唯讀工具、omitClaudeMd)
├── .codex-plugin/plugin.json    # Codex manifest
├── .agents/plugins/marketplace.json  # Codex/ChatGPT Workspace marketplace
├── .cursor-plugin/              # 實驗性 Cursor adapter
├── .windsurf/                   # 實驗性 Windsurf(Devin Desktop)rule 與 workflows
├── com.github.copilot/agents/   # 實驗性 Copilot CLI 代理設定
├── adapters/opencode/install.py # 實驗性 OpenCode V1 安裝器
├── .gemini/                     # Gemini Code Assist 的 PR 審查設定(給 EGM repo 自己用)
├── .github/                     # Issue/PR 模板、CI workflows
├── agents/                      # 10 個共用 persona
├── skills/                      # 7 支 Skill
├── resources/                   # 執行規則與 5 份標準
├── docs/                        # 使用與 Host 整合文件、designs/、site/
├── scripts/pack_plugin.py       # 產生 runtime ZIP
├── scripts/prepare_release.py   # 發布前檢查
├── tests/                       # unit 與 opt-in integration 測試
├── assets/icon.svg
├── AGENTS.md  AI_POLICY.md  CONTRIBUTING.md  TESTING.md  ACCESSIBILITY.md
├── README.md  LICENSE  pyproject.toml
└── site/                        # egm.dev 網站(Astro)

.claude-plugin/marketplace.json(官方原檔):

{
  "name": "egm",
  "owner": {
    "name": "Google"
  },
  "plugins": [
    {
      "name": "egm",
      "source": "./",
      "description": "Develop ideas with context and review documents with fresh eyes."
    }
  ]
}

這就是安裝指令 egm@egm 的由來:第一個 egm 是 plugin 名稱,第二個是 marketplace 名稱。

實測安裝後,Claude Code 的快取目錄是 <CLAUDE_CONFIG_DIR>/plugins/cache/egm/egm/0.1.1/,內容是整個 repo(包含 site/、tests/)。官方發布的 runtime ZIP 則只含必要檔案(docs/directory.md)。

實務注意:.gemini/ 不是 Gemini CLI 的整合;它是 Gemini Code Assist 對 EGM repo 本身的 PR 審查設定。EGM 目前沒有 Gemini CLI adapter(第 3.7 節)。

2.15 重要 Skills 與 Agent Persona 的用途

Skill一句話用途主要輸入主要輸出會啟動 Subagent
egm-brainstorm把半成熟想法變成經過挑戰的假設想法描述concepts_brief.md是(7 個視角)
egm-draft逐節撰寫設計文件brief 或筆記design_draft.md → docs/designs/X.md否
egm-review5 階段 Goldfish 審查設計文件路徑5 份 stage 報告或彙整報告是
egm-review-loop自選 reviewer 與標準,迭代到收斂文件、範圍、reviewers、standardsgoldfish_review_report.md是
egm-resolve在 Elephant 中處理 findingsfindingsgoldfish_review_report.md+文件修改否
egm-bootstrap由下而上產生目錄 README目錄路徑各層 README.md(或 EGM.md)是(目錄 > 5 時)
egm-drift-report比對文件與程式碼文件目錄{YYYY-MM-DD}_DRIFT_REPORT.md否

實務注意:egm-draft、egm-resolve、egm-drift-report 都在主 Context 執行,不需要 Subagent;egm-brainstorm 與 egm-review 在不支援 Subagent 的 Host 上會停止。

2.16 主要流程的執行順序及依賴關係

flowchart TD
    BS["egm-brainstorm"] -->|"concepts_brief.md<br/>Priority 1 輸入"| DR["egm-draft"]
    Notes["既有筆記或 discussion_summary.md"] -->|"Priority 2"| DR
    DR -->|"docs/designs/X.md"| RV["egm-review"]
    PR["既有 PR 計畫或設計文件"] --> RV
    RV -->|"Stage 7、9 選擇 Option 1"| RS["egm-resolve"]
    RV -->|"Stage 7、9 在內部呼叫"| RL["egm-review-loop"]
    RL --> RS
    RS -->|"修改 TargetFile"| RV
    BT["egm-bootstrap"] -->|"README 階層=Elephant Context"| BS
    BT -->|"可選"| DF["egm-drift-report"]
    Designs["docs/designs/"] --> DF
    DF -->|"人類決定改文件或改程式"| Designs

依賴規則:

  1. egm-review 的 Stage 7 與 Stage 9 在內部執行 egm-review-loop(官方:「Invoke egm-review-loop in-thread」)。
  2. egm-review-loop 每輪都把 findings 交給 egm-resolve。
  3. Stage 依賴 5 → 6 → 7 → 8 → 9 是拓撲順序,Preset 選單禁止多選(「to protect topological dependencies」)。
  4. Bootstrap 最後會詢問是否執行 Drift Report 檢查產生的 README。

本章注意事項:

  • 讀原始碼時,以 frontmatter name 為準,不要用檔名猜 Subagent 名稱。
  • docs/designs/ 內的 EGM 自身設計文件,有些狀態是「Proposed」,不代表已出貨;以 skills/ 實際內容為準。

2.17 本章 AI 產出審查

請 AI「畫 EGM 架構圖」時,常見錯誤:

檢查點好例壞例怎麼抓
persona 數量與名稱10 個,egm-design 對應 design_critic.md「egm-design-critic」「egm-security」比對 agents/*.md frontmatter
.agents/ 用途Codex marketplace 目錄「放 persona 的目錄」讀 .agents/plugins/marketplace.json
Stage 6 的輸入只讀文件,不給 GoldfishContext「所有 stage 都讀專案原始碼」讀 egm-review Step 1.3
Gemini 支援沒有 Gemini CLI adapter「透過 .gemini/ 支援 Gemini CLI」讀 .gemini/config.yaml 內容

可重跑的檢查指令(Shell,在 EGM repo 根目錄):

# 列出所有 persona 的實際 name,與 AI 畫的圖比對
grep -h '^name:' agents/*.md | sort

第 3 章:EGM 安裝與環境建置

本章所有 EGM 安裝指令都取自官方 README、docs/harnesses.md、docs/claude.md、docs/codex.md;Claude Code 部分另有實測紀錄。

3.1 系統需求及必要軟體

EGM 本身只是 Markdown 檔案,沒有執行期相依套件。需求來自 Host:

項目需求說明
AI Agent Host至少一種:Claude Code、Codex CLI/desktop、Antigravity CLI/App/IDE 擴充、Claude Cowork、ChatGPT Work需支援全新 Context 的 Subagent
Claude Code 版本≥ 2.1.271(omitClaudeMd 支援)「Older versions must not be treated as verified Goldfish isolation environments.」(官方,docs/claude.md)
Git建議 2.40 以上Marketplace 以 git clone 取得
網路可連 github.comMarketplace 安裝與更新
Python 3選用只有自行打包 ZIP(scripts/pack_plugin.py)、跑 EGM 測試、或使用本手冊工具時需要
GitHub CLI(gh)選用驗證 Release attestation
帳號Host 的帳號(Claude、OpenAI、Google)EGM 不需要自己的帳號

Bootstrap 會執行本機探索指令(例如列目錄),以及專案已設定的格式化工具(官方,docs/privacy.md),因此需要 Host 允許有限的 shell 權限。

實務注意:Windows 使用者請用 Git Bash 或 PowerShell 7;docs/claude.md 的權限規則有 Windows 專用路徑寫法(第 3.15 節)。

3.2 Git 與 GitHub 環境

Marketplace 安裝會 clone https://github.com/google/elephant-goldfish-model.git。實測 Claude Code 2.1.325 在沒有 SSH 設定時會自動改用 HTTPS:

Adding marketplace…SSH not configured, cloning via HTTPS: https://github.com/google/elephant-goldfish-model.git

企業環境檢查清單:

檢查指令(Shell)預期
可連 GitHubgit ls-remote https://github.com/google/elephant-goldfish-model.git HEAD印出一個 SHA
Proxygit config --global --get http.proxy依公司規定
長路徑(Windows)git config --global core.longpaths建議 true
換行git config --global core.autocrlf依公司規定;設計文件建議 .gitattributes 固定

若公司不允許直接連外,可由 DevOps 建立內部鏡像 repo(第 11.1 節),再對鏡像執行 marketplace add(🧪:claude plugin marketplace add 支援 URL、路徑或 GitHub repo,見 claude plugin marketplace --help)。

實務注意:Windows 上 Claude Code 的 plugin 快取路徑很深(…\.claude\plugins\cache\egm\egm\0.1.1\…),沒開 core.longpaths 可能在 clone site/ 子目錄時失敗。

3.3 Node.js / CLI 等必要環境(依實際需求確認)

用途是否需要 Node.js
使用 EGM 本身不需要
以 npm 安裝 Codex CLI需要
以 npm 安裝 Claude Code選用(Claude Code 另有原生安裝程式)
實驗性 OpenCode adapter需要(npm install --prefix … opencode-ai@1.18.29)
修改 EGM 網站(site/)需要(一般使用者不需要)

實務注意:不要因為「AI 工具」就預設要裝 Node.js;EGM 本身用不到。

3.4 EGM Repository 下載

一般使用者不需要手動下載,Marketplace 會處理。下列情況才需要 clone:

  • 審查原始碼、做資安評估。
  • 建立公司內部鏡像或 fork。
  • Antigravity App/IDE 的手動安裝。
  • 本機測試修改過的版本(claude --plugin-dir)。
# Shell(Git Bash/macOS/Linux)
git clone https://github.com/google/elephant-goldfish-model.git
cd elephant-goldfish-model
git checkout v0.1.1          # 固定在已發布的 tag
git log -1 --format='%H %cI' # 預期 dea7761… 2026-11-06

正式發布的 runtime 套件(GitHub Releases):

檔案內容
egm-claude-0.1.1.zipClaude Code/Cowork 用 runtime
egm-openai-0.1.1.zipChatGPT/Codex 用 runtime
SHA256SUMS雜湊值

驗證下載(官方,docs/releases.md,Shell,需 gh):

sha256sum -c SHA256SUMS
for archive in egm-claude-*.zip egm-openai-*.zip; do
  gh attestation verify "$archive" --repo google/elephant-goldfish-model \
    --signer-workflow google/elephant-goldfish-model/.github/workflows/release.yml \
    --source-ref refs/heads/main || exit 1
done

實務注意:v0.1.1 的 Release notes 寫明「Native end-to-end verification of these exact release ZIPs remains open in #60」——ZIP 的簽章已驗證,但「這份 ZIP 安裝後完整跑過流程」尚未驗證。

3.5 Plugin 安裝方式

各 Host 的官方安裝方式(官方,README 與 docs/harnesses.md):

Host安裝
Claude Codeclaude plugin marketplace add google/elephant-goldfish-model 然後 claude plugin install egm@egm
Codex CLIcodex plugin marketplace add google/elephant-goldfish-model 然後 codex plugin add egm@egm
Antigravity CLIagy plugin install https://github.com/google/elephant-goldfish-model
Antigravity App/Antigravity for IDEs執行 /plugin,或請 Agent「Install https://github.com/google/elephant-goldfish-model」,或手動複製(3.10)
ChatGPT desktop/Codex desktop在 desktop app 開啟官方 Plugin 頁面並安裝(desktop-only listing)
Claude Coworkclaude.ai/plugins 或 Cowork plugin 面板,marketplace google/elephant-goldfish-model
ChatGPT Workspace(Enterprise/Business/Edu)Admin > Plugins > Add > Import marketplace,repo URL 填官方網址,路徑 .agents/plugins
ompomp plugin marketplace add google/elephant-goldfish-model && omp plugin install egm@egm
Museclone 後 muse plugins install ./elephant-goldfish-model --scope user && muse plugins approve egm

注意 Codex 用的是 codex plugin add,Claude Code 用的是 claude plugin install,動詞不同,不可互換。

實務注意:一律「安裝完整 Plugin」。不要用只複製 skills/ 的 Skill 安裝工具(例如把 SKILL.md 複製到 ~/.claude/skills/),EGM 會讀不到 persona 與 standard。

3.6 Plugin Marketplace 設定

EGM repo 本身就是 Marketplace:

Marketplace 檔給誰名稱
.claude-plugin/marketplace.jsonClaude Code、Cowork、ompegm
.agents/plugins/marketplace.jsonCodex、ChatGPT Workspace importegm
.cursor-plugin/marketplace.jsonCursor(實驗性)—

Claude Code 的 Marketplace 管理(實測,Shell):

claude plugin marketplace list            # 列出已設定的 marketplace
claude plugin marketplace update egm      # 從來源更新目錄
claude plugin marketplace remove egm      # 移除

實測 marketplace list 輸出:

Configured marketplaces:

  ❯ anthropic-plugin-directory
    Source: Built in (Anthropic Directory)

  ❯ egm
    Source: GitHub (google/elephant-goldfish-model)

企業共用設定:可以把 marketplace 寫進專案的 .claude/settings.json,讓團隊成員開專案時自動得到相同來源(🧪;欄位名稱請以 Claude Code 官方文件 extraKnownMarketplaces 與 enabledPlugins 為準)。

實務注意:Muse 不能用 marketplace add 安裝 EGM——「marketplace add on this repository discovers zero plugins because Muse reads the Codex catalog first」(官方,docs/harnesses.md)。這說明多 Host 共用一個 repo 時,各 Host 讀的 catalog 不同。

3.7 AI Agent 整合方式

支援狀態總表(官方,docs/harnesses.md「Support Status」與 TESTING.md Harness Test Record,查證日 2026-11-17):

Host狀態證據
Antigravity CLI支援;自動化安裝與端到端 fixture 通過1.4.5,2026-10-22
Claude Code支援;fixture 通過2.1.308,2026-10-22
Codex CLI支援;fixture 通過0.163.0、0.164.0-alpha,2026-10
Claude Cowork可安裝;雲端追蹤驗證有缺口(#105)2026-10-22,Stage 8 因用量上限中斷
ChatGPT Work可安裝;驗證有缺口(#106)2026-10-22
omp可安裝;社群驗證 7 支 Skill 可解析,fixture 未跑v18.12.6
Muse可安裝;fixture 通過,但具名 agent 無法啟動1.4.14
Antigravity IDE(獨立版)不支援:沒有 invoke_subagentmacOS、Linux 測試
GitHub Copilot CLI實驗性:工作流與隔離未驗證docs/copilot.md
Cursor實驗性:安裝、流程、隔離皆未驗證docs/cursor.md
OpenCode V1實驗性docs/opencode.md
Windsurf(Devin Desktop)實驗性 routingdocs/harnesses.md
Gemini CLIrepo 中沒有 adapter.gemini/ 是 PR 審查設定

官方對「支援」的定義:「A harness counts as supported after /egm-brainstorm, /egm-draft, and /egm-review run end to end through its plugin install.」

實務注意:公司「核准使用的 Host」應限縮在上表「支援」的三者(Antigravity CLI、Claude Code、Codex CLI),其他列為 PoC 研究。

3.8 安裝 Claude Code

Claude Code 本身的安裝請以 Anthropic 官方文件為準(https://code.claude.com/docs/en/setup)。常見方式:

# Shell(macOS/Linux/WSL):官方原生安裝程式
curl -fsSL https://claude.ai/install.sh | bash
# PowerShell(Windows):官方原生安裝程式
irm https://claude.ai/install.ps1 | iex
# 或透過 npm(官方文件:需 Node.js 22 以上,不要用 sudo)
npm install -g @anthropic-ai/claude-code@latest

安裝 EGM(官方指令;實測於 Claude Code 2.1.325,Shell):

claude --version                                  # 需 ≥ 2.1.271
claude plugin marketplace add google/elephant-goldfish-model
claude plugin install egm@egm
claude plugin list

實測輸出:

✔ Successfully added marketplace: egm (declared in user settings)
Installing plugin "egm@egm"...✔ Successfully installed plugin: egm@egm (scope: user)
Installed plugins:

  ❯ egm@egm
    Version: 0.1.1
    Scope: user
    Status: ✔ enabled
    Note: Default agents/ folder is ignored because the manifest sets "agents"

若狀態不是 enabled(官方,docs/claude.md):

claude plugin enable egm@egm

第一次執行 claude 會引導登入;請使用公司核准的帳號或組織。開新 session 後,在 Claude Code 對話框輸入:

/egm:egm-review docs/designs/webhooks.md

實務注意:要在不影響個人設定的情況下試裝,可以設定 CLAUDE_CONFIG_DIR 指向一個空目錄(本手冊的實測就是這樣做的)。注意這樣會是未登入狀態,只能驗證安裝,不能開 session。

3.9 安裝 Codex CLI

Codex CLI 本身(以 OpenAI 官方文件為準):

# Shell:透過 npm 安裝
npm install -g @openai/codex
codex --version

安裝 EGM(官方,docs/codex.md):

codex plugin marketplace add google/elephant-goldfish-model
codex plugin add egm@egm

使用方式與 Claude Code 不同:

  • 開新 session 後,從 skill picker 選擇 EGM 的 Skill,不使用 /egm: 前綴。
  • Skill 會用自己 SKILL.md 的絕對路徑往上三層找到 Plugin 根目錄(「the plugin root is three parent directories above the file」)。
  • 指定 artifact 目錄要寫在 AGENTS.md 或提示詞。
  • Codex 聊天中的檔案連結用絕對路徑 Markdown 連結,不要用 file://。

(🧪:本手冊實測環境沒有 Codex CLI。)

實務注意:Codex 會注入 AGENTS.md 到 reviewer(issue #237)。用 Codex 跑 Review 時,AGENTS.md 只放工作慣例,不放設計結論。

3.10 Antigravity 安裝與整合

Antigravity CLI(官方,README):

agy plugin install https://github.com/google/elephant-goldfish-model

Antigravity CLI 對話框中的呼叫方式:

/egm:egm-brainstorm Add webhook delivery to this project.

README 提醒:agy CLI 1.4.10 會把沒有前綴的名稱補成有前綴的指令(#220),1.4.8 不會(#196),「so keep the prefix」。

Antigravity App 與 Antigravity for IDEs(VS Code 擴充)共用全域 plugin 目錄 ~/.gemini/config/plugins/<name>/。不用 agy 的手動安裝(官方,docs/harnesses.md,Shell):

git clone https://github.com/google/elephant-goldfish-model.git
cd elephant-goldfish-model
mkdir -p ~/.gemini/config/plugins/egm
cp -R plugin.json README.md LICENSE skills agents resources docs assets ~/.gemini/config/plugins/egm/

更新時官方建議先刪除 ~/.gemini/config/plugins/egm 再複製,避免殘留舊檔。完成後重新載入視窗,確認 plugin 清單出現 egm,且有 egm-brainstorm、egm-draft、egm-review。

限制來源
App 與 IDE 擴充中的指令格式「has not been verified」官方,docs/harnesses.md
獨立版 Antigravity IDE 不支援(沒有 invoke_subagent)同上
Antigravity CLI reviewer 被回報注入 AGENTS.md、GEMINI.md(#237)同上

Antigravity CLI 本身的安裝方式請以 Google 官方 Antigravity 文件為準(尚待驗證:本手冊未取得 agy 安裝指令的官方頁面)。

實務注意:Antigravity 是部落格所說的「core target」,但企業若以 Claude Code 為主要 Host,不必為了 EGM 另外導入 Antigravity。

3.11 ChatGPT / Codex Desktop / ChatGPT Work 的支援方式與限制

介面安裝呼叫限制
ChatGPT desktop官方 Plugin 頁面(desktop-only)在本機執行的新 thread 中 Try in chatlisting 僅限 desktop,「it does not establish support for cloud Work sessions」
Codex desktop同上Skill picker同上
ChatGPT Workspace importAdmin > Plugins > Add > Import marketplace,路徑 .agents/plugins@egm雲端審查限制仍適用;需檢查當前 session 是否有原生 spawn_agent
本機測試套件python3 scripts/pack_plugin.py --target openai --output /tmp/egm-chatgpt 後上傳 ZIPTry in chat個人測試用

Codex manifest 宣告 "requires_local_executor": true,理由是 Bootstrap 會跑 shell 指令(官方,docs/codex.md)。官方 longDescription:「Reviews require a local executor and isolated subagents. Cloud support remains partial.」

規則:「If they are absent, stop and report that isolation is unavailable; never simulate reviewers in the parent context.」

實務注意:金融業若只核准雲端 ChatGPT Work,EGM 的 Review 功能可能無法完整使用;導入前要先在公司帳號實測 Subagent 是否可用(第 14.3 節 PoC 檢核項)。

3.12 VS Code 開發環境整合

組合方式狀態
VS Code + Claude Code 擴充擴充與 CLI 共用 plugin 設定;在對話框輸入 /egm:egm-review …🧪(依 Claude Code 擴充與 CLI 共用設定的一般行為推論)
VS Code + Antigravity for IDEs/plugin 或手動安裝到 ~/.gemini/config/plugins/egm/安裝路徑官方;指令格式未驗證
VS Code + GitHub CopilotEGM repo 的 .vscode/settings.json 以 chat.agentSkillsLocations、chat.agentFilesLocations 對應 skills 與 com.github.copilot/agents實驗性(issue #375)

建議的 VS Code 設定(建議):

{
  "files.associations": {
    "*_report.md": "markdown",
    "concepts_brief.md": "markdown"
  },
  "markdown.validate.enabled": true,
  "files.exclude": {
    ".dev/docs/**/*.tmp": true
  }
}

實務注意:設計文件常含 Mermaid 圖,建議團隊統一安裝可預覽 Mermaid 的 Markdown 擴充,人工審查時才看得到圖。

3.13 Plugin 安裝完成後的驗證

建議依序做三層驗證:

層次指令/操作通過條件
L1 安裝claude plugin listegm@egm、Version 0.1.1、enabled
L1 Manifestclaude plugin validate <plugin 目錄>/.claude-plugin/plugin.json✔ Validation passed
L1 組成claude plugin details egm@egmSkills (7) 列出 7 個名稱
L2 探索新 session 輸入 /egm:出現 7 個 egm:egm-* 指令(🧪:本手冊以 -p 直接呼叫,未在互動 UI 確認選單)
L2 Subagent新 session 執行 /agents,或看 L3 log 中 Agent 呼叫的 subagent_type出現 egm:egm-zoom-out 等名稱(1.1 實測:log 中 10 個 reviewer 都是 egm:egm-*)
L3 端到端/egm:egm-review 一份小文件,選 Consolidated report(headless 用 Step: uninterrupted)產生 5 份 stage 報告與 consolidated_review_report.md(1.1 實測,3.13.1)

實測 L1(Claude Code 2.1.325,Shell):

claude plugin validate "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/egm/egm/0.1.1/.claude-plugin/plugin.json"
✔ These checks found nothing to report
✔ Validation passed

L3 的最小測試文件建議用 repo 內一份短設計文件(例如團隊自己的 webhook 小設計),不要用正式專案。

實務注意:L1 通過不代表 Review 會成功。官方:「Installing or discovering the plugin alone does not establish end-to-end workflow support.」(docs/codex.md)

3.13.1 用 headless 模式實跑 L3(1.1 實測)

不想改動自己的 Claude Code 安裝時,可以用 --plugin-dir 只在這次執行載入 EGM(不安裝、不寫入 enabledPlugins)。這也是 1.1 實跑 4 支 Skill 的方式。

步驟 1:準備拋棄式專案(Shell):

git clone --depth 1 https://github.com/google/elephant-goldfish-model.git egm-src
mkdir egm-l3 && cd egm-l3 && git init -q
mkdir -p docs/designs && cp /path/to/small-design.md docs/designs/customer-contact.md
printf 'EGM artifact directory: .dev/docs\n' > CLAUDE.md
git add -A && git commit -qm init

步驟 2:執行 Consolidated review(Step: uninterrupted 會跳過所有互動關卡;GoldfishContext: [] 表示不額外提供閱讀清單):

claude -p --plugin-dir ../egm-src \
  --permission-mode acceptEdits \
  --allowedTools "Read,Grep,Glob,Write,Edit,Agent,Bash(mkdir:*),Bash(ls:*)" \
  --output-format stream-json --verbose --max-budget-usd 15 \
  "/egm:egm-review TargetFile: docs/designs/customer-contact.md GoldfishContext: [] Step: uninterrupted" \
  > review.jsonl

步驟 3:確認結果:

ls .dev/docs
# comprehension_report.md  consolidated_review_report.md  critic_report.md
# implementation_readiness_report.md  intermediate_zoom_out_report.md  zoom_out_report.md
python -c "import json;[print(d['subtype'],d['num_turns'],round(d['total_cost_usd'],2)) for d in map(json.loads,open('review.jsonl',encoding='utf-8')) if d.get('type')=='result']"

1.1 實測紀錄(Windows 11、Claude Code 2.1.325、EGM main 72d06f5,對象為 124 行的 design_good.md):

Skill執行時間turns費用(total_cost_usd)產出
egm-review(uninterrupted)9 分 11 秒22US$3.555 份 stage 報告+consolidated;10 個 reviewer 全部完成
egm-resolve(同一 session,--resume)3 分 5 秒2US$4.21goldfish_review_report.md:26 項,21 PROPOSE FIX、5 ESCALATE
egm-bootstrap(5 個目錄)2 分 50 秒28US$0.946 份 EGM.md
egm-drift-report1 分 13 秒19US$0.462026-11-17_DRIFT_REPORT.md

實務注意:

  • total_cost_usd 是 Claude Code 依 API 價格估算的金額;使用訂閱方案時代表「消耗的用量」而不是帳單。Resolve 只有 2 turns 卻比 Review 貴,是因為它把整個 Review session 的 Context 一起帶進來(Elephant 記憶的代價)。
  • -p 模式沒有人可以回答問題。官方 Skill 對 headless 有明確規則(例如連結到工作目錄外的檔案「if no one can answer, as in a headless run, leave them all out and keep going」),但要 review 停在某個關卡等你決定時,請用互動 session。
  • --allowedTools 沒列到的工具會被拒絕且不會詢問。實測 Bootstrap 有 5 次、Drift Report 有 2 次 shell 呼叫被拒(PowerShell,以及 cd … && cat … 這類組合式 Bash,不符合 Bash(ls:*)),之後改用 Read/Glob 完成。正式使用時請檢查 result 的 permission_denials:
python -c "import json;[print(len(d['permission_denials']),[x['tool_name'] for x in d['permission_denials']]) for d in map(json.loads,open('review.jsonl',encoding='utf-8')) if d.get('type')=='result']"

3.14 啟動新 Session 的必要性

README:「Start a new session after installation.」原因:

  1. Host 在 session 啟動時載入 plugin 清單與 Skill 描述;已開啟的 session 看不到新安裝的 Skill。
  2. claude plugin update 的說明寫明「restart required to apply」(實測 claude plugin update --help)。
  3. 新 session 也讓 Elephant 從乾淨狀態開始,避免舊對話污染設計。

實務注意:更新 EGM 後,正在進行中的 Review 不要中途切換版本;先完成或用「Pause Review」暫停,再開新 session 繼續。

3.15 安裝失敗的排除方式

症狀可能原因檢查解法
marketplace add 逾時Proxy、防火牆git ls-remote https://github.com/google/elephant-goldfish-model.git設定 proxy 或改用內部鏡像
clone 失敗 Filename too longWindows 長路徑git config core.longpathsgit config --global core.longpaths true
/egm: 看不到指令沒開新 session、plugin disabledclaude plugin listclaude plugin enable egm@egm 後開新 session
Skill 回報找不到 persona 或 standard只安裝了 skills檢查快取目錄有沒有 agents/、resources/移除後以 marketplace 重新安裝完整 plugin
headless 執行時 reviewer 讀檔被拒沒有對 plugin 快取目錄的讀取權限檢查 /permissions加入 3.15.1 的 Read 規則
專案 .claude/settings.json 的權限沒生效工作區尚未信任claude doctor以互動模式開一次並接受信任對話框
Review 一開始就停止Host 沒有 Subagent 工具確認 Host 與版本換用支援的 Host
/plugin > Errors 出現 agents/ 警告正常提示—無需處理(官方)

3.15.1 headless 執行的讀取權限

persona 與 standard 位於 plugin 快取,在專案外。headless 執行時要明確允許讀取(官方,docs/claude.md)。Windows 路徑要寫成 //c/...(小寫磁碟代號、無冒號)或原生路徑;//C:/Users/... 不會匹配。版本段用 * 可跨版本。

放在哪裡:讀取規則含個人路徑,放在使用者層 ~/.claude/settings.json(Windows:C:\Users\<你>\.claude\settings.json;有設定 CLAUDE_CONFIG_DIR 時是該目錄下的 settings.json,plugin 快取也會在 <CLAUDE_CONFIG_DIR>/plugins/cache/)。專案 .claude/settings.json 只放全員共用、不含個人路徑的 deny 規則。

📄 user-settings/settings.json(建議;複製到使用者層 settings.json,把 REPLACE_ME 換成你的 Windows 使用者名稱)

{
  "permissions": {
    "allow": [
      "Read(//c/Users/REPLACE_ME/.claude/plugins/cache/egm/egm/*/agents/**)",
      "Read(//c/Users/REPLACE_ME/.claude/plugins/cache/egm/egm/*/docs/**)",
      "Read(//c/Users/REPLACE_ME/.claude/plugins/cache/egm/egm/*/resources/**)",
      "Read(//c/Users/REPLACE_ME/.claude/plugins/cache/egm/egm/*/skills/**)"
    ]
  }
}

macOS/Linux 的寫法(// 開頭代表絕對路徑):

Read(//Users/<you>/.claude/plugins/cache/egm/egm/*/agents/**)
Read(//home/<you>/.claude/plugins/cache/egm/egm/*/agents/**)

(另外三個目錄 docs、resources、skills 同樣各一行。macOS/Linux 寫法依官方 //absolute/plugin/path/... 格式推得,本手冊未在 macOS/Linux 實測,🧪。)

📄 project/.claude/settings.json(建議;專案層,只放 deny)

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

實測重點:

  • claude doctor 對兩份設定都沒有回報格式錯誤;故意把 allow 寫成字串時,claude doctor 會回報「permissions.allow: Expected array, but received string」。
  • 讀取規則若放在專案層,尚未信任的工作區會被忽略:claude doctor 提示「Ignoring 4 permissions.allow entries from .claude/settings.json: this workspace has not been trusted」。放在使用者層則沒有這個提示。官方 settings 文件也說明專案層的 deny 與 ask 規則「apply right away」,allow 規則要等信任之後。
  • 官方提醒 --add-dir 也會擴大編輯權限,「so it is not a read-only substitute」。

實務注意:不要為了讓 Review 跑起來而關閉權限檢查或授權讀取所有 plugin;只開 EGM 的 agents/、docs/、resources/、skills/ 四個目錄。

3.16 AI Agent 安裝比較表

AI Agent安裝方式指令或操作啟動方式支援限制
Claude Code(≥ 2.1.271)Marketplaceclaude plugin marketplace add google/elephant-goldfish-model、claude plugin install egm@egm新 session,/egm:egm-*headless 需讀取權限(3.15.1)
Codex CLIMarketplacecodex plugin marketplace add google/elephant-goldfish-model、codex plugin add egm@egm新 session,skill picker沒有具名 persona;AGENTS.md 會注入 reviewer(#237)
Antigravity CLIURL 安裝agy plugin install https://github.com/google/elephant-goldfish-model/egm:egm-*(保留前綴)AGENTS.md、GEMINI.md 會注入(#237)
Antigravity App/for IDEs/plugin 或手動複製~/.gemini/config/plugins/egm/重新載入視窗指令格式未驗證
Antigravity IDE(獨立版)———不支援(無 invoke_subagent)
ChatGPT/Codex desktop官方 Plugin 頁面desktop app 內安裝Try in chat(本機 thread)desktop-only listing
ChatGPT Work(Workspace)Admin import路徑 .agents/plugins@egm雲端驗證缺口(#106)
Claude Coworkclaude.ai/pluginsmarketplace google/elephant-goldfish-model指令格式未記錄子代理不能再啟動子代理(由主 Context 直接派工);雲端驗證缺口(#105)
GitHub Copilot CLI--plugin-dircopilot --plugin-dir "$EGM_ROOT" --add-dir "$EGM_ROOT" --agent egm:egm第一則訊息指定 package root 與 skill實驗性;持久安裝未驗證
Gemini CLI———沒有 adapter

3.17 本章 AI 產出審查

請 AI 寫「EGM 安裝 SOP」時:

檢查點好例壞例怎麼抓
Codex 指令動詞codex plugin add egm@egmcodex plugin install egm@egm對照 README Codex CLI 段落
Codex 呼叫方式skill picker/egm:egm-review讀 docs/codex.md
Antigravity App 指令「尚未驗證」寫成 /egm:egm-review 並宣稱可用讀 harnesses 的 App 段落
版本需求Claude Code ≥ 2.1.271沒寫版本讀 docs/claude.md 第一段
只裝 skills明確禁止「把 skills 資料夾複製到 ~/.claude/skills」搜尋「Skill-only installers」

可重跑的檢查指令(Shell,對 AI 產出的 SOP 檔):

# 找出把 Claude Code 動詞用在 Codex、或把 /egm: 前綴用在 Codex 的句子
grep -nE 'codex plugin install|codex.*/egm:' install-sop.md

第 4 章:EGM 設定與客製化

先講結論:EGM v0.1.1 沒有設定檔。沒有 egm.yaml、沒有環境變數、沒有 CLI 旗標。所有「設定」都透過四種方式完成:

  1. 一行文字指令(例如 EGM artifact directory: …)。
  2. 呼叫 Skill 時傳入的參數(TargetFile、GoldfishContext、Reviewers、Standards…)。
  3. 專案內的檔案慣例(docs/designs/、SITEMAP.md、.egmignore、Project Elephant Skill)。
  4. Fork 並修改 persona/standard(官方不建議日常這樣做,見 4.4)。

本章每個範例都標示「官方原始設定」「建議客製化設定」或「範例設定」。

4.1 EGM 預設設定

官方預設行為(官方,各 SKILL.md):

項目預設值可否變更方式
產出物目錄工作目錄(或 Host 的 artifact 目錄)可EGM artifact directory: <path>
設計文件目錄探測 docs/designs/,預設 docs/designs/可egm-draft Step 6 的選單
Bootstrap 產出檔名README.md可target_filename(例如 EGM.md)
Bootstrap 安全門檻目錄數 > 15 時要求確認否—
Bootstrap 直接執行門檻目錄數 ≤ 5 在主執行緒處理否—
Review 執行模式詢問 4 種 preset可呼叫時帶 Step(interactive、uninterrupted、feature_spec、implementation 或 5~9)
Review 每 stage 最多重審1 次否—
Review loop 上限5 輪可在上限時選擇繼續互動選單
Review loop 收斂條件連續 2 輪 clean否—
Synthesizer 重複審查可選擇每個 reviewer 啟動 A/B 兩個實例由 synthesizer 判斷—
Reviewer 失敗重試1 次,之後記為 not run否—

實務注意:「否」代表要改就得 fork。企業的第一原則是「不 fork,用外加方式客製」,才能持續跟上官方版本(第 11.13 節)。

4.2 Plugin 設定

唯一官方的 Plugin 層設定是啟用/停用與安裝範圍(Host 功能,非 EGM 功能):

# Shell(Claude Code)
claude plugin list
claude plugin disable egm@egm
claude plugin enable egm@egm

建議客製化設定:在專案 .claude/settings.json 宣告團隊共用的 marketplace 與啟用的 plugin,讓每位成員開專案時一致(格式已對照 Claude Code 官方 settings reference 的 extraKnownMarketplaces 範例;自動安裝行為未在登入 session 實測,🧪):

{
  "extraKnownMarketplaces": {
    "egm": {
      "source": { "source": "github", "repo": "google/elephant-goldfish-model" }
    }
  },
  "enabledPlugins": {
    "egm@egm": true
  }
}

官方 settings reference 寫明:專案 .claude/settings.json 中的 extraKnownMarketplaces 只有在使用者接受該資料夾的信任對話框之後才會生效,未信任的資料夾(包括在該處執行 -p)會「ignores them without a message」。這和本手冊實測 permissions.allow 的行為一致(3.15.1)。

實務注意:版本鎖定(只用 0.1.1)在 Marketplace 機制下不容易做到;需要嚴格版控的團隊,建議改用公司內部鏡像 repo,並只在鏡像上推進 tag(第 11.2 節)。

4.3 Skills 設定

Skill 沒有設定項,但有輸入參數。官方參數總表:

Skill參數必填說明
egm-brainstorm想法描述是沒給會被要求描述
egm-draftContext File否省略時依序找 concepts_brief.md → discussion_summary.md → 對話詢問
egm-reviewTargetFile是設計文件路徑
GoldfishContext否閱讀清單;空清單也算有提供
Step否preset 或 stage 編號
egm-review-loopTargetFile、SemanticTarget、Reviewers、Standards、GoldfishContext是(缺的會逐一詢問)SemanticTarget 可為 full file
egm-resolveTargetFile、LineRange、FindingsList自動模式由呼叫端提供;手動模式逐一詢問—
egm-bootstrappath是target_filename 選填
egm-drift-report文件目錄是沒給會被詢問

呼叫時參數是自然語言,由 Agent 解讀(範例設定,Claude Code 對話框):

/egm:egm-review docs/designs/customer-contact.md uninterrupted
/egm:egm-review docs/designs/customer-contact.md
GoldfishContext: [docs/adr/0007-hexagonal.md, customer-domain/README.md]
Step: feature_spec

實務注意:Step 等參數沒有正式的旗標語法,是寫在訊息中讓 Agent 解讀(尚待驗證:官方沒有定義精確格式)。若 Agent 仍跳出 preset 選單,直接在選單中選擇即可。

4.4 Agent Persona 設定

官方 persona 不提供設定項。三種客製方式比較:

方式隔離保證維護成本建議
A. 官方 persona + 公司 standard保有官方 adapter 的唯讀工具與 omitClaudeMd低首選
B. 公司自建 persona(以路徑傳給 egm-review-loop)視 Host 而定;Claude Code 需另建 adapter 才有唯讀與排除 CLAUDE.md中需要全新審查視角時
C. Fork EGM 修改官方 persona與官方相同高(每次升版都要合併)不建議

方式 B 的關鍵事實:egm-review-loop 規定「If the name contains a slash (/), treat it as an absolute or workspace-relative path and read it directly」(官方)。也就是 Reviewers 可以填 docs/egm/personas/security_reviewer.md。但這個 reviewer 在 Claude Code 會以 general-purpose subagent 讀 persona 檔執行——它沒有官方 adapter 的 tools: [Read, Grep, Glob] 與 omitClaudeMd: true。因此要自己補 adapter(4.13)。

實務注意:先想清楚「我要的是新視角,還是新標準」。九成的企業需求(OWASP、DDD、公司 coding standard)都是新標準,用方式 A 即可。

4.5 Review Rules 設定

EGM 的「審查規則」分散在三處:

規則位置例子
執行規則resources/execution_instructions.mdDesign-Only Scope、One Question At A Time、Contradiction Auditing
互動規則各 SKILL.md 的 Execution ConstraintsNo Glazing、Critique First、Banned Adjectives、一次只問一題
評分標準resources/document_standards/*.mdZero-Decision Rule、Alternatives Rule

官方 standard 的固定格式(範例取自 implementation-readiness-standard.md):

# Implementation Readiness Standard

This standard defines the quality bar for implementation plans and task lists.

## Core Principle

A plan passes if a competent engineer (or fresh AI session) who is unfamiliar
with the codebase can execute the plan and produce the correct changes on the
first attempt, without guessing, asking clarifying questions, or making
independent design choices.

## The Zero-Decision Rule
...
## Phasing & Checkpoints
...
## Requirements (Non-Exhaustive Examples)
...

自訂 standard 時沿用相同結構:Core Principle(一句可判斷的通過條件)→ 一條強制規則 → 非窮舉的需求清單。

實務注意:Core Principle 一定要寫成「一位陌生的工程師(或全新 AI session)能否……」的可判斷句型。寫成「設計要安全」這種句子,reviewer 無法判斷通過與否。

4.6 Design Document Template

官方模板:skills/egm-draft/references/design_doc.md。H2 章節依序為:

章節用途審查時屬於
標頭(Author、Status、Date)Status:Draft/Proposed/In Review/Approved—
## Overview高階摘要FeatureRange
## The Problem問題與解法摘要FeatureRange
## Goals / ## Non-Goals可量測目標;明確排除FeatureRange
## Open Questions跨 session 保留未解問題FeatureRange
## Critical User Journeys (CUJs)Given/When/ThenFeatureRange
## Technical Plan (Architecture)架構、資料流、圖FeatureRange
## Alternatives Considered每個替代方案的優缺點與否決理由FeatureRange
## Non-Functional Requirements只寫關鍵風險:安全、效能、上線與回滾FeatureRange
### Additional Resources、### Future Improvements選填FeatureRange
## Detailed Implementation Plan每個要改的檔案+Verification PlanDetailedRange

egm-review 以 ## Detailed Implementation Plan(或 ## Implementation Plan、## Work Breakdown、## Implementation Steps)作為切分點,上方是 FeatureRange、下方是 DetailedRange(官方,Step 3)。

中文文件的重要規則(建議):內文可以用中文,但 H2 標題保留官方英文名稱。原因:

  1. egm-review 用標題文字找切分點;寫成「## 詳細實作計畫」可能落入「Ambiguous Boundary」流程。
  2. egm-structural reviewer 會比對模板結構。
  3. 本手冊的 egm_design_lint.py 依英文標題檢查。

可以寫成「## Detailed Implementation Plan」,下一行再加中文說明。

實務注意:模板最後的 *Drafted with EGM* 是出處標記(Provenance),建議保留,方便日後稽核哪些文件由 AI 起草。

4.7 Feature Specification Standard

官方 feature-spec-standard.md 重點:

  • Core Principle:陌生工程師能理解功能、商業動機與設計取捨,並確認主要風險與替代方案都已處理。
  • The Alternatives Rule:只提出一條路、沒有證明考慮過其他方案,就不通過。否決理由要具體,不能把否決歸給 maintainer 而不附 issue/PR 連結。
  • Risks & Limits:要寫失效模式、安全影響、擴展上限與緩解。
  • 需求範例:Problem Statement、Goals & Non-Goals、Proposed Architecture、Alternatives Considered、Risks & Mitigations。

在 Stage 7 由 egm-design 與 egm-structural 套用(egm-style 不套用 standard)。

實務注意:企業最常被這份標準打回的是「Alternatives Considered 只寫『無』」。先準備至少一個被否決的方案,並寫「Rejected by author: <技術理由>」。

4.8 Implementation Readiness Standard

重點(官方):

  • Zero-Decision Rule:計畫不得留下任何設計或架構選擇給實作者。例如選資料表結構、設計 API 路徑、選相依套件、決定新邊界條件怎麼處理——只要實作者需要決定,就不通過。
  • Phasing & Checkpoints:每個階段完成後程式碼都要能 build、能測。
  • Target Scope & File Boundary:列出每一個要新增、修改、刪除的檔案(repo 相對路徑),可作為 Phase 5 寫入白名單;只有產生的檔案才可以用目錄 glob。
  • Test Plan:具體測試案例,包含正常路徑與邊界案例。

在 Stage 9 由 egm-implementation-readiness 與 egm-codebase-details 套用。

實務注意:這份標準是本手冊 egm_scope_guard.py 的依據——既然官方要求計畫列出完整檔案清單,CI 就可以拿它來擋越界修改。

4.9 Zoom-out Review Standard

zoom-out-standard.md 有五個檢查面向(官方):

編號面向不通過的典型
0Context Sufficiency看不出要達成什麼、為什麼 → 立即不通過
1Root Problem Focus只修症狀;與專案 README/context.md 的方向不一致
2Simplicity & ExtensibilityYAGNI、過早最佳化(快取、分片、非同步佇列)、資料流經過太多元件
3Anti-Weeds(高度控制)高階章節出現 helper function、迴圈變數等程式細節;放錯層
4Leverage Existing沒有重用既有元件;未遵循既有模式;出現已知反模式

Stage 5 審全文;Stage 8 再審一次,專門看 Comprehension 與 Critic 階段新增的內容(修 bug 時最容易把設計越改越複雜)。

實務注意:Zoom Out reviewer 會「用 code search 找可重用元件」,所以它需要讀得到專案原始碼。若設計文件放在與程式碼不同的 repo,Zoom Out 會失去重要能力。

4.10 專案專屬 Elephant Context

官方建議(docs/getting_started.md)建立一個 <project>-elephant Skill:「This skill does not need to be complicated. It should tell the LLM about your project, and give it links to the context you think is most relevant. That’s all.」

官方建議的目錄是 _agents/skills/<project>_elephant/SKILL.md。但 Skill 實際會從哪裡載入,取決於 Host:Claude Code 的專案 Skill 目錄是 .claude/skills/。以下範例放在 Claude Code 會載入的位置。

📄 project/.claude/skills/crm-elephant/SKILL.md(範例設定)

---
name: crm-elephant
description: Loads ACME CRM project context (architecture, design index, conventions) before EGM design work. Use when designing or reviewing CRM features.
---

# ACME CRM Elephant Context

Read these files before answering design questions. Do not load the source tree.

1. `docs/designs/SITEMAP.md` - index of approved designs (read the rows that match the feature).
2. `README.md` - module map produced by `egm-bootstrap`, reviewed by the architect.
3. `docs/adr/` - architecture decisions; ADR status `Accepted` overrides older designs.
4. `docs/standards/` - company review standards used with `egm-review-loop`.

Fixed facts (owner: CRM architect):

- Backend: Java 21, Spring Boot 4.0.x, modules `customer-api`, `customer-app`,
  `customer-domain`, `customer-infra`. Dependency direction api -> app -> domain.
- Database: PostgreSQL 17 (new modules), Oracle 19c (legacy loan schema, read-only).
- PII fields are listed in `docs/standards/pii-fields.md`; never copy sample PII into prompts.

If a question conflicts with an approved design or ADR, say so and ask; do not
silently pick one.

使用方式(Claude Code 對話框):

/crm-elephant
/egm:egm-brainstorm 客戶聯絡人需要支援「主要聯絡人」與個資遮罩

實務注意:Elephant Skill 只放「指向檔案的路徑」與「穩定事實」,不要把整份架構文件貼進 SKILL.md;文件會變,SKILL.md 很容易忘了更新。

4.11 建立企業共用 Project Context

企業有三層 Context,各自放在不同位置(建議客製化設定):

層次內容位置Goldfish 看得到嗎
公司層公司 coding standard、資安政策、審查標準公司共用 repo,以 git submodule 或複製方式放到 docs/standards/只有被列入 GoldfishContext 或作為 standard 傳入時
專案層架構、模組地圖、ADR、SITEMAP專案 repo docs/、README.md文件中有相對連結時自動加入
工作慣例artifact 目錄、禁止事項CLAUDE.md/AGENTS.mdClaude Code adapter 排除;Codex/Antigravity 可能注入

專案 CLAUDE.md 範例(範例設定):

📄 project/CLAUDE.md

# ACME CRM - agent instructions

EGM artifact directory: .dev/docs

- Approved designs live in `docs/designs/`; drafts and review reports go to `.dev/docs/` (git-ignored).
- During `/egm:egm-brainstorm`, `/egm:egm-draft`, `/egm:egm-review` do not edit production code.
- Implementation must stay inside the design's "Target Files to Create/Modify" list;
  CI runs `tools/egm_scope_guard.py`.
- Never paste customer data, credentials, or production logs into prompts.

實務注意:公司層的審查標準若放在另一個 repo,Goldfish 讀不到;必須在專案 repo 內有一份副本(或 submodule 已 checkout),並用工作目錄內的路徑傳給 reviewer。

4.12 多專案、多團隊設定

情境建議做法
多個 repo 共用審查標準公司 egm-standards repo,各專案以 submodule 放在 docs/standards/,鎖定 tag
Monorepo 多個團隊每個子系統有自己的 docs/designs/ 與 SITEMAP.md;egm-draft Step 6 會探測 <project>/docs/designs/
不同團隊用不同 Host設計文件格式相同即可互通;CLAUDE.md 與 AGENTS.md 內容保持一致
外包廠商外包使用公司鏡像版 EGM,審查報告隨 PR 提交(第 10.16 節)

SITEMAP.md 範例(官方欄位:Link、Date、Author、Components、Description;範例設定):

📄 project/docs/designs/SITEMAP.md

# Design Sitemap

| Link | Date | Author | Components | Description |
| --- | --- | --- | --- | --- |
| [customer-contact](./customer-contact.md) | 2026-11-17 | chihhung | customer-domain, customer-infra | 客戶聯絡人與主要聯絡人 |

實務注意:egm-draft 與 egm-brainstorm 只在 SITEMAP.md 已存在時才登錄;新專案要先手動建立一份空表。

4.13 如何新增自訂 Agent Reviewer

以「資安 reviewer」為例,分兩個檔案(建議客製化設定)。

步驟 1:寫共用 persona,格式仿照官方 persona(Core Mandates → Role → Instructions → Output Format)。

📄 project/docs/egm/personas/security_reviewer.md

---
name: acme-security-reviewer
description: Read-only security reviewer for ACME Bank designs (OWASP Top 10 2025, data classification, audit).
---

# Core Mandates (Universal Goldfish Context)

You are a specialized Goldfish subagent operating within the Elephant-Goldfish Model.

1. **Strict Read-Only Protocol**: You have NO tools to modify the workspace. Do not fix anything.
2. **Stateless Mindset (Goldfish Isolation)**: You have no conversation history. Read the document as a security reviewer who has never seen the project.
3. **No Chitchat**: Report only findings and rationale.

# Role

You are **ACME Security Goldfish**, a bank application security reviewer. You assume every
undocumented control is missing.

# Instructions

### IF Mode: REVIEW (Document Audit)

1. Read the target scope and the Target Standard (`docs/standards/enterprise-security-standard.md` unless the caller names another).
2. For each new or changed endpoint, data field, dependency, and integration, find the control the document states. If none is stated, report it.
3. Flag any claim such as "secure", "encrypted", or "compliant" that does not name the mechanism, key owner, or verification step.

# Output Format

For each finding:
1. **Severity**: [Blocker | Major | Nit] (Blocker = Restricted data or authorization without a stated control)
2. **Affected Scope**: section heading or line numbers
3. **OWASP / Rule**: e.g. A01 Broken Access Control, Data Classification Rule
4. **Rationale**: what is missing and what the document must state

步驟 2:在 Claude Code 補一個專案層 adapter,取得唯讀工具與排除 CLAUDE.md:

📄 project/.claude/agents/acme-security-reviewer.md

---
name: acme-security-reviewer
description: ACME Bank read-only security Goldfish reviewer. Use only when an EGM review names it.
tools: Read, Grep, Glob
model: inherit
omitClaudeMd: true
---

Read `docs/egm/personas/security_reviewer.md` before reviewing and follow it.
Remain read-only. Use only the task, the target document, the named standard,
and the explicitly supplied review context. If a required file cannot be read,
report an incomplete review instead of a verdict.

步驟 3:檢查隔離欄位。實測發現 claude plugin validate 對專案 .claude/ 目錄回報「Validation passed」時,--json 輸出的 contents 是空陣列——它根本沒有檢查 agent 檔。把 agent 包進一個最小 plugin 後雖然會檢查,但只對「缺 description」給警告,omitClaudeMd: maybe 這種錯誤值不會報錯。所以隔離欄位要自己檢查(Shell):

# 印出沒有唯讀工具或沒有 omitClaudeMd 的 agent;沒有輸出代表全部符合
for f in .claude/agents/*.md; do
  grep -qx 'omitClaudeMd: true' "$f" && grep -qxE 'tools: \[?Read, Grep, Glob\]?' "$f" || echo "NOT ISOLATED: $f"
done

實測:好例不輸出;omitClaudeMd: maybe 與 tools 多了 Bash 的兩個壞例都被列出。

步驟 4:使用(Claude Code 對話框):

/egm:egm-review-loop
TargetFile: docs/designs/customer-contact.md
SemanticTarget: full file
Reviewers: [design_critic, docs/egm/personas/security_reviewer.md]
Standards: {"design_critic": "feature-spec-standard", "docs/egm/personas/security_reviewer.md": "docs/standards/enterprise-security-standard.md"}
GoldfishContext: []

Agent 會以路徑讀取 persona。是否會改用你建的 acme-security-reviewer 具名 agent,取決於 Agent 對任務的解讀(🧪)。最保險的做法是在訊息中明確寫「請用 acme-security-reviewer subagent 執行此 reviewer」。

步驟 5:確認實際用到的是有隔離的 adapter(🧪,需在登入的 session 執行):

  1. 新 session 執行 /agents,確認清單中有 acme-security-reviewer。
  2. 在父對話中寫下一個唯一標記(例如 PARENT-MARKER-7f3a),然後要求:「請用 acme-security-reviewer subagent 回答:你是否知道 PARENT-MARKER-7f3a?你可用的工具有哪些?」
  3. 通過條件:子代理回答不知道標記(UNKNOWN),且工具只有 Read、Grep、Glob。不符合時,這個 reviewer 的結果不得當成 Goldfish 審查。

實務注意:自訂 reviewer 一律用 acme- 之類的公司前綴,避免與官方 egm-* 名稱衝突。

4.14 如何新增企業內部設計規範

設計規範=standard 檔。建議放在專案的 docs/standards/,以 egm-review-loop 的路徑功能使用。本手冊 Lab 中標示為 📄 standards/… 的檔案,在專案中一律放到 docs/standards/…(附錄 B.5 有複製指令);正文所有呼叫都使用 docs/standards/ 路徑。

📄 standards/clean-architecture-standard.md(範例設定)

# Clean Architecture & DDD Standard (ACME Bank)

Company standard for `egm-review-loop`. Not part of EGM.

## Core Principle

A design passes if a fresh reader can place every new class in exactly one
layer, and every dependency in the design points inward:
adapter -> application -> domain.

## The Dependency Rule

The design fails if domain code depends on a framework (Spring, JPA, Jackson),
an adapter, or infrastructure. Ports (interfaces) live in the domain or the
application layer; implementations live in adapters.

## Requirements (Non-Exhaustive Examples)

*   **Aggregates**: Name the aggregate root and the invariants it protects.
*   **Transactions**: One aggregate per transaction unless the design explains
    why not.
*   **DTO Boundary**: REST DTOs never leak into the domain.
*   **Architecture Test**: The Verification Plan names an ArchUnit test that
    enforces the dependency rule.

實務注意:standard 必須用英文寫嗎?不必,但官方 persona 是英文、會「cross-reference it with the Target Standard」;中英混寫時,規則名稱(例如「The Dependency Rule」)建議保留英文,方便 reviewer 在 finding 中引用。

4.15 如何新增 Coding Standards

EGM 審查的是文件,不是程式碼。Coding Standard 有兩個用法:

用法工具時機
讓設計文件寫明要遵守的規範在設計模板「Verification Plan」列出 lint/format 指令Draft
在 Review 時檢查計畫是否引用正確規範自訂 standard 加一條「Verification Plan 必須包含 Checkstyle/ESLint 指令」Stage 9 或 review loop
檢查程式碼本身Checkstyle、SpotBugs、ESLint、SonarQubePhase 5 之後的 CI

實務注意:不要把整份 Coding Standard(幾百條規則)塞給 reviewer,那會讓審查失焦;把「這次設計最可能違反的 5 條」寫進 standard 即可。

4.16 如何將 Clean Architecture、DDD、OWASP 等標準納入審查

組合方式(建議):

審查目的ReviewersStandards
架構分層design_critic、zoom_outdocs/standards/clean-architecture-standard.md、zoom-out-standard
資安design_critic 或自訂 security_reviewerdocs/standards/enterprise-security-standard.md
逆向工程文件codebase_details、comprehensionre-implementation-standard、docs/standards/reverse-engineering-evidence-standard.md
升級計畫implementation_readiness、codebase_detailsimplementation-readiness-standard、docs/standards/migration-readiness-standard.md

📄 standards/enterprise-security-standard.md(範例設定)

# Enterprise Security Standard (ACME Bank)

This standard defines the security bar for feature specifications and
implementation plans before implementation begins. It is a company standard
used with `egm-review-loop`; it is not part of EGM.

## Core Principle

A design passes if a security reviewer who has never seen the project can find,
in the document alone, how every OWASP Top 10 (2025) risk that applies to the
change is handled, and which control owner verifies it.

## The Data Classification Rule

Every new or changed data field must be classified as Public, Internal,
Confidential, or Restricted (PII, credentials, account numbers). A design fails
if a Restricted field has no stated storage protection (encryption, masking,
tokenization), no access control, and no retention period.

## Requirements (Non-Exhaustive Examples)

*   **Authentication & Authorization**: Named roles or permissions for each new
    endpoint; deny by default (OWASP A01).
*   **Injection**: Parameterized queries for all SQL, including stored
    procedure calls; no string-built SQL (OWASP A05).
*   **Secrets**: No secrets in source, config files, or logs; secret source named
    (Vault, KMS).
*   **Logging & Audit**: Which events are written to the audit trail, and which
    fields are masked in logs.
*   **Supply Chain**: Every new dependency names its version and license and
    passes SCA (OWASP A03).
*   **Error Handling**: Error responses do not expose stack traces or internal
    identifiers (OWASP A10).

實務注意:OWASP Top 10 的編號會隨版本改變(2025 版的 A03 是 Software Supply Chain Failures、A10 是 Mishandling of Exceptional Conditions)。standard 要寫明版本,否則 reviewer 可能用舊版編號。

4.17 如何客製化企業設計文件格式

原則:在官方模板之後追加章節,不刪、不改名官方章節(建議)。

## Non-Functional Requirements
(官方章節,保留)

## Security & Compliance
<!-- 公司追加:資料分類、OWASP 對應、稽核事件、個資遮罩 -->

## Operations & Rollback
<!-- 公司追加:監控指標、告警、回滾指令、資料相容性 -->

## Detailed Implementation Plan
(官方章節,保留在最後,作為 FeatureRange/DetailedRange 切分點)

公司追加章節要放在 ## Detailed Implementation Plan 之前,否則會被歸入 DetailedRange,Stage 7 的 Critic 看不到。

用 egm_design_lint.py 檢查官方章節與公司追加章節(Shell):

python tools/egm_design_lint.py docs/designs/customer-contact.md --require "Security & Compliance"

📄 tools/egm_design_lint.py(建議,公司自建工具)

#!/usr/bin/env python3
"""egm_design_lint.py - mechanical pre-check before /egm:egm-review.

It does not replace Goldfish review. It catches cheap problems so reviewers
spend their budget on design questions. Section names follow EGM's template
skills/egm-draft/references/design_doc.md (v0.1.1).

Rules:
  D1 every template H2 section exists (Open Questions is a warning only)
  D2 "Alternatives Considered" has at least one "### Alternative" entry
  D3 no placeholders (TBD, TODO, 待查, 待確認, 尚待驗證, 待補) anywhere outside
     code fences and outside "## Open Questions" (undecided items belong there)
  D4 "Rejected by maintainer" must carry a URL (template rule)
  D5 Status is one of Draft | Proposed | In Review | Approved
  D6 --require "Heading" adds company sections (e.g. "Security & Compliance")

Usage: python egm_design_lint.py DESIGN.md [--require "Security & Compliance" ...]
Exit 0 = pass (warnings allowed), 1 = fail.
"""
import argparse
import re
import sys
from pathlib import Path

TEMPLATE_H2 = [
    "Overview", "The Problem", "Goals", "Non-Goals", "Open Questions",
    "Critical User Journeys (CUJs)", "Technical Plan (Architecture)",
    "Alternatives Considered", "Non-Functional Requirements",
    "Detailed Implementation Plan",
]
WARN_ONLY = {"Open Questions"}
PLACEHOLDER = re.compile(r"\bTBD\b|\bTODO\b|\[File Path|\bGoal 1\b|\[Describe|\?\?\?"
                         r"|待查|待確認|尚待驗證|待補", re.I)
STATUS = re.compile(r"\*\*Status:\*\*\s*(.+)")


def h2_titles(lines):
    out, fence = [], False
    for ln in lines:
        if ln.lstrip().startswith("```"):
            fence = not fence
            continue
        if not fence and ln.startswith("## "):
            out.append(ln[3:].strip())
    return out


def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("design")
    ap.add_argument("--require", action="append", default=[])
    args = ap.parse_args(argv)
    lines = Path(args.design).read_text(encoding="utf-8").splitlines()
    heads = h2_titles(lines)
    fails, warns = [], []

    for sec in TEMPLATE_H2 + args.require:
        if not any(h == sec or h.startswith(sec + " ") for h in heads):
            (warns if sec in WARN_ONLY else fails).append(f"D1/D6 missing section: ## {sec}")

    text = "\n".join(lines)
    alt = re.search(r"^## Alternatives Considered(.*?)(?=^## |\Z)", text, re.M | re.S)
    if alt and not re.search(r"^### Alternative", alt.group(1), re.M):
        fails.append("D2 no '### Alternative' entry under Alternatives Considered")

    fence = False
    section = ""
    for i, ln in enumerate(lines):
        if ln.lstrip().startswith("```"):
            fence = not fence
            continue
        if fence:
            continue
        if ln.startswith("## "):
            section = ln[3:].strip()
        if section.startswith("Open Questions"):
            continue
        if PLACEHOLDER.search(ln) and not ln.lstrip().startswith("<!--"):
            fails.append(f"D3 placeholder at line {i + 1} ({section or 'header'}): {ln.strip()[:60]}")

    for i, ln in enumerate(lines, 1):
        if re.search(r"Rejected by maintainer", ln, re.I) and "http" not in ln:
            fails.append(f"D4 maintainer rejection without link at line {i}")

    st = next((STATUS.search(ln) for ln in lines[:15] if STATUS.search(ln)), None)
    if not st:
        fails.append("D5 no **Status:** line in header")
    elif st.group(1).strip() not in ("Draft", "Proposed", "In Review", "Approved"):
        fails.append(f"D5 unknown status: {st.group(1).strip()}")

    for w in warns:
        print(f"WARN {w}")
    for f in fails:
        print(f"FAIL {f}")
    print("LINT PASS" if not fails else f"LINT FAIL ({len(fails)})")
    return 1 if fails else 0


if __name__ == "__main__":
    sys.exit(main())

實測:好例 LINT PASS;壞例抓到缺 ## The Problem、## Non-Goals、沒有 Alternative、TBD、「Rejected by maintainer」無連結、Status 為 WIP 等 6 類問題;把 D4 規則弄壞後測試會失敗(突變測試)。

本章注意事項:

  • 客製化的優先順序:standard 檔 > 專案 Elephant Skill > 自訂 persona > fork。
  • 所有公司自建檔案都要寫明「not part of EGM」,避免日後被誤認為官方內容。

4.18 本章 AI 產出審查

檢查點好例壞例怎麼抓
設定檔「EGM 沒有設定檔」產生 egm.config.yaml 並宣稱 EGM 會讀在 repo 搜尋該檔名
自訂 reviewer 的隔離補 adapter 並檢查 omitClaudeMd只寫 persona 就宣稱「已隔離」執行 4.13 步驟 3 的檢查
公司章節位置在 ## Detailed Implementation Plan 之前加在文件最後grep -n '^## ' design.md 看順序
standard 的通過條件「陌生工程師能否……」「設計須符合最佳實務」讀 Core Principle 是否可判斷

第 5 章:EGM 標準開發流程

完整流程總覽(本章各節依序說明):

flowchart TD
    Start(["新需求或變更"]) --> Q{"錯了會不會很貴?"}
    Q -->|"否:小修正"| Direct["直接實作+一般 Code Review"]
    Q -->|"是"| HasDoc{"已有設計文件或 PR 計畫?"}
    HasDoc -->|"有"| RV
    HasDoc -->|"沒有"| HasCtx{"既有系統有文件嗎?"}
    HasCtx -->|"沒有"| BT["5.8 Bootstrap"]
    BT --> BS
    HasCtx -->|"有"| BS["5.1 Brainstorm"]
    BS --> DR["5.2 Draft"]
    DR --> RV["5.3 Goldfish Review<br/>Stage 5 到 9"]
    RV --> RS["5.4 Resolve"]
    RS -->|"重大修改"| RV
    RS --> HR["5.5 Human Review<br/>設計 PR"]
    HR -->|"退回"| DR
    HR -->|"核准"| IM["5.6 Implementation"]
    IM --> TEST["測試+Code Review+安全掃描"]
    TEST --> Release(["上線"])
    Release --> DF["5.7 Drift Report<br/>每週"]
    DF -->|"有漂移"| Fix{"改文件或改程式?<br/>由人決定"}
    Fix --> DR
    Fix --> IM

所有指令以「Claude Code/agy CLI 對話框」的 /egm: 格式示範。Codex 使用者請改用 skill picker 選擇同名 Skill,並在同一則訊息以文字寫出參數(例如設計文件路徑、Step: feature_spec);Skill 會用一般文字詢問缺少的參數(🧪)。

用哪個 session(本公司規定):Brainstorm、Draft、Review、Resolve 都在同一個設計 session(Elephant)中進行。Goldfish 的獨立性來自 Review 自動建立的全新 Subagent,不需要另開 session;而 Resolve 需要 Elephant 記得設計理由。只有實作使用新 session(5.6)。設計 session 已關閉時,新 session 先執行專案 Elephant Skill(4.10),再讀 brief 與設計文件,然後才 Review 或 Resolve。

5.1 Brainstorm:大象腦力激盪

目的:把半成熟的想法變成經過挑戰的假設,產出 concepts_brief.md。

5.1.1 如何啟動

/egm:egm-brainstorm 客戶管理系統要新增「客戶聯絡人」,業務希望能標示主要聯絡人,並遮罩個資

啟動前建議先載入專案 Elephant Skill(4.10),讓 Elephant 知道架構與既有設計。

5.1.2 流程(官方,skills/egm-brainstorm/SKILL.md)

sequenceDiagram
    autonumber
    actor U as 工程師
    participant E as Elephant(主 Context)
    participant Sy as egm-synthesizer
    participant G as 7 個 Goldfish 視角
    participant F as concepts_brief.md
    U->>E: /egm:egm-brainstorm 想法
    E->>E: 取得 Author(git config user.name)
    loop 多輪開放式提問(不得給選項)
        E->>U: 一次一個問題
        U->>E: 回答
    end
    E->>U: 2 到 3 句的工作假設+單選關卡
    U->>E: 選擇 Review with Goldfishes
    E->>Sy: Mode BRAINSTORM,7 個 reviewer
    par 平行
        Sy->>G: 每個視角一個全新 Context
    end
    G-->>Sy: 風險與挑戰
    Sy->>F: 去重後寫入 brief
    Sy-->>E: 完成與路徑
    E->>U: 提示 2 到 3 個主要反對意見
    U->>E: 調整方向或確認
    E->>U: 交接關卡(發布 RFC/進入 Draft/繼續/結束)

7 個 Brainstorm 視角(官方表格):

視角由哪個 persona 扮演質疑的問題
Contrarian/YAGNIegm-zoom-out為什麼需要這個功能?現成套件能不能解決 90%?
Cost, Quota & Token Economicsegm-design尖峰 QPS、記憶體、DB 負載、token 預算?
UX & Developer Ergonomicsegm-comprehensionAPI/CLI 直覺嗎?錯誤訊息能讓人採取行動嗎?
Migration & Backward Compatibilityegm-implementation-readiness既有資料怎麼遷移?回滾怎麼做?
Observability & SRE Debuggabilityegm-codebase-details凌晨 3 點值班的人怎麼排查?
Long-Term Tech Debt & Maintenanceegm-structural兩年後會不會變成維護負擔?
Inventive Catalystegm-inventive-catalyst這個設計把哪個取捨當成必然?能不能用已知模式消除?

5.1.3 如何提供專案背景、訪談需求、釐清邏輯

Elephant 會問這類開放式問題(官方列出的方向):

  • 這解決什麼具體問題、瓶頸或痛點?
  • 誰或哪個系統會使用?SLA、不變式是什麼?
  • 有哪些不可妥協的限制?
  • 邊界案例與範圍外是什麼?
  • 現在怎麼處理?為什麼不夠好?
  • 成功要怎麼衡量?

回答技巧(建議):

好的回答不好的回答
「每位客戶最多 50 位聯絡人,目前最多的客戶有 23 位」「應該不會很多」
「列表遮罩手機中間 4 碼;詳細頁明碼需 CONTACT_PII_READ」「要符合個資法」
「不做去重,另案;本案只保證同一 Email 在同客戶內唯一」「去重之後再看」
「成功=客服找聯絡人的平均時間從 3 分鐘降到 30 秒(客服系統量測)」「提升效率」

5.1.4 確認功能邊界、討論技術選型、分析替代方案

對話範例(節錄,Claude Code 對話框):

Elephant:目前描述把「主要聯絡人唯一」當成需求。若兩位業務同時把不同聯絡人設為主要,系統應以誰為準?
工程師:以後送出的為準,前一位自動取消主要。
Elephant:那「後送出」在資料庫層要怎麼判斷?如果靠應用程式先查後改,兩個交易可能同時看到「沒有主要聯絡人」。這是你要的行為,還是要直接拒絕第二個請求?
工程師:拒絕第二個,回 409,讓使用者重新整理。
Elephant:這和你一開始說的「以後送出為準」矛盾。請確認採用哪一個:自動取消前一位,或拒絕並回 409?
工程師:回 409。前面那句作廢。

注意 Elephant 的行為符合官方規則:一次只問一題、發現矛盾時不修改檔案、先指出矛盾並要求決定(execution_instructions.md 的 Contradiction Auditing)。

5.1.5 如何記錄設計決策

Brief 的固定結構(官方模板):

# [Feature Name]

* **Author:** [Author Name or GitHub Handle]
* **Date:** [YYYY-MM-DD]

## Overview
## Analysis
## Goals vs. Non-Goals
## Alternatives Weighed
## Key Decisions & Staging for Next Steps

其中 Alternatives Weighed 特別重要:官方註解寫明「/egm-draft copies these into Alternatives Considered and has no other source for them.」——Brainstorm 沒記下來的被否決方案,Draft 就不會知道。

5.1.6 多輪討論與交接

Brief 寫好後,Elephant 會提出 2~3 個主要反對意見並問你怎麼處理(轉向、縮小範圍、增加限制),可以重複 Goldfish 分析直到滿意。最後的交接選單(官方):

選項結果
Publish concepts_brief.md as RFC for team feedback寫到 docs/designs/<feature_name>.md,登錄 SITEMAP(若存在)
Proceed to egm-draft提示你執行 /egm:egm-draft,它會自動讀 brief
Continue refining回到迭代
Conclude and keep brief for later結束,brief 保留

5.1.7 如何避免直接開始寫程式

  • resources/execution_instructions.md:「You are strictly forbidden from writing, modifying, or building any production implementation files」;範例程式只能放在 Markdown 區塊或專案外的 scratch 目錄。
  • 若你在 Brainstorm 中要求「直接幫我寫」,Agent 應回答此流程只產生設計文件,並問你要繼續設計還是離開流程。

實務注意:這是「指示」不是「強制」。若 Agent 仍改了程式,用 git status 立即發現並還原;公司 CI 用 egm_scope_guard.py 擋下設計 PR 中的程式變更(10.9)。

5.2 Draft:設計文件草擬

目的:把 brief(或筆記)逐節轉成正式設計文件。

/egm:egm-draft

或指定輸入:

/egm:egm-draft docs/designs/customer-contact.md

這個用法適用於 Brainstorm 時選了「Publish as RFC」:RFC 已發布在 docs/designs/customer-contact.md,Draft 讀它作為輸入,草稿寫在 design_draft.md,最後 Step 6 儲存時選同一路徑,正式設計文件就會取代 RFC 版本。

5.2.1 流程(官方,skills/egm-draft/SKILL.md)

sequenceDiagram
    autonumber
    actor U as 工程師
    participant E as Elephant
    participant B as concepts_brief.md
    participant D as design_draft.md
    participant T as docs/designs/X.md
    U->>E: /egm:egm-draft
    E->>B: 依優先順序尋找輸入
    E->>U: 確認輸入正確並取得開始許可
    E->>D: Step 2 寫 Overview、Problem、Goals、Non-Goals
    E->>U: 摘要+路徑+核准關卡
    U->>E: 核准或要求修改
    E->>D: Step 3 寫 Technical Plan
    E->>U: 核准關卡
    Note over E,U: 遇到有多個合理答案的設計點,<br/>列出最多 3 個選項讓作者選,不排名、不預設
    E->>D: Step 4 從 brief 讀取並寫 Alternatives Considered
    E->>U: 核准關卡
    E->>D: Step 5 寫 Detailed Implementation(列出每個檔案)
    E->>U: 核准關卡
    E->>B: Step 6.1 重讀 brief 比對矛盾
    E->>U: 逐條列出矛盾並請你決定
    E->>U: 選擇儲存目錄
    E->>T: 寫入正式設計文件並登錄 SITEMAP
    E->>U: 建議執行 /egm:egm-review

5.2.2 Concept Brief、Design Draft、系統架構、資料庫、API

產物在 Draft 中的位置要求
Concept Brief輸入(Priority 1)Draft 不會自行補 brief
系統架構Step 3 Technical Plan寫成文字+ASCII 或 Mermaid 圖;說明新元件、修改檔案、API 變更
資料庫設計Step 3(概念)+Step 5(DDL 檔案)Draft 不寫實作程式,但可以寫 schema
API SpecificationStep 3(端點與語意)+Step 5(OpenAPI 檔案)「Pseudocode, APIs, or schemas are allowed」
實作計畫Step 5「List EVERY file that will be changed, created, or deleted」,每個檔案附理由
測試計畫Step 5 的 Verification PlanBuild、Unit、Lint、Coverage、E2E 指令

Author Decides Architecture(官方 Execution Constraint 13):遇到資料模型、元件邊界、儲存、協定等有多個合理答案的決定,Elephant 會列出最多三個選項(機制、取捨、失效條件),不排名、不預設。你說「你幫我選」時,它會重述取捨並再問一次。

5.2.3 如何確認設計文件完整性

Step 6.1 是 Draft 獨有的檢查:重讀 brief,與草稿比對。

  • Contradiction:brief 已決定的問題,草稿做了不同決定 → 全部列出,請你逐一裁決。
  • Addition:草稿決定了 brief 沒提到的問題 → 只有影響架構、外部介面或相依套件時才列出。

官方理由:「No Goldfish can do this check, because no Goldfish reads the brief.」

自我檢查清單(建議,進入 Review 前):

  • 每個 Goal 都可量測。
  • Non-Goals 至少一條。
  • 至少一個 CUJ 有 Given/When/Then。
  • Alternatives 至少一個,含否決理由。
  • Detailed Implementation Plan 列出每個檔案(含測試、設定、文件、migration)。
  • Verification Plan 的指令都能在本機執行。
  • python tools/egm_design_lint.py <檔案> 通過。

5.2.4 完整 Markdown 設計文件範本

以下是依官方模板撰寫的完整中文範例(範例設定;也是本手冊工具的測試 fixture):

📄 fixtures/design_good.md

# 客戶聯絡人管理(Customer Contact Management)

*   **Author:** chihhung
*   **Status:** In Review
*   **Date:** 2026-11-17

--------------------------------------------------------------------------------

## Overview

企業客戶管理系統(CRM)新增「客戶聯絡人」功能:業務人員可在客戶頁籤維護多位聯絡人,
並指定一位主要聯絡人(Primary Contact)。

## The Problem

目前聯絡人資料散落在 Excel 與 Email 簽名檔,客服無法判斷該聯絡誰;同一客戶常出現
重複聯絡人,個資遮罩規則也不一致。

## Goals

*   每位客戶可維護 0..50 位聯絡人,且最多一位 Primary Contact。
*   手機號碼與 Email 在列表頁一律遮罩,明碼僅在詳細頁且需 `CONTACT_PII_READ` 權限。
*   新增/修改/刪除聯絡人寫入稽核紀錄(Audit Trail)。

## Non-Goals

*   不做聯絡人去重(Dedup)批次作業,另案處理。
*   不串接外部 CRM(Salesforce)。

## Open Questions

*   **Question 1**: 刪除聯絡人是否需保留 7 年?(待法遵 2026-11-20 回覆)

## Critical User Journeys (CUJs)

### CUJ 1: 業務新增主要聯絡人

*   **Given**: 業務已登入且擁有 `CUSTOMER_EDIT` 權限,客戶 C001 尚無 Primary Contact。
*   **When**: 業務新增聯絡人並勾選「主要聯絡人」後送出。
*   **Then**: API 回 201,C001 恰有一位 Primary Contact,稽核表新增一筆 `CONTACT_CREATED`。

## Technical Plan (Architecture)

沿用既有 Hexagonal Architecture:`customer-api`(REST Adapter)→ `customer-app`
(Application Service)→ `customer-domain`(Aggregate:Customer 擁有 Contact)→
`customer-infra`(JPA Repository)。Primary Contact 唯一性由 Aggregate 維持,
資料庫以部分唯一索引(Partial Unique Index)二次保護。

## Alternatives Considered

### Alternative A: 聯絡人獨立成 Aggregate

*   **Pros**: 聯絡人可單獨鎖定,並行修改衝突較少。
*   **Cons**: 「每客戶最多一位 Primary」需跨 Aggregate 檢查,只能靠資料庫約束。
*   **Reason for Rejection**: Rejected by author: 唯一性規則屬於 Customer 不變式,拆開後只剩資料庫能保證。

## Non-Functional Requirements

*   Security & Privacy:PII 欄位以 AES-256-GCM 加密儲存,金鑰由 KMS 管理。
*   Performance:聯絡人列表 P95 < 300 ms(每客戶最多 50 筆,無分頁)。

## Security & Compliance

*   資料分類:`mobile`、`email` 為 Restricted;以 AES-256-GCM 加密儲存,金鑰由 KMS 管理。
*   權限:新增/修改需 `CUSTOMER_EDIT`;明碼讀取需 `CONTACT_PII_READ`(定義見 `docs/standards/iam-permissions.md`)。
*   OWASP 2025:A01 由端點權限註記與預設拒絕處理;A05 全部使用 JPA 參數化查詢。
*   稽核:`CONTACT_CREATED`、`CONTACT_UPDATED`、`CONTACT_DELETED` 經既有 `AuditPort` 寫入。

## Detailed Implementation Plan

### Target Files to Create/Modify

#### 1. `customer-domain/src/main/java/com/acme/crm/customer/domain/Contact.java` (Create)

*   **Type / Scope**: Domain Entity
*   **Proposed Changes**: 欄位 `id`、`name`、`mobile`、`email`、`primary`;建構子驗證 Email 格式。

#### 2. `customer-domain/src/main/java/com/acme/crm/customer/domain/Customer.java` (Modify)

*   **Type / Scope**: Aggregate Root
*   **Proposed Changes**: 新增 `addContact(Contact)`、`markPrimary(ContactId)`;超過 50 位丟出 `ContactLimitExceededException`。

#### 3. `customer-infra/src/main/resources/db/migration/V12__contact.sql` (Create)

*   **Type / Scope**: Flyway Migration
*   **Proposed Changes**: 建立 `crm_contact` 表與 `ux_contact_primary` 部分唯一索引(PostgreSQL `WHERE is_primary`)。

#### 4. `customer-app/src/main/java/com/acme/crm/customer/app/AddContactService.java` (Create)

*   **Type / Scope**: Application Service
*   **Proposed Changes**: `addContact(customerId, command)` 於單一交易載入 Customer、呼叫 `addContact`、儲存,並以既有 `customer-app/src/main/java/com/acme/crm/customer/app/port/AuditPort.java` 寫入 `CONTACT_CREATED`;樂觀鎖衝突轉為 `PrimaryContactExistsException`。

#### 5. `customer-api/src/main/java/com/acme/crm/customer/api/ContactController.java` (Create)

*   **Type / Scope**: REST Controller
*   **Proposed Changes**: `POST /api/customers/{customerId}/contacts`;權限 `CUSTOMER_EDIT`;201/409/422/403 依 Technical Plan 的例外對應表。

#### 6. `docs/api/customer-contact.openapi.yaml` (Create)

*   **Type / Scope**: API Specification
*   **Proposed Changes**: 上述端點的 request、response 與錯誤格式。

#### 7. `customer-domain/src/test/java/com/acme/crm/customer/domain/CustomerContactTest.java` (Create)

*   **Type / Scope**: Unit Test
*   **Proposed Changes**: 第 51 位聯絡人、重複 Primary、Email 格式錯誤三個案例。

#### 8. `customer-infra/src/test/java/com/acme/crm/customer/infra/ContactConcurrencyIT.java` (Create)

*   **Type / Scope**: Integration Test(Testcontainers PostgreSQL)
*   **Proposed Changes**: 兩執行緒同時設定主要聯絡人,一個成功、一個得到 `PrimaryContactExistsException`;驗證 `ux_contact_primary` 生效。

### Verification Plan

*   **Compilation/Build**: `mvn -q -pl customer-domain,customer-app,customer-api,customer-infra -am verify`
*   **Unit Tests**: `mvn -q -pl customer-domain test`
*   **Static Analysis & Linting**: `mvn -q spotbugs:check`
*   **Test Coverage Requirement**: `customer-domain` 分支覆蓋率 ≥ 85%
*   **E2E/Integration**: `mvn -q -pl customer-infra verify -Pit`(Testcontainers PostgreSQL)

--------------------------------------------------------------------------------

*Drafted with EGM*

實務注意:Claude Code 沒有 artifact 註解功能。要求修改草稿時,可以直接編輯 design_draft.md、在檔案中加 <!-- --> 註解,或在聊天中說明;模型每次修改前都會重讀草稿(官方,docs/claude.md)。

5.3 Goldfish Protocol:獨立審查

目的:在全新 Context 中,以 5 個 stage 審查設計文件。

/egm:egm-review docs/designs/customer-contact.md

5.3.1 前置:Intake、Preset、Semantic Split

  1. Intake:沒給路徑會用一般文字詢問。接著詢問是否提供 GoldfishContext(空清單也算)。
  2. Preset(單選,不可多選,官方):
選項內容適用
0Interactive review with all review rubrics(每 stage 後停下)第一次審查重要設計
1Consolidated report(全部跑完不停)時間緊、或 CI/headless
2Feature spec only(Stage 5~8)還沒寫實作計畫
3Implementation plan only(只跑 Stage 9)架構已核准,只審實作計畫

Step 參數與 preset 的對應(官方 Step 2.1:「map to the corresponding preset or subflow」):

Step 值等同執行範圍
interactivePreset 0Stage 5~9,每 stage 後停下
uninterruptedPreset 1Stage 5~9 不停,另產出 consolidated 報告
feature_specPreset 2Stage 5~8
implementationPreset 3只跑 Stage 9
5、6、7、8、9單一 stage只跑該 stage(常用於中斷後續跑)
  1. Semantic Split:找 ## Detailed Implementation Plan 等標題,自動切成 FeatureRange 與 DetailedRange,並在聊天中回報「Discovered semantic boundary at line L」。找不到或多個候選時會請你決定。
  2. Linked Files:在第一個需要 GoldfishContext 的 stage 前,把文件中的工作目錄內連結自動加入(2.8)。

5.3.2 五個審查階段

flowchart LR
    S5["Stage 5<br/>Initial Zoom Out<br/>egm-zoom-out+egm-inventive-catalyst<br/>全文"] --> S6["Stage 6<br/>Comprehension<br/>egm-comprehension<br/>只讀文件"]
    S6 --> S7["Stage 7<br/>Critic<br/>egm-design、egm-structural、egm-style<br/>FeatureRange"]
    S7 --> S8["Stage 8<br/>Intermediate Zoom Out<br/>egm-zoom-out<br/>全文,聚焦新增內容"]
    S8 --> S9["Stage 9<br/>Implementation Readiness<br/>egm-implementation-readiness、<br/>egm-codebase-details、egm-style<br/>DetailedRange"]

逐一說明(官方,skills/egm-review/SKILL.md;「失敗原因、修正方式」為本手冊整理):

Stage 5 — Initial Zoom-out Review:

項目內容
審查目的簡單性、YAGNI、重用既有元件、是否解決根本問題
Reviewer Personaegm-zoom-out(Skeptical Architect)+平行的 egm-inventive-catalyst(TRIZ)
輸入資料全文+GoldfishContext;standard:zoom-out-standard
執行方式synthesizer 或直接派工
輸出結果zoom_out_report.md
常見失敗原因目標不清楚(Context Sufficiency 直接不通過);提出快取、MQ 卻沒有效能證據;重造既有 util
修正方式補 Problem/Goals;刪除投機性設計;改為重用既有元件
通過標準無未處理的 Blocker;Major 有明確決定(修或接受)

Stage 6 — Comprehension Check:

項目內容
審查目的文件能否自我說明(self-containment),不是細節夠不夠
Reviewer Personaegm-comprehension(Naive Reader),直接啟動,不經 synthesizer
輸入資料FeatureRange+DetailedRange;不給 GoldfishContext、不套用任何 standard
執行方式先用自己的話改寫(paraphrase)文件提案與現有系統,再檢查未定義名詞
輸出結果comprehension_report.md,開頭是兩段 paraphrase,之後是 findings
常見失敗原因縮寫、內部系統名、權限碼沒定義;各節彼此不連貫
修正方式加名詞解釋或連結;補「現有系統怎麼運作」的段落
通過標準paraphrase 與作者原意一致;無 Blocker

為什麼 Stage 6 不用 synthesizer:「its report keeps only findings, and the author must see the paraphrase.」作者要親自比對 Goldfish 的理解是否正確——paraphrase 錯了,就是文件寫得讓人誤解。

Stage 7 — Antagonistic Review/Design Critique:

項目內容
審查目的架構、擴展瓶頸、失效模式、模板結構、文字精準度
Reviewer Personaegm-design(Hostile Critic)、egm-structural、egm-style
輸入資料FeatureRange+GoldfishContext;egm-design 與 egm-structural 套 feature-spec-standard
執行方式在主執行緒中執行 egm-review-loop
輸出結果critic_report.md
常見失敗原因沒有替代方案;沒寫並行與失效處理;「效能很好」這類無法驗證的說法
修正方式選 Option 1 交給 egm-resolve,或手動修改
通過標準Blocker 全部處理;Major 有決定與紀錄

Stage 8 — Intermediate Zoom-out Review:

項目內容
審查目的檢查 Stage 6、7 修正時新增的內容是否讓設計變複雜
Reviewer Personaegm-zoom-out
輸入資料全文+zoom_out_report.md 路徑+GoldfishContext
輸出結果intermediate_zoom_out_report.md
常見失敗原因為了回應 Critic 加了一堆防禦性機制
修正方式刪回最小解,把非必要機制移到 Future Improvements
通過標準同 Stage 5

Stage 9 — Implementation Readiness Check:

項目內容
審查目的實作者拿到計畫能否直接開工、不需做任何設計決定
Reviewer Personaegm-implementation-readiness(Tech Lead)、egm-codebase-details(稽核員)、egm-style
輸入資料DetailedRange+GoldfishContext;前兩者套 implementation-readiness-standard
執行方式egm-review-loop
輸出結果implementation_readiness_report.md
常見失敗原因檔案路徑不存在、函式簽章不明、測試案例只寫「要測試」、相依套件沒寫版本
修正方式補完整路徑、簽章、測試案例、版本
通過標準Zero-Decision Rule 成立;File Boundary 完整

Consolidated(Preset 1)另外產出 consolidated_review_report.md:跨 stage 去重、依 🔴 Blocker/🟡 Major/🟢 Nit 排序,並附 Traceability Matrix(原始 finding 對應到彙整後的行動項目)。

5.3.3 Stage 之間的關卡

Stage選項
5、6、80 進下一 stage;1 我先自己改文件(暫停);2 暫停審查
7、90 進下一 stage;1 交給 Agent 處理 findings(egm-resolve);2 我手動改(暫停);3 暫停審查

1-Audit Convergence Cap:每個 stage 最多重審一次。重審後又要改文件時,Agent 會告知已達上限,把剩餘 findings 記為「accepted trade-offs」並進入下一 stage。

5.3.4 Goldfish 如何使用獨立 Context

sequenceDiagram
    autonumber
    actor U as 工程師
    participant E as Elephant(主 Context)
    participant Sy as egm-synthesizer
    participant R as Reviewers(全新 Context)
    participant FS as 檔案
    U->>E: /egm:egm-review X.md
    E->>U: 詢問 GoldfishContext 與 preset
    U->>E: 選 Interactive
    E->>FS: 讀 X.md,找切分點
    E->>FS: 解析文件內連結,加入 GoldfishContext
    loop Stage 5、6、7、8、9 依序
        E->>Sy: reviewers、standards、範圍、閱讀清單
        Sy->>R: 每個 reviewer 一個新 Subagent
        R->>FS: 唯讀
        R-->>Sy: findings 或 incomplete
        Sy->>FS: 寫 stage 報告
        Sy-->>E: 狀態與路徑
        E->>U: 報告路徑+關卡
        U->>E: 繼續、Resolve 或暫停
    end

各 Host 的 Subagent 建立方式見 2.9。

實務注意:Interactive 模式中,Stage 6 的 paraphrase 一定要親自讀。它是整個流程中唯一能直接看到「陌生讀者怎麼理解你的文件」的地方。

5.3.5 實跑紀錄:一次真實的 Consolidated Review(1.1)

對象是附錄 B 的 fixtures/design_good.md(124 行,也就是第 5.2 節範例的完整版)。執行方式見第 3.13.1 節。Elephant 找到的語意分界寫在 consolidated_review_report.md 第 3 行:「FeatureRange 1..68, DetailedRange 69..124」,也就是 ## Detailed Implementation Plan 從第 69 行開始。

各 stage 的結果(摘自 consolidated_review_report.md):

StageReviewers🔴🟡🟢
5 Initial Zoom Outzoom-out, inventive-catalyst164
6 Comprehensioncomprehension144
7 Criticdesign, structural, style1116
8 Intermediate Zoom Outzoom-out154
9 Implementation Readinessimplementation-readiness, codebase-details, style776

從這次實跑可以學到的事:

  1. 「看起來完整」的設計文件仍有 11 個 Blocker。 本手冊 1.0 把這份文件當成「好例」,Goldfish 卻抓到:第 96 行引用的「例外對應表」不存在;樂觀鎖衝突全部轉成 PrimaryContactExistsException 是錯的;Customer.java、AuditPort.java 標成 Modify 卻不在 repo 中;Goals 承諾列表與明碼讀取,File Boundary 卻只有 POST。本手冊的獨立 Goldfish 審查(附錄 E.3)也獨立抓到同一個「例外對應表不存在」。
  2. Reviewer 之間會意見衝突。 Stage 7 要求補完整 CRUD、blind index、重試機制;Stage 8 主張縮小第一階段、把這些延後。Consolidated 報告把它整理成「Decisions the author must make first」,這是人要做的決定,不是交給 AI 投票。
  3. Stage 6 的 paraphrase 是給作者看的。 comprehension_report.md 開頭是「What this proposes」「How the existing system works, per this document」兩段改寫。SA 要逐句比對它和原意是否一致(第 10.5 節的人工項目)。
  4. 報告格式每次可能不同。 同一次執行的 6 份報告就有 4 種嚴重度寫法(第 10.5.1 節),閘門工具必須用真實報告測試。

實務注意:Goldfish 只讀得到 repo。設計文件寫「既有的 AuditPort」時,如果那個類別在另一個 repo,Goldfish 一律回報「找不到」。對策是把外部依賴的路徑或版本寫進文件,或把相關檔案列入 GoldfishContext;Resolve 時這類問題會被標成 ESCALATE(見 5.4.6)。

5.4 Resolve:問題修正

目的:在 Elephant(記得設計理由的 Context)中逐項處理 findings。

通常由 Stage 7/9 的 Option 1 自動呼叫;也可以單獨使用:

/egm:egm-resolve

單獨使用時會逐一詢問 TargetFile、LineRange、FindingsList。

5.4.1 分類規則(官方)

分類條件要求
CONTEST批評不正確或誤解程式碼必須引用 reviewer 讀得到的證據(檔案+符號,或文件中已記錄的決定)
ESCALATE批評不正確,但證據在 reviewer 讀不到的地方(團隊慣例、口頭決議)不修改;交給使用者
PROPOSE FIX批評正確給出精確的替換文字
DECLINE只是 Nit記錄,不修改

五條紀律(官方):

  1. 反駁必須可檢查——「This was intentional」不是證據。
  2. 不要只為了讓 reviewer 滿意而加內容;只有人類讀者也需要時才加。
  3. 不要反駁 comprehension gap——新讀者看不懂就是文件缺內容。
  4. 不要改嚴重度;認為 Blocker 其實是 Nit,就用 CONTEST 說明理由。
  5. 你寫了這份文件——想反駁不代表 reviewer 錯了。

5.4.2 流程

sequenceDiagram
    autonumber
    actor U as 工程師
    participant E as Elephant
    participant R as goldfish_review_report.md
    participant D as 設計文件
    E->>D: 讀取 LineRange
    E->>E: 每個 finding 分類 CONTEST/ESCALATE/PROPOSE FIX/DECLINE
    E->>R: 寫報告(含建議修改)
    E->>U: 先列出 ESCALATE,再給 5 種處理方式,然後停止
    alt auto accept
        U->>E: auto accept
        E->>D: 一次套用所有 PROPOSE FIX
    else interactive breakdown
        loop 每一項(DECLINE 除外)
            E->>U: 說明+建議
            U->>E: Accept/Skip/Overrule/Discuss
        end
        E->>D: 套用接受的修改
    else continue
        U->>E: continue
    end
    E->>R: 最上方加 Status: resolved
    E-->>U: 統計:接受、反駁、升級、略過、未處理

5.4.3 如何分類重大問題與一般建議(建議)

嚴重度公司處理規定
🔴 Blocker必須 PROPOSE FIX 或附證據 CONTEST;ESCALATE 需要架構師簽核
🟡 Major必須有決定;接受風險時寫入設計文件的 Non-Functional Requirements 或 Open Questions
🟢 Nit可 DECLINE

5.4.4 再次啟動 Goldfish 與確認問題已解決

  • 修正後,Stage 7/9 可重審一次(1-audit cap)。
  • 若用 egm-review-loop,收斂條件是連續兩輪 clean(第 5.9 節)。
  • 修正多、範圍大時,在同一設計 session 重新跑完整 /egm:egm-review;reviewer 每次都是新 Subagent,不會沿用上一輪的 Context。

5.4.5 保留審查紀錄

goldfish_review_report.md 的格式(官方):

# Goldfish Annotated Review Report

**Target:** `[TargetFile]` (`[LineRange]`)

## Prioritized Findings & AI Suggestions

### [Issue 1] [`[ReviewerPersona]`] - Severity: [Blocker | Major | Nit]
*   **Affected Scope:** ...
*   **Discrepancy Description:** ...
*   **Rationale:** ...
*   ***AI Suggestion:*** [CONTEST | ESCALATE | PROPOSE FIX | DECLINE]
*   ***Justification:*** ...
*   ***Proposed Edit:*** ...

公司要求把最終報告與 ESCALATE 簽核檔一起封存(10.16),並用 egm_report_gate.py 檢查(10.5)。

實務注意:DECLINE 只適用於 Nit。若看到 Major 被標成 DECLINE,代表 Elephant 偷偷降級了問題——報告閘門的 R3 規則會擋下。

5.4.6 實跑紀錄:在同一個 session 執行 Resolve(1.1)

1.0 定案的規則是「設計到 Resolve 在同一個 session,只有實作才開新 session」。1.1 用 --resume 回到 5.3.5 那次 Review 的 session 執行 Resolve,實際驗證這條規則(Shell):

SID=$(python -c "import json;print(json.loads(open('review.jsonl',encoding='utf-8').readline())['session_id'])")
claude -p --resume "$SID" --plugin-dir ../egm-src --permission-mode acceptEdits \
  --allowedTools "Read,Grep,Glob,Write,Bash(ls:*)" --output-format stream-json --verbose \
  "/egm:egm-resolve TargetFile: docs/designs/customer-contact.md LineRange: full file FindingsList: every Blocker and Major finding in .dev/docs/critic_report.md and .dev/docs/implementation_readiness_report.md. Write goldfish_review_report.md, then stop at the Interactive Resolution Gate. Do not edit the design document in this run." \
  > resolve.jsonl

結果:

項目實測
findings26 項(8 Blocker、18 Major)
分類21 PROPOSE FIX、5 ESCALATE、0 CONTEST、0 DECLINE
設計文件未修改(git status 只有 .dev/)
報告格式與 skills/egm-resolve/SKILL.md 模板完全一致:### [Issue N] [persona] - Severity: X、***AI Suggestion:***

ESCALATE 的 5 項都是「Goldfish 讀不到的事實」:AuditPort 是否在另一個 repo、重複聯絡人的實際比例、端點權限用哪個 annotation 等。Elephant 在 chat 中寫:「我不會自己編數字。」這就是 ESCALATE 的正確用法:需要人提供事實,不是請人按核准。

Elephant 記憶的價值(實測):Resolve 在 chat 回報中針對 Issue 7(鎖定機制)寫:「你先前提到團隊已選定 PostgreSQL advisory locks;只要你確認,我套用時就寫入這個機制。」這件事只在 Review 的呼叫訊息中說過,沒有寫進任何檔案;而且 Elephant 依指示沒有把它寫進報告檔。如果在新 session 執行 Resolve,這個脈絡就會遺失,Elephant 可能直接採用 reviewer 建議的另一種鎖定方案。

如何審查 AI 的 Resolve 結果:

檢查點好例壞例怎麼抓
CONTEST 有證據引用 reviewer 讀得到的檔案與符號「作者認為沒問題」grep -n "CONTEST" -A3 goldfish_review_report.md,逐項看 Justification
ESCALATE 是事實問題「AuditPort 在哪個 repo?」「請確認是否接受」讀 ESCALATE 的 Justification,問「這是 Goldfish 能查到的嗎?」
沒有偷改文件停在 Resolution Gate先改了才問git diff --stat docs/designs/ 應為空
數字不是編的留〔待作者確認〕自己填「重複率 12%」grep -n -E "[0-9]+%" goldfish_review_report.md 後逐一追問來源

5.5 Human Review:人工審查

官方:「Send a Pull Request with your design to another human. EGM does not replace human oversight, but encourages it.」

設計 PR 的內容(建議):

檔案必要
docs/designs/<feature>.md是
docs/designs/SITEMAP.md 更新若存在
docs/designs/reviews/<feature>/*.md(stage 報告、goldfish_review_report.md、review_signoff.md)公司規定
分支名稱 design/<feature>(CI 由此推導設計文件路徑,10.8)公司規定
正式程式碼不可(設計 PR 只含文件)

各角色審查責任:

角色審什麼不審什麼
Architect架構方案、替代方案取捨、與 ADR 一致、Stage 5/8 的取捨文字風格
SAGoals/Non-Goals/CUJ 是否等於需求;Stage 6 paraphrase 是否正確程式檔清單
SD/Tech LeadDetailed Implementation Plan 是否可執行、檔案清單完整商業優先順序
資安Security & Compliance 章節、資料分類、OWASP 對應—
PM範圍、時程、Non-Goals 是否與利害關係人一致技術細節
QACUJ 是否可測、Verification Plan 是否足夠—

實務注意:人工審查者要看的是「Goldfish 沒有能力判斷的事」:商業優先順序、組織限制、口頭決議、ESCALATE 項目。不要把 Goldfish 已經挑過的格式問題再挑一次。

5.6 Implementation:程式實作

官方立場:Phase 5 沒有 Skill,「Tell AI to build to the plan.」

flowchart TD
    A["設計 PR 已核准<br/>Status: Approved"] --> B["開新 session<br/>(不要沿用設計時的 Elephant)"]
    B --> C["提示:依設計文件實作 Phase 1<br/>只能修改 File Boundary 列出的檔案"]
    C --> D["AI 實作"]
    D --> E["本機執行 Verification Plan 指令"]
    E -->|"失敗"| F{"錯誤性質"}
    F -->|"小錯"| G["要求 AI 點修或自己修"]
    G --> E
    F -->|"設計錯誤"| H["停止實作<br/>更新設計文件並重審"]
    E -->|"通過"| I["egm_scope_guard.py 檢查範圍"]
    I -->|"越界"| J["還原或補設計"]
    I -->|"通過"| K["開實作 PR<br/>Code Review+CI"]
    K --> L{"還有下一個 Phase?"}
    L -->|"是"| C
    L -->|"否"| M["上線後另開 docs-only PR 更新 SITEMAP(10.4)"]

實作提示範本(建議,Claude Code 對話框):

請依 docs/designs/customer-contact.md 的「Detailed Implementation Plan」實作。
規則:
1. 只能新增或修改「Target Files to Create/Modify」列出的檔案(本例 8 個)。需要改其他檔案時,先停下來告訴我原因。
2. 不要新增相依套件、不要重構無關程式。
3. 每完成一個檔案,執行 Verification Plan 的對應指令並回報結果。
4. 設計文件與程式碼衝突時,以設計文件為準並回報衝突,不要自行決定。
需求做法
限制修改範圍提示詞+egm_scope_guard.py(CI 強制)
確保程式與設計一致Code Review 對照設計文件;之後跑 Drift Report
Unit/Integration/E2E執行設計文件 Verification Plan 列出的指令
Code Review人類審查者以設計文件為依據;可另用 Host 的 code review 功能
實作中發現新需求不要在實作 PR 中順手加;回到 Brainstorm 或在設計文件 Open Questions 記錄,走新設計 PR

官方 FAQ:「If it is making a minor mistake, adjust it. If it is wildly off base, maybe you need to go back to the drawing board and correct your design.」

實務注意:用新 session 實作。設計時的 Elephant 知道太多「沒寫進文件」的事,會讓你誤以為文件夠清楚;新 session 是最後一次驗證文件是否自足的機會。

5.7 Drift Report:架構及文件漂移檢查

/egm:egm-drift-report docs/designs/

5.7.1 官方行為(skills/egm-drift-report/SKILL.md)

  1. 確認有文件目錄,否則詢問。
  2. 列出目錄中所有檔案。
  3. 對每一份文件:讀文件 → 找出提到的檔案與符號 → 找不到明確路徑時用搜尋定位,並建議你在文件中補連結 → 讀程式碼現況 → 比對。
  4. 比對重點:Missing Features、Incomplete Models(欄位缺漏)、Logic Shortcuts(該動態卻寫死)、Architectural Divergence(用了不同的模式或套件)。
  5. 只報告差異;完全一致時寫「No drift detected.」
  6. 逐份附加到 {YYYY-MM-DD}_DRIFT_REPORT.md,格式:
## <DESIGN_DOC_NAME>

<Bulleted list of specific divergences found>
<Or "No drift detected">
  1. 依序處理文件,避免工具輸出溢位。

5.7.2 適用範圍

可比對說明
設計文件 vs 程式碼主要用途
README vs 程式碼官方 description 明列「designs or READMEs」;Bootstrap 也會建議對產生的 README 跑一次
API文件中的端點、欄位 vs Controller/OpenAPI 檔
資料庫結構文件中的資料表、欄位 vs migration 檔/DDL(需要 repo 內有 DDL)
系統架構文件中的分層 vs 實際 import(建議另用 ArchUnit 機械化檢查,6.6)

不在範圍:執行中的資料庫實際 schema、部署環境設定(EGM 只讀 repo 檔案)。

5.7.3 頻率與處理

官方建議「once per week」,排入例行維運。處理原則:「Either update the doc, or the code. Human picks which.」

實務注意:Drift Report 在主 Context 執行、不需要 Subagent,但它會讀很多檔案。文件目錄很大時,按子目錄分批執行(例如 /egm:egm-drift-report docs/designs/customer/)。

5.7.4 實跑紀錄:Drift Report 抓到跨層漂移(1.1)

做法:先用 Bootstrap 產生 EGM.md(5.8.4)並 commit,再只把 Java 的門檻從 300000 改成 500000,然後執行(Shell):

git -c user.name=lab -c user.email=lab@example.invalid commit -qam "bootstrap EGM.md"
sed -i 's/new BigDecimal("300000")/new BigDecimal("500000")/' legacy/java/LoanApprovalService.java
git -c user.name=lab -c user.email=lab@example.invalid commit -qam "raise auto-approve limit"
claude -p --plugin-dir ../egm-src --permission-mode acceptEdits \
  --allowedTools "Read,Grep,Glob,Write,Edit,Bash(ls:*),Bash(git log:*),Bash(git diff:*)" \
  "/egm:egm-drift-report legacy"

產出 .dev/docs/2026-11-17_DRIFT_REPORT.md(節錄,原文為 Elephant 依繁體中文 CLAUDE.md 慣例撰寫):

## legacy/java/EGM.md

- **Interface 漂移**:第 12 行記載 `AUTO_APPROVE_LIMIT = new BigDecimal("300000")`;實際為 `new BigDecimal("500000")`(`LoanApprovalService.java:7`)。
- **漏寫的跨元件影響**:文件沒有記錄 Java 門檻與 `approve.jsp`、`LoanForm.vue` 的提示門檻(仍為 300000)已不一致。

## legacy/db/EGM.md

No drift detected

## legacy/mapper/EGM.md

No drift detected

判讀:

  • 6 份合約中有 4 份回報漂移(root、java、jsp、vue),db 與 mapper 正確回報「No drift detected」。
  • 最有價值的是跨層發現:只改了 Java,畫面上的「Manual review required」提示仍停在 300000。單看 Java 的 diff 不會發現這件事。
  • 也有超出這次變更的發現(例如 LoanForm.vue 沒有送出按鈕)。Drift Report 檢查「文件 vs 現況」,不是只看最近的 commit,所以第一次跑時會出現既有的差異。

如何審查 Drift Report:

檢查點好例壞例怎麼抓
只列差異每項都指出文件行號與程式行號「XX 功能已正確實作」grep -n -i -E "matches|correctly|已正確|一致" *_DRIFT_REPORT.md 應無結果
每份文件都有段落6 份 EGM.md 各有 ## <文件>少了某份文件grep -c "^## " *_DRIFT_REPORT.md 等於文件數
引用的行號是真的LoanApprovalService.java:7 確實是門檻行號對不上sed -n 7p legacy/java/LoanApprovalService.java

5.8 Bootstrap:既有系統文件建立

/egm:egm-bootstrap customer-service/

不想動到既有 README 時:

/egm:egm-bootstrap customer-service/ target_filename=EGM.md

5.8.1 官方行為(「Peanuts and Hay」)

名詞意義模板章節
Peanuts葉節點:含原始碼的目錄 README(Component Package)Overview、Interface、Invariants、Side Effects、Verification
Hay父節點:彙總子目錄的 BlueprintOverview、Subdirectories & Boundaries
Root Blueprint根目錄System Overview、Subdirectories & System Boundaries、Global Invariants、Global Side Effects、System Verification

執行步驟(摘要):

  1. 偵測 build manifest 決定測試指令(package.json→npm test、Cargo.toml→cargo test…;pom.xml 不在清單中,見 5.8.2;*.csproj→dotnet test 只有 main 才有)。
  2. BFS 逐層探索(禁止 find、ls -R),略過 .git、node_modules、dist、build、third_party 等;套用 .gitignore 與 .egmignore。
  3. 目錄數 > 15 時必須先問你是否繼續。
  4. 由下而上修剪:沒有原始碼的目錄、純測試目錄都排除。
  5. ≤ 5 個目錄直接處理;> 5 個分割成 3~5 個子樹,平行派給 egm-bootstrap-orchestrator worker。
  6. 每個目錄用唯讀 goldfish-explorer scout 掃描(goldfish-explorer 是 Bootstrap 在執行時臨時定義的 Subagent,不在 agents/ 的 10 個 persona 中;它只回傳該目錄的介面、不變式與副作用 JSON,不能寫檔),每次約 1,500 行;scout 規則:「Never infer RPC methods, routes, status enums, or invariants from file or directory names alone; cite the exact [file:symbol_or_flag] for every entry」。
  7. 已有 README 時不覆寫,而是萃取既有內容再合併修正。
  8. 最後逐一重讀每份產出、檢查連結是否存在,並詢問是否跑 Drift Report。
  9. 不會 git add/git commit。

5.8.2 重要限制(讀原始碼+1.1 實跑)

Bootstrap 判斷「原始碼目錄」用的是 Skill 內的副檔名清單(skills/egm-bootstrap/SKILL.md Step 2.3),v0.1.1 與 main 不同:

類別v0.1.1(dea7761)main(72d06f5)新增
Managed & Enterprise.java、.kt、.scala、.cs、.fs.razor、.cshtml、.vb(#324)
Systems.c、.cpp、.h、.rs、.go 等Fortran(.f90 等)、.hs
Scripting.py、.rb、.php、.lua、.sh、.bash.ps1、.psm1、.r、.ex 等
Step 0 測試指令沒有 .NET*.sln/*.csproj → dotnet test(#409)

兩個版本都不包含 .vue、.jsp、.xml(例如 MyBatis mapper)、.properties、.yml;Step 0 也都沒有 pom.xml/build.gradle。

驗證指令(Shell,在 EGM repo):

git show v0.1.1:skills/egm-bootstrap/SKILL.md | grep -n -A2 "Managed & Enterprise"
grep -n -A2 "Managed & Enterprise" skills/egm-bootstrap/SKILL.md          # main
grep -c -E '\.vue|\.jsp|\.xml|pom\.xml' skills/egm-bootstrap/SKILL.md     # 兩版皆為 0

依規則,只有 .vue、.jsp 或 mapper XML 的目錄會被當成「沒有原始碼」而修剪掉;Java 專案的 Verification 會是 <test-command> 佔位符。

但實跑結果不同(1.1,5.8.4):Elephant 在回報中寫「.jsp、.vue、MyBatis .xml 不在這個 skill 認得的原始碼副檔名清單裡。照規則,jsp、mapper、vue 三個目錄會被排除。我判斷它們確實是程式碼……所以仍然寫了這三份。」它也依 pom.xml 自行填了 mvn test。

這告訴我們:Skill 是給 LLM 的指示,不是會照字面執行的程式。 同一份規則,這次被刻意偏離(而且有揭露),下次可能照規則修剪。因此:

  1. 不要依「規則說會修剪」來預估產出;Bootstrap 後一律列出實際產生的檔案。
  2. 讀 Elephant 的結尾回報,找「偏離規則」「deviat」等揭露,逐項決定要不要保留。
  3. 公司要求固定行為時,把要求寫進呼叫訊息(例如「.jsp、*Mapper.xml 目錄也要產生 EGM.md」),不要依賴 AI 的臨場判斷。

逆向工程時另以第 7 章的流程補齊。

5.8.3 人工驗證

官方:「Humans should still review this output.」驗證方式:

  1. git diff --stat 看改了哪些 README。
  2. 每份 README 的 Interface 抽查 3 個符號是否存在(grep -rn 符號名)。
  3. 對產生的 README 跑 /egm:egm-drift-report(Bootstrap 結束時會詢問)。
  4. 檢查有沒有「看起來合理但程式中不存在」的流程圖節點。

實務注意:Bootstrap 對大型 repo 會平行啟動很多 worker(「without artificial concurrency limits」,經你在安全門檻同意後)。先對單一模組試跑,確認品質與成本再擴大。

5.8.4 實跑紀錄:對舊系統目錄跑 Bootstrap(1.1)

測試目錄(附錄 B 的貸款 fixture,另加 3 個 Bootstrap 清單外的檔案):

legacy/
├── pom.xml
├── java/LoanApprovalService.java
├── db/PKG_LOAN.sql
├── mapper/LoanMapper.xml      # MyBatis,清單外
├── jsp/approve.jsp            # 清單外
└── vue/LoanForm.vue           # 清單外
claude -p --plugin-dir ../egm-src --permission-mode acceptEdits \
  --allowedTools "Read,Grep,Glob,Write,Edit,Agent,Bash(ls:*),Bash(mkdir:*)" \
  "/egm:egm-bootstrap path: legacy target_filename: EGM.md"
git status --short --untracked-files=all
?? legacy/EGM.md
?? legacy/db/EGM.md
?? legacy/java/EGM.md
?? legacy/jsp/EGM.md
?? legacy/mapper/EGM.md
?? legacy/vue/EGM.md

5 個目錄(≤ 5),所以沒有分派 worker,而是每個目錄派一個唯讀 scout,再由 Elephant 對照原始檔逐條確認。費用 US$0.94。log 顯示 5 個 scout 的 subagent_type 都是 Claude Code 內建的 Explore(描述為「Scout legacy/db」等),不是 Skill 文字中的 goldfish-explorer 名稱:Skill 只定義 scout 的提示詞,實際用哪種 subagent 由 Host 決定。

Bootstrap 在合約中寫出 5 個跨層不一致,這是逆向工程最有價值的產出:

#發現證據
1Java 回傳 "MANUAL_REVIEW",PL/SQL 寫入 'PENDING_REVIEW'LoanApprovalService.java、PKG_LOAN.sql
2JSP 與 Vue 表單都沒有送 creditScore,但 approve() 需要這個參數approve.jsp、LoanForm.vue
3callProcedure 在 LoanMapper.xml 沒有對應 statement;countPendingByBranch 沒有呼叫端LoanMapper.xml
4門檻 300000 寫死在 Java、JSP、Vue 三處三個檔案
5approve.jsp 沒有 JSTL taglib 宣告,${amount} 讀的不是送出的欄位approve.jsp

產生的 jsp/EGM.md(節錄,可作為 7.5.2 人工補寫 JSP 目錄時的範本):

# jsp

## Overview

舊版伺服器端貸款核准畫面。`approve.jsp` 渲染一個表單,以 POST 送到 `/loan/approve`。處理 `/loan/approve` 的 controller 不在樹中。功能與 [`../vue/EGM.md`](../vue/EGM.md) 的 `LoanForm.vue` 重疊。

## Interface

- `<form action="/loan/approve" method="post">` [`approve.jsp:form`]
- 請求參數 `applicationNo`:`required`、`maxlength="12"` [`approve.jsp:input[name=applicationNo]`]
- 請求參數 `amount`:`type="number"`、`min="1"`、`max="5000000"` [`approve.jsp:input[name=amount]`]

## Invariants

- 人工審核提示的門檻 `300000` 是寫死的字面值,與 `LoanApprovalService.AUTO_APPROVE_LIMIT` 重複,修改時需同步。
- 檔案沒有 JSTL `taglib` 指示詞,`<c:if>` 需要由外部 include 提供 prefix;本目錄內無法確認。`${amount}` 讀的是 JSP scope 變數,不是送出的表單欄位。

如何審查 Bootstrap 產出:

檢查點好例壞例怎麼抓
每條都有出處[approve.jsp:form]沒有 [file:symbol] 的條目grep -n "^- " legacy/*/EGM.md | grep -v "\[" 列出沒有出處的條目
出處真的存在approve.jsp 有 <form引用不存在的符號對每個 [檔案:符號] 執行 grep -n "符號" 檔案
「不在樹中」不是猜的「controller 不在樹中」「由 LoanController 處理」(未讀到)grep -rn "LoanController" legacy/ 應為空
偏離規則有揭露結尾回報列出偏離默默多寫或少寫比對 git status 與規則預期

5.9 Review Loop

目的:自己選 reviewer 與 standard,對特定文件或特定章節反覆審查直到收斂。

/egm:egm-review-loop
TargetFile: docs/designs/customer-contact.md
SemanticTarget: Target the "## Technical Plan (Architecture)" section
Reviewers: [design_critic, zoom_out]
Standards: {"design_critic": "docs/standards/clean-architecture-standard.md", "zoom_out": "zoom-out-standard"}
GoldfishContext: [docs/adr/0007-hexagonal.md]

5.9.1 收斂規則(官方)

名詞定義
Settled finding已被 CONTEST 或記錄為接受風險;之後不再重開
Fixed finding已套用修正;若後續 reviewer 在同範圍提出同問題,重開
Clean round沒有未 settled 的 Blocker 或 Major;Nit 不影響;有 reviewer not run 就不算 clean
Converged連續兩輪 clean
Cap5 輪
Churn新 finding 落在已修正的範圍,且還原那個修正就能解決

到達 cap 或 churn 時,會列出未解 findings 並問你:接受並繼續、超過上限繼續、或退回草擬。每輪之間 必須等你確認 才會再跑下一輪。

5.9.2 不同目的的 Reviewer 組合(官方推薦+本手冊建議)

目的ReviewersStandards來源
Feature specdesign_critic、structuralfeature-spec-standard官方推薦
實作計畫implementation_readiness、codebase_detailsimplementation-readiness-standard官方推薦
專案提案、PoC 計畫design_critic、comprehensionheilmeier-standard建議
模組 README(Bootstrap 產出)codebase_details、comprehensionre-implementation-standard建議
資安審查自訂 security_reviewer公司 security standard建議
對外 API 文件structural、style、comprehension公司 API 文件標準建議

本章注意事項:

  • 每個 Skill 都可以單獨使用;最常見的入門用法是「既有 PR 計畫 → /egm:egm-review」。
  • Agent 的互動規則(一次一題、不諂媚、先批評)是刻意的設計,不要要求它「說好話」。

5.10 本章 AI 產出審查

檢查點好例壞例怎麼抓
Stage 6 有沒有 paraphrase報告開頭有兩段改寫只有 findings 清單看 comprehension_report.md 開頭
Reviewer Status全部 completed;沒有表時(direct dispatch)在 consolidated 開頭寫明出現 not run/incomplete 卻寫「無重大問題」egm_report_gate.py R1;先確認計數不是全 0(R0)
CONTEST 的證據「見 Customer.java:addContact 已檢查上限」「這是刻意設計」搜尋 Justification 是否有檔案或章節
DECLINE 的嚴重度只有 NitMajor 被 DECLINEegm_report_gate.py R3
實作 PR 範圍只有計畫列出的檔案多了 pom.xml、util 類別egm_scope_guard.py
Drift Report 格式只列差異或「No drift detected」長篇描述哪些地方一致grep -n -i -E "matches|correctly|已正確" *_DRIFT_REPORT.md 應無結果(5.7.4)

第 6 章:EGM 開發 Web Application 實戰

本章說明「用 EGM 設計企業 Web Application 時,設計文件每一層要寫什麼、Goldfish 會抓什麼」。完整的逐步操作演練在第 15 章案例一。

6.1 專案技術背景

6.1.1 技術堆疊與相容性確認

本節版本是「設計文件要寫到這個精度」的示範。實際導入時,每個版本都要由 Elephant 在 Brainstorm 階段列出官方來源,再由人確認。

層技術本案選用相容性依據(必須在設計文件引用)
RuntimeJava21(LTS),預留 25Spring Boot 4.0 system requirements:最低 Java 17,相容到 Java 25
後端框架Spring Boot/Spring FrameworkBoot 4.0.x/Framework 7.0.x同上;Boot 4 以 Jakarta EE 11、Servlet 6.1 為基準
測試JUnit跟隨 Spring Boot 依賴管理尚待驗證:Boot 4.0 依賴管理的 JUnit 主版本請查官方 Dependency Versions 頁,不要自行指定
前端Vue 3+TypeScript+ViteVue 3.5 系列Vue 官方文件
UIPrimeVue+Tailwind CSSPrimeVue 4、Tailwind 4PrimeVue 官方的 Tailwind 整合說明
狀態Pinia3.xPinia 官方文件
資料庫PostgreSQL(新)、Oracle(既有唯讀)PostgreSQL 17、Oracle 19cJDBC driver 與 Flyway 對各資料庫的支援模組
其他Redis、MQ、SFTP、Spring Batch、OpenAPI、Podman依功能需要各自官方文件

設計文件「Technical Plan」中的版本段落寫法(好例):

後端採 Spring Boot 4.0.x(需 Java 17 以上,相容至 Java 25;
來源:https://docs.spring.io/spring-boot/4.0/system-requirements.html)。
本專案以 Java 21 編譯與執行;Java 25 列為 Future Improvements,待 CI 映像檔提供後評估。

壞例:「使用最新版 Spring Boot 與 Java 25」——沒有來源、沒有固定版本、沒有說明為什麼。

6.1.2 不要假設所有元件都能直接搭配

在 Brainstorm 時請 Elephant 列出「相容性未確認清單」,常見項目:

組合要確認的事
Spring Boot 4 + 既有內部共用函式庫共用庫是否仍用 javax.*、是否依賴已移除的 Boot 3 API
Spring Boot 4 + DB2/SQL ServerJDBC driver 版本、Flyway 是否需額外的資料庫模組
PrimeVue 4 + Tailwind 4樣式模式(styled/unstyled)與 Tailwind 整合方式
Micro-Frontend + PrimeVue多個子應用載入不同版本 PrimeVue 時的樣式衝突
Spring Batch + 多資料庫Job Repository 放在哪個資料庫

實務注意:Goldfish(egm-implementation-readiness)在 Stage 9 會抓「相依套件沒寫版本」;但它不會上網查證相容性。版本正確性是人類的責任。

6.2 新系統開發案例

案例:企業客戶管理系統(CRM)— 客戶聯絡人功能。

flowchart TD
    A["1 Brainstorm<br/>/egm:egm-brainstorm"] --> B["2 concepts_brief.md"]
    B --> C["3 Draft<br/>/egm:egm-draft"]
    C --> D["4 Goldfish Review<br/>/egm:egm-review"]
    D --> E["5 Resolve"]
    E --> F["6 設計 PR 人工核准"]
    F --> G["7 新 session 實作<br/>依 File Boundary"]
    G --> H["8 測試<br/>Unit、IT、ArchUnit、E2E"]
    H --> I["9 Code Review+scope guard"]
    I --> J["10 更新設計文件<br/>Status、SITEMAP、Drift"]
步驟指令或動作產出負責人
1/crm-elephant 後 /egm:egm-brainstorm 客戶聯絡人…對話SA+SD
2交接選單選「Proceed to egm-draft」concepts_brief.mdSD
3/egm:egm-draftdocs/designs/customer-contact.mdSD
4/egm:egm-review docs/designs/customer-contact.md5 份 stage 報告SD
5Stage 7、9 選 Option 1goldfish_review_report.mdSD+Architect
6開設計 PR核准紀錄Architect、資安、QA
7新 session 依 5.6 的提示實作程式 PRPG
8mvn verify、npm run test、Playwright測試報告PG、QA
9Code Review、egm_scope_guard.pyReview 紀錄Reviewer
10上線後另開 docs-only PR 更新 SITEMAP(Status 維持 Approved;10.4)文件SD

每一步的對話、文件、審查結果範例見第 15 章案例一。

實務注意:第 1 步的 Brainstorm 最好由 SA 與 SD 一起參加——Elephant 問的業務問題 SD 答不出來,技術問題 SA 答不出來。

6.3 前端設計

設計文件中前端應寫到的內容(建議),以及 Goldfish 最常挑出的缺漏:

主題設計文件要寫常見 Goldfish finding
Component Architecture頁面元件與共用元件清單、props/emits 介面「ContactForm 與 ContactDialog 的責任重疊」(zoom-out)
Routing路由表、路由守衛、權限對應「沒寫無權限時導向哪裡」(implementation-readiness)
State ManagementPinia store 名稱、state 形狀、哪些資料不放 store「PII 明碼是否會留在 store 中」(design)
API IntegrationAPI client 位置、錯誤碼對應、重試策略「409 衝突時 UI 行為未定義」(design)
Error Handling全域錯誤處理、表單驗證錯誤顯示「後端驗證訊息與前端是否同一份 i18n key」
Authentication登入方式(OIDC)、token 存放位置「token 存 localStorage 的 XSS 風險未說明」
Authorization前端只做顯示控制,後端為準「把權限判斷只寫在前端」
i18n語系、key 命名規則「沒定義缺 key 時的 fallback」
RWD斷點、表格在手機上的呈現「50 位聯絡人的表格在手機上怎麼顯示」
Accessibility鍵盤操作、ARIA、對比「遮罩的手機號碼螢幕閱讀器會念出什麼」

Pinia store 在設計文件中的寫法(設計文件允許 API 與 schema,不寫實作;範例):

// 設計文件中的介面描述(不是實作)
interface ContactSummary {
  id: string;
  name: string;
  mobileMasked: string; // 例:0912-***-678,後端遮罩後回傳
  emailMasked: string;
  primary: boolean;
}

// useContactStore(frontend/src/stores/contact.ts)
// state: { byCustomer: Record<string, ContactSummary[]>, loading: boolean }
// 不在 store 保存 PII 明碼;明碼只在詳細頁元件的區域狀態中,離開頁面即丟棄

實務注意:「前端遮罩」不是安全控制。設計文件要寫明「遮罩由後端完成,前端只顯示」,否則資安審查應退回。

6.4 後端設計

採 Hexagonal(Ports & Adapters)分層,設計文件要寫:

主題要寫的內容審查重點
Layered/Clean Architecture模組(customer-api、customer-app、customer-domain、customer-infra)與依賴方向依賴只能向內(ArchUnit 驗證,6.6)
Domain ModelAggregate Root、Entity、Value Object、不變式「最多 50 位」「最多一位 Primary」寫在哪個類別
Application ServiceUse case 清單、交易邊界一個交易只改一個 Aggregate
RepositoryPort 介面(domain 層)與實作(infra 層)Port 不可出現 JPA 型別
REST Controller端點、HTTP 狀態碼、錯誤格式409/422/403 何時回傳
DTORequest/Response 欄位、遮罩欄位DTO 不進入 domain
Exception HandlingDomain exception → HTTP 對應表不洩漏 stack trace(OWASP 2025 A10)
Transaction Management@Transactional 放在 application 層、隔離等級、樂觀鎖並行設定 Primary 的競態
Security端點權限、PII 欄位權限、稽核事件預設拒絕(OWASP 2025 A01)

API 規格寫法(範例,設計文件 Technical Plan 中):

# docs/api/customer-contact.openapi.yaml(節錄)
paths:
  /api/customers/{customerId}/contacts:
    post:
      summary: 新增聯絡人
      security: [{ oidc: [CUSTOMER_EDIT] }]
      responses:
        "201": { description: 建立成功 }
        "409": { description: 已有主要聯絡人,或已達 50 位上限 }
        "422": { description: Email 格式錯誤 }

例外對應表(範例):

Domain ExceptionHTTPerror code
ContactLimitExceededException409CONTACT_LIMIT
PrimaryContactExistsException409PRIMARY_EXISTS
IllegalArgumentException(格式)422VALIDATION
AccessDeniedException403FORBIDDEN

實務注意:「並行時最多一位 Primary」是 Goldfish(egm-design)幾乎一定會問的問題。設計文件要同時寫應用層(樂觀鎖 @Version)與資料庫層(部分唯一索引)兩道防線,並說明哪一道是最後保證。

6.5 資料庫設計

ERD(範例):

erDiagram
    CRM_CUSTOMER ||--o{ CRM_CONTACT : has
    CRM_CUSTOMER {
        varchar id PK
        varchar name
        bigint version
        varchar tenant_id
    }
    CRM_CONTACT {
        uuid id PK
        varchar customer_id FK
        varchar tenant_id
        varchar name
        bytea mobile_enc
        bytea email_enc
        varchar email_hash
        boolean is_primary
        timestamp created_at
        varchar created_by
    }

DDL(範例,PostgreSQL;設計文件中的 schema,不是實作):

-- customer-infra/src/main/resources/db/migration/V12__contact.sql
CREATE TABLE crm_contact (
    id           UUID PRIMARY KEY,
    customer_id  VARCHAR(20) NOT NULL REFERENCES crm_customer(id),
    tenant_id    VARCHAR(20) NOT NULL,
    name         VARCHAR(100) NOT NULL,
    mobile_enc   BYTEA,
    email_enc    BYTEA NOT NULL,
    email_hash   CHAR(64) NOT NULL,
    is_primary   BOOLEAN NOT NULL DEFAULT FALSE,
    created_at   TIMESTAMP NOT NULL,
    created_by   VARCHAR(50) NOT NULL
);

-- 同一客戶只能有一位主要聯絡人(資料庫層最後防線)
CREATE UNIQUE INDEX ux_contact_primary ON crm_contact (customer_id) WHERE is_primary;
-- 同一客戶內 Email 唯一(以雜湊比對,避免明碼索引)
CREATE UNIQUE INDEX ux_contact_email ON crm_contact (customer_id, email_hash);
CREATE INDEX ix_contact_tenant ON crm_contact (tenant_id, customer_id);

設計文件要涵蓋:

主題要寫的內容
Table Design欄位、型別、NULL、預設值
Index查詢路徑對應的索引;唯一約束
Transaction寫入順序、鎖、隔離等級
Data IntegrityFK、CHECK、唯一索引
MigrationFlyway 版本號、可否回滾、大表變更策略
Multi-Tenanttenant_id 來源、每個查詢都要過濾、是否用 Row Level Security
Database Security加密欄位、金鑰管理、DB 帳號最小權限
跨資料庫Oracle/DB2/SQL Server 沒有 PostgreSQL 的部分索引語法時的替代(例如函數索引或 filtered index)

實務注意:部分唯一索引(WHERE is_primary)是 PostgreSQL 語法;SQL Server 用 filtered index、Oracle 常用函數索引模擬。設計文件若宣稱「支援四種資料庫」,Stage 9 應該要求每種資料庫的 DDL 寫法,否則違反 Zero-Decision Rule。

6.6 測試與品質

測試工具設計文件中要寫
Unit TestJUnit+AssertJ;Vitest每個不變式至少一個案例
Integration TestTestcontainers(PostgreSQL)migration 與唯一索引行為
API TestSpring MockMvc/RestTestClient;或 Postman/Newman每個狀態碼至少一個案例
E2E TestPlaywright每個 CUJ 一個 E2E
Performance TestGatling/k6NFR 中的 P95 目標
Security TestOWASP ZAP(DAST)、SAST、SCA掃描指令與通過門檻
Architecture TestArchUnit依賴方向規則

6.6.1 ArchUnit 架構測試(實測)

設計文件的 Technical Plan 寫了「adapter → app → domain,domain 不依賴框架」,就要有測試證明。以下 Lab 已實測(Maven 3.9.9、JDK 21、ArchUnit 1.5.1)。

📄 archunit-lab/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.acme.crm</groupId>
  <artifactId>archunit-lab</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- 3.5.3 drops results of non-method tests such as @ArchTest fields (SUREFIRE-2299) -->
    <surefire.version>3.5.4</surefire.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.tngtech.archunit</groupId>
      <artifactId>archunit-junit5</artifactId>
      <version>1.5.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.13.4</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire.version}</version>
      </plugin>
    </plugins>
  </build>
</project>

📄 archunit-lab/src/test/java/com/acme/crm/customer/ArchitectureTest.java

package com.acme.crm.customer;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.onionArchitecture;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

/**
 * Architecture rules taken from the design doc "Technical Plan":
 * adapter -> app -> domain; the domain depends on no framework.
 * Plain JUnit tests (not @ArchTest) so the build always reports them as tests.
 */
class ArchitectureTest {

    private static JavaClasses classes;

    @BeforeAll
    static void importClasses() {
        classes = new ClassFileImporter()
                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
                .importPackages("com.acme.crm.customer");
        if (classes.size() < 5) {
            throw new IllegalStateException("imported only " + classes.size() + " classes; check the package name");
        }
    }

    /**
     * If you copy this test into a project whose packages differ (for example
     * ..api.. / ..infra..), the other rules also fail, but with long violation
     * lists or "failed to check". This check names the wrong mapping directly.
     */
    @Test
    void everyMappedLayerHasClasses() {
        for (String pkg : new String[] {".domain", ".app", ".adapter.web", ".adapter.persistence"}) {
            long n = classes.stream().filter(c -> c.getPackageName().contains(pkg)).count();
            if (n == 0) {
                throw new AssertionError("no classes in layer package *" + pkg + "*; fix the layer mapping");
            }
        }
    }

    @Test
    void hexagonalLayersAreRespected() {
        onionArchitecture()
                .withOptionalLayers(true)   // no domain-service classes yet
                .domainModels("..domain..")
                .applicationServices("..app..")
                .adapter("web", "..adapter.web..")
                .adapter("persistence", "..adapter.persistence..")
                .check(classes);
    }

    @Test
    void domainHasNoFrameworkImports() {
        noClasses().that().resideInAPackage("..domain..")
                .should().dependOnClassesThat()
                .resideInAnyPackage("org.springframework..", "jakarta.persistence..")
                .check(classes);
    }
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/domain/Customer.java

package com.acme.crm.customer.domain;

import java.util.ArrayList;
import java.util.List;

public class Customer {
    public static final int MAX_CONTACTS = 50;
    private final String id;
    private final List<Contact> contacts = new ArrayList<>();

    public Customer(String id) {
        this.id = id;
    }

    public void addContact(Contact contact) {
        if (contacts.size() >= MAX_CONTACTS) {
            throw new ContactLimitExceededException(id);
        }
        if (contact.primary() && contacts.stream().anyMatch(Contact::primary)) {
            throw new PrimaryContactExistsException(id);
        }
        contacts.add(contact);
    }

    public String id() {
        return id;
    }

    public List<Contact> contacts() {
        return List.copyOf(contacts);
    }
}

📄 archunit-lab/src/test/java/com/acme/crm/customer/CustomerContactTest.java

package com.acme.crm.customer;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

import com.acme.crm.customer.domain.Contact;
import com.acme.crm.customer.domain.ContactLimitExceededException;
import com.acme.crm.customer.domain.Customer;
import com.acme.crm.customer.domain.PrimaryContactExistsException;
import org.junit.jupiter.api.Test;

class CustomerContactTest {

    @Test
    void rejectsFiftyFirstContact() {
        Customer c = new Customer("C001");
        for (int i = 0; i < Customer.MAX_CONTACTS; i++) {
            c.addContact(new Contact("n" + i, "n" + i + "@acme.com", false));
        }
        assertThrows(ContactLimitExceededException.class, () -> c.addContact(new Contact("x", "x@acme.com", false)));
        assertEquals(50, c.contacts().size());
    }

    @Test
    void rejectsSecondPrimary() {
        Customer c = new Customer("C001");
        c.addContact(new Contact("a", "a@acme.com", true));
        assertThrows(PrimaryContactExistsException.class, () -> c.addContact(new Contact("b", "b@acme.com", true)));
    }

    @Test
    void rejectsInvalidEmail() {
        assertThrows(IllegalArgumentException.class, () -> new Contact("a", "not-an-email", false));
    }
}

📄 archunit-lab/src/test/java/com/acme/crm/customer/ArchRuleFieldTest.java

package com.acme.crm.customer;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

/**
 * The common ArchUnit style: a rule declared on a field.
 * With maven-surefire-plugin 3.5.3 this class reports "Tests run: 0" and a
 * violation does not fail the build; 3.5.4 reports it correctly.
 */
@AnalyzeClasses(packages = "com.acme.crm.customer", importOptions = ImportOption.DoNotIncludeTests.class)
class ArchRuleFieldTest {

    @ArchTest
    static final ArchRule domainDoesNotDependOnAdapters = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAPackage("..adapter..");
}

設計文件第 4、5 項定義的兩個例外類別(1.1 起 Lab 與設計一致,測試斷言具體型別,而不是 IllegalStateException):

📄 archunit-lab/src/main/java/com/acme/crm/customer/domain/ContactLimitExceededException.java

package com.acme.crm.customer.domain;

/** Thrown when a customer already has {@link Customer#MAX_CONTACTS} contacts (design: 422). */
public class ContactLimitExceededException extends RuntimeException {
    public ContactLimitExceededException(String customerId) {
        super("contact limit exceeded: " + customerId);
    }
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/domain/PrimaryContactExistsException.java

package com.acme.crm.customer.domain;

/** Thrown when a second primary contact is added (design: 409). */
public class PrimaryContactExistsException extends RuntimeException {
    public PrimaryContactExistsException(String customerId) {
        super("primary contact already exists: " + customerId);
    }
}

其餘 Contact.java、CustomerRepository.java、AddContactService.java、ContactController.java、InMemoryCustomerRepository.java 見附錄 B。

執行(Shell):

cd archunit-lab
mvn -B test | grep -E "Tests run:.*in com|BUILD"

實測結果(surefire 3.5.4):

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchRuleFieldTest
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchitectureTest
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.CustomerContactTest
BUILD SUCCESS

反例 1:依賴方向違規。 把附錄 B.4 的 negative/BadShortcut.java 複製到 domain 套件(domain 直接 new 一個 persistence adapter),測試必須失敗;做完記得刪除:

cp negative/BadShortcut.java src/main/java/com/acme/crm/customer/domain/
mvn -B test | grep -E "Tests run:.*in com|BUILD|BadShortcut.java"
rm src/main/java/com/acme/crm/customer/domain/BadShortcut.java
Tests run: 1, Failures: 1, Errors: 0, Skipped: 0 <<< FAILURE! -- in com.acme.crm.customer.ArchRuleFieldTest
Constructor <com.acme.crm.customer.domain.BadShortcut.<init>()> calls constructor <com.acme.crm.customer.adapter.persistence.InMemoryCustomerRepository.<init>()> in (BadShortcut.java:6)
Tests run: 3, Failures: 1, Errors: 0, Skipped: 0 <<< FAILURE! -- in com.acme.crm.customer.ArchitectureTest
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.CustomerContactTest
BUILD FAILURE

反例 2:照抄到套件名稱不同的專案。 本 Lab 的層是 ..adapter.web..、..adapter.persistence..;第 5.2 節範例設計的模組卻是 customer-api(..api..)、customer-infra(..infra..)。實測把 ContactController 搬到 ..api..:

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchRuleFieldTest
Tests run: 3, Failures: 2, Errors: 0, Skipped: 0 <<< FAILURE! -- in com.acme.crm.customer.ArchitectureTest
java.lang.AssertionError: no classes in layer package *.adapter.web*; fix the layer mapping
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.CustomerContactTest
BUILD FAILURE

這個反例也是「審查 AI 審查結果」的教材。本手冊 1.1 的獨立 Goldfish 審查(附錄 E.3)推論:「照抄到 api/infra 專案時 adapter 層是空的,加上 withOptionalLayers(true),規則會空轉通過。」實測結果不成立:

情境(使用 1.0 版的 ArchitectureTest,沒有層檢查)結果原因
web→api、persistence→infra 全部改名hexagonalLayersAreRespected 失敗onion 規則限制「誰可以存取 app 層」,層外的 ..api.. 類別存取 app 被判違規
domain→model 改名,並放入 BadShortcut兩個測試都失敗onion 規則抓到存取 adapter;domainHasNoFrameworkImports 報 failed to check:ArchUnit 預設 archRule.failOnEmptyShould=true,that() 沒有符合任何類別時規則直接失敗

所以 everyMappedLayerHasClasses 不是「唯一的防線」,它的價值在於錯誤訊息直接指出「層的對應錯了」,而不是一長串 violation。Goldfish 的推論方向合理,但結論要用反例實測後才能採用;這正是 egm-resolve 中 CONTEST 的用法:用 reviewer 也能檢查的證據反駁。

實務注意:AI 產生架構測試時,最常見的錯誤是「層的套件名稱對不上真實專案」。審查時請拿設計文件的 File Boundary 路徑,逐一比對測試中的套件字串;不要在 archunit.properties 中把 archRule.failOnEmptyShould 改成 false,那會關掉 ArchUnit 內建的空規則保護。

6.6.2 實測抓到的假綠燈:surefire 3.5.3 吞掉 @ArchTest 的結果

1.0 版發現:用 ArchUnit 官方常見寫法 @AnalyzeClasses+@ArchTest static final ArchRule 時,本機(Maven 3.9.9、surefire 3.5.3)一律顯示 Tests run: 0,故意放入違規也是 BUILD SUCCESS。當時根因不明,1.0 寫成「規則根本沒有執行」。

1.1 查明根因:規則有執行,是 surefire 3.5.3 沒有回報結果。 排查過程本身就是一個好的教材,因為每一步都在排除一個假設:

#假設實驗結果
1JUnit Platform 版本與 ArchUnit 不相容(ArchUnit 1.5.1 以 junit-platform-engine 1.14.4 編譯,專案解析到 1.13.4)升級 junit-jupiter 到 5.14.1仍是 0,排除
2類別或欄位可見性改成 public仍是 0,排除
3surefire 類別載入方式-Dsurefire.useManifestOnlyJar=false、-DforkCount=0、-Dsurefire.useSystemClassLoader=false仍是 0,排除
4ArchUnit engine 本身沒有找到規則改用 JUnit ConsoleLauncher 直接執行1 tests found、1 tests failed:engine 正常
5規則有沒有執行規則的 condition 每檢查一個類別就寫一行到檔案檔案有 6 行,規則有執行
6surefire 版本在 pom 實際改版本(-Dsurefire.version 在 pom 寫死版本時無效)3.0.0、3.2.5、3.5.4 都正確回報失敗,只有 3.5.3 回報 0

上游佐證:

  • apache/maven-surefire#834(2025-09-13 關閉):3.5.3 的回歸讓「不是 method 型的測試」(ArchUnit 的 field、Cucumber 的 scenario)不被計入,失敗也不會讓 build 失敗。留言中有使用者寫「ArchUnit tests are affected as well」,也有人回報 Spring Boot 3.4.5 把 surefire 從 3.5.2 帶到 3.5.3 後開始出現。
  • 修正:PR #828「[SUREFIRE-2298] fix xml output with junit 5 nested classes (fix integration with Cucumber and Archunit)」,2025-09-04 合併;以 gh api repos/apache/maven-surefire/compare/<merge commit>...surefire-3.5.4 確認已包含在 3.5.4 tag。
  • 審查網路資訊的提醒:issue 留言引用的 JIRA SUREFIRE-2299 在 2026-11-17 查詢時仍顯示 Open、沒有 Fix Version(Maven 已改用 GitHub issues)。「JIRA 還開著」不代表沒修好,「issue closed」也不代表已發布;要看修正 commit 是否在你使用的 tag 裡,再用反例實測。

企業專案常透過 spring-boot-starter-parent 繼承 surefire 版本(屬性 maven-surefire-plugin.version),因此可能在沒有修改任何測試的情況下中招。本機 Maven repository 中 Spring Boot 3.5.8 的 parent 帶 3.5.4、4.0.9~4.1.2 帶 3.5.6,都已包含修正;仍在 3.4.x/3.5.x 早期版本的專案請自行確認。

1.1 的 Lab 把 surefire 版本改成屬性,讓你可以親手重現(Shell):

cd archunit-lab
mvn -B test -Dsurefire.version=3.5.4 | grep -E "Tests run:.*ArchRuleFieldTest|BUILD"
mvn -B test -Dsurefire.version=3.5.3 | grep -E "Tests run:.*ArchRuleFieldTest|BUILD"

實測輸出(「反例」是把 ArchRuleFieldTest 的規則改成必定違規):

$ mvn -B test -Dsurefire.version=3.5.4   # 正常 Lab
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchRuleFieldTest
BUILD SUCCESS

$ mvn -B test -Dsurefire.version=3.5.3   # 正常 Lab
Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchRuleFieldTest
BUILD SUCCESS

$ mvn -B test -Dsurefire.version=3.5.4   # 反例:規則改成必定違規
Tests run: 1, Failures: 1, Errors: 0, Skipped: 0 <<< FAILURE! -- in com.acme.crm.customer.ArchRuleFieldTest
BUILD FAILURE

$ mvn -B test -Dsurefire.version=3.5.3   # 反例:規則改成必定違規
Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 -- in com.acme.crm.customer.ArchRuleFieldTest
BUILD SUCCESS

對策(建議,三道防線):

  1. 鎖定 surefire ≥ 3.5.4(或 ≤ 3.5.2)。使用 Spring Boot parent 時,在自己的 pom 覆寫 maven-surefire-plugin.version 屬性,並用 mvn help:effective-pom | grep -A1 maven-surefire-plugin 確認實際版本。
  2. 架構規則用 ClassFileImporter+JUnit @Test(6.6.1 的 ArchitectureTest)。這種寫法是 method 型測試,不受這類回報問題影響;@BeforeAll 檢查匯入的類別數,everyMappedLayerHasClasses 檢查每一層非空。
  3. CI 檢查每個架構測試類別的 Tests run 大於 0:
for f in target/surefire-reports/*Arch*Test.txt; do
  grep -q "Tests run: [1-9]" "$f" || { echo "architecture test did not report: $f"; exit 1; }
done

實務注意:這是 AI 時代特別要注意的審查習慣。AI 寫的測試「通過」不代表有執行,「有執行」也不代表有被回報。每一條新規則都要用反例證明它會讓 build 失敗;第一次導入或升級 build plugin 時要重做一次。

6.6.3 E2E(Playwright)對應 CUJ

設計文件的每個 CUJ 對應一個 E2E 測試名稱,讓 QA 與 Goldfish 都能追蹤(範例):

// frontend/e2e/contact.spec.ts
import { test, expect } from '@playwright/test';

test('CUJ 1: 業務新增主要聯絡人', async ({ page }) => {
  await page.goto('/customers/C001/contacts');
  await page.getByRole('button', { name: '新增聯絡人' }).click();
  await page.getByLabel('姓名').fill('王小明');
  await page.getByLabel('Email').fill('ming@example.com');
  await page.getByLabel('主要聯絡人').check();
  await page.getByRole('button', { name: '儲存' }).click();
  await expect(page.getByRole('row', { name: /王小明/ })).toContainText('主要');
});

(🧪:E2E 範例需要實際前端專案,本手冊未執行;Playwright 用法見同目錄〈Playwright 教學手冊〉。)

本章注意事項:

  • 設計文件中的每一個版本號都要有官方來源;Goldfish 不會替你查證。
  • Verification Plan 的每條指令都要能在 CI 跑;寫不出指令的驗證項目代表計畫還沒完成。

6.7 本章 AI 產出審查

檢查點好例壞例怎麼抓
版本來源每個版本附官方網址「使用最新版」搜尋「最新」「latest」
架構測試有執行Tests run ≥ 1,反例會讓 build 失敗Tests run: 0;surefire 3.5.36.6.2 的 for 迴圈;mvn help:effective-pom 查 surefire 版本
並行控制應用層+資料庫層兩道防線「先查詢再新增」搜尋設計文件的「並行」「concurrent」
PII後端遮罩、加密欄位、金鑰來源「前端遮罩」搜尋「mask」「遮罩」出現在哪一層
多資料庫 DDL每種資料庫各一段只有 PostgreSQL 卻宣稱支援四種比對 NFR 與 DDL 數量

第 7 章:EGM 逆向工程(Reverse Engineering)實戰

逆向工程的目標是把「只存在於程式碼與老員工腦中」的知識,變成 Elephant 可以讀、Goldfish 可以驗證、人類可以核准 的文件。EGM 沒有專門的逆向工程 Skill,本章示範如何組合 egm-bootstrap、egm-review-loop、egm-drift-report 與公司自建的證據檢查。

7.1 逆向工程的目的

目的典型觸發主要產出
舊系統文件缺失稽核要求、交接System Overview、Module Dependency
原始開發人員已離職維運只剩一人看得懂Business Rules、Exception Handling
業務邏輯不明確客訴、計算結果爭議Business Flow、Business Rules(附證據)
程式碼結構複雜新人上手要三個月模組 README、程式碼導覽
系統依賴關係不清楚要拆服務、要搬機房Interface Specification、Module Dependency
準備重構/升級/重新開發第 8 章 Framework 升級前As-Is Architecture、行為基準(golden master)

實務注意:先寫下「這次逆向工程是為了什麼決策」。為升級做的逆向工程和為稽核做的,要求的深度不同;沒有目的的逆向工程會變成無止境的文件生產。

7.2 逆向工程流程

flowchart TD
    S1["1 分析 Repository<br/>語言、build、目錄"] --> S2["2 執行 egm-bootstrap<br/>產生模組 README"]
    S2 --> S3["3 人工補齊 Bootstrap 漏掉的目錄<br/>.vue、.jsp、XML mapper"]
    S3 --> S4["4 程式入口<br/>main、web.xml、Controller、Listener、Job"]
    S4 --> S5["5 前端畫面與路由"]
    S4 --> S6["6 後端 API"]
    S6 --> S7["7 Business Logic"]
    S7 --> S8["8 資料庫 Schema"]
    S8 --> S9["9 Stored Procedure"]
    S4 --> S10["10 Batch Job"]
    S4 --> S11["11 MQ 與外部介接"]
    S7 --> S12["12 交易與例外處理"]
    S5 --> S13["13 系統架構文件"]
    S9 --> S13
    S10 --> S13
    S11 --> S13
    S12 --> S14["14 業務流程文件"]
    S13 --> S15["15 證據檢查+Goldfish 審查<br/>egm_evidence_check.py、egm-review-loop"]
    S14 --> S15
    S15 -->|"有 Blocker"| S7
    S15 --> S16["16 業務單位人工確認<br/>處理所有【待確認】"]
    S16 --> S17["17 commit 文件<br/>定期 drift report"]

步驟與 EGM 工具對應:

#步驟工具產出
1分析 RepositoryShell(git ls-files、副檔名統計)技術盤點表
2執行 Bootstrap/egm:egm-bootstrap <path>(既有 README 不想動時加 target_filename=EGM.md)各層 README/EGM.md
3建立模組說明人工補 Bootstrap 修剪掉的目錄補充 README
4~12逐項分析Elephant 對話(載入 Bootstrap 產出);每個結論附 [file:symbol]各分析文件
13~14架構與流程文件ElephantSystem Architecture、Business Flow
15獨立審查egm_evidence_check.py+/egm:egm-review-loop(codebase_details+re-implementation-standard+公司證據標準)審查報告
16人工確認業務單位、原開發者簽核紀錄
17持續維護/egm:egm-drift-report docs/legacy/drift 報告

實務注意:步驟 4~12 是 Elephant 的工作,不是 Goldfish 的。Goldfish 在步驟 15 才出場,負責「只看文件與程式碼,能不能驗證文件說的是真的」。

7.3 舊系統技術案例

7.3.1 Bootstrap 對各技術的覆蓋

egm-bootstrap 只把特定副檔名視為原始碼(官方,skills/egm-bootstrap/SKILL.md Step 2.3)。對照企業常見舊技術:

技術主要檔案Bootstrap 視為原始碼?需要人工補的部分
VB6.bas、.cls、.frm否全部
VB.NET.vbv0.1.1 否;main 是(#324).config、.resx
C#.cs是app.config、web.config
ASP.NET Web Forms.aspx、.ascx、.aspx.cs只有 .cs 是.aspx 畫面與事件綁定
ASP.NET MVC/Razor.cshtml、.razor、.csv0.1.1 只有 .cs;main 全部是(#324)v0.1.1 時補畫面檔
Java.java是—
JSP.jsp、.tag否畫面、<jsp:include>、表單欄位
Servlet.java+web.xml.java 是,web.xml 否URL 對應
Spring(XML 設定).java+applicationContext.xmlXML 否Bean 組裝、AOP、交易設定
Spring Boot.java+application.yml.yml 否設定值、Profile
MyBatis.java+*Mapper.xmlXML 否所有 SQL
Oracle PL/SQL.sql、.pks、.pkb只有 .sql 是.pks/.pkb 檔
DB2 Stored Procedure.sql、.db2只有 .sql 是其他副檔名
SQL Server SP.sql是—
IBM MQ.java/.cs+設定檔程式是Queue 名稱多在設定檔
Spring Batch.java+Job XMLXML 否XML 定義的 Step 流程
Vue 2.vue、.js只有 .js 是.vue 單檔元件

驗證方式:在 EGM repo 執行 git show v0.1.1:skills/egm-bootstrap/SKILL.md | grep -n -A2 "Managed & Enterprise"(換成你實際使用的版本)查看清單。

1.1 實跑時,Elephant 對清單外的 .jsp、.vue、mapper XML 目錄刻意偏離規則仍產生了文件,並在回報中揭露(5.8.2、5.8.4)。這張表是「規則」,不是「保證的結果」;每次都要以實際產出為準。

實務注意:這張表說明「Bootstrap 產出的 README 不完整」不是 AI 偷懶,而是規則本來就沒涵蓋。逆向工程計畫要預留人工補齊的時間。

7.3.2 各技術的分析重點

技術入口在哪要追的呼叫鏈證據寫法範例
VB/VB.NETSub Main、表單 _Click 事件事件 → 模組函式 → ADO 指令[src/Loan/frmApprove.vb:btnApprove_Click]
C#/ASP.NETGlobal.asax、Controller、Page_LoadController → Service → Repository/SqlCommand[Web/Controllers/LoanController.cs:Approve]
JSP/Servletweb.xml 的 <servlet-mapping>URL → Servlet doPost → DAO → JSP forward[WEB-INF/web.xml:L40-L48]
Spring@RequestMapping、XML beanController → @Service → @Transactional 邊界[src/.../LoanService.java:approve]
Oracle PL/SQLPackage spec 的公開程序程序 → UPDATE/INSERT 的表 → 觸發程序(Trigger)[db/PKG_LOAN.sql:SP_MANUAL_REVIEW]
DB2 SPCREATE PROCEDURE參數 → 游標 → COMMIT 時機[db2/LOAN_SP.sql:L10-L55]
SQL Server SPCREATE PROCEDUREBEGIN TRAN/COMMIT/TRY…CATCH[sql/usp_ApproveLoan.sql:BEGIN TRAN]
IBM MQMessageListener、MQQueue.get收訊 → 解析 → 業務 → 回覆佇列[mq/LoanListener.java:onMessage]
Spring Batch@Bean Job、Job XMLReader → Processor → Writer、skip/retry 策略[batch/LoanJobConfig.java:loanStep]

實務注意:交易邊界最容易被 AI 猜錯。Java 看 @Transactional 與 XML tx:advice;PL/SQL 看 COMMIT 出現在哪一層(呼叫端還是程序內);SQL Server 看 BEGIN TRAN 與 XACT_ABORT。每一條交易結論都要附證據。

7.4 逆向工程文件產出

文件內容建議檔名審查 standard
System Overview系統目的、使用者、上下游docs/legacy/00-overview.mdre-implementation-standard
System Architecture部署、分層、技術元件01-architecture.md同上+公司證據標準
Module Dependency模組相依圖(Mermaid)02-modules.md同上
Business Flow主要流程(flowchart)03-business-flow.md同上
Sequence Diagram關鍵交易的呼叫序列04-sequences.md同上
API Specification端點、參數、回應、錯誤05-api.md 或 OpenAPI同上
Database ERD表與關聯06-erd.md同上
Data Dictionary欄位意義、代碼值07-data-dictionary.md同上
Batch SpecificationJob、排程、輸入輸出、重跑08-batch.md同上
Interface SpecificationMQ、檔案、SFTP、外部 API09-interfaces.md同上
Business RulesBR 編號、規則、證據、狀態10-business-rules.md公司證據標準
Exception Handling錯誤碼、重試、補償11-exceptions.md同上
Security Design認證、授權、加密、稽核12-security.md公司 security standard

Business Rules 範本(建議;可被 egm_evidence_check.py 檢查):

| 編號 | 規則 | 證據 | 狀態 |
| --- | --- | --- | --- |
| BR-01 | 信用分數 < 600 直接拒絕 | [src/main/java/com/acme/loan/LoanApprovalService.java:creditScore < 600] | 【已確認】 |
| BR-04 | 門檻可能依分行不同 | 程式中為常數,未見分行參數 | 【推測】 |
| BR-05 | 人工審核 SLA 為 2 個工作天 | 程式與 SQL 皆無此資訊 | 【待確認】 |

三種狀態:

標記意義能不能進入升級設計
【已確認】有程式碼證據可以
【推測】AI 或人推論,沒有直接證據不可以,要先確認或明確列為假設
【待確認】需要業務單位或原開發者回答不可以

實務注意:EGM 的 re-implementation-standard 要求「every behaviorally significant contract must be explicit」。Business Rules 文件就是這個標準最直接的應用。

7.5 逆向工程注意事項

規則為什麼怎麼做
不可只憑類別名稱推論業務邏輯VipCustomerService 可能早就沒有 VIP 邏輯Bootstrap scout 規則同樣禁止(「Never infer … from file or directory names alone」)
不可將 AI 推測當成事實AI 很會寫「看起來合理」的流程所有結論標記【已確認】/【推測】/【待確認】
必須追蹤實際程式呼叫介面可能有多個實作、反射呼叫、XML 組裝從入口一路追到 SQL;IDE 的 Call Hierarchy 輔助
必須確認 SQL、SP 與交易業務規則常藏在 SP每張被寫入的表都要找到寫入它的語句
必須確認外部介接設定檔裡的端點可能依環境不同列出每個環境的設定來源
必須標記不確定的規則讓業務單位知道要回答什麼【待確認】清單交 PM 追蹤
必須保留程式碼證據與位置讓 Goldfish 與稽核能重新驗證[path:symbol] 或 [path:L10-L42]
Goldfish 要能檢查一致性文件與程式在同一個 repo 或可讀的路徑文件放在舊系統 repo 的 docs/legacy/

7.5.1 證據檢查工具(建議,公司自建)

📄 tools/egm_evidence_check.py

#!/usr/bin/env python3
"""egm_evidence_check.py - verify code citations in reverse-engineering docs.

Company convention (not part of EGM): every confirmed statement cites code as
  [relative/path.ext:SymbolName]   or   [relative/path.ext:L120-L168]
This follows the egm-bootstrap scout rule "cite the exact [file:symbol_or_flag]".
Statement tags:
  【已確認】 confirmed from code -> must carry at least one citation
  【推測】   AI inference        -> allowed without citation, counted
  【待確認】 needs a domain owner -> allowed without citation, counted

Rules (exit 1 on any FAIL):
  E1 cited file exists under --root
  E2 cited symbol appears in that file / cited line range is inside the file
  E3 a 【已確認】 line has no citation
  E4 a business rule row ("| BR-") has neither a citation nor 【推測】/【待確認】

Usage: python egm_evidence_check.py DOC.md [DOC.md ...] --root path/to/legacy-repo
"""
import argparse
import re
import sys
from pathlib import Path

CITE = re.compile(r"\[([A-Za-z0-9_./-]+\.[A-Za-z0-9]+):([^\]]+)\](?!\()")
LINES = re.compile(r"^L(\d+)(?:-L(\d+))?$")
CONFIRMED, GUESS, OPEN = "【已確認】", "【推測】", "【待確認】"


def check_doc(doc, root):
    fails, stats = [], {"cites": 0, "confirmed": 0, "guess": 0, "open": 0}
    cache = {}
    fence = False
    for no, line in enumerate(doc.read_text(encoding="utf-8").splitlines(), 1):
        if line.lstrip().startswith("```"):
            fence = not fence
            continue
        if fence:
            continue
        cites = CITE.findall(line)
        stats["confirmed"] += line.count(CONFIRMED)
        stats["guess"] += line.count(GUESS)
        stats["open"] += line.count(OPEN)
        for rel, target in cites:
            stats["cites"] += 1
            path = (root / rel).resolve()
            if not path.is_file():
                fails.append(f"{doc.name}:{no} E1 file not found: {rel}")
                continue
            if path not in cache:
                cache[path] = path.read_text(encoding="utf-8", errors="replace").splitlines()
            body = cache[path]
            m = LINES.match(target)
            if m:
                end = int(m.group(2) or m.group(1))
                if end > len(body):
                    fails.append(f"{doc.name}:{no} E2 line {end} beyond {rel} ({len(body)} lines)")
            elif not any(target in b for b in body):
                fails.append(f"{doc.name}:{no} E2 symbol '{target}' not in {rel}")
        if CONFIRMED in line and not cites:
            fails.append(f"{doc.name}:{no} E3 confirmed statement without citation")
        if line.lstrip().startswith("| BR-") and not cites and GUESS not in line and OPEN not in line:
            fails.append(f"{doc.name}:{no} E4 business rule without evidence or tag")
    return stats, fails


def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("docs", nargs="+")
    ap.add_argument("--root", required=True)
    args = ap.parse_args(argv)
    root = Path(args.root).resolve()
    total = 0
    for d in args.docs:
        stats, fails = check_doc(Path(d), root)
        print(f"{Path(d).name}: cites={stats['cites']} confirmed={stats['confirmed']} "
              f"guess={stats['guess']} open={stats['open']}")
        for f in fails:
            print(f"FAIL {f}")
        total += len(fails)
    print("EVIDENCE PASS" if total == 0 else f"EVIDENCE FAIL ({total})")
    return 1 if total else 0


if __name__ == "__main__":
    sys.exit(main())

測試用的舊系統程式(fixture):

📄 fixtures/legacy/src/main/java/com/acme/loan/LoanApprovalService.java

package com.acme.loan;

import java.math.BigDecimal;

public class LoanApprovalService {

    static final BigDecimal AUTO_APPROVE_LIMIT = new BigDecimal("300000");

    private final LoanDao loanDao;

    public LoanApprovalService(LoanDao loanDao) {
        this.loanDao = loanDao;
    }

    public String approve(String applicationNo, BigDecimal amount, int creditScore) {
        if (creditScore < 600) {
            loanDao.updateStatus(applicationNo, "REJECTED");
            return "REJECTED";
        }
        if (amount.compareTo(AUTO_APPROVE_LIMIT) <= 0) {
            loanDao.updateStatus(applicationNo, "APPROVED");
            return "APPROVED";
        }
        loanDao.callProcedure("PKG_LOAN.SP_MANUAL_REVIEW", applicationNo);
        return "MANUAL_REVIEW";
    }
}

📄 fixtures/legacy/db/PKG_LOAN.sql

CREATE OR REPLACE PACKAGE BODY PKG_LOAN AS
  PROCEDURE SP_MANUAL_REVIEW(p_app_no IN VARCHAR2) IS
  BEGIN
    UPDATE LOAN_APPLICATION SET STATUS = 'PENDING_REVIEW', UPDATED_AT = SYSDATE
     WHERE APP_NO = p_app_no;
    INSERT INTO LOAN_REVIEW_QUEUE (APP_NO, CREATED_AT) VALUES (p_app_no, SYSDATE);
  END SP_MANUAL_REVIEW;
END PKG_LOAN;
/

好例文件:

📄 fixtures/re_doc_good.md

# 貸款核准 Business Rules(逆向工程)

| 編號 | 規則 | 證據 | 狀態 |
| --- | --- | --- | --- |
| BR-01 | 信用分數 < 600 直接拒絕 | [src/main/java/com/acme/loan/LoanApprovalService.java:creditScore < 600] | 【已確認】 |
| BR-02 | 金額 ≤ 300,000 自動核准 | [src/main/java/com/acme/loan/LoanApprovalService.java:AUTO_APPROVE_LIMIT] | 【已確認】 |
| BR-03 | 超過門檻進人工審核佇列 | [db/PKG_LOAN.sql:LOAN_REVIEW_QUEUE] [db/PKG_LOAN.sql:L2-L7] | 【已確認】 |
| BR-04 | 門檻 300,000 可能依分行不同 | 程式中為常數,未見分行參數 | 【推測】 |
| BR-05 | 人工審核 SLA 為 2 個工作天 | 程式與 SQL 皆無此資訊,需授信部確認 | 【待確認】 |

壞例文件(AI 初稿常見錯誤):

📄 fixtures/re_doc_bad.md

# 貸款核准 Business Rules(AI 初稿,未驗證)

| 編號 | 規則 | 證據 | 狀態 |
| --- | --- | --- | --- |
| BR-01 | 信用分數 < 650 直接拒絕 | [src/main/java/com/acme/loan/LoanApprovalService.java:creditScore < 650] | 【已確認】 |
| BR-02 | 金額 ≤ 300,000 自動核准 | [src/main/java/com/acme/loan/LoanService.java:AUTO_APPROVE_LIMIT] | 【已確認】 |
| BR-03 | 人工審核由 SP_MANUAL_REVIEW 執行 | [db/PKG_LOAN.sql:L2-L40] | 【已確認】 |
| BR-04 | VIP 客戶免審 | 由類別名稱推論 | |

貸款核准會寫入 LOAN_HISTORY。【已確認】

執行(Shell):

python tools/egm_evidence_check.py fixtures/re_doc_good.md --root fixtures/legacy
python tools/egm_evidence_check.py fixtures/re_doc_bad.md --root fixtures/legacy

實測輸出:

re_doc_good.md: cites=4 confirmed=3 guess=1 open=1
EVIDENCE PASS
re_doc_bad.md: cites=3 confirmed=4 guess=0 open=0
FAIL re_doc_bad.md:5 E2 symbol 'creditScore < 650' not in src/main/java/com/acme/loan/LoanApprovalService.java
FAIL re_doc_bad.md:6 E1 file not found: src/main/java/com/acme/loan/LoanService.java
FAIL re_doc_bad.md:7 E2 line 40 beyond db/PKG_LOAN.sql (9 lines)
FAIL re_doc_bad.md:8 E4 business rule without evidence or tag
FAIL re_doc_bad.md:10 E3 confirmed statement without citation
EVIDENCE FAIL (5)

壞例抓到的五種錯誤,正是 AI 逆向工程最常見的問題:數字寫錯(650 vs 600)、類別名稱編造(LoanService)、行號範圍超出檔案、從類別名稱推論規則(「VIP 客戶免審」)、沒有證據就標「已確認」(LOAN_HISTORY 表根本不存在)。

實務注意:證據檢查只證明「引用的東西存在」,不證明「規則描述正確」。BR-01 引用 creditScore < 600 存在,但「直接拒絕」這個解讀仍要 Goldfish(codebase_details)與人工確認。

7.5.2 完整逆向工程操作範例

情境:貸款核准模組(Java+Oracle PL/SQL),準備升級前要建立文件。

步驟 1:技術盤點(Shell)

cd loan-service
git ls-files | sed -n 's/.*\.\([A-Za-z0-9]*\)$/\1/p' | sort | uniq -c | sort -rn | head -15

步驟 2:Bootstrap(Claude Code 對話框)

/egm:egm-bootstrap src/main/java/com/acme/loan target_filename=EGM.md

目錄超過 15 個時會先詢問;選「Yes, proceed」前確認範圍正確。

步驟 3:補齊 Bootstrap 沒處理的檔案(Shell)

# 找出有 .jsp/.xml/.pkb 但沒有 EGM.md 的目錄
git ls-files '*.jsp' '*.xml' '*.pkb' '*.pks' | xargs -n1 dirname | sort -u | while read -r d; do
  [ -f "$d/EGM.md" ] || echo "NEED-DOC $d"
done

步驟 4~12:在 Elephant 中逐項分析(Claude Code 對話框)

請讀 src/main/java/com/acme/loan/EGM.md 與 db/ 目錄,產生 docs/legacy/10-business-rules.md。
規則:
1. 只寫你在程式碼中看到的規則,每條附 [相對路徑:符號] 或 [相對路徑:L起-L迄],標【已確認】。
2. 推論標【推測】並說明推論依據;需要業務單位回答的標【待確認】。
3. 不得從類別名稱、表名推論規則。
4. 追到每一張被 UPDATE/INSERT 的表,寫出是哪個語句寫入。

步驟 15:證據檢查+Goldfish 審查

python tools/egm_evidence_check.py docs/legacy/*.md --root .
/egm:egm-review-loop
TargetFile: docs/legacy/10-business-rules.md
SemanticTarget: full file
Reviewers: [codebase_details, comprehension]
Standards: {"codebase_details": "re-implementation-standard", "comprehension": "docs/standards/reverse-engineering-evidence-standard.md"}
GoldfishContext: [src/main/java/com/acme/loan/, db/]

參數寫法依據(官方,skills/egm-review-loop/SKILL.md「Path & Standard Resolution Logic」):

參數官方定義本例寫法為何正確
Reviewers「reviewer shortname (e.g., design_critic, structural, style, implementation_readiness, codebase_details, comprehension, zoom_out) to agents/{name}.md」review-loop 用的是檔名;frontmatter 的 egm-design 是 Claude Code 的 subagent 類型名稱,兩者用途不同(2.4)
Standardsshortname 對應 resources/document_standards/{name}.md;「If the name contains a slash (/), treat it as an absolute or workspace-relative path」官方 standard 用 shortname,公司 standard 用含 / 的路徑
GoldfishContext「A reading list (source files, directories, or documentation URLs)」可以放目錄

壞例:Reviewers: [egm-design](review-loop 會去找 agents/egm-design.md,這個檔案不存在);Standards: {"comprehension": "reverse-engineering-evidence-standard"}(沒有 /,會被當成官方 standard 名稱)。檢查方式(Shell,在 EGM repo):

ls agents/codebase_details.md agents/comprehension.md                          # 兩個都要存在
ls resources/document_standards/re-implementation-standard.md                  # 官方 shortname

步驟 3 列出的 NEED-DOC 目錄要人工補寫 EGM.md。範本可以參考第 5.8.4 節 1.1 實跑產生的 jsp/EGM.md:Overview、Interface、Invariants、Side Effects 四段,每條附 [檔案:符號] 出處,寫不出出處的不要寫。

步驟 16:把【待確認】清單交給業務單位(Shell)

grep -n '【待確認】' docs/legacy/*.md > docs/legacy/open-questions.txt

步驟 17:commit 並排入每週 Drift Report。

本章注意事項:

  • Goldfish 審查逆向工程文件時必須能讀到舊系統原始碼;文件與程式放在不同 repo 時,要把程式碼路徑列入 GoldfishContext。
  • 舊系統常含個資樣本資料(測試 SQL、匯出檔)。逆向前先用 .egmignore/.gitignore 排除,並確認公司核准把該程式碼交給 AI 服務(第 10.11 節)。

7.6 本章 AI 產出審查

檢查點好例壞例怎麼抓
證據存在每條【已確認】都有可解析的引用引用不存在的類別egm_evidence_check.py E1、E2
推論標示「【推測】門檻可能依分行不同」「VIP 客戶免審」無標記E4
交易邊界「COMMIT 由呼叫端 LoanDao.commit 執行 [..]」「此程序為獨立交易」無證據人工抽查+codebase_details
覆蓋率JSP、XML mapper 都有說明只有 Java 有 README7.5.2 步驟 3 的指令
數字與程式常數一致600 寫成 650E2(引用原文字串)

第 8 章:EGM Framework 升級與系統現代化實戰

Framework 升級的難點不是改程式,而是「不知道會壞在哪裡」。EGM 在升級中的價值是:把升級計畫寫成可被陌生人執行與驗證的文件,並讓 Goldfish 在動手前找出缺漏的 Breaking Change 與回滾步驟。

本章著重 EGM 流程;各框架的技術細節請見同 repo 手冊:Spring boot 4.x升版教學、Java25升版教學、code-modernization 教學手冊、Claude Code Migration Kit 教學手冊。

8.1 升級前分析

面向要收集的資料怎麼收集EGM 工具
現有系統架構模組、分層、部署方式Bootstrap+人工補齊egm-bootstrap
Framework 版本Spring Boot、Spring、Hibernate、Vue…mvn dependency:tree、npm ls --depth=0—
Runtime 版本JDK、Node、App ServerCI 設定、Dockerfile—
Dependency直接與間接相依、授權mvn dependency:tree -Dverbose、SCA 工具—
API對外端點與契約OpenAPI 或逆向工程第 7 章
Database版本、方言、原生 SQLDDL、Mapper第 7 章
External IntegrationMQ、SFTP、第三方 API設定檔第 7 章
Security認證框架、加密套件程式+設定—
Test Coverage覆蓋率、有沒有可信的回歸測試JaCoCo 報告—
Deployment EnvironmentOS、容器映像、JVM 參數部署腳本—

收集指令範例(Shell,Maven 專案):

java -version 2>&1 | head -1
mvn -q help:evaluate -Dexpression=project.parent.version -DforceStdout   # Spring Boot parent 版本
mvn -q dependency:tree -DoutputFile=target/deps.txt
grep -rl "javax\." --include=*.java src | wc -l                          # 需改成 jakarta 的檔案數

實務注意:「測試覆蓋率低」是升級最大的風險,不是 Framework 本身。分析階段若發現沒有可信的回歸測試,計畫第 0 階段就應是「補行為基準測試(characterization/golden master)」。

8.2 升級規劃

常見升級路徑與官方依據(每一條都要在設計文件中附官方網址):

升級官方建議路徑(摘要)依據
Java 8 → 21/25逐一處理被移除的 API 與模組;Spring Boot 3 起最低 Java 17Oracle/OpenJDK 遷移指南、Spring Boot system requirements
Spring Boot 2.x → 3.x先升到最新 2.7.x 並消除 deprecation,再升 3.0;javax.* → jakarta.*Spring Boot 3.0 Migration Guide
Spring Boot 3.x → 4.x先升到最新 3.5.x 並消除 deprecation,再升 4.0;Jakarta EE 11、Servlet 6.1Spring Boot 4.0 Migration Guide
Spring Framework 5 → 6 → 7隨 Boot 升級Spring Framework 各版 Upgrading 頁
Vue 2 → Vue 3可用 Migration Build(@vue/compat)漸進遷移Vue 3 Migration Guide
JavaScript → TypeScript先 allowJs,逐檔改寫TypeScript 官方文件
舊版 Angular → 新版每次只升一個主版本Angular Update Guide
Maven 3 → Maven 4確認 plugin 相容性;POM model 版本Maven 4 官方說明

上表的路徑摘要來自各專案官方遷移指南的一般建議;實際升級前,Elephant 必須在 Brainstorm 階段讀取並引用當時最新版本的指南(尚待每次升級時重新驗證)。

輔助工具(🧪,本手冊未在本章實跑):

工具用途
OpenRewrite(Spring Boot 升級 recipe)機械化改寫 import、設定屬性
spring-boot-properties-migrator執行期回報已改名或移除的設定屬性
@vue/compatVue 3 相容模式,逐一關閉相容旗標
SCA 工具(OWASP Dependency-Check、Trivy)找出升級後仍有漏洞或已停止維護的套件

實務注意:「一次從 Boot 2.3 跳到 4.0」幾乎一定失敗。設計文件要把每個主版本拆成獨立 Phase,每個 Phase 都能單獨上線。

8.3 EGM 升級流程

flowchart TD
    A["1 Bootstrap 既有專案"] --> B["2 逆向分析現況<br/>第 7 章流程"]
    B --> C["3 As-Is Architecture"]
    C --> D["4 Brainstorm 升級目標<br/>/egm:egm-brainstorm"]
    D --> E["5 Draft To-Be Architecture<br/>/egm:egm-draft"]
    E --> F["6 Migration Plan<br/>Detailed Implementation Plan 分 Phase"]
    F --> G["7 Goldfish 審查<br/>egm-review(feature_spec)→ review-loop+migration standard"]
    G --> H["8 Breaking Changes 逐條對照"]
    H --> I["9 Dependency Compatibility"]
    I --> J["10 分階段計畫定稿"]
    J --> K["11 人工核准<br/>設計 PR"]
    K --> L["12 AI Agent 執行 Phase N<br/>新 session、scope guard"]
    L --> M["13 測試<br/>行為基準+回歸"]
    M -->|"失敗且屬設計問題"| E
    M --> N["14 驗證設計與實作一致性<br/>/egm:egm-drift-report(主 Context)"]
    N --> O{"還有 Phase?"}
    O -->|"是"| L
    O -->|"否"| P["15 升級完成報告"]

各步驟的 EGM 指令:

步驟指令(Claude Code 對話框)
1/egm:egm-bootstrap .
4/egm:egm-brainstorm 將 loan-service 從 Spring Boot 2.3/Java 8 升級到 Spring Boot 4.0/Java 21
5~6/egm:egm-draft
7/egm:egm-review docs/designs/loan-service-upgrade.md feature_spec(只跑 Stage 5~8;egm-review 的 stage 不接受自訂 standard,所以 Stage 9 改用下一列的 review loop)
8~9/egm:egm-review-loop(Reviewers:implementation_readiness、codebase_details;Standards:implementation-readiness-standard、docs/standards/migration-readiness-standard.md)
14/egm:egm-drift-report docs/designs/

公司升級審查標準(建議):

📄 standards/migration-readiness-standard.md

# Framework Migration Readiness Standard (ACME Bank)

Company standard for migration plans. Not part of EGM. Use together with EGM's
`implementation-readiness-standard`.

## Core Principle

A migration plan passes if an engineer who did not write it can run each phase,
know how to prove the phase did not change behavior, and roll it back.

## Requirements (Non-Exhaustive Examples)

*   **Version Evidence**: Every target version cites the vendor's official
    compatibility or system-requirements page.
*   **Breaking Changes**: Each breaking change from the official migration guide
    is listed with the affected files, or explicitly marked "not applicable"
    with the reason.
*   **Phasing**: Each phase leaves the build green and is deployable alone.
*   **Behavior Baseline**: Characterization (golden master) tests exist before
    the first code change.
*   **Rollback**: Each phase states its rollback command and data compatibility.

實務注意:升級設計文件的 Detailed Implementation Plan 很長。用 Preset 3(Implementation plan only)或 egm-review-loop 的 SemanticTarget 只審某個 Phase,可以降低成本並讓 findings 更聚焦。

8.4 升級風險

風險典型例子設計文件要寫測試方式
API Breaking Changesjavax.* → jakarta.*;移除的 Spring API受影響檔案清單編譯+單元測試
Dependency Conflicts兩個套件要求不同版本的 Jackson版本對照表、排除規則mvn dependency:tree -Dverbose
Security ChangesSpring Security 設定 DSL 改變、預設行為改變每個端點升級前後的授權結果權限矩陣測試
Database CompatibilityHibernate 方言、ID 產生策略改變原生 SQL 清單Testcontainers 整合測試
Configuration Changes屬性改名或移除屬性對照表spring-boot-properties-migrator
Authentication ChangesSession、Cookie、CSRF 預設改變登入流程 E2EPlaywright
Performance Regression新版預設連線池、序列化差異基準數據Gatling/k6 前後比較
Transaction Behavior Changes交易傳播、例外回滾規則差異每個 @Transactional 的期望整合測試驗證回滾
Legacy Integration FailureMQ client、SFTP 函式庫不支援新 JDK外部介接清單介接環境煙霧測試

實務注意:Goldfish 擅長抓「計畫沒寫到」的風險,但不知道你們實際的 MQ 版本。把外部介接清單(第 7 章產出)列入 GoldfishContext,reviewer 才有比對依據。

8.5 Framework 升級交付文件

文件內容放在哪裡
As-Is Architecture升級前架構(第 7 章產出)docs/legacy/01-architecture.md
To-Be Architecture升級後架構設計文件 Technical Plan
Compatibility Matrix每個元件的目前版、目標版、官方依據設計文件 Technical Plan
Dependency Analysis需升級、替換、移除的套件設計文件附錄
Breaking Changes Report官方遷移指南逐條對照設計文件附錄
Migration Plan分 Phase 的 Detailed Implementation Plan設計文件
Test Plan行為基準、回歸、效能、安全Verification Plan
Rollback Plan每 Phase 的回滾指令與資料相容性公司追加章節 Operations & Rollback
Security Assessment升級前後的安全差異公司追加章節 Security & Compliance
Upgrade Completion Report結果、偏差、遺留事項docs/designs/reviews/<feature>/completion.md

8.5.1 完整案例:Java 8/Spring Boot 2.3 → Java 21/Spring Boot 4.0

背景(虛構):loan-service,Spring Boot 2.3.12、Java 8、MyBatis、Oracle 19c、IBM MQ,單元測試覆蓋率 31%。

Compatibility Matrix(設計文件節錄,範例):

元件As-IsPhase 1Phase 2Phase 3官方依據
JDK8172121Spring Boot system requirements
Spring Boot2.3.122.7.x 最新3.5.x 最新4.0.x各版 Migration Guide
Namespacejavax.*javax.*jakarta.*jakarta.*Boot 3.0 Migration Guide
MyBatis Spring Boot Starter2.12.33.0待查(尚待驗證是否支援 Boot 4)MyBatis 官方相容表
IBM MQ JMScom.ibm.mq.allclient 9.19.3Jakarta 版Jakarta 版IBM 官方文件
Oracle JDBCojdbc8ojdbc11ojdbc11ojdbc11Oracle JDBC 相容表

Phase 規劃(Detailed Implementation Plan 節錄):

## Detailed Implementation Plan

### Phase 0:行為基準(不改產品程式)
#### 1. `src/test/java/com/acme/loan/golden/LoanApprovalGoldenTest.java` (Create)
*   **Proposed Changes**: 以 200 筆去識別化樣本跑 approve(),比對輸出與 SP 呼叫參數。
#### 2. `src/test/java/com/acme/loan/golden/LoanMqMessageGoldenTest.java` (Create)
*   **Proposed Changes**: 同一批樣本攔截送出的 MQ 訊息(body 與 MQRFH2 header),存成基準檔;Phase 1 起每次比對。

### Phase 1:Java 17+Spring Boot 2.7.x
#### 3. `pom.xml` (Modify)
*   **Proposed Changes**: parent 改為 2.7.x 最新版;maven.compiler.release=17;以 runtime scope 加入 spring-boot-properties-migrator(Phase 2 結束時移除;test scope 不會在應用啟動時載入,看不到警告)。
...

### Target Scope & File Boundary(Phase 0~1 節錄;完整清單 37 個檔案=Resolve 移除 Phase 3 後的 Phase 0~2 合計,含 MQ 比對測試)
- `pom.xml`
- `src/main/resources/application.yml`
- `src/test/java/com/acme/loan/golden/LoanApprovalGoldenTest.java`
- `src/test/java/com/acme/loan/golden/LoanMqMessageGoldenTest.java`

Goldfish 審查結果範例(implementation_readiness_report.md 節錄,範例):

### Phase 2 rollback undefined - Severity: Blocker
* **Reviewer Lens:** `egm-implementation-readiness`
* **Affected Scope:** `Phase 2`
* **Discrepancy Description**: Phase 2 changes javax to jakarta and the MQ client.
  The plan does not say how to roll back if MQ messages written by the new client
  cannot be read by the old consumer.
* **Rationale & Recommendation**: State whether the message format changes and give
  the rollback command and the drain procedure for in-flight messages.

### MyBatis version for Boot 4 is not decided - Severity: Major
* **Reviewer Lens:** `egm-codebase-details`
* **Affected Scope:** `Compatibility Matrix`
* **Discrepancy Description**: "待查" leaves a dependency choice to the implementer.
* **Rationale & Recommendation**: Zero-Decision Rule. Name the version or move Phase 3
  out of this plan until it is known.

Resolve(範例):

Finding分類處理
Phase 2 rollback undefinedPROPOSE FIX加「Phase 2 回滾:停止新版 consumer、確認佇列清空、重新部署 Phase 1 映像;訊息格式不變(MQRFH2 header 相同)」
MyBatis for Boot 4PROPOSE FIX把 Phase 3 移到下一份設計文件,本文件只涵蓋 Phase 0~2

升級完成報告範本(建議):

# loan-service Upgrade Completion Report(Phase 0–2)

* **Design:** docs/designs/loan-service-upgrade.md(Approved 2026-11-25)
* **Result:** Phase 0、1、2 已上線;Phase 3 另案

| 項目 | 計畫 | 實際 | 偏差說明 |
| --- | --- | --- | --- |
| Golden test 樣本 | 200 | 200 | — |
| 回歸測試 | 全部通過 | 全部通過 | — |
| P95(approve) | ≤ 升級前 +10% | +4% | — |
| 變更檔案 | 37(各 Phase File Boundary 合計) | 37 | 每個 Phase 的 PR 以 `egm_scope_guard.py --phase N` 檢查,0 越界 |

## 遺留事項
- 【待確認】Oracle 23ai 是否列入 Phase 3(DBA 2026-12 回覆)

實務注意:升級的每個 Phase 都開一份獨立的實作 PR(分支 feat/<feature>-p<N>);egm_scope_guard.py --phase N 只取設計文件中 ### Phase N 底下列出的檔案(10.9)。把三個 Phase 塞進一個 PR,回滾與審查都會失控。

8.6 本章 AI 產出審查

檢查點好例壞例怎麼抓
版本依據每個目標版本附官方網址「Spring Boot 4 支援所有 Java 版本」搜尋設計文件中的版本號是否都有連結
路徑2.3 → 2.7 → 3.5 → 4.02.3 直接到 4.0看 Phase 數量
待查項目移出本計畫或明確決定「待查」「TBD」留在計畫中egm_design_lint.py D3(1.1 起掃全文、含「待查」「待確認」;Open Questions 除外)
回滾每 Phase 有指令與資料相容性「必要時回滾」migration-readiness-standard 的 Rollback 項
行為基準Phase 0 先建 golden master(含 MQ 訊息比對)直接改程式awk '/^### Phase 0/,/^### Phase 1/' design.md | grep -n 'src/main' 應無結果

第 9 章:EGM 與其他 AI 開發工具整合

EGM 官方 FAQ 第一題:「Are there alternatives? Yes. Many. EGM is one of the ways teams are making LLMs work better. It is not the way.」本章說明 EGM 與常見工具怎麼分工。其他工具的詳細指令請見同目錄手冊(本章不重複,避免版本不一致)。

9.1 工具比較表

工具主要定位與 EGM 的關係建議使用階段
Claude CodeAI Coding Agent HostEGM 的支援 Host;提供 Subagent、權限、Plugin全程
OpenAI CodexAI Coding Agent HostEGM 的支援 Host(CLI);以 skill picker 使用全程
GitHub CopilotIDE/CLI AI 助手Copilot CLI 為實驗性 adapter;VS Code 整合在研究中(#375)實作;EGM 審查暫不建議
Gemini CLIAI Coding AgentEGM 沒有 adapter不適用(可用來實作已核准的設計)
Google AntigravityGoogle 的 Agent 開發環境EGM 的核心目標 Host(CLI 支援;獨立 IDE 不支援)全程
GitHub Spec Kit規格 → 計畫 → 任務的 SDD 工具互補:可用 EGM 審查 Spec Kit 的產出規格產出後
OpenSpec以「變更提案」管理規格的 SDD 工具互補:可用 EGM 審查 proposal 與 design提案審查
BMAD-METHOD多角色敏捷 Agent 方法論分工:BMAD 管角色與 Story,EGM 管獨立審查架構文件、Story 審查
SuperpowersClaude Code 技能組(brainstorming、計畫、TDD、子代理開發)互補:Superpowers 管實作紀律,EGM 管設計審查實作階段
MCP Server讓 Agent 存取外部系統的協定EGM runtime 不宣告 MCP;reviewer adapter 沒有 MCP 工具Elephant 收集資料時
Agent SkillsSkill 封裝格式EGM 本身就是 7 支 Skill+persona全程
PlaywrightE2E 測試把 CUJ 變成可執行測試實作後
ArchUnitJava 架構測試把 Technical Plan 的分層規則機械化實作後、CI
SonarQube程式品質與 SASTEGM 不審程式碼,由它補位CI
Trivy容器/相依套件弱點掃描、SBOM補 SCA 與 SBOMCI、發布前

同目錄手冊:spec-kit使用教學、OpenSpec使用教學、BMAD-METHOD使用教學、Superpowers教學手冊、Playwright 教學手冊、Agent Skills教學手冊。

實務注意:判斷工具關係時問一個問題——「它有沒有在全新 Context 中獨立審查文件?」大多數工具沒有,這正是 EGM 可以補上的地方。

9.2 Host 整合重點

HostEGM 用法特別注意
Claude Code/egm:egm-*;具名 reviewer egm:egm-*需 ≥ 2.1.271;headless 要設讀取權限(3.15.1);/agents 可確認 reviewer
Codex CLIskill pickerreviewer 以 general-purpose agent 讀 persona;fork_context: false/fork_turns: "none";AGENTS.md 會注入
Antigravity CLI/egm:egm-*AGENTS.md、GEMINI.md 會注入;App/IDE 指令格式未驗證
GitHub Copilot CLIcopilot --plugin-dir "$EGM_ROOT" --add-dir "$EGM_ROOT" --agent egm:egm官方:「Workflow execution and reviewer isolation remain unverified」
Gemini CLI無可用來「實作」已核准的設計文件,但不能跑 EGM 審查

實務注意:同一份設計文件可以在 Claude Code 跑 Review、在 Codex 實作——檔案就是介面。但 Review 一定要在支援 Subagent 的 Host 上跑。

9.3 EGM 是否取代 Spec Kit?

不取代。 兩者重點不同:

面向Spec KitEGM
核心規格 → 計畫 → 任務 → 實作的結構化流程設計文件+全新 Context 的獨立審查
規格格式工具定義的檔案結構一般 Markdown(官方模板)
審查以工具內的檢查與分析為主5 stage、8 個 reviewer persona
實作有任務執行流程不管實作

組合用法(建議):用 Spec Kit 產生規格與計畫,再用 /egm:egm-review-loop 審查——規格用 design_critic+feature-spec-standard,計畫用 implementation_readiness+implementation-readiness-standard。

實務注意:Spec Kit 的檔案不是 EGM 模板格式,egm-review 的 Semantic Split 可能找不到 ## Detailed Implementation Plan。對非 EGM 格式的文件,用 egm-review-loop 並明確指定 SemanticTarget。

9.4 EGM 是否取代 OpenSpec?

不取代。 OpenSpec 管的是「規格的變更生命週期」(提案、套用、封存);EGM 管的是「這份提案或設計夠不夠好」。

組合用法(建議):OpenSpec 的 proposal 與 design 檔寫好後,以 /egm:egm-review-loop 審查;審查通過才進入 OpenSpec 的實作步驟。OpenSpec 封存後的規格可以納入 /egm:egm-drift-report 的掃描目錄。上游另有「在 OpenSpec 變更提案內直接執行 EGM」的 RFC(PR #450,2026-11-17 仍未合併,見 11.18),合併前請維持本節做法。

實務注意:兩個工具都會在 repo 留下規格目錄,公司要規定「哪一份是 Single Source of Truth」,避免 docs/designs/ 與 OpenSpec 目錄各說各話。

9.5 EGM 與 BMAD 如何分工?

工作BMADEGM
角色化協作(Analyst、PM、Architect、Dev、QA…)主力—
PRD、架構文件、Story 的產出主力egm-draft 也可產出設計文件
文件的獨立審查角色互審(同一 Context 內的角色扮演)全新 Context 的 Goldfish
Story 是否可直接實作—Stage 9 Implementation Readiness

建議:BMAD 的 Architect 產出架構文件後,跑 /egm:egm-review(Preset 2 Feature spec only);Story 進入開發前,跑 egm-review-loop+implementation-readiness-standard。

實務注意:BMAD 的「角色」與 EGM 的「Goldfish」差異在 Context。同一個 session 扮演 QA 不等於獨立審查;這正是 EGM 官方「a review in the same context is not a Goldfish review」的意思。

9.6 EGM 與 Superpowers 如何互補?

Superpowers 是 Claude Code 的技能組,強調 brainstorming、寫計畫、執行計畫、TDD、子代理開發等實作紀律。

階段建議工具
想法釐清EGM egm-brainstorm(有 7 視角 Goldfish 挑戰)或 Superpowers brainstorming(擇一,避免重複)
設計文件EGM egm-draft
設計審查EGM egm-review
實作計畫 → 程式Superpowers 的計畫執行與 TDD 技能,以 EGM 設計文件為輸入
實作後檢查Superpowers 的 code review 技能+EGM egm-drift-report

實務注意:兩套都有「brainstorm」類技能,同時啟用時 Agent 可能混用。公司規範要寫明設計階段用哪一套。

9.7 EGM 如何整合 Claude Code Skills?

  • EGM 的 7 支 Skill 都設 disable-model-invocation: true,只能手動呼叫,不會被 Claude 自動觸發。
  • Claude Code 的 Skill 工具會拒絕 EGM Skill;EGM 內部要呼叫其他 EGM Skill 時,是「讀 SKILL.md 並在同一 thread 照做」(官方,docs/claude.md)。
  • 公司自己的 Skill(例如 4.10 的 crm-elephant、實作規範 Skill)可以和 EGM 並用:先 /crm-elephant 載入 Context,再 /egm:egm-brainstorm。
  • 實作階段的公司 Skill(coding standard、測試策略)寫進設計文件的 Verification Plan,官方鼓勵:「Add your skills to your implementation plan!」

實務注意:不要在公司 Skill 中呼叫 EGM Skill(例如「先執行 egm-review」),因為 Skill 工具會拒絕;改寫成「請使用者執行 /egm:egm-review」。

9.8 EGM 如何整合 Codex Skills?

  • Codex 以 skill picker 選擇 EGM Skill,不使用 /egm: 前綴。
  • Codex 沒有具名 persona:reviewer 以 general-purpose agent 啟動,任務中給 persona 的絕對路徑。
  • 公司 Skill 與 EGM Skill 並存時,AGENTS.md 只寫穩定慣例(#237 指出它會被注入 reviewer)。
  • 指定產出目錄:AGENTS.md 中加 EGM artifact directory: .dev/docs。

(🧪:本手冊實測環境沒有 Codex CLI。)

實務注意:Codex 的 Review 隔離只驗證到 parent-turn isolation,instruction-file exclusion 未驗證。金融業若要求「審查者不得看到專案指示」,目前只有 Claude Code 有明確機制(omitClaudeMd)。

9.9 MCP、Playwright、ArchUnit、SonarQube、Trivy 的位置

flowchart LR
    subgraph Design["設計(EGM)"]
        BS["Brainstorm"] --> DR["Draft"] --> RV["Review"]
    end
    subgraph Build["實作與驗證"]
        IM["Implementation"] --> UT["Unit/IT"]
        UT --> AU["ArchUnit"]
        AU --> PW["Playwright E2E"]
    end
    subgraph Gate["CI 閘門"]
        SQ["SonarQube<br/>品質+SAST"]
        TR["Trivy<br/>SCA+SBOM"]
        SG["egm_scope_guard.py"]
    end
    MCP["MCP Server<br/>(Elephant 取外部資料)"] -.-> BS
    RV --> IM
    PW --> SQ
    PW --> TR
    PW --> SG
    SG --> DF["Drift Report"]
工具在 EGM 流程中的接點
MCP ServerElephant 在 Brainstorm/Draft 時查 Jira、Confluence、資料庫結構;reviewer 不用 MCP(Claude adapter 工具只有 Read、Grep、Glob;synthesizer「cannot … use the session’s MCP connectors」)
PlaywrightCUJ → E2E 測試名稱一對一
ArchUnitTechnical Plan 的分層 → 測試規則(6.6)
SonarQube實作 PR 的品質門檻
Trivy映像檔與相依套件掃描、產生 SBOM

實務注意:Goldfish 看不到 MCP 取得的資料。Elephant 透過 MCP 查到的重要事實(例如現有資料表欄位),要寫進設計文件或存成 repo 檔案,Goldfish 才能驗證。

9.10 EGM 是否可以作為企業 AI Coding 標準流程?

可以作為設計與審查的標準流程,但不是完整的 SDLC 標準。原因:

可以不足之處補位
設計文件格式標準化不管實作公司實作規範+Superpowers 等
獨立審查機制不審程式碼SonarQube、Code Review
文件與程式一致性Drift Report 靠 AI 判斷,非確定性ArchUnit、契約測試
多 Host 可用雲端 Host 驗證不完整限定核准 Host
開源、可客製pre-1.0、非 Google 官方支援內部鏡像與版本凍結

9.11 企業工具組合建議

組合適用內容
精簡組合中小型專案、PoCClaude Code+EGM+JUnit/ArchUnit+公司 CI
標準組合一般企業專案Claude Code(或 Codex)+EGM+公司 standard+egm 閘門工具+Playwright+SonarQube+Trivy
既有 SDD 團隊已用 Spec Kit/OpenSpec原工具產規格+EGM review loop 審查+原工具實作
大型多角色團隊已用 BMADBMAD 角色與 Story+EGM 審查架構與 Story

本章注意事項:

  • 不要同時導入三套 SDD 工具。先選一套產生規格,EGM 負責審查。
  • 其他工具的指令以各自手冊與官方文件為準,本章不列。

9.12 本章 AI 產出審查

檢查點好例壞例怎麼抓
Gemini CLI「EGM 沒有 adapter」「EGM 支援 Gemini CLI(.gemini 目錄)」讀 .gemini/config.yaml
Copilot「實驗性,隔離未驗證」「EGM 支援 Copilot」讀 docs/copilot.md 第一段
取代關係「互補,分工如下」「EGM 可取代 Spec Kit」看是否區分「規格產生」與「獨立審查」
reviewer 與 MCPreviewer 無 MCP「Goldfish 會自動查 Confluence」讀 adapter 的 tools 欄位

第 10 章:企業級 AI Agent 開發治理

本章是公司內部規範。除了引用官方的部分,全部屬於「建議」,各單位可依風險等級調整。

flowchart TD
    R["需求登錄"] --> C{"10.4 是否需走 EGM?"}
    C -->|"否"| N["一般開發流程"]
    C -->|"是"| D["設計階段<br/>Elephant+Goldfish"]
    D --> G1{"Gate 1:報告閘門<br/>egm_report_gate.py"}
    G1 -->|"失敗"| D
    G1 --> H1{"Gate 2:Human Approval<br/>Architect+資安"}
    H1 -->|"退回"| D
    H1 --> I["實作階段<br/>新 session、最小權限"]
    I --> G2{"Gate 3:CI<br/>scope guard、測試、SAST、SCA"}
    G2 -->|"失敗"| I
    G2 --> H2{"Gate 4:Code Review<br/>人類簽核"}
    H2 --> REL["發布+SBOM+稽核封存"]
    REL --> M["維運<br/>每週 Drift Report"]
    M -->|"漂移"| D

10.1 AI Agent 角色定義

角色實體權限禁止
Elephant主 session(設計階段)讀 repo;寫設計文件與報告寫正式程式碼、改相依套件
GoldfishEGM reviewer subagent唯讀修改任何檔案、執行 shell、使用 MCP
Synthesizeregm-synthesizer啟動 reviewer、寫報告shell、MCP
Implementer實作 session(新開)寫 File Boundary 內的檔案、跑測試越界修改、推送到受保護分支
Bootstrap Workeregm-bootstrap-orchestrator本機探索、寫 README改原始碼、git commit

實務注意:同一位工程師可以操作多個角色,但同一個 session 不可以同時是 Elephant 與 Implementer。

10.2 Elephant 與 Goldfish 權責

項目ElephantGoldfish人類
提出設計選項✔
選擇設計方案✔
指出缺漏與風險✔(自我檢查)✔(獨立審查)✔
決定 finding 是否處理建議✔
修改設計文件✔(經核准)✔
對結果負責✔

10.3 PM / SA / SD / PG / QA 分工

階段PMSASD/ArchitectPGQA資安
Brainstorm確認範圍與優先主導需求回答主導技術回答選擇性參與提出可測性問題高風險時參與
Draft—審 Goals、CUJ主導審實作計畫審 Verification Plan審安全章節
Review/Resolve—審 Stage 6 paraphrase主導審 Stage 9—ESCALATE 簽核
Human Review範圍核准需求核准架構核准—可測性核准安全核准
Implementation進度—處理設計問題主導準備測試—
驗證驗收業務驗證Drift 處理修正主導掃描結果核准

10.4 Design Document 審查規範

何時必須走 EGM(建議):

條件(任一成立)必須
新增或變更對外 API、資料表、訊息格式完整流程
影響 3 個以上模組,或預估 > 300 行正式程式碼完整流程
涉及個資、金流、權限、加密完整流程+資安 reviewer
Framework/Runtime 主版本升級完整流程+migration standard
修 bug、文字、設定值微調不需要

參考:EGM 自己的 AI_POLICY.md 對貢獻者的門檻是「> 100 non-test lines or >= 3 core files」需先走設計文件。

設計文件規範:

  1. 使用官方模板,H2 標題保留英文(4.6)。
  2. 公司追加 ## Security & Compliance、## Operations & Rollback,放在 ## Detailed Implementation Plan 之前。
  3. Status 依序:Draft → Proposed(選用)→ In Review → Approved,與 EGM 模板及 egm_design_lint.py D5 一致。
  4. 合併前通過 egm_design_lint.py --require "Security & Compliance"。

設計文件的生命週期與 PR 分工(1.1 定案):

1.0 版有矛盾:好幾處要求「實作後更新設計文件 Status 與 SITEMAP」,但 10.9 的 CI 規定實作 PR 改到設計文件就算越界。1.1 定案如下,並在 CI 模擬中實測(10.9):

時點誰改改什麼在哪個 PRCI 檢查
審查中SD設計內容;Status: In Reviewdesign/<feature>lint、報告閘門、只能改 docs/
設計 PR 合併前SD(Architect 核准後)Status 改為 Approved同一個 design/<feature> PRStatus 不是 Approved 就失敗
實作PG只改 File Boundary 內的檔案feat/<feature>-p<N>scope guard;改設計文件或 SITEMAP 都算越界
上線後SDSITEMAP.md(Status 維持 Approved)再開一個 design/<feature> 的 docs-only PR同設計 PR
實作中發現設計要改SD設計內容(重新審查)design/<feature> PR,合併後實作 PR rebase同設計 PR

10.5 Goldfish Review 通過標準

條件判定
所有 stage 的 Reviewer Status 都是 completed(沒有表時,consolidated 開頭寫明每個 reviewer 已完成)必要
🔴 Blocker 全部 PROPOSE FIX 已套用,或有證據的 CONTEST必要
🟡 Major 全部有決定(修正、CONTEST、或記錄為接受風險)必要
ESCALATE 項目都有人類簽核必要
goldfish_review_report.md 標示 Status: resolved必要
Stage 6 paraphrase 經 SA 確認與原意一致必要(人工)
🟢 Nit不影響

報告閘門的 R1 對應第 1 項、R4 對應第 4 項、R2 對應第 5 項,R3 另外擋下「Major/Blocker 被 DECLINE」。第 2、3 項(修正是否真的套用、每個 Major 是否有決定)與第 6 項由人工確認,閘門不會檢查。1.1 版新增兩條規則,都是對真實報告實測後才發現需要的(10.5.1):

規則擋下什麼為什麼需要
R0檔案中有 🔴/🟡/Blocker 等標記,卻一個 finding 都解析不到1.0 版遇到不認得的格式時會回報「0 個問題、GATE PASS」
R5stage 報告有 Blocker,卻沒有一起提供 goldfish_review_report.md只封存 stage 報告、跳過 Resolve,也能通過

R1 也改成「Reviewer Status 表中不是 completed 就失敗」(1.0 只認得字面上的 not run,incomplete review 會通過);R4 改成簽核行必須同時寫出報告檔名與 Issue 編號,避免 A 報告的 [Issue 2] 簽核被拿來放行 B 報告的 [Issue 2]。簽核檔不存在時,只有在真的有 ESCALATE 項目時才會失敗。

📄 tools/egm_report_gate.py(建議,公司自建工具)

#!/usr/bin/env python3
"""egm_report_gate.py - enterprise gate over EGM review artifacts.

This is a company rule set built on EGM's report formats. EGM itself has no
gate script. Three finding layouts are recognized:
  * inline:    "### Title - Severity: Blocker"   (agents/synthesizer.md,
                                                  skills/egm-resolve/SKILL.md)
  * sectioned: "## 🔴 Blockers" then "### CR-1: Title" items
  * table:     "### 🔴 Blockers" then "| A1 | action | lines |" rows
  * bullets:   "## 🟡 Majors" then "*   **IR-8** text" items
  * emoji:     "### ZO-1 🔴 Blocker: Title"
In Claude Code the review runs by direct dispatch (subagents cannot nest), so
the Elephant writes the stage reports itself and the layout is not fixed.

Rules (exit 1 when any FAIL is printed):
  R0 the report has severity markers but no finding could be parsed
     (unknown layout: fail instead of passing with zero findings)
  R1 every row of a "Reviewer Status" table must say completed
     ("not run", "incomplete", "failed", ... all mean the lens was not reviewed)
  R2 an annotated report (goldfish_review_report.md) must start with Status: resolved
  R3 DECLINE is only for Nits; a Blocker or Major marked DECLINE fails
  R4 every ESCALATE item needs a human sign-off line in --signoff FILE that
     names both the report file and the issue key, e.g.
     "- goldfish_review_report.md [Issue 3] ... 簽核:..."
     (a missing sign-off file only fails when there is an ESCALATE item)
  R5 a stage report with Blockers needs an annotated report in the same run

Usage:
  python egm_report_gate.py REPORT.md [REPORT.md ...] [--signoff review_signoff.md]
"""
import argparse
import re
import sys
from pathlib import Path

ISSUE = re.compile(r"^#{2,5}\s+(.+?)\s+-\s+Severity:\s*\[?(Blocker|Major|Nit)\]?", re.I)
SECTION = re.compile(r"^(#{2,4})\s+(?:🔴|🟡|🟢)?\s*(Blocker|Major|Nit)s?\b(?!.*Severity:)", re.I)
HEADING = re.compile(r"^(#{1,6})\s+(.+)$")
EMOJI_ISSUE = re.compile(r"^#{2,5}\s+(.*?)(?:🔴|🟡|🟢)\s*(Blocker|Major|Nit)\b:?\s*(.*)$", re.I)
ROW = re.compile(r"^\|\s*`?([A-Z][A-Z0-9]*-?\d+)`?\s*\|\s*(.+?)\s*\|")
BULLET = re.compile(r"^\s*[*-]\s+\*\*([A-Z][A-Z0-9]*-?\d+)\*\*\s*(.*)$")
SUGGESTION = re.compile(r"AI Suggestion:\**\s*\[?(CONTEST|ESCALATE|PROPOSE FIX|DECLINE)\]?", re.I)
STATUS_ROW = re.compile(r"^\|\s*`?([\w:-]+)`?\s*\|\s*([^|]+?)\s*\|")
RESOLVED = re.compile(r"^\**Status:?\**:?\s*resolved", re.I)
MARKER = re.compile(r"🔴|🟡|Severity:|\bBlockers?\b", re.I)
EXPLICIT_NONE = re.compile(r"^\W*(none|no findings|無)\W*$", re.I)


def parse_issues(lines):
    issues = []
    current = None
    section = None  # (level, severity) from a "## 🔴 Blockers" style heading
    for line in lines:
        m = ISSUE.match(line)
        if m:
            current = {"title": m.group(1).strip(), "severity": m.group(2).capitalize(),
                       "suggestion": None}
            issues.append(current)
            continue
        e = EMOJI_ISSUE.match(line)
        if e:
            current = {"title": (e.group(1) + e.group(3)).strip(), "severity": e.group(2).capitalize(),
                       "suggestion": None}
            issues.append(current)
            continue
        s = SECTION.match(line)
        if s:
            section = (len(s.group(1)), s.group(2).capitalize())
            current = None
            continue
        h = HEADING.match(line)
        if h:
            level = len(h.group(1))
            if section and level > section[0]:
                current = {"title": h.group(2).strip(), "severity": section[1], "suggestion": None}
                issues.append(current)
            else:
                section = None
                current = None
            continue
        r = ROW.match(line.strip()) or BULLET.match(line)
        if r and section:
            issues.append({"title": f"{r.group(1)}: {r.group(2)[:60]}", "severity": section[1],
                           "suggestion": None})
            continue
        g = SUGGESTION.search(line)
        if g and current is not None and current["suggestion"] is None:
            current["suggestion"] = g.group(1).upper()
    return issues


def check(path, signoff_text):
    fails = []
    lines = path.read_text(encoding="utf-8").splitlines()
    in_status = False
    for line in lines:
        if line.startswith("#"):
            in_status = "Reviewer Status" in line
            continue
        m = STATUS_ROW.match(line.strip()) if in_status else None
        if m and m.group(1).lower() != "reviewer" and not set(m.group(2)) <= set("-: "):
            if m.group(2).strip("` ").lower() != "completed":
                fails.append(f"R1 reviewer {m.group(2).strip()}: {m.group(1)}")
    issues = parse_issues(lines)
    if not issues and any(MARKER.search(ln) for ln in lines) \
            and not any(EXPLICIT_NONE.match(ln) for ln in lines):
        fails.append("R0 severity markers found but no finding parsed (unknown report layout)")
    annotated = any("Goldfish Annotated Review Report" in ln for ln in lines[:10])
    if annotated:
        head = [ln.strip() for ln in lines[:6]]
        if not any(RESOLVED.match(ln) for ln in head):
            fails.append("R2 annotated report is not marked 'Status: resolved'")
        for it in issues:
            if it["suggestion"] == "DECLINE" and it["severity"] in ("Blocker", "Major"):
                fails.append(f"R3 {it['severity']} declined: {it['title']}")
            if it["suggestion"] == "ESCALATE":
                key = re.match(r"(\[Issue \d+\])", it["title"])
                needle = key.group(1) if key else it["title"]
                signed = any(needle in ln and path.name in ln for ln in signoff_text.splitlines())
                if not signed:
                    fails.append(f"R4 ESCALATE without human sign-off: {it['title']}")
    counts = {k: sum(1 for i in issues if i["severity"] == k) for k in ("Blocker", "Major", "Nit")}
    return counts, fails, annotated


def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("reports", nargs="+")
    ap.add_argument("--signoff", help="file with human decisions for ESCALATE items")
    args = ap.parse_args(argv)
    signoff_text = ""
    if args.signoff and Path(args.signoff).is_file():
        signoff_text = Path(args.signoff).read_text(encoding="utf-8")
    total_fail = 0
    stage_blockers = []
    any_annotated = False
    for r in args.reports:
        p = Path(r)
        if not p.is_file():
            print(f"FAIL {r}: file not found")
            total_fail += 1
            continue
        if args.signoff and p.resolve() == Path(args.signoff).resolve():
            continue  # the sign-off file is not a review report
        counts, fails, annotated = check(p, signoff_text)
        any_annotated = any_annotated or annotated
        if not annotated and counts["Blocker"]:
            stage_blockers.append(p.name)
        print(f"{p.name}: blocker={counts['Blocker']} major={counts['Major']} nit={counts['Nit']}")
        for f in fails:
            print(f"FAIL {p.name}: {f}")
        total_fail += len(fails)
    if stage_blockers and not any_annotated:
        print("FAIL R5 Blockers in " + ", ".join(stage_blockers)
              + " but no Goldfish Annotated Review Report was given")
        total_fail += 1
    print("GATE PASS" if total_fail == 0 else f"GATE FAIL ({total_fail})")
    return 0 if total_fail == 0 else 1


if __name__ == "__main__":
    sys.exit(main())

簽核檔範例(每行:報告檔名+Issue 編號+決定+簽核人與日期):

📄 fixtures/reports/review_signoff.md

# Review sign-off

- goldfish_review_report_good.md [Issue 2] 金鑰輪替:依銀行金鑰政策 KMS-07,資料金鑰每 90 天由 KMS 自動輪替,本設計不另行處理。簽核:資安科 陳美華 2026-11-18(EGM v0.1.1、Claude Code 2.1.325)

實測輸出(Shell):

$ python tools/egm_report_gate.py fixtures/reports/critic_report.md
critic_report.md: blocker=1 major=0 nit=1
FAIL critic_report.md: R1 reviewer not run: egm-structural
FAIL R5 Blockers in critic_report.md but no Goldfish Annotated Review Report was given
GATE FAIL (2)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/goldfish_review_report_good.md
goldfish_review_report_good.md: blocker=1 major=1 nit=1
FAIL goldfish_review_report_good.md: R4 ESCALATE without human sign-off: [Issue 2] [`egm-design`]
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/goldfish_review_report_good.md --signoff fixtures/reports/review_signoff.md
goldfish_review_report_good.md: blocker=1 major=1 nit=1
GATE PASS
(exit=0)

$ python tools/egm_report_gate.py fixtures/reports/goldfish_review_report_bad.md --signoff fixtures/reports/review_signoff.md
goldfish_review_report_bad.md: blocker=1 major=2 nit=0
FAIL goldfish_review_report_bad.md: R2 annotated report is not marked 'Status: resolved'
FAIL goldfish_review_report_bad.md: R4 ESCALATE without human sign-off: [Issue 2] [`egm-design`]
FAIL goldfish_review_report_bad.md: R3 Major declined: [Issue 3] [`egm-style`]
GATE FAIL (3)
(exit=1)

第一個例子同時觸發 R1 與 R5:critic_report.md 有一個 reviewer not run,而且有 Blocker 卻沒有 annotated report。測試 fixture 見附錄 B。

10.5.1 對真實報告實測閘門(1.1)

1.0 版的閘門只用自己寫的 fixture 測試過。1.1 拿第 5.3.5 節實跑產生的 6 份報告與 Resolve 報告去跑,結果如下:

# 1.0 版閘門
comprehension_report.md: blocker=0 major=0 nit=0
consolidated_review_report.md: blocker=0 major=0 nit=0
critic_report.md: blocker=0 major=0 nit=0
implementation_readiness_report.md: blocker=0 major=0 nit=0
intermediate_zoom_out_report.md: blocker=0 major=0 nit=0
zoom_out_report.md: blocker=0 major=0 nit=0
GATE PASS
(exit=0)

# 1.1 版閘門
comprehension_report.md: blocker=1 major=4 nit=4
consolidated_review_report.md: blocker=7 major=12 nit=6
critic_report.md: blocker=1 major=11 nit=6
implementation_readiness_report.md: blocker=7 major=7 nit=6
intermediate_zoom_out_report.md: blocker=1 major=5 nit=4
zoom_out_report.md: blocker=1 major=6 nit=4
FAIL R5 Blockers in comprehension_report.md, consolidated_review_report.md, critic_report.md, implementation_readiness_report.md, intermediate_zoom_out_report.md, zoom_out_report.md but no Goldfish Annotated Review Report was given
GATE FAIL (1)
(exit=1)

# 1.1 版閘門+Resolve 後的 goldfish_review_report.md(尚未 resolved、尚未簽核)
comprehension_report.md: blocker=1 major=4 nit=4
consolidated_review_report.md: blocker=7 major=12 nit=6
critic_report.md: blocker=1 major=11 nit=6
implementation_readiness_report.md: blocker=7 major=7 nit=6
intermediate_zoom_out_report.md: blocker=1 major=5 nit=4
zoom_out_report.md: blocker=1 major=6 nit=4
goldfish_review_report.md: blocker=8 major=18 nit=0
FAIL goldfish_review_report.md: R2 annotated report is not marked 'Status: resolved'
FAIL goldfish_review_report.md: R4 ESCALATE without human sign-off: [Issue 3] [`egm-codebase-details`]
FAIL goldfish_review_report.md: R4 ESCALATE without human sign-off: [Issue 8] [`egm-codebase-details`, `egm-implementation-readiness`]
FAIL goldfish_review_report.md: R4 ESCALATE without human sign-off: [Issue 16] [`egm-design`, `egm-structural`]
FAIL goldfish_review_report.md: R4 ESCALATE without human sign-off: [Issue 19] [`egm-style`]
FAIL goldfish_review_report.md: R4 ESCALATE without human sign-off: [Issue 23] [`egm-implementation-readiness`]
GATE FAIL (6)
(exit=1)

1.0 版對一份有 11 個 Blocker 的審查結果回報 0 個問題、GATE PASS。原因是 Claude Code 這次走 direct dispatch(2.10.1),報告由 Elephant 撰寫,同一次執行就出現 4 種嚴重度寫法,沒有一種是 1.0 認得的 ### 標題 - Severity: X:

寫法出現在範例(逐字節錄)
標題內含 emoji 嚴重度zoom_out_report.md、comprehension_report.md、intermediate_zoom_out_report.md### ZO-1 🔴 Blocker: The plan builds only part of what the Goals promise
嚴重度章節+### 項目critic_report.md、implementation_readiness_report.md(Blocker 段)## 🔴 Blockers 之後接 ### CR-1: No Risks & Mitigations section
嚴重度章節+粗體 ID 清單implementation_readiness_report.md(Major、Nit 段)## 🟡 Majors 之後接 * **IR-8** (readiness-M7, codebase-M1): No phases.
嚴重度章節+表格consolidated_review_report.md### 🔴 Blockers 之後接 | A1 | Choose the phase scope (Decision 1). ... |

1.1 版的解析結果與 consolidated_review_report.md 自己的統計表(5.3.5)逐 stage 完全一致,這就是驗證 parser 的「正確答案」。附錄 B 的 fixtures/reports/layouts/ 是從這次實跑逐行節錄的 4 種寫法,加上 1 份 R0 反例與 1 份 incomplete review 反例:

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_emoji.md
layout_emoji.md: blocker=1 major=1 nit=1
FAIL R5 Blockers in layout_emoji.md but no Goldfish Annotated Review Report was given
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_sectioned.md
layout_sectioned.md: blocker=1 major=1 nit=1
FAIL R5 Blockers in layout_sectioned.md but no Goldfish Annotated Review Report was given
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_bullets.md
layout_bullets.md: blocker=1 major=2 nit=1
FAIL R5 Blockers in layout_bullets.md but no Goldfish Annotated Review Report was given
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_table.md
layout_table.md: blocker=1 major=1 nit=0
FAIL R5 Blockers in layout_table.md but no Goldfish Annotated Review Report was given
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_unknown.md
layout_unknown.md: blocker=0 major=0 nit=0
FAIL layout_unknown.md: R0 severity markers found but no finding parsed (unknown report layout)
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/status_incomplete.md
status_incomplete.md: blocker=0 major=0 nit=1
FAIL status_incomplete.md: R1 reviewer incomplete review: egm-structural
GATE FAIL (1)
(exit=1)

$ python tools/egm_report_gate.py fixtures/reports/layouts/layout_sectioned.md fixtures/reports/goldfish_review_report_good.md --signoff fixtures/reports/review_signoff.md
layout_sectioned.md: blocker=1 major=1 nit=1
goldfish_review_report_good.md: blocker=1 major=1 nit=1
GATE PASS
(exit=0)

實務注意:

  • 報告格式是 EGM pre-1.0 的輸出,官方說 1.0 才會穩定「report formats」;而且只要走 direct dispatch,格式就由 LLM 決定。閘門以 goldfish_review_report.md 為主(格式寫死在 egm-resolve 模板中,實測完全一致),stage 報告只用來計數,並靠 R0/R5 防止漏網。
  • 每次升級 EGM 或 Claude Code,都要用真實執行的報告重跑閘門(第 11.10 節 L4),不能只跑 fixture。
  • 這也是一般原則:「沒有發現問題」的檢查工具,要先證明它解析得到問題。

10.6 Human Approval Gate

Gate時點核准者證據
G-Design設計 PR 合併前Architect+Tech Lead(必要);資安(涉及個資或權限時)PR approve 紀錄、review_signoff.md
G-Code實作 PR 合併前Code Reviewer(非作者)PR approve 紀錄
G-Release上線前變更管理委員會(依公司既有流程)測試報告、SBOM、掃描結果

在 GitHub 以 CODEOWNERS 強制(範例):

# .github/CODEOWNERS
/docs/designs/            @acme/architects
/docs/designs/reviews/    @acme/architects @acme/appsec
/docs/standards/          @acme/architects @acme/appsec

實務注意:EGM 自己的 repo 也用 CODEOWNERS 把審查導向 @google/egm-maintainers(commit 7bd119c),這是 Plugin 作者自身採用的做法。

10.7 AI Coding 權限管制

階段建議的 Claude Code 權限
設計只允許寫 docs/、.dev/docs/;拒絕 Bash(git push:*)
審查reviewer 由 adapter 限制唯讀;headless 時只開 EGM 四個目錄的讀取(3.15.1)
實作允許編輯 repo;拒絕讀 .env、secrets/;拒絕 git push --force

實務注意:Claude Code 對 plugin subagent 會忽略 hooks 與 permissionMode(官方,docs/claude.md),synthesizer「只寫報告」是指示而非強制。權限要在 session 層設定。

10.8 Git Branch / Pull Request 管理

分支用途內容
design/<feature>設計 PRdocs/designs/<feature>.md、docs/designs/reviews/<feature>/(只能改 docs/)
feat/<feature>-p<N>第 N 個 Phase 的實作 PR(沒有分 Phase 的設計用 -p1)該 Phase File Boundary 內的檔案
main受保護需通過 egm-gate 與人工核准

PR 標題慣例:design: customer-contact、feat(customer-contact): phase 1。官方 FAQ 對大 PR 的回答:「No. … The answer is the same as when you built things without AI.」

10.9 程式碼修改範圍管理

官方:Phase 1~4 只寫規格與報告,「This is a convention, and nothing enforces it.」;Stage 9 通過後,「the plan’s Target Scope & File Boundary list is the set of files Phase 5 implementation may write」。公司以 CI 強制:

📄 tools/egm_scope_guard.py(建議,公司自建工具)

#!/usr/bin/env python3
"""egm_scope_guard.py - compare changed files with the design's file boundary.

EGM convention (docs/designs/architecture.md, Phase 5): once Stage 9 passes,
the plan's "Target Scope & File Boundary" list is the set of files that
implementation may write. EGM does not enforce this. This script does.

Allowed files are read from the design document:
  * headings like:  #### 1. `src/a/B.java` (Create)
  * bullets under a heading named "Target Scope & File Boundary":  - `path`
Globs (fnmatch) are allowed, e.g. `build/generated/**`.

Usage:
  python egm_scope_guard.py DESIGN.md --base origin/main [--allow PATTERN ...]
  python egm_scope_guard.py DESIGN.md --changed-file changed.txt
  python egm_scope_guard.py DESIGN.md --phase 2 --base origin/main   # only 'Phase 2' files

Exit codes: 0 = in scope, 1 = out-of-scope files found, 2 = usage / parse error.
"""
import argparse
import fnmatch
import re
import subprocess
import sys
from pathlib import Path

HEADING = re.compile(r"^#{3,5}\s+\d+\.\s+`([^`]+)`\s*\((Create|Modify|Delete)\)", re.I)
BOUNDARY = re.compile(r"^#{2,5}\s+Target Scope\s*&\s*File Boundary", re.I)
BULLET = re.compile(r"^\s*[-*]\s+`([^`]+)`")


PHASE = re.compile(r"^#{2,4}\s+Phase\s+(\d+)", re.I)


def parse_allowlist(text, phase=None):
    # A design without any "Phase N" heading is a single phase: --phase 1 means the whole list.
    if phase == "1" and not any(PHASE.match(ln) for ln in text.splitlines()):
        phase = None
    allowed = {}
    in_boundary = False
    in_fence = False
    current = None
    for line in text.splitlines():
        if line.lstrip().startswith("```"):
            in_fence = not in_fence
            continue
        if in_fence:
            continue
        pm = PHASE.match(line)
        if pm:
            current = pm.group(1)
            continue
        if phase is not None and current != phase:
            continue
        m = HEADING.match(line)
        if m:
            allowed[m.group(1).strip()] = m.group(2).capitalize()
            continue
        if BOUNDARY.match(line):
            in_boundary = True
            continue
        if in_boundary and re.match(r"^#{1,5}\s", line):
            in_boundary = False
        if in_boundary:
            b = BULLET.match(line)
            if b:
                allowed.setdefault(b.group(1).strip(), "Listed")
    return allowed


def changed_from_git(base):
    out = subprocess.run(
        ["git", "diff", "--name-only", f"{base}...HEAD"],
        capture_output=True, text=True, check=False,
    )
    if out.returncode != 0:
        sys.stderr.write(out.stderr)
        sys.exit(2)
    return [p.strip() for p in out.stdout.splitlines() if p.strip()]


def matches(path, patterns):
    return any(path == p or fnmatch.fnmatch(path, p) for p in patterns)


def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("design")
    src = ap.add_mutually_exclusive_group(required=True)
    src.add_argument("--base", help="git base ref, e.g. origin/main")
    src.add_argument("--changed-file", help="text file with one changed path per line")
    ap.add_argument("--phase", help="only use files listed under the heading 'Phase N'")
    ap.add_argument("--allow", action="append", default=[],
                    help="extra allowed pattern (e.g. docs/designs/*.md)")
    args = ap.parse_args(argv)

    design = Path(args.design)
    if not design.is_file():
        print(f"ERROR design not found: {design}")
        return 2
    allowed = parse_allowlist(design.read_text(encoding="utf-8"), args.phase)
    if not allowed:
        where = f" for Phase {args.phase}" if args.phase else ""
        print(f"ERROR no file boundary found in design{where} (Detailed Implementation Plan headings)")
        return 2

    if args.base:
        changed = changed_from_git(args.base)
    else:
        changed = [p.strip().replace("\\", "/") for p in
                   Path(args.changed_file).read_text(encoding="utf-8").splitlines() if p.strip()]

    patterns = list(allowed) + args.allow
    outside = [p for p in changed if not matches(p, patterns)]
    untouched = [p for p, kind in allowed.items()
                 if not any(ch == p or fnmatch.fnmatch(ch, p) for ch in changed)]

    print(f"allowlist={len(allowed)} changed={len(changed)} outside={len(outside)}")
    for p in outside:
        print(f"OUT-OF-SCOPE {p}")
    for p in untouched:
        print(f"NOT-YET-TOUCHED {p} ({allowed[p]})")
    return 1 if outside else 0


if __name__ == "__main__":
    sys.exit(main())

實測(越界情境):

$ python tools/egm_scope_guard.py fixtures/design_good.md --changed-file fixtures/changed_drift.txt
allowlist=8 changed=4 outside=2
OUT-OF-SCOPE customer-app/src/main/java/com/acme/crm/customer/app/util/StringUtils2.java
OUT-OF-SCOPE pom.xml
NOT-YET-TOUCHED customer-infra/src/main/resources/db/migration/V12__contact.sql (Create)
NOT-YET-TOUCHED customer-app/src/main/java/com/acme/crm/customer/app/AddContactService.java (Create)
NOT-YET-TOUCHED customer-api/src/main/java/com/acme/crm/customer/api/ContactController.java (Create)
NOT-YET-TOUCHED docs/api/customer-contact.openapi.yaml (Create)
NOT-YET-TOUCHED customer-domain/src/test/java/com/acme/crm/customer/domain/CustomerContactTest.java (Create)
NOT-YET-TOUCHED customer-infra/src/test/java/com/acme/crm/customer/infra/ContactConcurrencyIT.java (Create)

分 Phase 的設計用 --phase N 只取 ### Phase N 底下的檔案;沒有任何 Phase 標題的設計,--phase 1 代表整份清單,其他編號視為錯誤(rc=2)。

CI 的兩個設計決定(避免實作 PR 自己放寬限制):

  1. 設計文件路徑由分支名稱推導(design/<feature>、feat/<feature>-p<N>),不需要額外的設定檔,多個功能並行也不會互相覆蓋。
  2. 實作 PR 的檔案清單從 base 分支(已核准、已合併的設計文件)讀取;實作 PR 若修改設計文件本身,會被視為越界。

CI workflow(建議):

📄 project/.github/workflows/egm-gate.yml

# Company EGM gate (not part of EGM). Runs on every pull request.
# Branch convention (handbook 10.8):
#   design/<feature>      -> design PR: only files under docs/ may change;
#                            the design must say "**Status:** Approved" before merge.
#                            Also used after release for docs-only SITEMAP updates.
#   feat/<feature>-p<N>   -> implementation PR for Phase N of docs/designs/<feature>.md
#                            (must not touch the design document itself)
# Review reports are archived under docs/designs/reviews/<feature>/.
name: egm-gate

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  gate:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Resolve design from branch name
        id: design
        env:
          HEAD_REF: ${{ github.head_ref }}
        run: |
          case "$HEAD_REF" in
            design/*) mode=design; feature="${HEAD_REF#design/}"; phase="" ;;
            feat/*-p[0-9]*) mode=impl; rest="${HEAD_REF#feat/}"; feature="${rest%-p*}"; phase="${rest##*-p}" ;;
            *) mode=skip; feature=""; phase="" ;;
          esac
          { echo "mode=$mode"; echo "feature=$feature"; echo "phase=$phase"; } >> "$GITHUB_OUTPUT"

      - name: Design PR gate
        if: steps.design.outputs.mode == 'design'
        env:
          FEATURE: ${{ steps.design.outputs.feature }}
          BASE: origin/${{ github.base_ref }}
        run: |
          python tools/egm_design_lint.py "docs/designs/$FEATURE.md" --require "Security & Compliance"
          grep -Eq '^\*   \*\*Status:\*\* Approved$' "docs/designs/$FEATURE.md" \
            || { echo "design PR must set Status: Approved before merge"; exit 1; }
          dir="docs/designs/reviews/$FEATURE"
          python tools/egm_report_gate.py "$dir"/*.md --signoff "$dir/review_signoff.md"
          outside="$(git diff --name-only "$BASE...HEAD" | grep -v '^docs/' || true)"
          if [ -n "$outside" ]; then echo "design PR changes non-doc files:"; echo "$outside"; exit 1; fi

      - name: Implementation PR scope guard (design read from the base branch)
        if: steps.design.outputs.mode == 'impl'
        env:
          FEATURE: ${{ steps.design.outputs.feature }}
          PHASE: ${{ steps.design.outputs.phase }}
          BASE: origin/${{ github.base_ref }}
        run: |
          git show "$BASE:docs/designs/$FEATURE.md" > "$RUNNER_TEMP/design.md"
          python tools/egm_scope_guard.py "$RUNNER_TEMP/design.md" --phase "$PHASE" --base "$BASE" \
            --allow "docs/designs/reviews/$FEATURE/**"

在暫存 git repo 以相同的分支解析與指令模擬(實測,ci_sim.sh;1.1 新增 Status 檢查與情境 5、6):

情境分支結果
1a 設計 PR,Status 仍是 In Reviewdesign/customer-contactdesign PR must set Status: Approved before merge,rc=1
1b 同上,Status 改為 Approveddesign/customer-contactLINT PASS、GATE PASS,rc=0
2 設計 PR 夾帶程式 src/X.javadesign/customer-contactdesign PR changes non-doc files: src/X.java,rc=1
3 實作 PR(只改計畫內的 Contact.java)feat/customer-contact-p1allowlist=8 changed=1 outside=0,rc=0
4 實作 PR 在設計文件加一項 pom.xml 並修改 pom.xmlfeat/customer-contact-p1OUT-OF-SCOPE docs/designs/customer-contact.md、OUT-OF-SCOPE pom.xml,rc=1
5 實作 PR 順便更新 SITEMAPfeat/customer-contact-p1OUT-OF-SCOPE docs/designs/SITEMAP.md,rc=1
6 上線後另開 docs-only PR 更新 SITEMAPdesign/customer-contactLINT PASS、GATE PASS,rc=0

完整輸出:

== 1 design PR (docs only)
LINT PASS
design PR must set Status: Approved before merge
rc=1   (Status still In Review)
LINT PASS
GATE PASS
rc=0
== 2 design PR that also changes code
LINT PASS
GATE PASS
design PR changes non-doc files: src/X.java
rc=1
== 3 implementation PR inside the boundary
allowlist=8 changed=1 outside=0
rc=0
== 4 implementation PR that edits the design to widen its own boundary
allowlist=8 changed=3 outside=2
OUT-OF-SCOPE docs/designs/customer-contact.md
OUT-OF-SCOPE pom.xml
rc=1
== 5 implementation PR that also updates SITEMAP (should be a separate docs PR)
allowlist=8 changed=2 outside=1
OUT-OF-SCOPE docs/designs/SITEMAP.md
rc=1
== 6 after release: docs-only PR on design/customer-contact updates SITEMAP
LINT PASS
GATE PASS
rc=0

情境 5、6 對應 10.4 的生命週期表:實作 PR 不碰任何設計文件,上線後的 SITEMAP 更新走另一個 docs-only PR。

(🧪:workflow 在 GitHub Actions 上未實跑;以上是在本機 git repo 以相同指令模擬。)

實務注意:scope guard 只看檔名,不看改了什麼。在計畫內的檔案裡加了計畫外的功能,要靠 Code Review 與 Drift Report。

10.10 AI Agent 存取權限

資源ElephantGoldfishImplementer
專案原始碼讀讀讀寫(範圍內)
設計文件讀寫讀讀
.env、金鑰、憑證拒絕拒絕拒絕
正式環境資料庫拒絕拒絕拒絕
測試資料庫透過 MCP 唯讀(核准後)無測試用
外部網路依 Host 設定無 URL 能力(Claude adapter)套件倉庫

實務注意:官方提醒隔離「is context and tool isolation, not filesystem isolation: reviewers can read accessible files」。機密檔案要用 deny 規則或根本不放在工作目錄。

10.11 敏感資料保護

  1. 設計文件、brief、報告不得含真實個資、帳號、交易資料;範例一律去識別化。
  2. 逆向工程前先排除樣本資料、匯出檔(.gitignore、.egmignore、deny 規則)。
  3. 官方 docs/privacy.md:「Provide only the files needed for the review.」、「Outputs can repeat information from the inputs.」
  4. 報告會被 commit 與封存,寫入前檢查(Shell,建議):
# 粗略掃描台灣身分證字號與手機號碼格式;有輸出就人工確認
grep -rnE --include='*.md' '[A-Z][12][0-9]{8}|09[0-9]{2}-?[0-9]{3}-?[0-9]{3}' docs/designs .dev/docs
# 不要寫成 docs/designs/**/*.md:bash 預設沒開 globstar,** 只等於一層,會漏掉 reviews/<feature>/

實務注意:EGM 不傳資料到 Google;資料流完全由 Host 決定(官方)。資料保護的審查對象是「你核准的 Host 與其帳號設定」。

10.12 金融業資安要求

要求(一般性)EGM 流程中的落實點
委外與雲端服務管理Host(Claude、OpenAI、Google)需經公司核准與合約
最小權限10.7、10.10
變更管理設計 PR、實作 PR、G-Release
稽核軌跡10.16
個資保護10.11
弱點管理10.14、10.15

具體法規條文(例如主管機關的資安或 AI 指引)請依公司法遵單位最新解釋為準,本手冊不列條文(尚待法遵確認)。

10.13 OWASP Top 10

設計階段以 standard 納入(4.16)。OWASP Top 10 2025 與設計文件檢查點:

編號類別設計文件要寫
A01Broken Access Control每個端點的權限、預設拒絕
A02Security Misconfiguration安全相關設定與預設值
A03Software Supply Chain Failures新相依套件的版本、來源、SCA
A04Cryptographic Failures加密演算法、金鑰來源
A05Injection參數化查詢、SP 呼叫方式
A06Insecure Design威脅情境、濫用案例
A07Authentication Failures認證方式、session 管理
A08Software or Data Integrity Failures簽章、反序列化
A09Security Logging and Alerting Failures稽核事件、告警
A10Mishandling of Exceptional Conditions錯誤回應不洩漏內部資訊、失敗時的安全預設

(類別名稱以 OWASP 官方 2025 版為準;導入時請核對最新官方頁面。)

10.14 SAST / DAST / SCA

類型工具範例時點門檻(建議)
SASTSonarQube、Semgrep、CodeQL實作 PR無新增 Critical/High
SCATrivy、OWASP Dependency-Check實作 PR、每日無已知可利用的 Critical
DASTOWASP ZAP測試環境部署後無 High
Secret Scangitleaks、GitHub secret scanning每次 push0

實務注意:EGM 審查的是設計;它能確認「設計文件有寫要跑 SCA」,不能代替 SCA。

10.15 SBOM

  • 發布時以 Trivy 等工具產生 CycloneDX 或 SPDX 格式 SBOM,隨版本封存。
  • EGM 本身的 Release 提供 SHA256SUMS 與 GitHub attestation(gh attestation verify,3.4)——公司鏡像 EGM 時也要保存這些驗證結果,當作 AI 工具的供應鏈證據。

10.16 Audit Trail

每個走 EGM 的功能封存以下檔案於 docs/designs/reviews/<feature>/:

檔案來源
zoom_out_report.md、comprehension_report.md、critic_report.md、intermediate_zoom_out_report.md、implementation_readiness_report.md(或 consolidated_review_report.md)egm-review
goldfish_review_report.mdegm-resolve
review_signoff.md人工(ESCALATE 簽核)
completion.md實作完成報告(8.5.1 範本)
EGM 版本在 review_signoff.md 記錄 EGM v0.1.1、Host 與版本

實務注意:報告預設寫到工作目錄或 .dev/docs(可能被 git ignore),要在設計 PR 前主動複製到封存目錄。

10.17 AI 產出文件版本管理

  • 設計文件以 git 管理;Status 欄位反映狀態。
  • 大幅修改(改變架構或外部介面)時,新開一份設計文件並在舊文件標註被取代,而不是覆寫。
  • *Drafted with EGM* 出處標記保留。
  • concepts_brief.md、design_draft.md 屬草稿,不 commit。

10.18 AI 產出程式碼責任歸屬

原則說明
PR 作者負全責與 EGM AI_POLICY.md 一致:「Every pull request must have a human author who has personally reviewed, tested, and verified every line of changed code.」
不得以「AI 產生的」作為免責官方:「It’s not the tool that did that, it was you that did that.」
Reviewer 需理解程式不得把審查意見丟給 AI 再原樣貼回(AI_POLICY.md Interactive Code Review)
commit 標註依公司規定加 Co-Authored-By 或 trailer 標示 AI 協作

10.19 AI 產出內容人工驗證

產出最低驗證
BriefSA 確認 Goals/Non-Goals
設計文件Architect 核准;SA 確認 Stage 6 paraphrase
Review 報告抽查 Blocker 是否屬實
Bootstrap README每份抽查 3 個符號;跑 Drift Report
逆向工程文件egm_evidence_check.py+業務單位確認【待確認】
程式碼測試+Code Review+掃描

10.20 企業 AI 開發政策

政策要點(建議範本):

  1. 只使用公司核准的 AI Host 與帳號。
  2. 符合 10.4 條件的變更必須走 EGM 設計與審查。
  3. Goldfish 審查必須在支援 Subagent 的 Host 執行;不得以同一 session 自我審查代替。
  4. 設計與實作使用不同 session。
  5. 不得輸入機密、個資或正式環境資料。
  6. 所有 AI 產出由人類審查並負責。
  7. 審查紀錄封存至少與系統文件相同年限。
  8. EGM 版本升級須經 11 章 SOP。

10.21 EGM Enterprise Development SOP

步驟動作負責產出/證據Gate
1需求登錄,依 10.4 判斷是否走 EGMPMIssue 標籤 egm-required—
2/crm-elephant(專案 Elephant)+/egm:egm-brainstormSA+SDconcepts_brief.md—
3/egm:egm-draft,H2 保留英文,加公司章節SDdocs/designs/<f>.md—
4python tools/egm_design_lint.py … --require "Security & Compliance"SDLINT PASS—
5在**設計 session(Elephant)**中 /egm:egm-review …,Interactive(reviewer 自動是新 Subagent)SD5 份報告—
6Stage 7、9 選 Option 1 Resolve;ESCALATE 交簽核SD+Architectgoldfish_review_report.md、review_signoff.md—
7複製報告到 docs/designs/reviews/<f>/;在 design/<f> 分支提交SD封存檔Gate 1:egm-gate CI
8開設計 PRSDPRGate 2:Human Approval
9新 session 依 Phase 實作(5.6 提示),分支 feat/<f>-p<N>PG實作 PR—
10CI:scope guard、測試、ArchUnit、SAST、SCAPGCI 報告Gate 3
11Code ReviewReviewerapproveGate 4
12發布+SBOMDevOpsRelease、SBOMG-Release
13上線後另開 docs-only PR 更新 SITEMAP(10.4)SD文件—
14每週 /egm:egm-drift-report docs/designs/模組負責人drift 報告—

本章注意事項:

  • 治理的目的是讓「該想清楚的事」在寫程式前被想清楚,不是增加文件。符合 10.4「不需要」的變更不要硬套。
  • 所有自建閘門工具都要有測試與反例(附錄 B);閘門本身的假綠燈比沒有閘門更危險。

10.22 本章 AI 產出審查

檢查點好例壞例怎麼抓
自建工具標示「公司自建,not part of EGM」把 egm_scope_guard.py 寫成 EGM 內建搜尋工具名是否附「建議」
範圍限制CI 強制「EGM 會限制 AI 只改計畫內檔案」對照 architecture.md「nothing enforces it」
隔離說明Context 與工具隔離,不是檔案系統隔離「Goldfish 看不到機密檔」讀 docs/claude.md Reviewer isolation
法規交由法遵確認自行引用條號檢查條號是否有來源

第 11 章:系統維護與版本升級

EGM 是 pre-1.0、迭代快速的專案(v0.1.1 之後 9 天內 main 又有 45 個 commit)。維護的核心是:知道自己用的是哪一版、升級前知道變了什麼、升級後證明還能用、出問題能退回。

flowchart TD
    W["每週:檢查上游<br/>gh release list、git log"] --> N{"有新 tag?"}
    N -->|"否"| W
    N -->|"是"| RN["讀 Release notes 與 diff<br/>skills、agents、resources、docs"]
    RN --> IMP{"影響公司客製?<br/>報告格式、Skill 名、參數"}
    IMP --> PRE["11.9 升級前檢查"]
    PRE --> MIR["更新內部鏡像到新 tag"]
    MIR --> PIL["試點環境安裝+L1 到 L3 驗證"]
    PIL --> OK{"11.10 驗證通過?"}
    OK -->|"否"| RB["11.11 Rollback"]
    RB --> ISS["回報上游 Issue/內部追蹤"]
    OK -->|"是"| ROLL["全公司升級公告"]
    ROLL --> REC["更新版本相容性表+手冊"]
    REC --> W

11.1 EGM Repository 維護

建議公司建立內部鏡像(例如 git.acme.internal/ai/elephant-goldfish-model):

做法優點缺點
直接用 GitHub 官方 Marketplace最新、零維護無法鎖版、依賴外網
內部鏡像,只同步 tag可控、可審查 diff需要專人維護
Fork 並修改可深度客製每次升版都要合併,不建議

鏡像同步指令(Shell,DevOps 執行):

git clone --mirror https://github.com/google/elephant-goldfish-model.git egm-mirror.git
cd egm-mirror.git
git remote add internal https://git.acme.internal/ai/elephant-goldfish-model.git
git fetch origin --tags
git push internal refs/tags/v0.1.1:refs/tags/v0.1.1
git push internal v0.1.1^{commit}:refs/heads/main --force   # 內部 main 指向核准的 tag

實務注意:最後一行會覆寫內部 main,只能由鏡像維護者執行,且要先在變更單核准。

11.2 Plugin 版本管理

確認目前版本(Shell):

claude plugin list | grep -A2 'egm@egm'          # Version: 0.1.1
git ls-remote --tags https://github.com/google/elephant-goldfish-model.git | tail -3
gh release list -R google/elephant-goldfish-model --limit 3

v0.1.1 實測 gh release list 輸出:

EGM v0.1.1	Latest	v0.1.1	2026-11-06T21:50:31Z
EGM v0.1.0		v0.1.0	2026-10-27T07:46:34Z

查證心得:本手冊撰寫時,網頁擷取工具摘要 GitHub repo 首頁回報「Releases section is empty」,但 gh release list 明確列出兩個 Release。版本資訊請以 gh 或 git ls-remote 為準,不要只看 AI 摘要的網頁內容。

版本規則(官方,docs/releases.md):pre-1.0 時 patch 為相容修正、minor 為功能或不相容的流程變更;已發布的 tag 不會移動。

實務注意:Marketplace 的 egm@egm 會跟著官方 repo 走。需要「全公司固定在 0.1.1」時,Marketplace 來源要指向內部鏡像(11.1)。Claude Code 的 extraKnownMarketplaces 支援自架 git URL(官方 settings reference 範例格式):

{
  "extraKnownMarketplaces": {
    "egm": {
      "source": { "source": "git", "url": "https://git.acme.internal/ai/elephant-goldfish-model.git" }
    }
  }
}

(🧪:以內部鏡像作為 marketplace 來源未實測。)

11.3 Skills 更新

每次升級檢查 Skill 的差異(Shell,在鏡像 repo):

git diff --stat v0.1.0 v0.1.1 -- skills/
git diff v0.1.0 v0.1.1 -- skills/egm-review/SKILL.md | head -80

重點關注:

變更影響
Skill 名稱、參數公司 SOP、提示範本、CI 都要改
報告檔名或格式egm_report_gate.py 可能解析失敗
Stage 與 reviewer 組合審查成本與通過標準
Execution ConstraintsAgent 互動方式

實務注意:v0.1.1 的 Release notes 寫「Existing skill names, descriptions, and per-skill prompt files are unchanged by the listing update. No migration is required」。每次都要找這類句子,沒有就自己 diff。

11.4 Agent Persona 更新

git diff v0.1.0 v0.1.1 -- agents/ .claude-plugin/agents/
grep -h '^name:' agents/*.md | sort     # persona 名稱是否改變

v0.1.1 新增 inventive_catalyst.md(TRIZ reviewer,#299)。新增 persona 會讓 Stage 5 多一個 reviewer,成本增加。

實務注意:公司自訂 reviewer(4.13)若用了與官方相同的名稱,升級後可能衝突;一律使用 acme- 前綴。

11.5 Resources 更新

git diff v0.1.0 v0.1.1 -- resources/

standard 的文字改變會直接改變審查結果。公司若以某 standard 作為通過條件,升級前請 Architect 讀過差異。

11.6 Review Rules 更新

公司 standard(docs/standards/)的版本管理:

項目做法
版本standard 檔頭加 Version: 1.2、Owner:
變更PR+CODEOWNERS(Architect、AppSec)
生效新版 standard 只套用在之後開始的審查
回溯封存的審查紀錄記錄當時的 standard 版本

11.7 AI Agent 版本相容性

版本相容性檢查表(每次升級 EGM 或 Host 時更新):

項目目前值要求檢查方式結果
EGM0.1.1公司核准版本claude plugin list通過
Claude Code2.1.325≥ 2.1.271claude --version通過
Codex CLI(待填)官方測試 0.163.0 以上codex --version🧪
Antigravity CLI(待填)官方測試 1.4.5;建議 ≥ 1.4.10 以免前綴問題agy --version(🧪)🧪
公司工具測試(4 支)17 passed全通過python -m pytest -q tests通過
Stage 報告檔名5 個 + consolidated與閘門一致跑一次 Consolidated review待 L3
Windows 權限規則//c/…/egm/egm/*/…版本段用 *claude doctor通過

實務注意:Host 升級也可能讓 EGM 行為改變(例如 Subagent 工具名稱、隔離行為)。Host 升級要和 EGM 升級一樣做 L3 驗證。

11.8 Plugin Marketplace 更新

Claude Code(Shell,實測 --help):

claude plugin marketplace update egm   # 從來源更新 marketplace 目錄
claude plugin update egm@egm           # 更新 plugin(restart required to apply)
claude plugin list                     # 確認新版本

Codex CLI 與 Antigravity 的更新指令,官方文件未列出(尚待驗證)。Antigravity App/IDE 的手動安裝要先刪除 ~/.gemini/config/plugins/egm 再複製新版(官方)。

實務注意:更新後一定要開新 session;舊 session 仍使用舊的 Skill 描述。

11.9 版本升級前檢查

  • 讀 Release notes;確認是否有「breaking」「migration」字樣。
  • git diff --stat <舊tag> <新tag> -- skills agents resources docs/claude.md docs/codex.md。
  • 下載 Release ZIP,執行 sha256sum -c SHA256SUMS 與 gh attestation verify(3.4)。
  • 確認進行中的 Review 都已完成或暫停。
  • 公司閘門工具的 fixture 是否需要更新(報告格式)。
  • 確認 Host 版本仍符合需求。
  • 變更單核准。

11.10 升級後驗證

層次檢查通過條件
L1claude plugin list、plugin validate、plugin details新版本號;7 支 Skill
L2新 session 輸入 /egm:7 個指令
L3用固定的「驗證用設計文件」跑 Consolidated review(可用 3.13.1 的 headless 指令)5 份 stage 報告+consolidated;consolidated 寫明每個 reviewer 已完成
L4對 L3 產出跑 egm_report_gate.py計數與 consolidated 的統計表一致;沒有 R0(格式解析不到)。1.0 版閘門在這一步回報 0 個問題,見 10.5.1
L5公司閘門工具 python -m pytest -q tests全通過

建議準備一份固定的驗證用設計文件(例如本手冊的 fixtures/design_good.md),每次升級都用它跑 L3,比較前後 findings 的數量與類型。注意:LLM 非確定性,findings 數量本來就會浮動;重點是流程有沒有跑完、格式有沒有變。

11.11 Rollback

安裝方式回滾做法
內部鏡像 Marketplace鏡像 main 指回舊 tag → claude plugin marketplace update egm → claude plugin update egm@egm → 新 session(🧪:update 是否接受較低版本未實測;不行時改用下方「完全移除」後重新 install)
官方 Marketplace無法指定版本;改用內部鏡像或本機目錄
本機目錄(臨時)git -C egm checkout v0.1.0 後以 claude --plugin-dir ./egm 啟動(官方說明此方式用於本機測試,並建議用唯一名稱的副本避免與已安裝的 egm 混淆)
Antigravity App/IDE刪除 ~/.gemini/config/plugins/egm,複製舊 tag 的檔案

完全移除(Shell):

claude plugin uninstall egm@egm
claude plugin marketplace remove egm

通過條件:claude plugin list 顯示 egm@egm 的 Version 為回滾目標(例如 0.1.0),新 session 中 /egm: 仍列出 7 支 Skill;再跑一次 11.10 的 L3、L4。

實務注意:回滾後,用新版產生的報告格式可能和閘門工具不一致;回滾也要同步回滾閘門工具的設定。

11.12 Git Tag 與 Release 管理

官方發布流程摘要(docs/releases.md):

  1. 所有 manifest 版本一致(scripts/prepare_release.py 會檢查)。
  2. pytest tests/unit 通過。
  3. 維護者在 main 上建 annotated tag vMAJOR.MINOR.PATCH,不移動已存在的 tag。
  4. 「Prepare draft release」workflow 產生兩個 ZIP、SHA256SUMS、provenance。
  5. 人工審查後才發布。

公司內部對應:

官方公司
tag v0.1.1鏡像同步同名 tag;不自行打 v0.1.1-acme 這類 tag(避免與上游混淆)
Release ZIP下載、驗證後存到內部 artifact repository
Release notes內部公告附中文摘要與影響評估

11.13 自訂規則與官方版本同步

原則:公司內容放在專案或公司 repo,不改 EGM 本身。

公司內容位置與官方升級的關係
standarddocs/standards/不受影響
自訂 persona+adapterdocs/egm/personas/、.claude/agents/檢查官方 persona 格式是否改變
Elephant Skill.claude/skills/<project>-elephant/不受影響
閘門工具tools/報告格式改變時需更新
手冊本文件每次升級更新版本基準

實務注意:若真的需要改 EGM 本身(例如修 bug),優先向上游送 PR。EGM 的 AI_POLICY.md 要求較大的變更先開 Feature Inquiry Issue 並走 EGM 設計文件。

11.14 團隊共用設定管理

設定位置共用方式
Marketplace 與啟用 plugin專案 .claude/settings.jsoncommit
headless 讀取權限使用者層 settings.json(3.15.1:專案層的 allow 在未信任工作區會被忽略,且路徑含使用者名稱);專案層只放 deny範本+說明
artifact 目錄CLAUDE.md/AGENTS.mdcommit
自訂 reviewer.claude/agents/commit
公司 standarddocs/standards/(submodule)鎖 tag

實務注意:專案層權限規則在「尚未信任的工作區」不會生效(實測 claude doctor 訊息,3.15.1)。新同仁第一次開專案時要以互動模式接受信任。

11.15 問題追蹤與故障排除

EGM 維護 SOP:

頻率工作負責
每週檢查上游 Release 與 main 重要變更;整理內部 IssueAI 工具維運
每週各專案 Drift Report模組負責人
每月審查成本與 finding 品質統計(14.10)架構組
每次升級11.9~11.10AI 工具維運+架構組
每季檢討公司 standard 與本手冊架構組

EGM 升級 SOP:

步驟動作證據
1讀 Release notes 與 diff影響評估表
2驗證 ZIP 簽章sha256sum、gh attestation verify 輸出
3鏡像同步新 tag鏡像 commit
4試點安裝,L1~L5 驗證驗證紀錄
5更新閘門工具與 fixture(如需要)PR
6公告升級,要求重開 session公告
7更新版本相容性表與本手冊文件 PR

EGM 故障排除表:

症狀原因檢查解法
升級後 /egm: 消失舊 session開新 session—
升級後閘門解析失敗報告格式改變比對新報告與 fixture更新 regex 與 fixture,重跑測試
reviewer 讀不到 persona權限規則寫死舊版本號/permissions版本段改 *
Review 成本突然變高新增 reviewer personaRelease notes調整使用的 preset
某 Host 突然停在 ReviewHost 升級改了 Subagent 工具Host Release notes回報上游;暫時換 Host

本章注意事項:

  • 版本資訊用指令查,不要依賴網頁摘要或 AI 記憶。
  • 每次升級都更新本手冊的「版本基準」與「版本紀錄」。

11.16 本章 AI 產出審查

檢查點好例壞例怎麼抓
鎖版方式內部鏡像「claude plugin install egm@egm@0.1.1」(不存在的語法)claude plugin install --help
更新後動作開新 session「立即生效」claude plugin update --help 的 restart required
Release 資訊gh release list 結果「目前沒有 Release」直接執行指令

11.17 main 與 v0.1.1 的差異(1.1 追蹤)

查證日期 2026-11-17:最新 tag 仍是 v0.1.1(dea7761),main 停在 72d06f5(2026-11-15),兩者相差 45 個 commit。查證指令(Shell):

git ls-remote https://github.com/google/elephant-goldfish-model HEAD 'refs/tags/*'
gh release list -R google/elephant-goldfish-model -L 3
git -C egm-src log --oneline v0.1.1..origin/main -- skills agents .claude-plugin docs/harnesses.md

與企業使用者有關的差異(不含網站、CI、依賴更新):

變更PR影響企業對策
Bootstrap 認得更多副檔名(.razor、.cshtml、.vb、.ps1、Fortran 等)#324鎖 v0.1.1 時,ASP.NET Razor/VB.NET 目錄仍會被修剪(5.8.2)第 7 章的人工補齊清單依「實際使用的版本」調整
Bootstrap 偵測 .NET(*.sln/*.csproj → dotnet test)#409.NET 專案的 Verification 不再是佔位符同上
實驗性 Windsurf(Devin Desktop)adapter#379、#407新 Host,官方只記錄 Devin CLI 測試(所有寫檔被拒,沒有跑到最終產出),IDE 未測不列入公司核准的 Host
mention 中和(防止 @user 在報告中通知別人)修正 fence 繞過#439;後續 #457 未合併只影響把報告貼到 GitHub 的情境報告 PR 前人工檢查 @
harnesses.md:明寫「approved specifications 要 commit 到 docs/designs/,.dev/docs 只放草稿」文件與本手冊 10.4 的做法一致無
release 附上 provenance bundle、加 OpenSSF Scorecard#426、#425下一個 tag 起可驗證發布來源內部鏡像時一併保存 provenance

實務注意:本手冊實跑 Skill(1.1)使用的是 main 72d06f5,安裝驗證(第 3 章)使用的是 v0.1.1。兩者的 Skill 文字在 Review/Resolve/Drift Report 上沒有差異(git diff v0.1.1..72d06f5 -- skills/egm-review skills/egm-resolve skills/egm-drift-report 為空),Bootstrap 有上表的差異。

11.18 開放中的 RFC 與 PR 追蹤表(1.1)

EGM 迭代很快,社群在 2026-11-10~17 一週內就開了十多個設計提案。下表是尚未合併的項目,不可當成現有功能寫進公司規範:

提案編號(狀態)內容對公司流程的可能影響目前替代做法
EGM LiteIssue #460(design-ready)、#461;PR #438、#459、#463(open)小變更用的 5 階段輕量流程:Critique Pause → 檢查清單 → 範圍內執行 → fresh-context 程式碼審查 → 收尾關卡10.4「何時必須走完整流程」可能新增中間級距維持 10.4 的門檻表;小變更不走 EGM
EGM in ChatIssue #414;PR #464(open)讓網頁版聊天 Host 也能跑 EGM可能讓 PM/SA 不裝 CLI 就能審查目前只核准 CLI Host
Finding 證據標記Issue #433(open)每個 finding 標示依據:文件內缺陷、與引用檔不符、或無法回答的問題有助於 CONTEST/ESCALATE 判斷,閘門可能可以檢查人工依 5.4.6 的表格判斷
提供已記錄的決策給 GoldfishIssue #408(design-ready)讓 reviewer 讀 ADR,但不讀對話直接解決 2.9.1 的「沒寫進文件的決定」問題把 ADR 列入 GoldfishContext
依核准設計檢查實作 diffIssue #436(open)用 Goldfish 比對一個實作 diff 與它的設計(計畫外檔案、漏做 CUJ、越過 Non-Goal)可能取代或補強 egm_scope_guard.pyscope guard(檔名)+ Drift Report(內容)
每個 feature 一個編號資料夾Issue #448(open)egm/NNN-short-name/ 存放同一 feature 的 brief、draft、報告會改變報告路徑,閘門與封存規則要跟著改EGM artifact directory:+10.16 封存路徑
Review loop 執行紀錄與狀態帳本PR #462(open)記錄每一輪的 reviewer、結果與狀態可能成為稽核軌跡的一部分10.16 的封存規則
OpenSpec 原生整合PR #450(RFC,open)在 OpenSpec 的變更提案內直接執行 EGM9.4 的分工可能改變9.4 的做法
plugin-root 路徑解析Issue #455;PR #456(open)Skill 用 ${CLAUDE_PLUGIN_ROOT} 以外的方式找 persona影響 omp 等 Host無

查證方式(每次引用前都要做):

gh pr view 438 -R google/elephant-goldfish-model --json state,mergedAt
gh issue view 460 -R google/elephant-goldfish-model --json state,labels
MERGE_SHA="REPLACE_ME"                            # 換成:gh pr view 的 mergeCommit
git -C egm-src tag --contains "$MERGE_SHA"        # 合併了也要確認在哪個 tag

本節 AI 產出審查:

檢查點好例壞例怎麼抓
未合併功能「EGM Lite(RFC #460,未合併)」「EGM 提供 Lite 模式處理小變更」對 AI 提到的每個功能名稱,grep -rn "egm-lite" egm-src/skills 應有結果才算存在
版本「v0.1.1 沒有 .razor,main 有」「Bootstrap 支援 Razor」git show v0.1.1:skills/egm-bootstrap/SKILL.md | grep -c razor
社群文章註明作者是否實際執行、用哪一版把排行榜、部落格評論當成官方說法回到 repo 原始檔核對

實務注意:Issue #451、#452「Your plugin ranked #6 on the AI plugin leaderboard」是外部排行網站作者開的推廣性 issue(內容是每日排名,「It moved up 4 places since yesterday」),不是功能說明或品質評測,不要引用成「EGM 受業界肯定」之類的依據。

第 12 章:常見問題與疑難排解

每題依「發生原因/檢查方式/解決方法/預防措施」說明。指令以 Claude Code 為主,其他 Host 另註。

12.1 Plugin 無法安裝

項目內容
發生原因無法連 GitHub、proxy、Windows 長路徑、Claude Code 版本過舊、在 Codex 用了 Claude 的指令
檢查方式git ls-remote https://github.com/google/elephant-goldfish-model.git HEAD;claude --version;看錯誤訊息是否含 Filename too long
解決方法設定 proxy;git config --global core.longpaths true;升級 Claude Code;Codex 用 codex plugin add egm@egm
預防措施公司提供內部鏡像與安裝腳本;SOP 依 Host 分頁

12.2 Agent 找不到 EGM Skills

項目內容
發生原因沒開新 session;plugin 停用;在 Codex 輸入 /egm:;期待模型自動觸發(EGM 設 disable-model-invocation: true)
檢查方式claude plugin list 看 Status;claude plugin details egm@egm 看 Skills (7)
解決方法claude plugin enable egm@egm 後開新 session;Codex 改用 skill picker;手動輸入 /egm:egm-<skill>
預防措施教育訓練強調「EGM Skill 只能手動呼叫」

12.3 Agent 無法建立 Subagent

項目內容
發生原因Host 沒有 Subagent 工具(獨立版 Antigravity IDE、部分 ChatGPT 模式);Cowork 子代理不能再建子代理
檢查方式Review 開始時 Agent 回報「a review in the same context is not a Goldfish review」並停止
解決方法換用支援的 Host(Antigravity CLI、Claude Code、Codex CLI);Cowork 由主 Context 直接派工(官方已處理)
預防措施3.7 的支援表列入公司核准 Host 清單

注意:Agent 停止是正確行為。若 Agent 說「我改在目前對話中模擬 reviewer」,那份結果不能當成 Goldfish 審查。

12.4 Goldfish 仍然讀取到先前對話

項目內容
發生原因用了 fork 或 resume 舊 reviewer;Codex 未設 fork_context: false/fork_turns: "none";把父對話內容貼進 reviewer 任務;Host 注入 AGENTS.md(#237)
檢查方式官方建議的探針:在父對話放一個唯一標記(例如 PARENT-MARKER-7f3a),請 reviewer 回報是否知道;正確答案是 UNKNOWN。「check the actual child result, not the parent’s claim」。1.1 做法:在 CLAUDE.md 與呼叫訊息各放一個金絲雀,用 egm_isolation_probe.py 分析 log(2.9.1);注意 reviewer 自己 Read CLAUDE.md 不算注入
解決方法每次 review 都建立新的 reviewer;任務只傳路徑;AGENTS.md 移除設計結論
預防措施PoC 時在公司 Host 跑一次探針並記錄(14.3)

12.5 Goldfish 無法讀取設計文件

項目內容
發生原因路徑錯誤;文件在 artifact 目錄(工作目錄外);權限規則拒絕
檢查方式報告的 Reviewer Status 為 not run,或 finding 寫「incomplete review」
解決方法傳絕對路徑;把文件放在工作目錄內;調整讀取權限
預防措施設計文件一律放 docs/designs/

12.6 Reviewer 無法存取引用的 Source Files

項目內容
發生原因連結指向工作目錄外(需要你核准);URL(Claude reviewer 不能開 URL);headless 時未核准的連結全部排除
檢查方式Review 開始時 Agent 列出「left out」的連結
解決方法把需要的資料存成工作目錄內的檔案,用相對連結;URL 先存成檔案再傳路徑
預防措施設計文件不引用 Confluence 或內網 URL 當作唯一來源

12.7 Review 過程中斷

項目內容
發生原因用量上限(官方 Cowork 測試在 Stage 8 因此中斷)、網路、session 關閉
檢查方式已產生哪些 stage 報告
解決方法已完成的報告保留;用 Step 參數從下一個 stage 繼續(例如 /egm:egm-review X.md 8);Interactive 模式可選 Pause Review 後再繼續
預防措施大文件用 Preset 2/3 分段審;避開用量尖峰

12.8 Review 結果不一致

項目內容
發生原因LLM 非確定性。官方:「Fresh reviewers sample differently each round, so a round with zero findings is rare even when the document improves.」
檢查方式比較兩次的 Blocker/Major 是否指向同一範圍
解決方法用 egm-review-loop 的收斂規則(連續兩輪 clean);settled finding 不重開
預防措施通過標準看「Blocker/Major 是否已處理」,不看 finding 總數

12.9 設計文件過大

項目內容
發生原因一份文件塞了多個功能或多個升級 Phase
檢查方式行數 > 800、Detailed Implementation Plan 檔案數 > 30
解決方法拆成多份設計文件;或用 egm-review-loop 的 SemanticTarget 只審一節;Preset 3 只審實作計畫
預防措施一份設計文件對應一個可獨立上線的變更

12.10 Context 遺失

項目內容
發生原因Elephant 對話太長被自動摘要;換 session 後沒有載入 brief
檢查方式Agent 重複問已回答過的問題
解決方法決策寫進 brief 的 Key Decisions 或設計文件的 Open Questions;新 session 先載入 Elephant Skill 與 brief
預防措施每次重要決定後要求 Elephant 更新檔案

12.11 AI 直接開始寫程式

項目內容
發生原因沒用 EGM Skill,而是直接請 AI 設計;提示中帶了「順便實作」
檢查方式git status 出現 src/ 的變更
解決方法git restore 還原;重新以 /egm:egm-draft 進行
預防措施設計 PR 由 egm-gate 的 docs-only 檢查擋下(git diff --name-only 中有 docs/ 以外的檔案就失敗,10.9 情境 2)

12.12 設計文件與實際程式碼不一致

項目內容
發生原因實作中臨時調整沒有回寫;上線後的 hotfix
檢查方式/egm:egm-drift-report docs/designs/
解決方法由模組負責人決定改文件或改程式(官方:「Human picks which.」)
預防措施每週 drift report;上線後以 docs-only PR 更新 SITEMAP(10.4);實作 PR 不改設計文件

12.13 Bootstrap 產生錯誤文件

項目內容
發生原因副檔名清單未涵蓋(.vue、.jsp、.xml);scout 逾時用了佔位符;從名稱推論
檢查方式搜尋 (Details pending/documentation failed);抽查 Interface 中的符號是否存在
解決方法對錯誤目錄重跑(已存在的檔案會依 Correction Policy 修正);人工補齊
預防措施先小範圍試跑;Bootstrap 結束時選擇跑 drift report

檢查指令(Shell):

grep -rn "Details pending/documentation failed" --include=README.md --include=EGM.md .

12.14 Framework 升級後測試失敗

項目內容
發生原因設計文件漏列 Breaking Change;行為基準測試不足;相依套件衝突
檢查方式失敗的測試對應到哪個 Phase、哪個檔案
解決方法小錯點修;屬於設計遺漏時停止實作、更新設計文件、重跑 Stage 9
預防措施Phase 0 先建行為基準;migration standard 要求逐條對照官方遷移指南

12.15 Plugin 更新後無法使用

項目內容
發生原因沒開新 session;權限規則寫死版本路徑;Skill 名稱或報告格式改變
檢查方式claude plugin list 版本;/permissions;Release notes
解決方法開新 session;權限版本段改 *;依 11.11 回滾
預防措施11.9 升級前檢查;試點環境先驗證

12.16 不同 AI Agent 執行結果不同

項目內容
發生原因隔離程度不同(Claude 排除 CLAUDE.md;Codex/Antigravity 會注入指示檔);具名 persona vs general-purpose;模型不同
檢查方式比較 Reviewer Status、findings 指向的範圍
解決方法同一功能的 Review 固定用同一 Host;AGENTS.md 只放穩定慣例
預防措施公司指定「審查用 Host」;記錄每次審查的 Host 與版本(10.16)

12.17 其他常見問題

問:Goldfish 意見太多,看不完怎麼辦?

官方建議「Take what you think is relevant. Ignore the rest.」先處理 Blocker,再處理 Major;Nit 可以全部 DECLINE。使用 Consolidated report 的 Traceability Matrix 看去重後的行動項目。

問:可以讓 AI 自己決定採用哪個設計方案嗎?

不行。egm-draft 刻意不排名、不預設;你說「幫我選」,它會再把取捨列一次。

問:EGM 會把程式碼送到 Google 嗎?

不會。EGM 沒有伺服器;資料流由你使用的 Host 決定(官方,docs/privacy.md)。

問:Windows 上的讀取權限規則一直不生效?

路徑要寫 //c/Users/...(小寫、無冒號)或 C:\Users\...;//C:/Users/... 不會匹配(官方)。另外檢查工作區是否已信任(3.15.1)。

本章注意事項:遇到本章沒有的問題,先查官方 Issue(https://github.com/google/elephant-goldfish-model/issues),回報時不要附上公司程式碼或個資(官方 docs/privacy.md)。

12.18 本章 AI 產出審查

請 AI 協助排錯時,檢查它的建議:

檢查點好例壞例
Subagent 不可用換 Host「改在同一個對話裡模擬 reviewer」
權限錯誤開放 EGM 四個目錄的讀取「關閉權限檢查」「--dangerously-skip-permissions」
Review 不一致用收斂規則「多跑幾次直到沒有 finding」
隔離問題放金絲雀,用 egm_isolation_probe.py 看 reviewer 實際讀了什麼「報告沒提到就代表沒讀到」
閘門結果先證明閘門解析得到 findings(看 blocker/major 計數)「GATE PASS 就代表沒有問題」

怎麼抓(Shell):

# AI 建議中出現危險的繞過手段
grep -n -i -E "dangerously-skip-permissions|bypassPermissions|failOnEmptyShould=false|--no-verify" ai_suggestion.md
# 閘門 PASS 但計數全為 0:先確認報告格式是否被解析
python tools/egm_report_gate.py .dev/docs/*.md | grep -E "blocker=0 major=0 nit=0"

第 13 章:同仁使用指南與教育訓練

13.1 PM

如何使用 EGM 釐清需求:參加 Brainstorm 的前 2~3 輪,回答「為什麼要做」「怎麼衡量成功」「什麼不做」。

操作範例(Claude Code 對話框,PM 與 SA 一起):

/egm:egm-brainstorm 客服希望在客戶頁快速找到「該聯絡誰」,目前平均要翻 3 分鐘 Excel

Elephant 問「成功要怎麼衡量?」時,PM 給可量測的回答:「客服找到聯絡人的時間 ≤ 30 秒,以客服系統操作紀錄量測,上線後 4 週評估」。

如何檢查需求完整性:讀 concepts_brief.md 的「Goals vs. Non-Goals」,逐條問自己:

  • 每個 Goal 都能在驗收時判斷達成與否。
  • 利害關係人以為會做、但其實不做的事,都列在 Non-Goals。
  • Alternatives Weighed 中被否決的方案,業務上可以接受。

如何確認交付成果:驗收時對照設計文件的 CUJ(每個 CUJ 一個驗收情境)與 Goals。

實務注意:PM 不需要看懂 Detailed Implementation Plan,但要確認 Non-Goals——範圍爭議九成來自這裡。

13.2 SA

如何利用 Elephant 進行需求分析:先載入專案 Elephant Skill,再 Brainstorm;回答時給數字、給邊界、給例外。

如何產生系統規格:Draft 的 Step 2(Overview、Problem、Goals、Non-Goals)由 SA 核准;CUJ 由 SA 撰寫或修改成 Given/When/Then。

CUJ 好例與壞例:

好例壞例
Given 業務有 CUSTOMER_EDIT 且 C001 無主要聯絡人/When 新增並勾選主要/Then 回 201,C001 恰有一位主要聯絡人,稽核表新增 CONTACT_CREATEDGiven 使用者登入/When 新增聯絡人/Then 成功

如何利用 Goldfish 找出需求缺漏:

  1. Interactive Review 時,親自讀 comprehension_report.md 開頭的兩段 paraphrase。
  2. paraphrase 與你的理解不同的地方,就是文件寫得不清楚的地方。
  3. 對需求類文件(不是設計文件),可用 review loop:
/egm:egm-review-loop
TargetFile: docs/requirements/contact-requirements.md
SemanticTarget: full file
Reviewers: [comprehension, design_critic]
Standards: {"design_critic": "feature-spec-standard"}
GoldfishContext: []

實務注意:SA 最有價值的動作是「否定 Goldfish 的 paraphrase」——它理解錯了,代表新進同仁也會理解錯。

13.3 SD / Architect

如何進行架構設計:在 Draft Step 3 面對多個可行方案時,Elephant 會列出最多三個選項;Architect 的工作是選擇並寫下理由。

如何設計 ADR:EGM 的 Alternatives Considered 就是 ADR 的核心。建議重大決定另存 ADR(範例):

# ADR-0012: 主要聯絡人唯一性由 Customer Aggregate 維持

* **Status:** Accepted
* **Date:** 2026-11-20
* **Design:** docs/designs/customer-contact.md

## Context
同一客戶只能有一位主要聯絡人;兩位業務可能同時設定。

## Decision
由 Customer Aggregate 檢查,資料庫以部分唯一索引作為最後防線;衝突回 409。

## Alternatives
- 聯絡人獨立成 Aggregate:Rejected by author,唯一性只能靠資料庫,錯誤訊息不友善。

## Consequences
- 修改聯絡人需鎖定 Customer(樂觀鎖),高並行客戶可能出現較多 409。

如何審查架構:讀 Stage 5、7、8 報告;用 review loop+公司 Clean Architecture standard(4.14)。

如何確認 Implementation Readiness:Stage 9 通過、egm_design_lint.py 通過、File Boundary 每個檔案都有理由。

實務注意:Architect 審設計 PR 時,重點是「Goldfish 無法判斷的事」:與公司架構方向一致嗎?與其他團隊的計畫衝突嗎?

13.4 PG

如何依照設計文件進行 AI Coding:用新 session,給 5.6 的實作提示範本;一次只做一個 Phase。

如何控制 AI 修改範圍:

# 實作過程中隨時檢查(Shell)
# 參數與 CI 完全相同:設計從 base 分支讀、只看本 Phase、只允許 reviews 目錄
git show origin/main:docs/designs/customer-contact.md > design-base.md
python tools/egm_scope_guard.py design-base.md --phase 1 --base origin/main \
  --allow "docs/designs/reviews/customer-contact/**"

如何執行測試:執行設計文件 Verification Plan 的每一條指令;ArchUnit 要確認 Tests run ≥ 1(6.6.2)。

如何確認實作符合規格:

  • 每個 CUJ 都有對應測試。
  • 每個不變式(例如最多 50 位)都有單元測試。
  • 例外對應表中的每個 HTTP 狀態都有 API 測試。
  • scope guard 無越界。

實務注意:實作中發現設計沒寫清楚的地方,不要自己決定(那正是 Zero-Decision Rule 要避免的)。記錄問題,請 SD 更新設計文件。

13.5 QA

如何依照設計文件產生測試案例(Claude Code 對話框):

請讀 docs/designs/customer-contact.md,為每個 CUJ 與 Goals 中的每一條規則產生測試案例表,
欄位:編號、對應 CUJ/Goal、前置條件、步驟、預期結果、測試層級(Unit/API/E2E)。
不要假設文件沒寫的行為;文件沒寫的列在「需求缺口」表。

如何找出需求與測試缺口:AI 產出的「需求缺口」表就是回饋給 SA 的清單。也可以用 review loop 讓 Goldfish 審查測試計畫:

/egm:egm-review-loop
TargetFile: docs/qa/customer-contact-testplan.md
SemanticTarget: full file
Reviewers: [implementation_readiness, comprehension]
Standards: {"implementation_readiness": "implementation-readiness-standard"}
GoldfishContext: [docs/designs/customer-contact.md]

如何執行獨立驗證:QA 的測試案例由 QA(或 QA 的 AI session)依設計文件產生,不使用實作者的 session,避免「實作者寫的測試只驗證實作者的理解」。

實務注意:QA 是公司內最接近「人類 Goldfish」的角色——只看文件,不看實作對話。

13.6 DevOps

如何管理 Plugin 版本:內部鏡像(11.1)、版本相容性表(11.7)、升級 SOP(11.15)。

如何管理 AI Agent 執行環境:

項目做法
Host 版本公司映像檔固定 Claude Code 版本,≥ 2.1.271
設定專案 .claude/settings.json 與 CLAUDE.md 進 git
權限headless 只開 EGM 四個目錄讀取(3.15.1)
隔離試裝CLAUDE_CONFIG_DIR=<空目錄> 驗證安裝而不影響個人設定

如何整合 CI/CD:egm-gate workflow(10.9)、ArchUnit Tests run 檢查(6.6.2)、SBOM(10.15)。

實務注意:CI 只做機械檢查;不要在 CI 中自動跑 /egm:egm-review,除非已處理成本、權限與非確定性問題(🧪,官方的 opt-in 整合測試「consume model usage」)。

13.7 教育訓練課程規劃

課程對象時數內容實作
E1 EGM 觀念全員1第 1 章;Elephant/Goldfish/人類手動練習:一個 session 寫設計、另開 session 只貼文件請它找問題
E2 安裝與第一次審查PG、SD、DevOps2第 3 章;60 秒審查安裝後對既有 PR 計畫跑 /egm:egm-review
E3 Brainstorm 與 DraftSA、SD3第 5.1~5.2 章以虛構需求完成 brief 與設計文件
E4 Review 與 ResolveSD、Architect3第 5.3~5.4 章解讀 5 份報告,練習 CONTEST 與 ESCALATE
E5 逆向工程SD、PG3第 7 章用 fixture 練習證據檢查
E6 升級SD、PG、DevOps3第 8 章撰寫一份 Phase 0~1 升級設計
E7 治理與閘門Architect、DevOps、資安2第 10 章跑 egm-gate 6 種情境(10.9)

課後評量(建議):

  • 能說出 Review 5 個 stage 與各自的 reviewer。
  • 能說出為什麼 Stage 6 不給 GoldfishContext。
  • 能分辨 CONTEST 與 ESCALATE。
  • 能用 scope guard 找出越界檔案。
  • 能說出 EGM 不能做的三件事。

13.8 本章 AI 產出審查

角色檢查點好例壞例怎麼抓
PMNon-Goals 完整「不做去重批次,另案處理」Non-Goals 空白或只寫「無」awk '/^## Non-Goals/,/^## Open/' design.md
SACUJ 可驗證Given/When/Then 都有可觀察的結果(狀態碼、筆數)「系統正常運作」grep -n -E "\*\*Then\*\*" design.md 逐條看有沒有數字或狀態
SDAlternatives 真有比較每個方案有 Pros/Cons/Reason for Rejection只有一個方案,或理由也適用於選定方案egm_design_lint.py D2;人工讀 Rejection 理由
PG沒有越界、測試真的有跑scope guard 0 越界;Tests run ≥ 1改了計畫外檔案;Tests run: 013.4 的 scope guard;6.6.2 的 for 迴圈
QA測試涵蓋文件沒寫的假設測試名稱可對應到 CUJ 或 Invariant測試斷言 AI 自己假設的行為grep -n "@DisplayName|it(" -r src/test 對照 CUJ 清單
DevOps閘門用反例驗證過故意放違規,CI 失敗只看過 CI 綠燈10.9 CI 模擬的 6 個情境

第 14 章:企業導入計畫與效益評估

14.1 導入目標

目標可量測的說法
在寫程式前發現設計缺漏設計階段發現的 Blocker/Major 數;實作階段才發現的設計問題數
降低返工實作 PR 因設計問題退回的比例
建立可維護的設計文件有核准設計文件的功能比例;drift 項目數
讓 AI 實作可控scope guard 越界次數

不設定「生產力提升 X%」這種目標。官方 FAQ:「Completing the EGM workflow alone does not demonstrate a productivity improvement.」

14.2 導入前準備

項目負責完成條件
核准 AI Host 與帳號(Claude Code/Codex)資安、法遵書面核准
確認 Host 支援 SubagentAI 工具維運12.4 探針結果
內部鏡像或允許連 GitHubDevOps3.2 檢查通過
公司 standard 初版架構組4.14~4.16
閘門工具與 CI 範本DevOps附錄 B 測試全通過
本手冊審閱架構組版本紀錄
試點專案與人員PM名單

14.3 PoC

期間 2~3 週,1~2 位資深工程師。

週工作證據
1手動練習 Rensin 流程一次(不裝 Plugin);安裝 EGM,L1~L3 驗證驗證紀錄
1隔離探針(12.4)、權限設定(3.15.1)探針結果
2對 2 份既有設計文件或 PR 計畫跑 /egm:egm-review,由原作者評估 findings 有用率finding 評分表
2對 1 個小型新功能跑完整流程全部產物
3成本統計、問題清單、Go/No-GoPoC 報告

PoC 報告可用 heilmeier-standard 讓 Goldfish 審查(2.5)。

PoC 檢核:

  • 公司核准的 Host 能建立全新 Context 的 Subagent。
  • Review 能完整跑完 5 個 stage。
  • findings 有用率(由作者判定)達到團隊可接受程度。
  • 單次 Review 的時間與費用可接受。
  • 資安確認資料流可接受。

14.4 Pilot

期間 1~2 個月,1~2 個專案團隊,納入 CI 閘門。每兩週回顧:哪些 finding 沒價值(調整 preset 或 standard)、哪些步驟太重(調整 10.4 的門檻)。

14.5 正式導入

階段範圍條件
1新專案、高風險變更Pilot 回顧通過
2升級專案(第 8 章)migration standard 定稿
3既有系統逆向工程(第 7 章)證據規範定稿

14.6 教育訓練

依 13.7 課程表。每個團隊至少一位完成 E1~E4 的「EGM 種子人員」。

14.7 企業共用規範

規範位置
本手冊.github/教學/AI開發/
公司 standarddocs/standards/(公司共用 repo)
閘門工具與 CI 範本公司共用 repo tools/、.github/workflows/
設計文件模板(官方+公司追加章節)公司共用 repo

14.8 團隊推廣

  • 從「60 秒審查」開始:對現有 PR 計畫跑 /egm:egm-review,讓團隊先看到價值。
  • 分享「Goldfish 抓到的真實問題」案例(去識別化)。
  • 不強迫所有變更走 EGM(10.4)。

14.9 導入風險

風險影響緩解
審查意見過多造成疲乏同仁忽略所有 finding教 Blocker/Major 優先;調整 preset
審查成為瓶頸交付變慢10.4 門檻;Preset 2/3
Host 不支援 SubagentReview 無法執行PoC 先驗證
EGM 升級改變格式閘門失效11 章 SOP
把 AI 審查當成人工審查責任模糊10.18 責任歸屬
資料外洩法遵風險10.11

14.10 效益評估

建議 KPI(計算方式與資料來源要在 PoC 前定義,並在導入前收集基準值):

KPI計算方式資料來源評估注意事項
設計文件完整度通過 egm_design_lint.py 的設計文件數 ÷ 設計文件總數CI 紀錄只代表格式完整,不代表內容正確
Goldfish Review 缺失發現率作者判定「有用」的 Blocker+Major 數 ÷ 全部 Blocker+Major 數finding 評分表(人工標註)由作者標註有偏差;抽樣請第二人複核
設計返工率設計核准後因設計問題重開設計 PR 的次數 ÷ 核准設計數Git/PR 紀錄需求變更造成的重開要排除
Coding 一次通過率第一次提交就通過 CI 與 Code Review 的實作 PR 數 ÷ 實作 PR 數PR 紀錄受 PR 大小影響,要分組比較
程式缺陷密度上線後 90 天內缺陷數 ÷ 變更 KLOC缺陷追蹤系統樣本小時波動大
自動化測試覆蓋率分支覆蓋率(JaCoCo、Vitest)CI 報告覆蓋率高不代表測對;搭配突變測試抽查
AI 產出程式碼人工修改比例AI 產生後到合併前被人修改的行數 ÷ AI 產生行數Git diff(需標記 AI commit)需要 commit 標註慣例
Framework 升級成功率按計畫 Phase 上線且未回滾的 Phase 數 ÷ 計畫 Phase 數變更紀錄回滾本身可能是正確決定
文件與程式碼一致性drift 項目數 ÷ 設計文件數(每週)Drift ReportAI 判斷非確定性,看趨勢不看單次
開發交付週期需求登錄到上線的天數(中位數)Issue/部署紀錄設計時間會增加,看總週期

評估方法(建議):

  1. 導入前收集 3 個月基準值。
  2. 同類型、同規模的變更才比較。
  3. 每月報告附「樣本數」;樣本 < 10 時只描述,不下結論。
  4. 同時報告成本:Review 的時間、token 費用、人工處理 finding 的時間。

本章注意事項:官方 FAQ 對生產力的立場是「It depends」,並建議「Compare total time, useful findings, and rework on your own tasks」。公司的結論也只能來自自己的數據。

14.11 本章 AI 產出審查

檢查點好例壞例怎麼抓
效益數字「PoC 樣本 6 件,有用 finding 率 58%(作者判定)」「導入後效率提升 40%」每個數字要有樣本數與來源
KPI 定義分子、分母、資料來源「品質提升」看能否寫成公式
成本列出 token 與人工時間只講效益搜尋「成本」

第 15 章:實戰範例與完整操作演練

五個案例都依同一格式:專案背景 → 使用者需求 → Elephant 操作步驟 → Brainstorm 對話 → Draft 文件 → Goldfish 審查結果 → Resolve → 人工核准 → AI Coding 指令 → 測試案例 → 最終交付文件。

案例中的對話與報告是依 EGM v0.1.1 的 Skill 規則與報告格式撰寫的示範,用來說明每一步長什麼樣子;不是某一次實際執行的逐字輸出(實際 findings 每次都不同)。可實際執行的部分(工具、ArchUnit、測試)已標示實測。

15.1 案例一:新建 Web Application

15.1.1 專案背景

ACME Bank 企業客戶管理系統(CRM),Vue 3+PrimeVue 前端、Spring Boot 4.0 後端、PostgreSQL。既有模組:customer-api、customer-app、customer-domain、customer-infra。

15.1.2 使用者需求

客服與業務需要在客戶頁維護多位聯絡人、標示一位主要聯絡人,列表遮罩個資。

15.1.3 Elephant 操作步驟

#操作(Claude Code 對話框)說明
1/crm-elephant載入專案 Context(4.10)
2/egm:egm-brainstorm 客戶頁新增聯絡人與主要聯絡人,列表遮罩個資開始
3回答 6~10 輪問題一次一題
4選「Review with Goldfishes」7 視角挑戰
5處理主要反對意見後,選「Proceed to egm-draft」brief 定稿
6/egm:egm-draft逐節核准
7儲存到 docs/designs/customer-contact.mdStep 6

15.1.4 Brainstorm 對話範例

Elephant:這個功能目前怎麼處理?為什麼不夠好?
業務 SA:聯絡人放在 Excel 與 Email 簽名檔,客服平均要 3 分鐘才找到該聯絡誰。

Elephant:「主要聯絡人」的判斷依據是什麼?由誰決定?
業務 SA:由負責業務指定,一個客戶最多一位。

Elephant:一位客戶最多可能有多少聯絡人?目前資料的最大值是多少?
SD:上限訂 50;目前最多的是 23 位。

Elephant:個資遮罩規則由誰定義?列表與詳細頁的權限是否不同?
SA:列表一律遮罩;詳細頁明碼需要 CONTACT_PII_READ 權限。

Elephant:Anchored feature hypothesis:業務可為客戶維護最多 50 位聯絡人並指定一位主要聯絡人;
列表遮罩手機與 Email,明碼僅限有 CONTACT_PII_READ 的詳細頁;所有異動寫稽核。How would you like to proceed?
  - Review with Goldfishes
  - Clarify additional constraints or assumptions in chat
SD:Review with Goldfishes

Goldfish 提出的主要反對意見(Elephant 在聊天中摘要 2~3 項):

concepts_brief.md 已更新。主要風險:
1. Contrarian/YAGNI:既有 CRM 的「客戶備註」能否滿足 80% 需求?若不行,原因要寫進 brief。
2. Migration:Excel 既有聯絡人要不要匯入?若要,去重規則是什麼?
3. Observability:主要聯絡人被改掉時,客服如何知道是誰改的?
請問要如何處理這些意見?

決定:備註欄無法搜尋與遮罩(寫入 Alternatives Weighed);匯入另案(Non-Goal);稽核紀錄可查詢(Goal)。

15.1.5 Draft 文件範例

完整設計文件見 5.2.4(fixtures/design_good.md),公司另追加 ## Security & Compliance 章節。

Draft 過程中 Elephant 遇到的架構選擇(Author Decides Architecture):

「主要聯絡人唯一性」有三種做法:
A. Customer Aggregate 檢查+資料庫部分唯一索引。取捨:修改聯絡人需鎖 Customer;失效條件:高並行時 409 較多。
B. 聯絡人獨立 Aggregate,只靠資料庫唯一索引。取捨:鎖粒度小;失效條件:錯誤只能從 DB 例外轉換,訊息不友善。
C. 應用層先查後寫,不加索引。取捨:最簡單;失效條件:並行時可能出現兩位主要聯絡人。
請選擇其一。

SD 選 A,B 寫入 Alternatives Considered,C 因無法保證一致性未列入(在 brief 中標為 Rejected by author)。

15.1.6 Goldfish 審查結果範例

/egm:egm-review docs/designs/customer-contact.md

選 Interactive。各 stage 代表性 findings(示範):

StageReviewerSeverityFinding
5egm-zoom-outMajor「Email 唯一以雜湊比對」引入新的雜湊工具類,但專案已有 common-crypto 模組的 HashService
5egm-inventive-catalystNit唯一性與並行的取捨可用「Beforehand Cushioning」(409 後前端自動重新載入)
6egm-comprehensionMajorparaphrase 把 CONTACT_PII_READ 理解成「角色」,文件未說明它是權限碼及其核發單位
7egm-designBlocker未說明兩個交易同時設定主要聯絡人時,哪一層保證、回應碼為何
7egm-designMajorSecurity & Compliance 未說明 AES 金鑰的輪替週期
7egm-structuralNit缺 ### Additional Resources
8egm-zoom-outNit為回應 Stage 7 新增的「重試佇列」超出需求,建議移除
9egm-codebase-detailsMajorAddContactService 要寫稽核,但計畫沒寫明使用哪個既有介面、位於哪個模組
9egm-implementation-readinessMajor測試案例未包含「同時設定主要聯絡人」的整合測試

Stage 6 的 paraphrase(comprehension_report.md 開頭,示範):

## What the document proposes
Sales staff can store up to 50 contacts per customer and mark one as primary.
Lists show masked phone and email. Full values need the CONTACT_PII_READ role.

## How the existing system works (as described)
Contacts are kept outside the CRM in spreadsheets and email signatures.

SA 比對後發現 Goldfish 把權限碼理解成「角色」——正是 Stage 6 的 Major 所指的問題。

15.1.7 Resolve 修正範例

goldfish_review_report.md(節錄,示範):

Issue分類處理
並行設定主要聯絡人(Blocker)PROPOSE FIXTechnical Plan 加「Customer @Version 樂觀鎖+ux_contact_primary 為最後防線;衝突回 409 PRIMARY_EXISTS」
CONTACT_PII_READ 未定義(Major)PROPOSE FIXcomprehension gap 不可反駁:在 Security & Compliance 加定義與 docs/standards/iam-permissions.md 連結
金鑰輪替(Major)ESCALATE銀行金鑰政策 KMS-07 規定 KMS 每 90 天自動輪替,reviewer 讀不到該政策;由資安科簽核
既有 HashService(Major)PROPOSE FIX改為重用 common-crypto 的 HashService
稽核介面(Major)PROPOSE FIX第 4 項寫明使用既有 customer-app/.../port/AuditPort.java
缺並行整合測試(Major)PROPOSE FIXVerification Plan 加 Testcontainers 並行測試
重試佇列(Nit)PROPOSE FIX移除(值得修的 Nit)
缺 Additional Resources(Nit)DECLINE—

ESCALATE 簽核檔見 10.5 的 review_signoff.md。

15.1.8 人工核准

核准者確認內容結果
Architect方案 A、重用 HashService、與 ADR-0007 一致Approve
資安PII 加密、遮罩在後端、稽核事件Approve,要求加 A01 對照
QACUJ 可測、並行測試Approve
CI egm-gate設計 PR:lint、Status、report gate、docs-only;實作 PR:scope guard全部通過

15.1.9 AI Coding 指令

新 session(Claude Code 對話框):

請依 docs/designs/customer-contact.md 的 Detailed Implementation Plan 實作。
1. 只修改「Target Files to Create/Modify」列出的檔案。需要其他檔案時停下來說明。
2. 不新增相依套件;HashService 使用 common-crypto 既有實作。
3. 依計畫第 1~8 項的順序完成(domain → migration → app → api → OpenAPI → 測試)。
4. 每完成一個檔案就執行 Verification Plan 的對應指令並回報。
5. 設計文件與現有程式衝突時,回報衝突,不要自行決定。

15.1.10 測試案例

編號對應層級案例預期
T1Goal 1Unit新增第 51 位聯絡人例外;仍為 50 位
T2Goal 1Unit第二位主要聯絡人例外
T3CUJ 1APIPOST 新增主要聯絡人201
T4Blocker 修正Integration兩執行緒同時設定主要一個 201、一個 409
T5Goal 2API無 CONTACT_PII_READ 取詳細資料手機遮罩
T6架構ArchUnit依賴方向通過,且 Tests run ≥ 1
T7CUJ 1E2EPlaywright 6.6.3列表顯示「主要」

T1、T2、T6 對應的程式在 archunit-lab 實測通過(6.6.1)。

15.1.11 最終交付文件

文件路徑
設計文件(Approved)docs/designs/customer-contact.md
SITEMAPdocs/designs/SITEMAP.md
審查紀錄docs/designs/reviews/customer-contact/*.md
ADRdocs/adr/0012-primary-contact-uniqueness.md
OpenAPIdocs/api/customer-contact.openapi.yaml
測試報告CI artifact
完成報告docs/designs/reviews/customer-contact/completion.md

實務注意:本案最有價值的 finding 是 Stage 7 的並行 Blocker 與 Stage 6 的 paraphrase 誤解——兩者都是作者「覺得理所當然」而沒寫清楚的事。

15.2 案例二:既有 Java 系統逆向工程

15.2.1 專案背景

貸款核准模組 loan-service:Spring Boot 2.3.12、Java 8;交易設定仍沿用 Spring XML(WEB-INF/applicationContext.xml),畫面為 JSP,另有 MyBatis、Oracle PL/SQL、IBM MQ。原開發者已離職,文件只有 2014 年的 Word 檔。

15.2.2 使用者需求

授信部要求說明「什麼條件會自動核准」;架構組計畫明年升級(案例三)。

15.2.3 Elephant 操作步驟

#操作產出
1技術盤點(7.5.2 步驟 1)副檔名統計
2/egm:egm-bootstrap src/main/java/com/acme/loan target_filename=EGM.mdEGM.md 階層
3找出未處理的 .jsp、*Mapper.xml、.pkb(7.5.2 步驟 3)NEED-DOC 清單
4Elephant 逐項分析(7.5.2 步驟 4~12 提示)docs/legacy/*.md
5證據檢查+review loop報告
6業務單位回答【待確認】簽核

15.2.4 Brainstorm 對話範例

逆向工程不從 Brainstorm 開始,而是從 Elephant 的分析對話開始(示範):

SD:請找出所有會改變 LOAN_APPLICATION.STATUS 的程式。
Elephant:找到三處:
1. LoanApprovalService.approve 呼叫 loanDao.updateStatus(REJECTED、APPROVED)
   [src/main/java/com/acme/loan/LoanApprovalService.java:approve]
2. PKG_LOAN.SP_MANUAL_REVIEW 設為 PENDING_REVIEW [db/PKG_LOAN.sql:SP_MANUAL_REVIEW]
3. 【推測】LoanMapper.xml 可能有其他 UPDATE,但 Bootstrap 未處理 XML,需要我讀 LoanMapper.xml 嗎?
SD:讀。
Elephant:LoanMapper.xml 的 updateStatus 只有一個 UPDATE,參數化 #{status},沒有其他狀態變更。

15.2.5 Draft 文件範例

docs/legacy/10-business-rules.md 見 7.5.1 的 re_doc_good.md。System Architecture 節錄(示範):

flowchart LR
    JSP["approve.jsp"] --> CTL["LoanApproveController"]
    CTL --> SVC["LoanApprovalService"]
    SVC --> DAO["LoanDao/LoanMapper.xml"]
    DAO --> ORA[("Oracle LOAN_APPLICATION")]
    SVC -->|"金額大於門檻"| SP["PKG_LOAN.SP_MANUAL_REVIEW"]
    SP --> Q[("LOAN_REVIEW_QUEUE")]
    MQ["IBM MQ LOAN.RESULT"] -.->|"【待確認】由誰消費"| EXT["核心系統"]

15.2.6 Goldfish 審查結果範例

python tools/egm_evidence_check.py docs/legacy/*.md --root .

AI 初稿的實測結果見 7.5.1(EVIDENCE FAIL (5))。review loop(codebase_details+re-implementation-standard)的 findings(示範):

SeverityFinding
BlockerBR-02「自動核准」未說明交易邊界:updateStatus 與 MQ 發送是否在同一交易
MajorData Dictionary 未列 STATUS 的所有代碼值(程式中出現 PENDING_REVIEW,文件只有三個)
Major例外處理文件沒說明 SP 失敗時 approve() 回傳什麼

15.2.7 Resolve 修正範例

Finding分類處理
交易邊界PROPOSE FIX追 applicationContext.xml 的 tx:advice,補「approve 在交易內;MQ 發送在交易外【已確認】[WEB-INF/applicationContext.xml:L88-L97]」
代碼值PROPOSE FIX補 PENDING_REVIEW
SP 失敗ESCALATE程式只記 log 後回傳 MANUAL_REVIEW,是否符合業務預期需授信部確認

注意:本表描述的是完整的 loan-service(含 try/catch、MQ 發送與 WEB-INF/applicationContext.xml)。附錄 B 的 fixtures/legacy 只是精簡版,沒有這些程式碼;對 fixture 跑 egm_evidence_check.py 驗證這兩句會得到 E1。這正是證據檢查要抓的情況:引用的檔案必須真的存在。

15.2.8 人工核准

授信部確認 BR-01~03;BR-04「門檻依分行不同」確認為錯誤推測(全行一致);BR-05 SLA 由授信部補充為 2 個工作天。

15.2.9 AI Coding 指令

逆向工程本身不寫程式。唯一的程式產出是行為基準測試(為案例三準備,新 session):

請依 docs/legacy/10-business-rules.md 中【已確認】的 BR-01~BR-03,
在 src/test/java/com/acme/loan/golden/ 新增 characterization test:
固定輸入(去識別化),記錄 approve() 回傳值與 LoanDao 被呼叫的參數。
不得修改 src/main。

15.2.10 測試案例

編號規則輸入預期
G1BR-01score=599, amount=100000REJECTED
G2BR-01 邊界score=600, amount=100000APPROVED
G3BR-02 邊界score=700, amount=300000APPROVED
G4BR-03score=700, amount=300001MANUAL_REVIEW,呼叫 SP

15.2.11 最終交付文件

docs/legacy/00-overview.md~12-security.md(7.4 表)、open-questions.txt(已全部關閉)、證據檢查報告、golden master 測試。

實務注意:BR-04 的錯誤推測若沒有被標成【推測】,就會被帶進升級設計,變成新系統的「需求」。

15.3 案例三:Spring Boot Framework 升級

15.3.1 專案背景

承案例二的同一個 loan-service(Spring Boot 2.3.12、Java 8、Spring XML 交易設定、JSP、MyBatis、Oracle 19c、IBM MQ);案例二已完成文件與 golden master 測試。

15.3.2 使用者需求

Java 8 與 Spring Boot 2.3 已停止支援,資安要求一年內升級;不改變業務行為。

15.3.3 Elephant 操作步驟

#操作產出
1/crm-elephant(或 loan 專案的 Elephant Skill)載入 As-Is 文件
2/egm:egm-brainstorm 將 loan-service 升級到 Java 21/Spring Boot 4.0,業務行為不變brief
3/egm:egm-draftdocs/designs/loan-service-upgrade.md
4/egm:egm-review … feature_specStage 5~8
5review loop+migration standard 審 Detailed Implementation Plan報告

15.3.4 Brainstorm 對話範例

Elephant:「業務行為不變」要怎麼證明?現有的 golden master 涵蓋哪些路徑?
SD:approve() 的四個分支,200 筆樣本。
Elephant:MQ 訊息格式、Oracle 交易行為不在 golden master 範圍內。它們算不算「業務行為」?
SD:算。MQ 訊息內容與 header 都不能變。
Elephant:那要有 MQ 訊息的比對測試,目前沒有。要列入 Phase 0,還是接受風險?
SD:列入 Phase 0。

Goldfish(Migration 視角)的反對意見:「一次升到 4.0 的回滾成本過高,建議以 2.7、3.5 為中繼點各自上線。」

15.3.5 Draft 文件範例

Compatibility Matrix 與 Phase 規劃見 8.5.1。Phase 1 的實作計畫節錄(示範):

### Phase 1:Java 17+Spring Boot 2.7.x

#### 2. `pom.xml` (Modify)
*   **Type / Scope**: Build Configuration
*   **Proposed Changes**: parent `spring-boot-starter-parent` 2.3.12 → 2.7.x(實作當日最新 patch,
    寫入 PR 描述);`maven.compiler.release` 17;`ojdbc8` → `ojdbc11`;以 runtime scope 新增
    `spring-boot-properties-migrator`(Phase 2 結束時移除)。

#### 3. `src/main/resources/application.yml` (Modify)
*   **Proposed Changes**: 依 properties-migrator 的啟動警告逐項改名;不得新增屬性。

### Verification Plan
*   **Unit Tests**: `mvn -q test`(含 golden master G1~G4)
*   **E2E/Integration**: `mvn -q verify -Pit`(Testcontainers Oracle Free、MQ 訊息比對)

15.3.6 Goldfish 審查結果範例

見 8.5.1(Phase 2 回滾未定義 Blocker、MyBatis 版本未決 Major)。另一個常見 finding(示範):

SeverityReviewerFinding
Majoregm-implementation-readiness「2.7.x 最新 patch」仍留給實作者決定版本;應在計畫中寫死版本或寫明「以 PR 開立當日 Maven Central 最新 2.7.x,並在 PR 描述記錄」的決定規則

15.3.7 Resolve 修正範例

Finding分類處理
Phase 2 回滾PROPOSE FIX加回滾與佇列清空程序
MyBatis for Boot 4PROPOSE FIXPhase 3 移到下一份設計
2.7.x patch 版本CONTEST文件已寫決定規則(引用 Phase 1 第 2 項原文);reviewer 讀得到,屬可檢查證據

15.3.8 人工核准

Architect 核准 Phase 0~2;資安確認 Spring Security 設定變更的權限矩陣測試;維運確認每 Phase 的部署窗口與回滾演練。

15.3.9 AI Coding 指令

請只實作 docs/designs/loan-service-upgrade.md 的 Phase 1。
1. 只改 Phase 1 列出的檔案。
2. 啟動應用一次,把 spring-boot-properties-migrator 的警告完整貼回給我,再改 application.yml。
3. 執行 mvn -q test 與 mvn -q verify -Pit,回報結果;golden master 任何差異都停下來,不要修改測試。

15.3.10 測試案例

編號類型內容預期
M1Golden masterG1~G4與升級前完全相同
M2MQ 比對送出 50 筆,比對 body 與 MQRFH2 header相同
M3交易SP 失敗時 approve 的回傳與 DB 狀態與升級前相同
M4權限矩陣每個端點 × 角色與升級前相同
M5效能approve P95≤ 升級前 +10%

15.3.11 最終交付文件

As-Is(案例二)、loan-service-upgrade.md(To-Be、Compatibility Matrix、Breaking Changes 對照、Phase 計畫、Rollback)、審查紀錄、每 Phase 的測試報告、Upgrade Completion Report(8.5.1 範本)。

實務注意:CONTEST 成立的關鍵是「reviewer 讀得到的證據」。本案引用文件本身的原文,所以是合格的 CONTEST;若理由是「團隊都知道」,就只能 ESCALATE。

15.4 案例四:Vue 2 升級 Vue 3

15.4.1 專案背景

CRM 舊前端 crm-web:Vue 2.7、Vuex 3、Vue Router 3、Element UI、JavaScript、Webpack,約 180 個 .vue 檔。新功能已用 Vue 3+PrimeVue 開發(案例一),兩套並存。

15.4.2 使用者需求

Vue 2 已停止支援;統一成 Vue 3+TypeScript+Pinia+PrimeVue,分批上線,不影響業務操作。

15.4.3 Elephant 操作步驟

#操作注意
1盤點:.vue 檔數、Vuex module、全域 filter、event bus、Element UI 元件使用次數Bootstrap 不處理 .vue(5.8.2),要用 Shell 盤點
2/egm:egm-brainstorm 將 crm-web 從 Vue 2 升級到 Vue 3+TS+Pinia+PrimeVue,分批上線—
3/egm:egm-draft—
4/egm:egm-review docs/designs/crm-web-vue3.md—

盤點指令(Shell):

cd crm-web
git ls-files '*.vue' | wc -l
grep -rln "Vue.filter\|\$on(\|\$off(\|\$listeners\|\$scopedSlots" src | wc -l   # Vue 3 移除或改變的 API
grep -rhoE "<el-[a-z-]+" src | sort | uniq -c | sort -rn | head -20              # Element UI 元件使用排行
grep -rln "this\.\$store" src | wc -l                                            # 依賴 Vuex 的元件數

15.4.4 Brainstorm 對話範例

Elephant:「分批上線」的單位是什麼?頁面、模組,還是路由?
SD:以路由模組為單位,共 9 個模組。
Elephant:分批期間,Vue 2 與 Vue 3 頁面如何共存?同一個 SPA,還是 Micro-Frontend?
SD:還沒決定。
Elephant:這是架構決定,有三種做法:
A. Vue 3 Migration Build(@vue/compat)整包升級後逐步關閉相容旗標。取捨:一次切換、無需兩套 runtime;失效條件:Element UI 不支援 Vue 3,相容模式也無法執行。
B. Micro-Frontend:新舊各自一個應用,由殼層路由。取捨:可逐模組替換;失效條件:登入狀態、共用 store、樣式需跨應用處理。
C. 新應用重寫,舊應用凍結。取捨:最乾淨;失效條件:9 個模組全部完成前無法下線舊應用。
請選擇。
SD:Element UI 不支援 Vue 3,A 不可行。選 B。

Goldfish 反對意見(UX 視角):「兩個應用的 UI 套件不同(Element UI vs PrimeVue),使用者在模組間切換會看到不一致的介面,brief 應列出是否接受。」

15.4.5 Draft 文件範例

Technical Plan 節錄(示範):

## Technical Plan (Architecture)

殼層(shell)採 Vue 3,負責登入、選單與路由;舊 crm-web 以 iframe 嵌入未遷移的模組,
新模組以 Vue 3 路由直接載入。登入 token 由殼層以 postMessage 傳給 iframe(同源)。

| Vue 2 | Vue 3 對應 | 遷移規則 |
| --- | --- | --- |
| Vuex module | Pinia store(同名) | state 形狀不變;mutation 改 action |
| Vue.filter | 共用函式 `src/utils/format.ts` | 全域 filter 移除 |
| event bus($on/$off) | Pinia action 或 mitt | 每個用到的地方列在 Detailed Plan |
| Element UI | PrimeVue 4 | 元件對照表見附錄 |
| v-model(.sync) | v-model:propName | 逐元件修改 |

Detailed Implementation Plan 節錄(Phase 2;15.4.9 的 AI Coding 指令與 scope guard 都以這段為準):

## Detailed Implementation Plan

### Phase 2:客戶查詢模組

#### 1. `crm-web-next/src/modules/customer/CustomerSearchView.vue` (Create)
*   **Proposed Changes**: 以 PrimeVue DataTable 重寫查詢頁;排序與分頁行為依 Element UI 對照表。

#### 2. `crm-web-next/src/modules/customer/useCustomerSearch.ts` (Create)
*   **Proposed Changes**: 查詢條件與結果狀態(取代 Vue 2 的 mixin)。

#### 3. `crm-web-next/src/stores/customer.ts` (Create)
*   **Proposed Changes**: Pinia store,取代 event bus 的 `customer:selected` 事件。

#### 4. `crm-web-next/src/router/customer.ts` (Create)
*   **Proposed Changes**: `/customers` 路由。

#### 5. `crm-web-next/tests/e2e/customer-search.spec.ts` (Create)
*   **Proposed Changes**: CUJ 2「依統編查詢客戶」的 Playwright 測試。

實作 PR(分支 feat/crm-web-vue3-p2)的範圍檢查(Shell):

git show origin/main:docs/designs/crm-web-vue3.md > /tmp/design.md
python tools/egm_scope_guard.py /tmp/design.md --phase 2 --base origin/main \
  --allow "docs/designs/reviews/crm-web-vue3/**"

15.4.6 Goldfish 審查結果範例

StageReviewerSeverityFinding
5egm-zoom-outMajoriframe 與 postMessage 傳 token 是自建機制;應確認是否已有公司 Micro-Frontend 框架可重用
6egm-comprehensionMajor「同源」的前提未說明部署方式;新讀者無法判斷 iframe 能否讀取 cookie
7egm-designBlockerpostMessage 未限定 targetOrigin、接收端未驗證 event.origin,token 可能外洩
9egm-implementation-readinessMajorElement UI → PrimeVue 對照表缺 el-table 的排序與分頁行為

15.4.7 Resolve 修正範例

Finding分類處理
postMessage 安全(Blocker)PROPOSE FIX規定 targetOrigin 為固定網域、接收端驗證 event.origin、token 只傳短效 access token
公司框架(Major)ESCALATE公司 MFE 框架的狀態只有平台組知道;交平台組確認
同源前提(Major)PROPOSE FIX補部署架構圖(同一網域、不同路徑)
el-table 行為(Major)PROPOSE FIX對照表補排序、分頁、選取的對應

15.4.8 人工核准

平台組回覆:公司 MFE 框架尚未支援 Vue 3,維持 iframe 方案,並將「改用 MFE 框架」寫入 Future Improvements。資安核准 postMessage 規則。UX 確認接受過渡期介面不一致。

15.4.9 AI Coding 指令

請實作 docs/designs/crm-web-vue3.md 的 Phase 2「客戶查詢模組」。
1. 只修改 Phase 2 列出的檔案;不得修改 crm-web(Vue 2)原始碼。
2. Vuex 的 customer module 轉成 Pinia store,state 形狀不變。
3. Element UI → PrimeVue 依附錄對照表;表中沒有的元件停下來問。
4. 完成後執行 npm run type-check、npm run test:unit、npx playwright test e2e/customer-search.spec.ts。

15.4.10 測試案例

編號層級內容預期
V1Unit(Vitest)customer store 的 action 與原 Vuex mutation 結果一致相同 state
V2Unitformat.ts 取代 filter 的輸出與舊 filter 相同
V3E2E客戶查詢:輸入、排序、分頁結果與舊頁面相同
V4Security從其他網域 postMessage被忽略
V5E2E從新模組切到 iframe 舊模組免重新登入

(🧪:案例四沒有可執行的前端專案,測試為設計示範。)

15.4.11 最終交付文件

docs/designs/crm-web-vue3.md(含 Vue 2→3 對照表、Element UI→PrimeVue 對照表)、每 Phase 的審查紀錄、Playwright 報告、遷移進度表(9 個模組)、殼層部署文件。

實務注意:前端升級的 Goldfish 重點常在安全(跨視窗通訊、token)與 UX 一致性,而不是 Vue API 本身——後者有官方遷移指南與工具可以處理。

15.5 案例五:企業跨系統整合

15.5.1 專案背景

CRM 要與三個系統整合:

  • 核心系統:REST API 查詢客戶授信額度。
  • 帳務系統:IBM MQ 接收「客戶狀態變更」事件。
  • 外部徵信中心:每日 02:00 以 SFTP 提供批次檔,Spring Batch 匯入。

15.5.2 使用者需求

客戶頁顯示即時額度;客戶被帳務系統凍結時,CRM 在 1 分鐘內顯示凍結;每日更新徵信評等。

15.5.3 Elephant 操作步驟

#操作說明
1把三個介面的規格(PDF 轉 Markdown)存成 docs/interfaces/*.md讓 Goldfish 讀得到(12.6)
2/egm:egm-brainstorm CRM 整合核心額度 REST、帳務 MQ 事件、徵信 SFTP 批次—
3/egm:egm-draft三個整合各一個子章節
4/egm:egm-review docs/designs/crm-integration.md,GoldfishContext 加入 docs/interfaces/—

15.5.4 Brainstorm 對話範例

Elephant:核心系統 API 逾時或錯誤時,客戶頁要顯示什麼?
SA:顯示「額度暫時無法取得」,其他資料照常顯示。
Elephant:MQ 事件如果重複送達,同一個凍結事件處理兩次會有什麼影響?
SD:狀態一樣是凍結,但稽核會多一筆。
Elephant:稽核多一筆可以接受嗎?若不行,需要冪等鍵;帳務系統的訊息有唯一 ID 嗎?
SD:有 MsgId。用 MsgId 去重。
Elephant:MsgId 要保存多久?帳務系統的重送視窗是多長?
SD:不知道,要問帳務系統。
Elephant:這會列為 Open Question,草稿中先寫明「去重保存 7 天,待帳務系統確認」,是否同意?
SD:同意。

15.5.5 Draft 文件範例

整合架構(示範):

sequenceDiagram
    autonumber
    participant UI as CRM 前端
    participant API as customer-api
    participant CORE as 核心系統 REST
    participant MQ as IBM MQ ACCT.CUSTOMER.STATUS
    participant L as StatusListener
    participant DB as CRM DB
    participant SFTP as 徵信 SFTP
    participant B as CreditRatingJob
    UI->>API: GET /customers/C001/credit-limit
    API->>CORE: GET /limits/C001(逾時 2 秒,斷路器)
    CORE-->>API: 額度
    API-->>UI: 額度或「暫時無法取得」
    MQ->>L: 狀態變更事件(MsgId)
    L->>DB: 依 MsgId 去重後更新狀態並寫稽核
    L-->>MQ: commit(失敗 3 次移到 backout queue)
    B->>SFTP: 02:30 下載 rating_YYYYMMDD.csv 與 .sha256
    B->>B: 驗證 SHA-256 與筆數
    B->>DB: chunk 寫入,失敗可從上次 chunk 重跑

非功能需求節錄:

項目要求
REST逾時 2 秒、斷路器、不重試寫入類 API
MQ冪等(MsgId 保存 7 天,Open Question);backout threshold 3;poison message 告警
SFTP主機金鑰固定(known_hosts);檔案 SHA-256 驗證;檔案到達後才處理(.done 旗標)
Batchchunk 1,000;skip 上限 10 筆後失敗;可重跑且不重複寫入

Detailed Implementation Plan 節錄(Phase 2;15.5.9 的 AI Coding 指令與 scope guard 都以這段為準):

## Detailed Implementation Plan

### Phase 2:帳務 MQ 事件

#### 1. `crm-integration/src/main/java/com/acme/crm/integration/acct/StatusListener.java` (Create)
*   **Proposed Changes**: 接收 `ACCT.CUSTOMER.STATUS`;DB 交易提交後再 commit MQ;依 MsgId 去重。

#### 2. `crm-integration/src/main/java/com/acme/crm/integration/acct/ProcessedMessageRepository.java` (Create)
*   **Proposed Changes**: MsgId 保存 7 天(Open Question 1 決定後調整)。

#### 3. `crm-integration/src/main/resources/db/migration/V21__processed_message.sql` (Create)
*   **Proposed Changes**: `crm_processed_message(msg_id PK, received_at)`。

#### 4. `crm-integration/src/test/java/com/acme/crm/integration/acct/StatusListenerIT.java` (Create)
*   **Proposed Changes**: 15.5.10 的 I3~I5 與 DB 失敗、MQ commit 失敗情境。

實作 PR(分支 feat/crm-integration-p2)的範圍檢查(Shell):

git show origin/main:docs/designs/crm-integration.md > /tmp/design.md
python tools/egm_scope_guard.py /tmp/design.md --phase 2 --base origin/main \
  --allow "docs/designs/reviews/crm-integration/**"

15.5.6 Goldfish 審查結果範例

StageReviewerSeverityFinding
5egm-zoom-outMajor斷路器以自建方式描述;專案已使用 Resilience4j
6egm-comprehensionMajor「backout queue」「.done 旗標」未定義
7egm-designBlockerMQ 事件順序:同一客戶的「凍結」與「解凍」若亂序到達,最後狀態會錯
7egm-designMajorSFTP 檔案若在 02:30 仍未到達,批次行為未定義
9egm-codebase-detailsMajorStatusListener 的交易與 MQ commit 順序未寫:DB 成功但 MQ commit 失敗時會重送

15.5.7 Resolve 修正範例

Finding分類處理
事件亂序(Blocker)PROPOSE FIX事件帶帳務系統的 eventTime;CRM 只接受比現有狀態更新的事件,舊事件記錄並略過
SFTP 未到達PROPOSE FIX02:30 未到達則每 15 分鐘重試至 06:00,之後告警並沿用前一日評等
交易與 MQ commitPROPOSE FIX明訂「DB 交易提交後再 commit MQ;重送由 MsgId 去重處理」
Resilience4jPROPOSE FIX改用既有 Resilience4j 設定
名詞定義PROPOSE FIX補名詞表
MsgId 保存期ESCALATE待帳務系統回覆;保留在 Open Questions

15.5.8 人工核准

整合三方(核心、帳務、徵信窗口)確認介面假設;帳務系統回覆重送視窗為 72 小時,MsgId 保存 7 天足以涵蓋,Open Question 關閉;資安核准 SFTP 金鑰管理;維運確認告警與值班手冊。

15.5.9 AI Coding 指令

請實作 docs/designs/crm-integration.md 的 Phase 2「帳務 MQ 事件」。
1. 只修改 Phase 2 列出的檔案。
2. 交易順序:DB 交易提交 → MQ commit;不得改變。
3. 去重以 MsgId,保存 7 天;亂序以 eventTime 判斷,舊事件寫 log 後略過。
4. 撰寫整合測試:重複事件、亂序事件、DB 失敗、MQ commit 失敗四種情境。
5. MQ 連線設定只讀環境變數,不得把主機、通道、帳密寫進程式或 application.yml。

15.5.10 測試案例

編號整合情境預期
I1REST核心逾時2 秒後顯示「暫時無法取得」
I2REST連續失敗斷路器開啟,不再呼叫
I3MQ同 MsgId 送兩次狀態更新一次、稽核一筆
I4MQ解凍先到、凍結後到(eventTime 較舊)最後狀態為解凍
I5MQ連續失敗 3 次移到 backout queue 並告警
I6SFTPSHA-256 不符批次失敗、不寫入
I7Batch第 3 個 chunk 失敗後重跑從第 3 個 chunk 繼續,無重複資料
I8Batch06:00 仍無檔案告警、沿用前一日評等

(🧪:整合測試需 MQ 與 SFTP 測試環境,本手冊未執行。)

15.5.11 最終交付文件

docs/designs/crm-integration.md、docs/interfaces/*.md(三方介面規格副本)、Interface Specification、Batch Specification、告警與值班手冊、審查紀錄、整合測試報告。

實務注意:整合設計的 Blocker 幾乎都在「失敗與順序」——逾時、重送、亂序、部分成功。Brainstorm 時就要逐一問「如果這一步失敗會怎樣」。

15.6 本章 AI 產出審查

檢查點好例壞例怎麼抓
案例中的指令依 Host 寫明格式Codex 情境寫 /egm:對照附錄 A
報告格式每個 finding 有 Severity、範圍、理由只有一段文字評論python tools/egm_report_gate.py <報告>:計數不是全 0、沒有 R0
失敗情境每個整合都有逾時、重送、亂序只有成功路徑搜尋「失敗」「逾時」「重送」
推測標記不確定的事列為 Open Question 或 ESCALATE直接寫成事實搜尋「應該」「可能」是否有標記

企業實務最佳實踐(Best Practices)

#實踐理由/依據
1設計階段禁止直接寫正式程式碼execution_instructions.md Design-Only Scope
2符合 10.4 條件的功能必須有設計文件有設計決策的變更才值得審查
3重要架構決策寫入 Alternatives Considered,重大者另立 ADRfeature-spec-standard Alternatives Rule
4Goldfish 必須在全新 Subagent Context 執行官方:同 Context 不是 Goldfish 審查
5Goldfish 需要的資料必須是工作目錄內的檔案reviewer 讀不到 URL 與工作目錄外檔案
6不得以同一 Agent 的自我檢查代替獨立審查官方 architecture.md「the model validates its own mistakes」
7重大設計變更(架構、外部介面、相依套件)必須重新審查Draft Step 6.1 的 Addition 規則
8審查報告與簽核封存於 docs/designs/reviews/10.16 Audit Trail
9設計文件經 Architect 與相關角色人工核准官方 Human Review 步驟
10不讓 AI 自行決定未核准的架構變更egm-draft Author Decides Architecture
11設計文件必須有可執行的 Verification Plan官方模板
12涉及個資、權限、金流必須加資安 reviewer 與 standard4.16、10.13
13每個上線 Phase 必須有 Rollback Planmigration-readiness-standard
14設計文件 commit 到 docs/designs/ 並維護 SITEMAP官方 Living Specifications
15每週跑 Drift Report官方建議 once per week
16控管 AI Agent 權限,headless 只開 EGM 四個目錄讀取docs/claude.md
17不把機密與個資提供給未核准的 AI 服務docs/privacy.md
18逆向工程結論必須附程式碼證據並標記【已確認】/【推測】/【待確認】7.5
19Framework 升級先逐條對照官方 Breaking Changes,並先建行為基準第 8 章
20建立公司共用 standard、閘門工具與手冊,集中維護14.7
21設計與實作使用不同 session新 session 是最後一次檢驗文件是否自足
22H2 標題保留官方英文名稱Semantic Split 與 structural reviewer 依標題運作
23親自讀 Stage 6 的 paraphrase唯一能看到「陌生讀者怎麼理解」的地方
24CONTEST 必須引用 reviewer 讀得到的證據;否則 ESCALATEegm-resolve
25Reviewer 出現 not run 視同未審查agents/synthesizer.md
26實作範圍以 CI 強制,不依賴提示詞官方「nothing enforces it」
27每個自建檢查工具都要用反例證明會失敗本手冊實測抓到 @ArchTest 與 plugin validate 的假綠燈
28AGENTS.md/GEMINI.md 只放穩定慣例,不放設計結論#237 指示檔注入
29版本資訊用指令查(gh、git ls-remote),不信網頁摘要11.2 查證心得
30用「錯了會不會很貴」決定是否走 EGM,不強迫小修正官方 getting_started

新進成員檢查清單(Checklist)

第一天:環境

  • 確認公司核准的 AI Host 與帳號。
  • Claude Code 版本 ≥ 2.1.271(claude --version)。
  • 安裝 EGM:claude plugin marketplace add google/elephant-goldfish-model、claude plugin install egm@egm(Codex 用 codex plugin add egm@egm)。
  • claude plugin list 顯示 egm@egm、enabled。
  • 開新 session,輸入 /egm: 看到 7 個指令。
  • Windows:git config --global core.longpaths true。

第一週:觀念與第一次審查

  • 讀第 1 章;能說出 Elephant、Goldfish、人類各自負責什麼。
  • 對一份既有 PR 計畫或設計文件跑 /egm:egm-review,選 Interactive。
  • 讀完 5 份 stage 報告,特別是 Stage 6 的 paraphrase。
  • 能分辨 Blocker、Major、Nit,以及 CONTEST、ESCALATE、PROPOSE FIX、DECLINE。

第一次正式使用

  • 先載入專案 Elephant Skill。
  • Brainstorm:回答給數字、給邊界;決定寫入 brief。
  • Draft:H2 標題保留英文;公司章節放在 Detailed Implementation Plan 之前。
  • python tools/egm_design_lint.py <設計文件> --require "Security & Compliance" 通過。
  • 在設計 session 跑 Review(reviewer 自動是新 Subagent);Blocker/Major 都有決定。
  • ESCALATE 取得簽核並寫入 review_signoff.md。
  • 報告複製到 docs/designs/reviews/<feature>/。
  • 設計 PR 只含文件;人工核准。
  • 新 session 實作,只改 File Boundary 內的檔案。
  • Verification Plan 的指令全部通過;架構測試 Tests run ≥ 1。
  • 設計文件 Status 與 SITEMAP 更新。

不要做的事

  • 不在同一個 session 自我審查並稱為 Goldfish 審查。
  • 不只複製 skills/ 目錄當成安裝。
  • 不把個資、金鑰、正式資料貼進提示詞或設計文件。
  • 不在 Codex 輸入 /egm: 前綴。
  • 不關閉權限檢查來讓 Review 跑起來。

附錄 A:指令速查

A.1 安裝與維護

動作Claude Code(Shell)Codex CLI(Shell)Antigravity CLI(Shell)
安裝claude plugin marketplace add google/elephant-goldfish-model + claude plugin install egm@egmcodex plugin marketplace add google/elephant-goldfish-model + codex plugin add egm@egmagy plugin install https://github.com/google/elephant-goldfish-model
啟用claude plugin enable egm@egm尚待驗證尚待驗證
驗證claude plugin list、claude plugin validate <dir>/.claude-plugin/plugin.json、claude plugin details egm@egm新 session 檢查 skill picker新 session 輸入 /egm:
更新claude plugin marketplace update egm + claude plugin update egm@egm尚待驗證尚待驗證
移除claude plugin uninstall egm@egm尚待驗證尚待驗證
本機測試副本claude --plugin-dir <copy>——

A.2 工作流程

動作Claude Code/agy CLI 對話框Codex
Brainstorm/egm:egm-brainstorm <想法>skill picker 選 egm-brainstorm
Draft/egm:egm-draft [brief 或文件路徑]skill picker 選 egm-draft
Review/egm:egm-review <設計文件> [interactive/uninterrupted/feature_spec/implementation/5~9]skill picker 選 egm-review
Resolve/egm:egm-resolve(通常由 Stage 7、9 自動呼叫)skill picker
Bootstrap/egm:egm-bootstrap <目錄> [target_filename=EGM.md]skill picker
Review Loop/egm:egm-review-loop+TargetFile、SemanticTarget、Reviewers、Standards、GoldfishContextskill picker
Drift Report/egm:egm-drift-report <文件目錄>skill picker

ChatGPT Workspace import 以 @egm 使用;omp 以 /skill:egm-<command> 使用(官方,docs/harnesses.md)。

A.3 公司自建工具

工具指令(Shell)
設計文件檢查python tools/egm_design_lint.py DESIGN.md [--require "Heading"]
報告閘門python tools/egm_report_gate.py REPORT.md ... [--signoff review_signoff.md]
隔離探針python tools/egm_isolation_probe.py review.jsonl --canary X [--canary Y] [--watch CLAUDE.md]
範圍守門python tools/egm_scope_guard.py DESIGN.md (--base origin/main | --changed-file FILE) [--phase N] [--allow PATTERN]
證據檢查python tools/egm_evidence_check.py DOC.md ... --root <legacy repo>
工具測試python -m pytest -q tests

附錄 B:實測 Lab 檔案

本附錄收錄正文未完整列出、但測試需要的檔案。目錄結構:

egm-lab/
├── tools/                 # 5 支工具(正文 4.17、7.5.1、10.5、10.9、2.9.1)
├── tests/test_tools.py    # 25 個測試
├── fixtures/              # 設計文件、報告、舊系統程式的好例與壞例
├── standards/             # 4 份公司 standard(正文 4.14、4.16、8.3)
├── project/               # 專案設定範例(CLAUDE.md、.claude/、workflow)
└── user-settings/         # 使用者層 settings.json 範例(3.15.1)
archunit-lab/              # 正文 6.6.1(negative/ 為反例,不參與編譯)

執行全部測試(Shell):

cd egm-lab
python -m pytest -q tests          # 實測:25 passed
cd ../archunit-lab
mvn -B test                        # 實測:ArchRuleFieldTest 1、ArchitectureTest 3、CustomerContactTest 3

突變測試(實測):1.0 版把四支工具各一條規則改壞,測試分別出現 2、1、1、1 個失敗,--phase 改壞出現 2 個失敗;1.1 新增 10 個突變(閘門的 R0、R1、R4、R5、emoji/清單格式、簽核檔處理,lint 的中文佔位詞與 Open Questions 例外),全部被測試抓到。還原後 25 passed。

B.1 測試程式

📄 tests/test_tools.py

"""Tests for the EGM enterprise gate tools. Run: python -m pytest -q tests"""
import sys
from pathlib import Path

LAB = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(LAB / "tools"))

import egm_design_lint  # noqa: E402
import egm_evidence_check  # noqa: E402
import egm_report_gate  # noqa: E402
import egm_scope_guard  # noqa: E402

FX = LAB / "fixtures"


def run(mod, args, capsys):
    rc = mod.main([str(a) for a in args])
    return rc, capsys.readouterr().out


# ---- scope guard ----------------------------------------------------------
def test_scope_ok_with_design_doc_allowed(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_good.md", "--changed-file",
                                    FX / "changed_ok.txt", "--allow", "docs/designs/*.md"], capsys)
    assert rc == 0, out
    assert "NOT-YET-TOUCHED customer-domain/src/test" in out


def test_scope_flags_unplanned_files(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_good.md", "--changed-file",
                                    FX / "changed_drift.txt"], capsys)
    assert rc == 1
    assert "OUT-OF-SCOPE pom.xml" in out
    assert "OUT-OF-SCOPE customer-app/src/main/java/com/acme/crm/customer/app/util/StringUtils2.java" in out


def test_scope_without_allow_flags_design_doc(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_good.md", "--changed-file",
                                    FX / "changed_ok.txt"], capsys)
    assert rc == 1 and "OUT-OF-SCOPE docs/designs/customer-contact.md" in out


def test_scope_phase_limits_allowlist(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_phased.md", "--phase", "1", "--changed-file",
                                    FX / "changed_phase2.txt"], capsys)
    assert rc == 1 and "OUT-OF-SCOPE src/main/java/com/acme/loan/mq/LoanListener.java" in out
    rc, out = run(egm_scope_guard, [FX / "design_phased.md", "--phase", "2", "--changed-file",
                                    FX / "changed_phase2.txt"], capsys)
    assert rc == 0, out


def test_scope_single_phase_design(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_good.md", "--phase", "1", "--changed-file",
                                    FX / "changed_ok.txt", "--allow", "docs/designs/*.md"], capsys)
    assert rc == 0, out
    rc, out = run(egm_scope_guard, [FX / "design_good.md", "--phase", "2", "--changed-file",
                                    FX / "changed_ok.txt"], capsys)
    assert rc == 2


def test_scope_unknown_phase_is_usage_error(capsys):
    rc, out = run(egm_scope_guard, [FX / "design_phased.md", "--phase", "9", "--changed-file",
                                    FX / "changed_phase2.txt"], capsys)
    assert rc == 2


def test_scope_no_boundary_is_usage_error(capsys):
    rc, out = run(egm_scope_guard, [FX / "re_doc_good.md", "--changed-file",
                                    FX / "changed_ok.txt"], capsys)
    assert rc == 2


# ---- design lint ----------------------------------------------------------
def test_lint_good(capsys):
    rc, out = run(egm_design_lint, [FX / "design_good.md"], capsys)
    assert rc == 0, out


def test_lint_good_with_company_section(capsys):
    rc, out = run(egm_design_lint, [FX / "design_good.md", "--require", "Security & Compliance"], capsys)
    assert rc == 0, out


def test_lint_good_with_company_section_missing(capsys):
    rc, out = run(egm_design_lint, [FX / "design_good.md", "--require", "Operations & Rollback"], capsys)
    assert rc == 1 and "missing section: ## Operations & Rollback" in out


def test_lint_bad(capsys):
    rc, out = run(egm_design_lint, [FX / "design_bad.md"], capsys)
    assert rc == 1
    for key in ("## The Problem", "## Non-Goals", "D2", "D3", "D4", "D5 unknown status: WIP"):
        assert key in out, key


def test_lint_pending_word_outside_plan_fails(capsys):
    rc, out = run(egm_design_lint, [FX / "design_pending.md"], capsys)
    assert rc == 1 and "D3 placeholder at line 34 (Technical Plan (Architecture))" in out
    assert "Open Questions" not in out.split("D3", 1)[1].split("\n", 1)[0]


# ---- report gate ----------------------------------------------------------
def test_gate_not_run_reviewer_fails(capsys):
    rc, out = run(egm_report_gate, [FX / "reports" / "critic_report.md"], capsys)
    assert rc == 1
    assert "R1 reviewer not run: egm-structural" in out
    assert "blocker=1 major=0 nit=1" in out


def test_gate_good_with_signoff(capsys):
    rc, out = run(egm_report_gate, [FX / "reports" / "goldfish_review_report_good.md",
                                    "--signoff", FX / "reports" / "review_signoff.md"], capsys)
    assert rc == 0, out


def test_gate_escalate_needs_signoff(capsys):
    rc, out = run(egm_report_gate, [FX / "reports" / "goldfish_review_report_good.md"], capsys)
    assert rc == 1 and "R4 ESCALATE without human sign-off: [Issue 2]" in out


def test_gate_bad_report(capsys):
    rc, out = run(egm_report_gate, [FX / "reports" / "goldfish_review_report_bad.md",
                                    "--signoff", FX / "reports" / "review_signoff.md"], capsys)
    assert rc == 1
    assert "R2" in out and "R3 Major declined: [Issue 3]" in out


# Layouts below are verbatim excerpts of a real Claude Code run (direct dispatch).
LAYOUTS = FX / "reports" / "layouts"


def test_gate_parses_real_layouts(capsys):
    expected = {
        "layout_emoji.md": "blocker=1 major=1 nit=1",
        "layout_sectioned.md": "blocker=1 major=1 nit=1",
        "layout_bullets.md": "blocker=1 major=2 nit=1",
        "layout_table.md": "blocker=1 major=1 nit=0",
    }
    for name, counts in expected.items():
        rc, out = run(egm_report_gate, [LAYOUTS / name], capsys)
        assert f"{name}: {counts}" in out, out
        assert "R0" not in out


def test_gate_unknown_layout_fails_instead_of_passing(capsys):
    rc, out = run(egm_report_gate, [LAYOUTS / "layout_unknown.md"], capsys)
    assert rc == 1 and "R0 severity markers found but no finding parsed" in out


def test_gate_stage_blockers_need_annotated_report(capsys):
    rc, out = run(egm_report_gate, [LAYOUTS / "layout_sectioned.md"], capsys)
    assert rc == 1 and "R5 Blockers in layout_sectioned.md" in out
    rc, out = run(egm_report_gate, [LAYOUTS / "layout_sectioned.md",
                                    FX / "reports" / "goldfish_review_report_good.md",
                                    "--signoff", FX / "reports" / "review_signoff.md"], capsys)
    assert rc == 0, out


def test_gate_incomplete_reviewer_fails(capsys):
    rc, out = run(egm_report_gate, [LAYOUTS / "status_incomplete.md"], capsys)
    assert rc == 1 and "R1 reviewer incomplete review: egm-structural" in out


def test_gate_signoff_must_name_the_report(tmp_path, capsys):
    other = tmp_path / "review_signoff.md"
    other.write_text("- another_report.md [Issue 2] signed\n", encoding="utf-8")
    rc, out = run(egm_report_gate, [FX / "reports" / "goldfish_review_report_good.md",
                                    "--signoff", other], capsys)
    assert rc == 1 and "R4" in out


def test_gate_missing_signoff_file_only_matters_with_escalate(tmp_path, capsys):
    missing = tmp_path / "review_signoff.md"
    rc, out = run(egm_report_gate, [LAYOUTS / "layout_emoji.md",
                                    FX / "reports" / "goldfish_review_report_good.md",
                                    "--signoff", missing], capsys)
    assert rc == 1 and "R4" in out and "Traceback" not in out


def test_gate_skips_signoff_file_in_glob(capsys):
    rc, out = run(egm_report_gate, [FX / "reports" / "goldfish_review_report_good.md",
                                    FX / "reports" / "review_signoff.md",
                                    "--signoff", FX / "reports" / "review_signoff.md"], capsys)
    assert rc == 0 and "review_signoff.md:" not in out


# ---- evidence check -------------------------------------------------------
def test_evidence_good(capsys):
    rc, out = run(egm_evidence_check, [FX / "re_doc_good.md", "--root", FX / "legacy"], capsys)
    assert rc == 0, out
    assert "cites=4 confirmed=3 guess=1 open=1" in out


def test_evidence_bad(capsys):
    rc, out = run(egm_evidence_check, [FX / "re_doc_bad.md", "--root", FX / "legacy"], capsys)
    assert rc == 1
    for key in ("E2 symbol 'creditScore < 650' not in",
                "E1 file not found: src/main/java/com/acme/loan/LoanService.java",
                "E2 line 40 beyond db/PKG_LOAN.sql",
                "E4 business rule without evidence",
                "E3 confirmed statement without citation"):
        assert key in out, key

B.2 測試 fixture

📄 fixtures/design_bad.md

# 客戶匯入

*   **Author:** someone
*   **Status:** WIP
*   **Date:** 2026-11-17

## Overview

批次匯入客戶。

## Goals

*   匯入要快。

## Technical Plan (Architecture)

用 Spring Batch。

## Alternatives Considered

沒有其他方案。考慮過 Kafka,Rejected by maintainer.

## Detailed Implementation Plan

#### 1. `batch/src/main/java/com/acme/ImportJob.java` (Create)

*   **Proposed Changes**: TBD

📄 fixtures/reports/critic_report.md

# Goldfish Review Report

**Target:** `docs/designs/customer-contact.md` (`1..58`)

## Reviewer Status

| Reviewer | Status |
| --- | --- |
| `egm-design` | completed |
| `egm-structural` | not run |
| `egm-style` | completed |

## Prioritized Findings (Blockers -> Major -> Nits)

### Primary contact race condition - Severity: Blocker
* **Reviewer Lens:** `egm-design`
* **Affected Scope:** `Lines 40-44`
* **Discrepancy Description**: Two concurrent requests can both mark a primary contact.
* **Rationale & Recommendation**: State the locking strategy.

### Vague latency claim - Severity: Nit
* **Reviewer Lens:** `egm-style`
* **Affected Scope:** `Lines 52`
* **Discrepancy Description**: "fast enough" is not measurable.
* **Rationale & Recommendation**: Use a P95 number.

📄 fixtures/reports/goldfish_review_report_good.md

Status: resolved

# Goldfish Annotated Review Report

**Target:** `docs/designs/customer-contact.md` (`1..58`)

## Prioritized Findings & AI Suggestions

### [Issue 1] [`egm-design`] - Severity: Blocker
*   **Affected Scope:** Lines 40-44 (Technical Plan)
*   **Discrepancy Description:** Two concurrent requests can both mark a primary contact.
*   **Rationale:** No locking strategy.
*   ***AI Suggestion:*** PROPOSE FIX
*   ***Justification:*** Valid. Add optimistic locking on Customer version and the partial unique index.
*   ***Proposed Edit:***
    *   Location: Technical Plan
    *   Change: add one paragraph on `@Version` and `ux_contact_primary`.

### [Issue 2] [`egm-design`] - Severity: Major
*   **Affected Scope:** Lines 70-74 (Security & Compliance)
*   **Discrepancy Description:** The design does not state a key rotation period for the AES key.
*   **Rationale:** Without rotation, a leaked key exposes all stored contacts.
*   ***AI Suggestion:*** ESCALATE
*   ***Justification:*** Bank key policy KMS-07 rotates all data keys every 90 days; the policy is outside the files the reviewer could read.
*   ***Proposed Edit:***
    *   Location: none
    *   Change: none

### [Issue 3] [`egm-style`] - Severity: Nit
*   **Affected Scope:** Lines 52
*   **Discrepancy Description:** Wording.
*   **Rationale:** Style.
*   ***AI Suggestion:*** DECLINE
*   ***Justification:*** Nit.
*   ***Proposed Edit:***
    *   Location: none
    *   Change: none

📄 fixtures/reports/goldfish_review_report_bad.md


# Goldfish Annotated Review Report

**Target:** `docs/designs/customer-contact.md` (`1..58`)

## Prioritized Findings & AI Suggestions

### [Issue 1] [`egm-design`] - Severity: Blocker
*   **Affected Scope:** Lines 40-44 (Technical Plan)
*   **Discrepancy Description:** Two concurrent requests can both mark a primary contact.
*   **Rationale:** No locking strategy.
*   ***AI Suggestion:*** PROPOSE FIX
*   ***Justification:*** Valid. Add optimistic locking on Customer version and the partial unique index.
*   ***Proposed Edit:***
    *   Location: Technical Plan
    *   Change: add one paragraph on `@Version` and `ux_contact_primary`.

### [Issue 2] [`egm-design`] - Severity: Major
*   **Affected Scope:** Lines 70-74 (Security & Compliance)
*   **Discrepancy Description:** The design does not state a key rotation period for the AES key.
*   **Rationale:** Without rotation, a leaked key exposes all stored contacts.
*   ***AI Suggestion:*** ESCALATE
*   ***Justification:*** Bank key policy KMS-07 rotates all data keys every 90 days; the policy is outside the files the reviewer could read.
*   ***Proposed Edit:***
    *   Location: none
    *   Change: none

### [Issue 3] [`egm-style`] - Severity: Major
*   **Affected Scope:** Lines 52
*   **Discrepancy Description:** Wording.
*   **Rationale:** Style.
*   ***AI Suggestion:*** DECLINE
*   ***Justification:*** Nit.
*   ***Proposed Edit:***
    *   Location: none
    *   Change: none

📄 fixtures/changed_ok.txt

customer-domain/src/main/java/com/acme/crm/customer/domain/Contact.java
customer-domain/src/main/java/com/acme/crm/customer/domain/Customer.java
customer-infra/src/main/resources/db/migration/V12__contact.sql
docs/designs/customer-contact.md

📄 fixtures/changed_drift.txt

customer-domain/src/main/java/com/acme/crm/customer/domain/Contact.java
customer-domain/src/main/java/com/acme/crm/customer/domain/Customer.java
customer-app/src/main/java/com/acme/crm/customer/app/util/StringUtils2.java
pom.xml

📄 fixtures/design_phased.md

# loan-service 升級(節錄)

*   **Status:** Approved

## Detailed Implementation Plan

### Phase 1:Java 17+Spring Boot 2.7.x

#### 1. `pom.xml` (Modify)

*   **Proposed Changes**: parent 2.7.x;release 17。

#### 2. `src/main/resources/application.yml` (Modify)

*   **Proposed Changes**: 屬性改名。

### Phase 2:Spring Boot 3.5.x+jakarta

#### 3. `pom.xml` (Modify)

*   **Proposed Changes**: parent 3.5.x。

#### 4. `src/main/java/com/acme/loan/mq/LoanListener.java` (Modify)

*   **Proposed Changes**: `javax.jms` 改為 `jakarta.jms`。

📄 fixtures/changed_phase2.txt

pom.xml
src/main/java/com/acme/loan/mq/LoanListener.java

📄 fixtures/design_pending.md

# 貸款服務升級(節錄)

*   **Author:** someone
*   **Status:** In Review

## Overview

Spring Boot 2.3 升級到 3.5。

## The Problem

2.3 已停止支援。

## Goals

*   升級到 Spring Boot 3.5.x。

## Non-Goals

*   不升級 Oracle。

## Open Questions

*   **Question 1**: MyBatis 版本待確認(這一節允許)。

## Critical User Journeys (CUJs)

### CUJ 1: 核貸流程維持不變

## Technical Plan (Architecture)

| 元件 | 目前 | 目標 |
|---|---|---|
| MyBatis | 3.5.6 | 待查 |

## Alternatives Considered

### Alternative A: 直接升到 4.0

## Non-Functional Requirements

*   效能不得退化。

## Detailed Implementation Plan

#### 1. `pom.xml` (Modify)

以下 4 份是 1.1 實跑報告的逐行節錄(10.5.1),另加 2 份反例:

📄 fixtures/reports/layouts/layout_emoji.md

# Stage 5: Initial Zoom Out Report

## egm-zoom-out

### ZO-1 🔴 Blocker: The plan builds only part of what the Goals promise
*   **Scope:** Goals (lines 21–23), NFR Performance (line 60), Open Question 1 (line 32) vs. Target Files (lines 73–111).
*   **Issue:** The Goals promise masked list view, a detail view gated by `CONTACT_PII_READ`, audit records for update and delete (`CONTACT_UPDATED`, `CONTACT_DELETED`, also line 67), and list P95 < 300 ms. Target Files create only `POST /contacts`. There is no list, detail, update, or delete endpoint, no masking component, and no service for them. The repository rules limit implementation to the Target Files list (checked by CI), so the plan as written cannot deliver the Goals. The 7-year retention question decides soft vs. hard delete, and delete is not planned at all.
*   **Fix:** Either cut Goals and NFRs to "create contact" for this round (simpler), or add the missing endpoints and components.

### ZO-2 🟡 Major: Every optimistic-lock conflict becomes `PrimaryContactExistsException`
*   **Scope:** Line 91, line 111.
*   **Issue:** A version conflict on the Customer aggregate fires on any concurrent change. Two users adding two ordinary contacts at once would see "primary contact already exists". If the version check always fires first, the partial unique index never produces the error callers see, and the integration test passes because of the lock, not because `ux_contact_primary` works.
*   **Fix:** Map optimistic-lock conflicts to a generic concurrent-modification 409 or retry. Map only the uniqueness violation or invariant check to the primary-contact error. State this mapping once at architecture level.

### ZO-6 🟢 Nit: `markPrimary` has no caller
*   **Scope:** Line 81, line 111.
*   **Issue:** No endpoint, service, or journey uses `markPrimary`, yet the integration test describes two threads setting the primary contact at once.
*   **Fix:** Remove it, or add a "change primary contact" journey and endpoint.

📄 fixtures/reports/layouts/layout_sectioned.md

# Stage 7: Critic Review Report

## 🔴 Blockers

### CR-1: No Risks & Mitigations section
*   **Raised by:** design-1, structural-1
*   **Scope:** Lines 42–67 (no heading exists).
*   **Issue:** The standard requires failure modes, security implications, scalability limits, and mitigations. Unaddressed: KMS unavailable or slow; whether the audit write shares the contact write's transaction; AES key rotation; concurrent edits on one Customer aggregate; behavior at the 50-contact cap; encryption cost against P95 < 300 ms. The concurrency failure mode appears only in the implementation plan (lines 91, 111).
*   **Fix:** Add `## Risks & Mitigations` listing each risk with its mitigation and the limits (50 contacts, one write at a time per customer).

## 🟡 Majors

### CR-2: Only one alternative, and its rejection reason also applies to the chosen design
*   **Raised by:** design-3, structural-2
*   **Scope:** Lines 47, 49–55.
*   **Issue:** Alternative A is rejected because "only the database can guarantee uniqueness", but the chosen design also depends on the database index when two transactions race. Alternative A's benefit (fewer conflicts) is never weighed against whole-customer locking. Missing options: a nullable `primary_contact_id` on the customer table, a JSON column, an application-level lock, do nothing.

## 🟢 Nits

*   **CR-13** (design-10, structural-6, style-3): Encryption/KMS sentence duplicated on lines 59 and 64. Keep it in Security & Compliance.

📄 fixtures/reports/layouts/layout_bullets.md

# Stage 9: Implementation Readiness Report

## 🔴 Blockers

### IR-1: The exception-to-status table cited on line 96 does not exist
*   **Raised by:** readiness-B1, codebase-B4, style-B1
*   **Scope:** Lines 96, 101 (Technical Plan lines 42–47).
*   **Issue:** No mapping for `ContactLimitExceededException`, `PrimaryContactExistsException`, invalid email, or customer-not-found (404 not listed). Error body schema for the OpenAPI file is undefined.
*   **Fix:** Add a table: exception → HTTP status → error code; define the error body fields and types.

## 🟡 Majors

*   **IR-8** (readiness-M7, codebase-M1): No phases. The CI gate runs `egm_scope_guard.py --phase N` on `feat/<feature>-p<N>` branches, so a flat list cannot produce a per-phase allowlist. Suggested phases: domain + unit tests → migration + infra → app service → API + OpenAPI, each with its own verification command.
*   **IR-9** (readiness-M3, codebase-M2): `ContactId`, `ContactLimitExceededException`, `PrimaryContactExistsException`, the `command` type, and request/response DTOs are used but not listed as files.

## 🟢 Nits

*   **IR-15** (readiness-N1, style-N1): `primary` / `is_primary` / "Primary" / "主要聯絡人": state the mapping; `primary` is an SQL reserved word.

📄 fixtures/reports/layouts/layout_table.md

# Consolidated Review Report: Customer Contact Management

### 🔴 Blockers

| ID | Action | Lines |
|---|---|---|
| A1 | Choose the phase scope (Decision 1). Make Goals, NFRs, Security, CUJs, and Target Files agree. State explicitly what is deferred. | 21–23, 32, 60, 67, 71–111 |

### 🟡 Majors

| ID | Action | Lines |
|---|---|---|
| A8 | Remove "Rejected by author:" or link the decision. Fix the Alternative A rejection reason, which also applies to the chosen design. Add the do-nothing option; add the other storage option from Decision 2. | 49–55 |

📄 fixtures/reports/layouts/layout_unknown.md

# Stage 7: Critic Review Report

Findings, most severe first.

1. **Blocker.** The exception mapping table cited on line 96 does not exist.
2. **Major.** Only one alternative is weighed.
3. **Nit.** The encryption sentence appears twice.

📄 fixtures/reports/layouts/status_incomplete.md

# Goldfish Review Report

**Target:** `docs/designs/customer-contact.md` (`1..58`)

## Reviewer Status

| Reviewer | Status |
| --- | --- |
| `egm-design` | completed |
| `egm-structural` | incomplete review |

## Prioritized Findings (Blockers -> Major -> Nits)

### Vague latency claim - Severity: Nit
* **Reviewer Lens:** `egm-design`

📄 tools/egm_isolation_probe.py

#!/usr/bin/env python3
"""egm_isolation_probe.py - check what Goldfish reviewers actually saw in one run.

Input: the log of `claude -p --output-format stream-json --verbose "/egm:egm-review ..."`.
For every subagent (Agent/Task tool call) it prints:
  * the subagent type
  * canaries found in the prompt the Elephant sent      (prompt leak)
  * canaries found in the text the reviewer returned    (the reviewer saw it)
  * whether the reviewer itself opened a watched file    (e.g. CLAUDE.md via Read)

Exit 1 if any canary reached a reviewer. Plant the canaries yourself:
one line in CLAUDE.md, one sentence in your /egm:egm-review message.

Usage:
  python egm_isolation_probe.py review.jsonl --canary CANARY-CLAUDEMD-7731 \
      --canary PROMPTCANARY-4419 [--watch CLAUDE.md]
"""
import argparse
import json
import sys
from collections import defaultdict


def text_of(content):
    if isinstance(content, list):
        return "\n".join(x.get("text", "") for x in content if isinstance(x, dict))
    return content or ""


def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("log")
    ap.add_argument("--canary", action="append", required=True)
    ap.add_argument("--watch", action="append", default=["CLAUDE.md", "AGENTS.md"])
    args = ap.parse_args(argv)
    sys.stdout.reconfigure(encoding="utf-8")

    calls, order, opened = {}, [], defaultdict(set)
    with open(args.log, encoding="utf-8") as fh:
        for line in fh:
            d = json.loads(line)
            msg = d.get("message")
            if not isinstance(msg, dict) or not isinstance(msg.get("content"), list):
                continue
            parent = d.get("parent_tool_use_id")
            for c in msg["content"]:
                if not isinstance(c, dict):
                    continue
                if c.get("type") == "tool_use":
                    inp = c.get("input", {})
                    if c.get("name") in ("Agent", "Task"):
                        calls[c["id"]] = {"type": inp.get("subagent_type"),
                                          "prompt": inp.get("prompt", ""), "result": ""}
                        order.append(c["id"])
                    elif parent:
                        path = str(inp.get("file_path", ""))
                        for w in args.watch:
                            if path.replace("\\", "/").endswith("/" + w) or path == w:
                                opened[parent].add(w)
                if c.get("type") == "tool_result" and c.get("tool_use_id") in calls:
                    calls[c["tool_use_id"]]["result"] = text_of(c.get("content"))

    leak = False
    for i, cid in enumerate(order, 1):
        c = calls[cid]
        p_hit = [k for k in args.canary if k in c["prompt"]]
        r_hit = [k for k in args.canary if k in c["result"]]
        leak = leak or bool(p_hit or r_hit)
        print(f"{i:2} {str(c['type']):34} prompt={','.join(p_hit) or '-':22} "
              f"result={','.join(r_hit) or '-':22} opened={','.join(sorted(opened[cid])) or '-'}")
    print(f"subagents={len(order)} leaked={'yes' if leak else 'no'}")
    return 1 if leak else 0


if __name__ == "__main__":
    sys.exit(main())

B.3 公司 standard

📄 standards/reverse-engineering-evidence-standard.md

# Reverse Engineering Evidence Standard (ACME Bank)

Company standard for reviewing documents produced from legacy code. Not part of
EGM. Use together with EGM's `re-implementation-standard`.

## Core Principle

A document passes if a reviewer can trace every statement marked as confirmed
to a file and symbol (or line range) in the legacy source, and every statement
without such evidence is visibly marked as inference or open question.

## The Evidence Rule

*   Confirmed statements use the tag 【已確認】 and cite `[path:Symbol]` or
    `[path:L10-L42]`.
*   Inferences use 【推測】. Questions for domain owners use 【待確認】.
*   A business rule inferred only from a class, table, or method name fails.

## Requirements (Non-Exhaustive Examples)

*   **Entry Points**: Every screen, API, batch job, and MQ listener is listed
    with its source file.
*   **SQL & Stored Procedures**: Every table written is listed with the statement
    or procedure that writes it.
*   **Transactions**: Commit and rollback boundaries are cited.
*   **External Interfaces**: Every outbound call names protocol, endpoint key,
    and timeout as found in configuration.

B.4 ArchUnit Lab 其餘檔案

📄 archunit-lab/src/main/java/com/acme/crm/customer/domain/Contact.java

package com.acme.crm.customer.domain;

public record Contact(String name, String email, boolean primary) {
    public Contact {
        if (email == null || !email.contains("@")) {
            throw new IllegalArgumentException("invalid email");
        }
    }
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/domain/CustomerRepository.java

package com.acme.crm.customer.domain;

import java.util.Optional;

public interface CustomerRepository {
    Optional<Customer> findById(String id);

    void save(Customer customer);
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/app/AddContactService.java

package com.acme.crm.customer.app;

import com.acme.crm.customer.domain.Contact;
import com.acme.crm.customer.domain.Customer;
import com.acme.crm.customer.domain.CustomerRepository;

public class AddContactService {
    private final CustomerRepository repository;

    public AddContactService(CustomerRepository repository) {
        this.repository = repository;
    }

    public void addContact(String customerId, Contact contact) {
        Customer customer = repository.findById(customerId)
                .orElseThrow(() -> new IllegalArgumentException("customer not found: " + customerId));
        customer.addContact(contact);
        repository.save(customer);
    }
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/adapter/web/ContactController.java

package com.acme.crm.customer.adapter.web;

import com.acme.crm.customer.app.AddContactService;
import com.acme.crm.customer.domain.Contact;

public class ContactController {
    private final AddContactService service;

    public ContactController(AddContactService service) {
        this.service = service;
    }

    public int post(String customerId, String name, String email, boolean primary) {
        service.addContact(customerId, new Contact(name, email, primary));
        return 201;
    }
}

📄 archunit-lab/src/main/java/com/acme/crm/customer/adapter/persistence/InMemoryCustomerRepository.java

package com.acme.crm.customer.adapter.persistence;

import com.acme.crm.customer.domain.Customer;
import com.acme.crm.customer.domain.CustomerRepository;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

public class InMemoryCustomerRepository implements CustomerRepository {
    private final Map<String, Customer> store = new HashMap<>();

    @Override
    public Optional<Customer> findById(String id) {
        return Optional.ofNullable(store.get(id));
    }

    @Override
    public void save(Customer customer) {
        store.put(customer.id(), customer);
    }
}

反例(不在 src/ 內,不參與編譯;用法見 6.6.1):

📄 archunit-lab/negative/BadShortcut.java

package com.acme.crm.customer.domain;

import com.acme.crm.customer.adapter.persistence.InMemoryCustomerRepository;

public class BadShortcut {
    private final Object repo = new InMemoryCustomerRepository();
}

B.5 從手冊抽出 Lab

手冊中每個 📄 區塊的下一個程式碼區塊就是該檔案內容。抽出腳本(Shell+Python,存成 extract_lab.py 後執行 python extract_lab.py "elephant-goldfish-model 教學手冊.md" out/):

import re
import sys
from pathlib import Path

text = Path(sys.argv[1]).read_text(encoding="utf-8").replace("\r\n", "\n")
out = Path(sys.argv[2])
pattern = re.compile(r"^📄 `([^`]+)`.*?\n\n(`{3,})[a-z]*\n(.*?)\n\2$", re.M | re.S)
count = 0
for m in pattern.finditer(text):
    rel, body = m.group(1), m.group(3)
    dest = out / rel
    dest.parent.mkdir(parents=True, exist_ok=True)
    dest.write_bytes((body + "\n").encode("utf-8"))
    count += 1
print("extracted", count)

實務注意:抽出後的路徑以 📄 標示為準(例如 tools/… 對應 egm-lab/tools/…、archunit-lab/… 自成一個專案)。

放到實際專案時的對應(Shell,在抽出目錄執行;<project> 換成專案根目錄):

PROJECT="REPLACE_ME"                               # 換成:專案根目錄
mkdir -p "$PROJECT/tools" "$PROJECT/docs/standards" "$PROJECT/.github/workflows"
cp tools/*.py "$PROJECT/tools/"
cp standards/*.md "$PROJECT/docs/standards/"       # 正文呼叫一律使用 docs/standards/
cp project/.github/workflows/egm-gate.yml "$PROJECT/.github/workflows/"

user-settings/settings.json 的內容合併到使用者層 settings.json(3.15.1),不要放進專案。


附錄 C:術語表

術語說明
Elephant擁有長 Context 的主 Agent,負責設計與修正
Goldfish在全新 Context 中執行、唯讀的審查 Subagent
Harness/Host執行 EGM 的 AI Agent 環境(Claude Code、Codex、Antigravity…)
Personaagents/*.md 定義的審查者或協調者系統指示
Adapter.claude-plugin/agents/*.md,替 Claude Code 設定工具與隔離,讀取共用 persona
Synthesizer啟動 reviewer、去重、寫報告的中介 Subagent
Document Standardresources/document_standards/*.md 評分標準
GoldfishContext傳給 reviewer 的閱讀清單
FeatureRange/DetailedRange設計文件以 ## Detailed Implementation Plan 切分的上下兩段
PresetReview 的 4 種執行模式
CUJCritical User Journey,Given/When/Then
Zero-Decision Rule實作計畫不得留任何設計決定給實作者
Zero-Assumption Rule逆向/現況文件不得讓讀者猜測行為
Alternatives Rule規格必須證明考慮過其他方案
Peanuts/HayBootstrap 的葉節點 README/父節點 Blueprint
goldfish-explorerBootstrap 在執行時臨時定義的唯讀 scout Subagent(不是 agents/ 中的 persona)
Drift文件與程式碼的不一致
Artifact-First長內容寫成檔案,聊天只給路徑
Clean round/Convergedreview loop 中無未 settled 的 Blocker/Major 的一輪;連續兩輪 clean
CONTEST/ESCALATE/PROPOSE FIX/DECLINEResolve 的四種分類
TRIZTheory of Inventive Problem Solving;Inventive Catalyst reviewer 的方法
omitClaudeMdClaude Code subagent 設定,排除 user/project/local 指示檔

附錄 D:Mermaid 圖表索引

#圖位置
1EGM 整體架構圖2.1
2Elephant/Goldfish 角色架構圖1.7
3EGM Plugin 元件架構圖2.2
4EGM 完整工作流程圖第 5 章開頭
5Brainstorm Sequence Diagram5.1.2
6Draft Sequence Diagram5.2.1
7Goldfish Review Sequence Diagram2.10、5.3.4
8Resolve Sequence Diagram5.4.2
9AI Coding 實作流程圖5.6
10Web Application 開發流程圖6.2
11Reverse Engineering 流程圖7.2
12Framework Migration 流程圖8.3
13Enterprise AI Development Governance 流程圖第 10 章開頭
14EGM 維護與升級流程圖第 11 章開頭
—其他:SDLC(1.10)、Context Transfer(2.8)、Skill 依賴(2.16)、Stage 流程(5.3.2)、ERD(6.5)、工具位置(9.9)、案例圖(15.2、15.5)—

附錄 E:品質驗收與 Goldfish 獨立審查

E.1 品質驗收清單

項目結果說明
已研究官方 GitHub Repository✔v0.1.1 tag 與 main@72d06f5 全部 283 個檔案;逐檔閱讀 skills、agents、resources、docs
已研究 Google Open Source Blog✔2026-10-22 文章(第 1.2 節)
已研究官方 Getting Started✔docs/getting_started.md
已研究 EGM Architecture✔docs/designs/architecture.md
已研究 Plugin、Skills、Agents、Resources✔第 2 章
已確認各 AI Agent 的安裝方式✔(部分實測)Claude Code 實測;Codex、Antigravity 依官方文件,標 🧪
已確認實際指令✔Skill 名稱取自 SKILL.md frontmatter;CLI 指令取自 README 與 --help
已說明完整 EGM Workflow✔第 5 章
已說明 Goldfish 獨立審查機制✔第 2.9~2.11、5.3 節
已提供 Web Application、Reverse Engineering、Framework Migration 實戰✔第 6、7、8 章與第 15 章
已提供企業治理、維護升級、教育訓練、導入計畫✔第 10、11、13、14 章
已提供 Mermaid 圖表✔24 張,mermaid.parse() 全部通過(附錄 D 索引)
已提供完整操作指令與最佳實踐✔附錄 A;30 項最佳實踐
已附上官方及延伸參考來源✔參考資料 50 項(1.1 新增上游 PR/Issue 與 surefire 回歸來源)
所有內容均在同一個 Markdown 檔案✔—

E.2 機械驗證結果

檢查結果
markdownlint-cli2 0.18.1(同目錄 .markdownlint.jsonc)0 error
Hugo(autoHeadingIDType=github)錨點目錄連結全部解析、無重複 heading id、目錄順序與正文一致
Mermaid 語法(Node+jsdom mermaid.parse();故意寫壞的範例會失敗)全部通過
所有 bash 區塊 bash -n、PowerShell 區塊 Parser::ParseFile全部通過
從手冊以附錄 B.5 腳本抽出所有 📄 檔案與實測原檔逐位元相同,無遺漏
抽出後重跑 python -m pytest -q tests、mvn -B test25 passed;ArchUnit 4+單元 3 通過
交叉引用(「第 X.Y 節」「(X.Y)」)全部指向存在的小節,並逐一核對上下文
外部連結除 Medium(擋自動化工具,HTTP 403)外皆為 200;code.claude.com 頁面以 <title> 確認不是軟 404
控制字元掃描0
1.1 實測輸出全部由 make_outputs.sh 實跑後嵌入;節錄與引文由 check_quotes.py 逐行比對實跑產物
1.1 CI 模擬6 種情境結果與 10.9 表格一致

E.3 Goldfish 獨立審查

依需求第十節,以一個全新 Context 的 subagent 擔任 Goldfish:只給它這份 Markdown 的路徑與 8 個問題,不提供撰寫過程、不允許上網或讀其他檔案。

初審結論:

問題初審主要缺口修正後
1 能否理解整體架構Yes—Yes
2 能否獨立完成安裝Partlyheadless 權限只有 Windows 寫法;未說明登入補使用者層設定、macOS/Linux 寫法、登入說明;Codex/agy 仍依官方文件(🧪)
3 能否操作完整 WorkflowPartlyResolve 該在哪個 session 跑沒定案;Step 參數沒有對照規定設計到 Resolve 都在同一 Elephant session;補 Step ↔ Preset 對照表
4 Web ApplicationPartly主範例檔案清單做不出 CUJ;範例過不了公司 lint檔案清單補到 8 個並加 Security & Compliance;測試同步更新
5 逆向工程Partlystandard 路徑不一致統一為 docs/standards/,補複製指令
6 Framework 升級Partly案例二、三系統描述矛盾;migrator scope 錯;scope guard 不能依 Phase統一為同一個 loan-service;改 runtime scope;工具加 --phase 並測試
7 維護與升級 EGMPartlyCodex/agy 更新指令未知維持「尚待驗證」標示(官方未提供)
8 企業工程師能否直接執行PartlyCI 可被實作 PR 繞過;閘門宣稱過度;自訂 reviewer 隔離無驗證方法CI 改由分支推導並從 base 讀設計;閘門說明改為只宣稱 R1~R4;補隔離驗證步驟

逐項處理(嚴重度由 Goldfish 判定):

#嚴重度Finding處理
1Blocker主範例 File Boundary 只有 4 檔,做不出 CUJ 與測試補 AddContactService、ContactController、OpenAPI、並行整合測試,共 8 檔;5.6、15.1.9 提示同步
2BlockerReview 在新 session,Resolve 卻需要 Elephant 記憶第 5 章開頭明定:Brainstorm~Resolve 同一設計 session,reviewer 本來就是新 Subagent;只有實作開新 session
3Major報告閘門宣稱檢查 1~5 項改為列出 R1~R4 實際對應項目,其餘人工確認
4Majorscope guard 不支援 Phase;37 與 3 檔數字不一致新增 --phase(含 3 個測試與突變測試);節錄標示「完整清單 37 個」
5Major實作 PR 可改設計文件放寬白名單;.egm/current-design 並行衝突CI 改由分支名推導、從 base 讀設計;本機模擬情境 4 證明會擋下
6Major案例二、三系統矛盾統一為 loan-service(Boot 2.3.12+Spring XML 交易設定+JSP)
7Majorproperties-migrator 放 test scope改 runtime scope 並寫明移除時機
8Majorstandard 路徑 standards/ vs docs/standards/4.14 與附錄 B.5 說明對應並補複製指令
9Majordesign_good 過不了 --require設計範例加 Security & Compliance;測試改為 PASS 案例+缺 Operations & Rollback 的 FAIL 案例
10Majorcomprehension gap 被歸為 ESCALATE改為 PROPOSE FIX;ESCALATE 範例換成真正的「證據在 reviewer 讀不到的政策中」(金鑰輪替)
11MajorStep 值與 Preset 無對照5.3.1 新增對照表
12Major含個人路徑的規則放專案設定;無 macOS/Linux改放使用者層(實測不受工作區信任影響);專案層只放 deny;補其他 OS 與 CLAUDE_CONFIG_DIR 說明
13Major自訂 reviewer 隔離無驗證方法4.13 新增步驟 5(/agents+標記探針)
14Major實測範圍分散重要聲明第 5 點集中列出已實測/未實測
15Major8.3 要求 review 吃自訂 standard改為 feature_spec 後接 review loop
16NitResolve 處理方式數量不一2.11 統一為官方的 5 種
17Nitdrift report 被寫成 Goldfish8.3 圖改為「主 Context」
18NitStage 9 範例 finding 與計畫自相矛盾換成「稽核介面未指明」
19Nit「report gate 測試 13 passed」改為「公司工具測試(4 支)17 passed」
20Nitgoldfish-explorer 未定義5.8.1 與術語表補定義
21NitCowork 限制寫在 Claude Code 列移到 Cowork 列
22NitDraft 輸入與輸出路徑相同未說明5.2 補 RFC → 正式文件的說明
23Nit附錄 E 空白本節

E.3.1 1.1 版 Goldfish 獨立審查

1.1 再用一個全新 Context 的 subagent 審查 1.0 定稿(只給 md 路徑,禁止讀其他檔案與上網),要求找出「讀者照做會得到錯誤結果」或「無法驗證」的缺口。共 25 項(4 Blocker、15 Major、6 Nit)。每一項都先實測或查官方原文,再決定採用或反駁:

#嚴重度Finding(摘要)查證處理
1Blocker多處要求實作後更新設計 Status/SITEMAP,但 CI 把實作 PR 改設計文件判為越界屬實10.4 新增生命週期表;workflow 加「設計 PR 合併前 Status 必須 Approved」;CI 模擬新增情境 5、6(10.9)
2Blocker13.4 本機 scope guard 參數與 CI 不同屬實13.4 改成與 CI 相同(從 base 讀設計、--phase、只允許 reviews 目錄)
3Blocker8.6 說 D3 抓得到「待查」,實際上抓不到屬實D3 改為全文(Open Questions 除外)並加入中文佔位詞;新增 design_pending.md 與測試
4Blocker照抄 ArchitectureTest 到 api/infra 專案時規則會空轉實測不成立(6.6.1 反例 2)反駁並記錄證據;仍加入 everyMappedLayerHasClasses 讓錯誤訊息更直接
5Majordesign_good.md 既不是 Resolve 前也不是 Resolve 後,例外對應表不存在屬實;1.1 實跑 Review 也抓到同一點5.3.5 明寫它是「審查前」的輸入,並以實跑結果說明缺什麼
6MajorLab 丟 IllegalStateException,與設計的例外類別不一致屬實Lab 新增兩個例外類別,測試斷言具體型別
7Major8.3 流程圖仍寫 egm-review+migration standard屬實改為 feature_spec → review-loop
8MajorR1 只認 not run屬實R1 改為「不是 completed 就失敗」;新增 incomplete fixture
9MajorR4 簽核可跨報告冒用;沒有簽核檔時會當掉屬實簽核行須含報告檔名;檔案不存在不再當掉
10Major11.14 把 headless 讀取權限放專案層屬實改為使用者層
11Majordocs/designs/**/*.md 在 bash 沒開 globstar 時漏掃屬實改用 grep -rnE --include
12MajorPhase 0 沒有 MQ 比對測試,Phase 1 卻引用屬實Phase 0 補 LoanMqMessageGoldenTest
13Major案例四、五沒有 Phase 2 檔案清單屬實15.4.5、15.5.5 補節錄,並以 scope guard 解析驗證
14MajorGoldfishContext 放目錄沒有依據官方允許(review-loop:「source files, directories, or documentation URLs」)7.5.2 補官方原文;補 JSP 目錄 EGM.md 範本(5.8.4)
15Major15.2.7 的【已確認】在 fixture 中找不到證據屬實註明是完整舊系統的示範,fixture 只是精簡版
16MajorReviewers 用檔名、與 2.4 的 frontmatter 名稱矛盾官方就是用檔名(review-loop「shortname … to agents/{name}.md」)7.5.2 補對照表與壞例
17MajorBadShortcut.java 沒有原始碼屬實收進附錄 B.4,6.6.1 補放置與還原步驟
18Major多個審查節沒有可重跑指令屬實5.10、8.6、12.18、13.8 補指令或「怎麼抓」欄
19Major11.11 回滾沒有標 🧪、沒有通過條件屬實標 🧪 並補 claude plugin list 通過條件
20Nit設計 PR 實際用的是 docs-only 檢查,不是 scope guard屬實12.11、15.1.8 改寫
21Nit「37 個檔案」的口徑不清屬實註明是 Resolve 移除 Phase 3、補 MQ 測試後的 Phase 0~2 合計
22Nit2.15 與 5.8.1 對 Bootstrap 何時用 Subagent 說法不同部分屬實;實測 5 個目錄時仍派了 scout5.8.4 記錄實測行為
23NitERD 少了 tenant_id、name屬實補齊
24Nit少數指令缺 /egm: 前綴;validate 路徑寫死 ~/.claude屬實(3.7 為官方原文引用,保留)1.4 加前綴;3.13 改用 CLAUDE_CONFIG_DIR
25NitE7 課程寫「三種情境」屬實改為 6 種(10.9)

這一輪最值得記錄的是第 4、14、16 項:Goldfish 推論的方向合理,但結論錯了,要靠實測或官方原文才能判斷。這正是 egm-resolve 的 CONTEST 規則:「A wish to contest is not evidence that the reviewer is wrong.」反過來說,有證據時就應該反駁,而不是照單全收。

E.4 仍存在的限制

  • 1.1 實跑了 4 支 Skill(review、resolve、bootstrap、drift-report),使用 headless claude -p,EGM main 72d06f5。未實跑:egm-brainstorm、egm-draft、egm-review-loop,以及互動模式下的關卡(Interactive preset、Resolution Gate 的 auto accept)。第 5、15 章中標示「範例」的對話仍是依規則撰寫的示範。
  • LLM 輸出不固定:同一份文件再跑一次,findings 數量與報告寫法都可能不同(5.3.5、10.5.1)。本手冊記錄的是單次實跑結果。
  • Codex CLI、Antigravity、GitHub Copilot 的操作未實測;Codex/agy 的更新、移除指令官方未列出。
  • GitHub Actions 未實跑;CI 行為以本機 git repo 模擬 6 種情境(10.9)。
  • @ArchTest Tests run: 0 的根因已查明(surefire 3.5.3 回歸,6.6.2);其他 build 工具(Gradle)未測。
  • Rensin 原文(Medium)無法以自動化工具讀取,理念整理來自 repo 文件、Google 部落格與 Google Research 摘要。

參考資料(References)

官方來源

  1. google/elephant-goldfish-model(GitHub Repository):https://github.com/google/elephant-goldfish-model
  2. README:https://github.com/google/elephant-goldfish-model/blob/main/README.md
  3. Getting Started:https://github.com/google/elephant-goldfish-model/blob/main/docs/getting_started.md
  4. Documentation Index:https://github.com/google/elephant-goldfish-model/blob/main/docs/index.md
  5. Architecture:https://github.com/google/elephant-goldfish-model/blob/main/docs/designs/architecture.md
  6. Harnesses(安裝、Delegation、支援狀態):https://github.com/google/elephant-goldfish-model/blob/main/docs/harnesses.md
  7. Claude Code integration:https://github.com/google/elephant-goldfish-model/blob/main/docs/claude.md
  8. Codex integration:https://github.com/google/elephant-goldfish-model/blob/main/docs/codex.md
  9. GitHub Copilot CLI integration(experimental):https://github.com/google/elephant-goldfish-model/blob/main/docs/copilot.md
  10. FAQ:https://github.com/google/elephant-goldfish-model/blob/main/docs/faq.md
  11. Data handling(privacy):https://github.com/google/elephant-goldfish-model/blob/main/docs/privacy.md
  12. Versioned releases:https://github.com/google/elephant-goldfish-model/blob/main/docs/releases.md
  13. Skills:https://github.com/google/elephant-goldfish-model/tree/main/skills
  14. Agents(personas):https://github.com/google/elephant-goldfish-model/tree/main/agents
  15. Resources(standards):https://github.com/google/elephant-goldfish-model/tree/main/resources
  16. Design documents:https://github.com/google/elephant-goldfish-model/tree/main/docs/designs
  17. TESTING(Harness Test Record):https://github.com/google/elephant-goldfish-model/blob/main/TESTING.md
  18. AI Policy:https://github.com/google/elephant-goldfish-model/blob/main/AI_POLICY.md
  19. Releases(v0.1.0、v0.1.1):https://github.com/google/elephant-goldfish-model/releases
  20. Issue #237(reviewer 指示檔注入):https://github.com/google/elephant-goldfish-model/issues/237
  21. Google Open Source Blog〈Introducing the Elephant-Goldfish Model plugin: scaling design-driven AI software development〉(2026-10-22):https://opensource.googleblog.com/2026/10/introducing-elephant-goldfish-model-plugin.html
  22. Dave Rensin〈Elephants, Goldfish, and the New Golden Age of Software Engineering〉(Medium):https://medium.com/@drensin/elephants-goldfish-and-the-new-golden-age-of-software-engineering-c33641a48874
  23. Google Research 出版頁:https://research.google/pubs/elephants-goldfish-and-the-new-golden-age-of-software-engineering/

Host 與延伸來源

  1. Claude Code plugins reference:https://code.claude.com/docs/en/plugins-reference
  2. Claude Code skills:https://code.claude.com/docs/en/skills
  3. Claude Code subagents:https://code.claude.com/docs/en/sub-agents
  4. Claude Code setup:https://code.claude.com/docs/en/setup
  5. Spring Boot 4.0 System Requirements:https://docs.spring.io/spring-boot/4.0/system-requirements.html
  6. Spring Boot 4.0 Migration Guide:https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
  7. ArchUnit User Guide:https://www.archunit.org/userguide/html/000_Index.html
  8. OWASP Top 10:https://owasp.org/Top10/
  9. Vue 3 Migration Guide:https://v3-migration.vuejs.org/
  10. GitHub Spec Kit:https://github.com/github/spec-kit
  11. OpenSpec:https://github.com/Fission-AI/OpenSpec
  12. BMAD-METHOD:https://github.com/bmad-code-org/BMAD-METHOD
  13. Superpowers:https://github.com/obra/superpowers
  14. EGM PR #379(實驗性 Windsurf/Devin Desktop adapter,已合併於 main):https://github.com/google/elephant-goldfish-model/pull/379
  15. EGM PR #324(Bootstrap 新增副檔名,已合併於 main,未進 v0.1.1):https://github.com/google/elephant-goldfish-model/pull/324
  16. EGM Issue #460(EGM Lite RFC,未合併):https://github.com/google/elephant-goldfish-model/issues/460
  17. EGM Issue #408(提供已記錄的決策給 Goldfish,未合併):https://github.com/google/elephant-goldfish-model/issues/408
  18. EGM Issue #433(finding 證據標記,未合併):https://github.com/google/elephant-goldfish-model/issues/433
  19. EGM Issue #436(依核准設計檢查實作 diff,未合併):https://github.com/google/elephant-goldfish-model/issues/436
  20. EGM Issue #448(每個 feature 一個編號資料夾,未合併):https://github.com/google/elephant-goldfish-model/issues/448
  21. EGM PR #450(OpenSpec 原生整合 RFC,未合併):https://github.com/google/elephant-goldfish-model/pull/450
  22. Maven Surefire Issue #834(3.5.3 不計入非 method 型測試):https://github.com/apache/maven-surefire/issues/834
  23. Maven Surefire PR #828(SUREFIRE-2298 修正,含於 3.5.4):https://github.com/apache/maven-surefire/pull/828
  24. Claude Code CLI reference(-p、--plugin-dir、--output-format、--resume):https://code.claude.com/docs/en/cli-reference

同 repo 相關手冊

  1. spec-kit使用教學、OpenSpec使用教學、BMAD-METHOD使用教學、Superpowers教學手冊
  2. Playwright 教學手冊、code-modernization 教學手冊、Claude Code Migration Kit 教學手冊
  3. Spring boot 4.x升版教學、Java25升版教學、Vue3 前端framework教學、PrimeVue使用教學