AIDive

Pack de vídeo

Revise o plano do Claude Code antes: o kit EGM e o checklist de pular ou revisar

7 min de leitura

TL;DR e veredito

O agente que escreveu o seu plano não enxerga os furos dele. O EGM, o Elephant-Goldfish Model, é o plugin gratuito do Google para o Claude Code que resolve isso: o elefante escreve o plano com você, e revisores peixinhos-dourados, sem memória da conversa, leem só o plano e o seu código. Não é um produto oficialmente suportado pelo Google s25.

Rodamos o plugin numa feature real de um app de lista de presentes da família (Next.js, Notion como banco de dados): deixar um parente reservar um presente para que duas pessoas nunca comprem o mesmo, sem que os pais possam ver quem reservou o quê. Numa cópia do repositório, nunca na lista real.

  • O planejador nomeou a race sozinho. Os revisores encontraram duas falhas que ninguém na conversa tinha levantado: os pais podiam descobrir quem reservou o quê pelos logs da própria hospedagem, e um cookie salvo podia ser reenviado para cancelar a reserva de outra pessoa.
  • A correção que a revisão deu para a race enfraquecia o objetivo. Nós contestamos, e o design mudou.
  • Uma sessão nova construiu a feature conforme o design aprovado: 216 testes, e 30 de 30 corridas pela última unidade deram exatamente um vencedor. Isso rodou contra um substituto do Notion, então a verificação real ainda é nossa para fazer.
  • Num conserto de uma linha no README, o fluxo simples custou $0.0455 e 10 s. O caminho do EGM para a feature custou $7.10 e 32 min antes de qualquer código.

Veredito: rode a revisão quando um erro tocar dados, privacidade, permissões ou dinheiro de outra pessoa. Pule-a para um conserto pequeno e claro. O pacote abaixo traz a instalação, a linha do CLAUDE.md, uma cheat sheet e o checklist.

Síntese com fontes

O que é o EGM. O README do Google diz que milhares de engenheiros do Google o usam para redigir specs com agentes de contexto profundo e testá-las sob estresse com subagentes de contexto zero antes de escrever código s1. Essa é uma afirmação do próprio Google, sem número. A ideia vem de Dave Rensin, que escreveu "We are mass-producing our mistakes" (estamos produzindo nossos erros em massa) se não tomarmos cuidado s7. A única versão até agora é a v0.1.0, publicada em 2026-10-27 s26. É Apache-2.0 e "not an officially supported Google product" (não é um produto oficialmente suportado pelo Google) s25 s9.

A instalação são dois comandos e uma sessão nova. claude plugin marketplace add google/elephant-goldfish-model, depois claude plugin install egm@egm, depois abrir uma sessão nova s1 s2. Outros relatam os mesmos dois comandos s6 s8. Nós adicionamos --scope project à instalação, então ela vale só para aquele repositório. Exige o Claude Code 2.1.271 ou mais recente, por causa do suporte a omitClaudeMd s2. A nossa versão era a 2.1.294.

Por que os revisores são cegos. Subagentes normais excluem a conversa do agente pai. O omitClaudeMd exclui também os arquivos de instruções do usuário, do projeto e locais s2. Os adaptadores de revisor declaram tools: [Read, Grep, Glob], model: inherit e omitClaudeMd: true s20. O sintetizador é diferente: ele cria revisores, com aninhamento permitido até 3 níveis s2. A documentação acrescenta uma ressalva: isso é "context and tool isolation, not filesystem isolation: reviewers can read accessible files" (isolamento de contexto e de ferramentas, não de sistema de arquivos: os revisores podem ler os arquivos acessíveis) s2.

Uma linha no CLAUDE.md mantém os relatórios numa pasta. Sem ela, os arquivos da revisão se acumulam na raiz do repositório, onde você pode commitá-los por engano s23. Uma linha EGM artifact directory: <path> no CLAUDE.md ou no AGENTS.md envia os arquivos para essa pasta s2.

O fluxo.

  • O brainstorm cria um enxame de peixinhos-dourados com 6 lentes e escreve concepts_brief.md s21.
  • O draft escreve design_draft.md s22.
  • A revisão roda cinco fases: Initial Zoom Out Review, Comprehension Review, Design Critique, Intermediate Zoom Out Review e Implementation Readiness s3.
  • O resolve marca cada problema com CONTEST, ESCALATE, PROPOSE FIX ou DECLINE. Você escolhe, e "auto accept" aplica em lote as correções propostas, pulando os itens contestados s24.

O que outras pessoas encontraram. Um relato de campo sobre o Claude Code e o EGM 0.1.0 contou 26 achados (9 blockers, 9 major, 8 nits), 20 corrigidos, 4 pulados, 2 errados, cerca de $3.40 de uso a preços de API e 24 de 24 testes passando de primeira. A lição do próprio autor: "Goldfish read documents. They don't run code." (Os peixinhos-dourados leem documentos. Não rodam código.) s6. Rensin diz que cerca de 30% das sugestões são altamente valiosas, o que ele chama de mais do que suficiente s7.

E o que diz para pular. O README: para a correção de um bug pequeno e claro, use seu fluxo de código normal s25. O FAQ: design e revisão "may not pay off for a small, well-understood change" (podem não compensar numa mudança pequena e bem compreendida), e concluir o fluxo por si só "does not demonstrate a productivity improvement" (não demonstra um ganho de produtividade) s4. Um co-construtor o testaria em jobs de background, permissões, mudanças de dados ou uma nova fronteira de serviço s10. Um pequeno piloto (três execuções por braço) concluiu que o EGM "added nothing over the plain plan, at about five times the cost" (não acrescentou nada ao plano simples, a cerca de cinco vezes o custo) s5. Citamos isso como um pequeno piloto, não como uma regra.

Por que a race é real. A documentação do Notion não oferece incremento atômico nem escrita condicional para uma propriedade, e as escritas substituem o valor inteiro s27. Dois parentes que leem a mesma contagem podem os dois escrever, e uma reserva se perde.

Nossa própria execução, palavra por palavra. Estes números são nossos, não de uma fonte acima. O modelo da sessão foi o Claude Sonnet 5.5, e os revisores o herdam. Os custos são equivalentes a preços de API no Sonnet 5.5.

  • A revisão completa rodou 9 subagentes revisores em 5 etapas sequenciais, e o turno consolidado levou 7 min 24 s. Achados brutos nas cinco etapas: 77. Consolidados em 12 itens de ação, com 1 Blocker.
  • O resolve produziu 37 problemas: 4 ESCALATE, 5 CONTEST, 2 DECLINE, 26 PROPOSE FIX. Ele conferiu os revisores contra o código primeiro e achou um achado errado: um revisor disse que input.tsx ficaria sem uso, mas a página de login ainda o importa.
  • A direção de correção da revisão para a race era abandonar o objetivo. Nós contestamos. O design que deu um único vencedor veio dessa contestação, e nenhum revisor o leu.
  • Construção a partir do design aprovado numa sessão nova: 216 testes passaram, e o teste da race na última unidade deu um sucesso e um "cheio" em 30 de 30 seeds.
  • Custo: $7.10 e 32 min de tempo de modelo antes de qualquer código (brainstorm, draft, review, resolve). A correção do README numa cópia sem o EGM: $0.0455 e 10 s.

Código

Cinco arquivos de referência. Os quatro primeiros você copia para o seu repositório ou deixa abertos. O quinto é o relatório real da nossa execução, para você ver como é a saída.

1. Instalar e desinstalar. Rode na pasta do seu projeto e depois abra uma sessão nova.

egm-install.sh

#!/usr/bin/env bash
# Install Google's EGM plugin for this project only.
# Needs Claude Code 2.1.271 or later (the reviewers rely on omitClaudeMd).
claude plugin marketplace add google/elephant-goldfish-model
claude plugin install egm@egm --scope project

# Start a new Claude Code session now, so the plugin loads.
# The commands then show up with the /egm: prefix.

# Uninstall (run from the same project folder):
# claude plugin uninstall egm@egm --scope project
# claude plugin marketplace remove egm

egm-install.sh on GitHub

2. A linha do CLAUDE.md. Adicione ao CLAUDE.md do seu projeto para que os relatórios caiam em docs/egm.

CLAUDE.md

<!-- Keeps EGM reports in one folder instead of the repo root. Create docs/egm or let EGM create it. -->
EGM artifact directory: docs/egm

CLAUDE.md on GitHub

3. A cheat sheet da revisão. Os comandos em ordem, as cinco etapas e seus arquivos de relatório, o que significam os rótulos do resolve e as configurações dos revisores.

egm-review-cheatsheet.md

# EGM review cheat sheet

## The commands, in order

1. `/egm:egm-brainstorm <the feature in one sentence>` writes `concepts_brief.md`.
2. `/egm:egm-draft` writes the design document, one section at a time. You approve each section.
3. `/egm:egm-review <design>` runs the five review stages (below). Pick the consolidated mode to get one merged list.
4. `/egm:egm-resolve` turns the reports into one table of issues. You answer each one.
5. Open a fresh session and send:

```
Build the feature exactly to the approved design in docs/egm/<file>.md; add tests.
```

## The five review stages and their report files

| Stage | What it asks | Report file |
|---|---|---|
| 1. Initial Zoom Out Review | Does the design solve the right problem? | `zoom_out_report.md` |
| 2. Comprehension Review | Would a newcomer understand it? | `comprehension_report.md` |
| 3. Design Critique | Attacks the design, its structure and its wording | `critic_report.md` |
| 4. Intermediate Zoom Out Review | Zooms out again on the unedited design | `intermediate_zoom_out_report.md` |
| 5. Implementation Readiness | Checks each step against your real code | `implementation_readiness_report.md` |

The consolidated mode also writes `consolidated_review_report.md`. Resolve writes `goldfish_review_report.md`.

## What resolve's suggestions mean

- ESCALATE: the reviewers found a decision only you can make.
- CONTEST: the agent thinks the finding is wrong or the fix is too weak, and says why. You can still overrule it.
- DECLINE: the agent proposes not acting on the finding.
- PROPOSE FIX: the agent proposes an edit to the design.
- "auto accept": reply with these two words to batch-apply every PROPOSE FIX and skip CONTEST items. Decide the escalated issues first.

## Reviewer settings (Claude adapters)

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

Read-only tools, the same model as your session, and no CLAUDE.md or other instruction files. This is context and tool isolation, not filesystem isolation: reviewers can read accessible files.

## Before you build

Reviewers read documents. They do not run code. If your design relies on an outside service behaving a certain way, run a check against a copy of the real thing before you ship.

egm-review-cheatsheet.md on GitHub

4. O checklist de pular ou revisar. Leia antes de digitar o prompt de construção.

skip-or-review.md

# Skip or review

Ask one question before you type the build prompt: if this is wrong, whose data, privacy, permissions or money does it touch?

## Run the EGM review when the change involves

- [ ] Data that several people write at the same time
- [ ] Privacy: something someone must not be able to see or work out
- [ ] Permissions: who can do, change or cancel what
- [ ] Money: a charge, a price, a balance, a refund
- [ ] A time rule, a background job or a new service boundary

## Use your normal workflow when

- [ ] The fix is small and clear and you can say it in one sentence
- [ ] You could one-shot it
- [ ] A wrong result is visible at once and costs nothing to undo

## What the README says

> Use it when a feature needs design decisions before implementation. For a small, clear bug fix, use your normal coding workflow.

## What the FAQ adds

> Design and review take time and may not pay off for a small, well-understood change.

> Completing the EGM workflow alone does not demonstrate a productivity improvement.

skip-or-review.md on GitHub

5. Um relatório consolidado real. É o relatório da nossa execução num app de lista de presentes da família. Repare como cada item de ação aponta de volta para os achados das etapas por trás dele.

example-consolidated-report.md

<!-- The consolidated review report from our run on a family gift-list app. -->

# Consolidated Review Report

**Target:** `docs/egm/gift-reservations.md` (464 lines; FeatureRange 1-280, DetailedRange 281-464)
**Mode:** Consolidated report, all five stages, no checkpoints. No edits were applied to the document.
**Stage reports:** `zoom_out_report.md` (5), `comprehension_report.md` (6), `critic_report.md` (7), `intermediate_zoom_out_report.md` (8), `implementation_readiness_report.md` (9).

**Overall:** The design fits the problem and keeps Notion as the only store. It is not ready to implement. Five issues need decisions from the author, and the plan has errors a reader can check against the code: a build that breaks mid-sequence, a wrong HTTP status, and a wrong assumption about SDK retries.

## Blockers
Stage 8 raised one item to Blocker (A1). Stages 5, 6, 7 and 9 report none.

## Action items by priority

### 🔴 Blocker

**A1. Decide whether to drop the post-write re-read.** (Stage 5 ZO-2, Stage 6 CO-3/CO-6, Stage 7 CR-1/CR-2/CR-3/CR-8, Stage 8 Z8-1, Stage 9 IR-6)
Lines 28, 132-134, 159, 174, 220, 276, 360, 366, 415.
The re-read does not catch the main race (the document says so at line 174), assumes read-after-write consistency with no evidence, checks only `x`, adds a third Notion call, and leaves the cookie and response behaviour undefined when it fails. Goal 2 and the rejection of Alternative F rest on it. Stage 8 recommends removing it, along with `changed_meanwhile` and the "unverified" branch, rewriting Goal 2 as "reduces duplicate purchases, does not prevent them" and rewriting Alternative F around the real trade-off. If kept, every post-write failure needs a stated cookie and response behaviour. Decide this first: it closes or removes about eight other findings.

### 🟡 Major: design and scope

**A2. Fix the cookie's stated guarantees and the stale-record dead end.** (CR-4, CR-5, Z8-2, Z8-3, ZO-5)
Lines 32, 34, 85, 111, 114, 144-148, 246-250, 355.
A saved copy of the cookie can be replayed to cancel someone else's unit, and clearing the cookie bypasses the one-unit and 80-id limits. After the parents release a unit by hand, the stale cookie makes reserve fail with 409 `already_reserved`. State the real threat model (stops accidental cancels and casual tampering among about 30 relatives), and decide whether to keep the `already_reserved` guard and the 80-id cap.

**A3. Qualify "no identity is stored or logged", and decide on the bespoke log line.** (CR-6, Z8-4, CO-7)
Lines 29, 37, 270-271, 367.
Vercel request logs and Notion edit history, together with timestamped log lines, can let the parents correlate who reserved what. The log line is also specified three different ways.

**A4. Settle where configuration is checked, and the effect on the list route.** (ZO-4, Z8-5, CR-17, CO-12, IR-13)
Lines 36, 115, 117, 168, 394-395, 403.
The proxy 503 for `/api/registry*` changes the existing list GET route, which the plan doesn't list. Configuration is checked in the proxy, the routes and `canReserve`. The 401 versus 503 precedence is unspecified.

**A5. Reuse the existing HMAC helper.** (ZO-1, IR-8)
Lines 111, 324. `src/lib/auth.ts` already has `hmacBase64Url`. The plan writes a second implementation and leaves the crypto details (key import, base64url without `Buffer`, signed text) unspecified.

### 🟡 Major: factual errors and unstated assumptions

**A6. "Each step leaves the project building" is false.** (CO-2, IR-1, Z8-6)
Line 283. The build is red from item 8 through item 16. Group the changes into one landing phase or keep the old exports until the consumers go.

**A7. The deleted `PATCH` route returns 404, not 405.** (CO-5, CR-7, IR-2)
Lines 116, 181, 388, 458. Correct the claim and manual test 7. A 410 stub is an option, but Stage 8 advises against adding code for it.

**A8. Handler signatures ignore Next 16 async APIs.** (IR-3)
Lines 115, 378, 382, 402. `params` is a `Promise`, and `cookies()` is async.

**A9. The Notion SDK already retries 429s, and error classification is unspecified.** (IR-4, IR-5)
Lines 276, 339-345. "No automatic retry" is false unless `getClient` sets `retry: false`. Name how `rate_limited`, `not_found` and `retry-after` are detected, state the `pages.update` payloads, and reconcile the two signatures of `writeReservationState`. A missing `Acheté ?` returns 502 before the 422 check.

**A10. Undefined terms and sources.** (CO-1, CR-12, CO-4, CO-10, CO-14)
`concepts_brief.md`, "the owner", "reconciliation", "Public only" filter, `x` and `y`, and the data-source id are used without definition or link. Five places justify choices by process history a new reader cannot verify.

**A11. Required sections and rationale.** (CR-9, CR-10, CR-11)
There is no Risks & Mitigations section (the content is scattered). Alternatives A, J and M are rejected only on "the parents decided"; C and F lack the decisive trade-off. The Open Question at line 57 points to intro wording that is not in the plan.

**A12. Unresolved decisions in the plan.** (IR-6, IR-7, IR-9, IR-10, IR-11, IR-12)
Cancel error mapping, the cookie-change rule, response bodies, final French copy, the client rewrite details and automated test coverage for the Notion layer, routes, proxy and table.

### 🟢 Nit

*   **Simplicity.** Single `[action]` route instead of two files; delete the unused `checkbox.tsx` and `input.tsx`; remove the "Optional extras" question; revert to strict `x/y` parsing or fix the Goal wording; fold Alternatives G, H and I into Goals and Non-Goals. (ZO-6, ZO-8, Z8-7, Z8-8, Z8-9, CR-19)
*   **Structure.** Reorder Open Questions; split CUJ 4; add one error-path CUJ; fix the ambiguous state table and the packed response table; fix the "two new calls" list. (CR-13 to CR-16)
*   **Wording and terminology.** Unify `acheté`/`achete`/`Acheté ?` and `x/y` versus `acquise/totale`; remove filler and duplicated statements; fix French copy and apostrophes; pin `vitest`; split the dense reserve step 7 and `act` handler sentences. (CR-18, CR-20 to CR-24, IR-14 to IR-20)

## Traceability matrix

| Action item | Stage 5 | Stage 6 | Stage 7 | Stage 8 | Stage 9 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| A1 re-read | ZO-2 | CO-3, CO-6 | CR-1, CR-2, CR-3, CR-8 | Z8-1 | IR-6 |
| A2 cookie guarantees, stale record | ZO-5 | | CR-4, CR-5 | Z8-2, Z8-3 | |
| A3 identity and logging | | CO-7 | CR-6 | Z8-4 | IR-17 |
| A4 config checks, list route | ZO-4 | CO-12 | CR-17 | Z8-5 | IR-13 |
| A5 HMAC reuse | ZO-1 | | | | IR-8 |
| A6 build order claim | | CO-2 | | Z8-6 | IR-1 |
| A7 405 vs 404 | | CO-5 | CR-7 | Z8-7 | IR-2 |
| A8 async handler APIs | | | | | IR-3 |
| A9 SDK retry, error mapping | | | | | IR-4, IR-5 |
| A10 undefined terms | | CO-1, CO-4, CO-10, CO-14 | CR-12 | | |
| A11 risks section, rationale | | | CR-9, CR-10, CR-11 | | |
| A12 unresolved plan decisions | ZO-3 | CO-13 | | | IR-6 to IR-12 |
| Nits | ZO-6 to ZO-8 | CO-8, CO-9, CO-11, CO-15, CO-16 | CR-13 to CR-24 | Z8-7 to Z8-9 | IR-14 to IR-20 |

## Coverage and limits
- Stage 7 critics reviewed lines 1-280 only. Stage 9 reviewers audited lines 281-464 against the real code under `src/`.
- No stage reviewed any file outside the target document and the existing source files named above.
- Stage 8 ran on the unedited document, so its recommendations (drop the re-read, drop `already_reserved`, remove the proxy 503) are proposals for the author to decide, not settled findings.
- Reviewers cannot run the app. The claims about Next.js (404 versus 405) and the Notion SDK (retry defaults) come from the reviewers reading the code and type definitions in the repo and should be confirmed during the fix.

example-consolidated-report.md on GitHub

Faça isto na segunda-feira

  • Confira claude --version. Você precisa da 2.1.271 ou mais recente.
  • Rode os dois comandos de instalação de egm-install.sh num projeto e abra uma sessão nova.
  • Adicione EGM artifact directory: docs/egm ao CLAUDE.md desse projeto.
  • Escolha uma feature que você ainda não construiu e em que um erro toque dados compartilhados, privacidade, permissões ou dinheiro. Rode /egm:egm-brainstorm nela, em uma frase.
  • Rode /egm:egm-draft, aprove o design seção por seção, depois /egm:egm-review <design> e leia os cinco relatórios.
  • Rode /egm:egm-resolve. Responda você mesmo aos problemas escalados e conteste qualquer correção que enfraqueça o seu objetivo.
  • Abra uma sessão nova e envie: "Build the feature exactly to the approved design in docs/egm/.md; add tests." Depois teste você mesmo o caminho arriscado.
  • Para o seu próximo conserto pequeno e claro, abra skip-or-review.md e vá direto ao seu fluxo normal.

Para ir além

Outros comandos que deixamos de fora. O plugin tem também /egm:egm-bootstrap e /egm:egm-drift-report, um segundo fluxo para uma base de código existente e uma verificação semanal de drift. Não os rodamos, então não dizemos nada sobre o quão bem funcionam.

Outros harnesses e modelos misturados. Rodamos só o Claude Code. Os revisores usam model: inherit, então rodaram no modelo da nossa sessão e podem compartilhar os pontos cegos dele. Não testamos outros harnesses nem a mistura de modelos.

Plan Mode e outros planejadores. Não comparamos o EGM com o Plan Mode nem com outras ferramentas de planejamento. O piloto acima é o único confronto direto que citamos, e é pequeno.

Limites honestos da nossa execução.

  • A correção do claim ledger para a race saiu do resolve depois que contestamos a revisão, e nenhum peixinho-dourado a revisou de novo.
  • A correção depende de o Notion manter uma única ordem para anexos simultâneos. A documentação do Notion não promete isso.
  • O resultado de 30 de 30 rodou contra um substituto do Notion. A verificação da race do próprio design contra uma cópia do banco de dados real não foi executada. Rode-a antes de publicar.
  • A revisão confere documentos e código, e não pode rodar o app. Duas afirmações sobre o framework no nosso relatório (404 contra 405, padrões de retry do SDK) vêm de leitura de código, e o relatório manda confirmá-las.
  • Os 30% de Rensin e os números do relato de campo são dos autores deles, não nossos.

FAQ

Os revisores veem o meu CLAUDE.md ou a nossa conversa? Não. Eles excluem a conversa, e omitClaudeMd: true esconde o CLAUDE.md e os outros arquivos de instruções. Ainda assim leem o plano e qualquer arquivo acessível s2.

Por que os arquivos da revisão estão na raiz do repositório? O Claude Code não tem pasta de artefatos por padrão s23. Adicione a linha EGM artifact directory: ao CLAUDE.md.

Preciso responder a todos os problemas no resolve? Não. Responda aos escalados e depois diga "auto accept" para aplicar em lote as correções propostas. Os itens contestados são pulados s24.

Uma suíte de testes verde é prova suficiente? Não. A nossa passou 216 testes, e mesmo assim a verificação da race contra o Notion real ainda não tinha sido feita. Teste você mesmo o caminho arriscado.

Quando devo pular a revisão? Para um conserto pequeno e claro, como diz o README s25. Na nossa execução, esse conserto custou $0.0455 e 10 s sem ela.

Arquivos