Use Superpowers

grill-with-docs: faça a IA parar de concordar com tudo e sabatinar seu plano primeiro

Você entrega um pedido à IA e ela já dispara pro código, cravando no projeto tudo o que você ainda não tinha pensado direito. O grill-with-docs vira o jogo: em vez de escrever código, ele te entrevista usando o glossário e o código do seu próprio projeto, não deixa você seguir enquanto as palavras não estiverem afiadas, e vai anotando glossário e decisões pelo caminho. Abaixo, uma rodada de verdade — ele pegou um choque de termos que tinha passado batido por mim.

github.com/mattpocock/skills @ 6eeb81b

Resumo de 30 segundos · sem tempo pro texto todo? pega isto

  • O problema: a IA concorda com tudo. Entregue um plano meio cru → ela escreve código → sua confusão vai junto pro projeto.
  • O grill-with-docs faz o contrário: ele te sabatina. Usa o glossário do CONTEXT.md + o código do seu projeto pra furar seu plano, um buraco de cada vez.
  • Como ele sabatina: uma pergunta por vez, resposta recomendada na frente; lê o código em vez de perguntar quando dá; termo fechado → entra no CONTEXT.md; decisão difícil de reverter → vira um ADR.
  • Instalar: npx skills@latest add mattpocock/skills · Usar: “sabatina meu plano com o grill-with-docs: ”
  • Melhor pra: adicionar uma função complexa a um projeto maduro onde algumas palavras significam coisas diferentes pra cada pessoa. Não vale a pena: repositório vazio / mudança boba / esperar que ele escreva o código por você.

1. Uma IA que concorda com tudo é um risco escondido

O mais perigoso em parear com uma IA é que ela quase nunca te contraria.

Você joga pra ela um plano meio cru — “adiciona uma função: deixa o usuário cancelar alguns itens de um pedido e devolver o dinheiro” — e ela nem pisca: “Claro!”, e o código jorra. Só que aquela frase está cheia de coisa que você nunca fechou, e ela não perguntou nenhuma: “cancelar” é antes ou depois do envio? De quem é o reembolso? É a mesma coisa que o seu código já chama de cancelamento? Ela não pergunta. Ela assume por você e crava essas suposições no código.

Três semanas depois você descobre que aquela palavra, “cancelar”, significa três coisas diferentes pro produto, pro código e pro banco. O código virou um angu.

Não é que a IA não seja esperta. É que ela quer ajudar a tal ponto que não para pra te fazer pensar.

O grill-with-docs faz o oposto: impede a IA de concordar com tudo e sabatina seu plano primeiro (grill é sabatinar, é botar no fogo pra interrogar). Enquanto as palavras não estiverem afiadas, você não segue.

2. Como funciona: uma entrevista que lembra do seu projeto

O mecanismo numa frase: ele usa a linguagem e as decisões do seu próprio projeto pra sabatinar seu plano novo.

Alguns detalhes (o autor separou esse comportamento em dois skills, grilling e domain-modeling — falo disso adiante):

Uma pergunta por vez, resposta recomendada na frente. Ele percorre a árvore de decisão do seu plano galho por galho, e toda pergunta começa com “eu iria por aqui, porque…” — em vez de despejar um questionário de vinte itens no seu colo.

Se dá pra ler no código, ele não te pergunta. O que uma olhada rápida no código responde, ele mesmo vai lá e busca.

Ele te prende ao glossário. Aquele CONTEXT.md na raiz do projeto é a régua dele. Solte uma palavra que não bate com a definição e ele te trava na hora: “Seu glossário diz que ‘estorno’ é X, mas você claramente quer dizer Y — qual é?”

Palavra vaga, ele afia. Você diz “conta” e ele pergunta: “Você fala do Customer ou do User? São duas coisas diferentes.”

Ele confere contra o código. Você afirma que uma função funciona de um jeito, ele lê o código pra verificar; se não bate, ele aponta: “O código cancela o pedido inteiro, mas você acabou de dizer parcial — qual vale?”

Termo fechado, vai direto pro CONTEXT.md. Sem juntar, sem “depois”.

Só decisão difícil de reverter rende um ADR. Ele é pão-duro com ADR (registro de decisão de arquitetura): só propõe um quando os três valem juntos — difícil de reverter, confuso sem contexto, fruto de um trade-off de verdade.

No fundo isso são os dois hábitos sérios do domain-driven design — linguagem onipresente (ubiquitous language) e deixar um rastro das decisões — embrulhados numa conversa de que você não escapa.

Uma mudança que vale conhecer: na real são dois skills aparafusados. O Matt separou o grill-with-docs em grilling (a entrevista implacável) e domain-modeling (a disciplina de glossário + ADR), deixando o grill-with-docs como uma casca fina cujo corpo é uma linha só: “roda /grilling, usando /domain-modeling”. Nada mudou no comportamento, mas dá pra usar as metades separadas: só quer a sabatina, /grilling; só quer manter o glossário e os ADRs, /domain-modeling; quer os dois — aí é o grill-with-docs.

3. Mãos à obra: instale e entregue um plano

Instalar. Está no mattpocock/skills — um comando oficial, marque o grill-with-docs quando ele perguntar:

npx skills@latest add mattpocock/skills

Por causa daquela separação, o grill-with-docs agora precisa do grilling e do domain-modeling pra ficar completo, então marque os três (ou use os outros dois direto). Já clonou o repositório? Copiar essas pastas pro .claude/skills/ do seu projeto também resolve.

Alimentar. Pare de dizer “implementa X pra mim”. Diga isto:

Sabatina meu plano com o grill-with-docs: <jogue aqui o plano que você ainda não pensou direito>

Atenção: ele vem marcado com disable-model-invocation, então não aparece sozinho — você tem que chamá-lo pelo nome (ou digitar /grill-with-docs) pra começar. Aí prepare-se: ele não vai concordar com você, vai começar a perguntar.

O primeiro resultado de verdade costuma ser a primeira pergunta: algo que você achava resolvido e, uma pergunta depois, percebe que não estava. Aqui está uma rodada que eu mesmo rodei.

4. Veja uma sabatina de verdade

Montei um projetinho pra ele sabatinar, com uma armadilha plantada de propósito. O projeto já tinha um CONTEXT.md:

**Cancellation**:
An order is voided in full before shipping; stock returns to inventory as-is. No refund flow is involved.
_Avoid_: Refund, Return

O código em src/orders.ts também joga limpo: cancelOrder() só cancela pedidos inteiros, só antes do envio, nunca mexe em dinheiro.

Aí entreguei o plano (o mesmo lá do começo): “Deixa o usuário cancelar alguns itens de um pedido (não o pedido todo) e devolver o dinheiro desses itens.”

Ele leu o código e o glossário, e a primeira frase não foi “Claro” — foi:

Antes de começar, dois choques de terminologia precisam ser sinalizados.

Seu “cancelar alguns itens e reembolsar” colide com duas definições existentes:

  1. O CONTEXT.md define Cancellation = cancelamento do pedido inteiro + sem fluxo de reembolso. Você está descrevendo um cancelamento parcial, com reembolso — os dois pontos batem de frente.
  2. A lista _Avoid_ do glossário exclui explicitamente a palavra “Return”.

Ou seja, a ação que você descreve não tem palavra existente. Precisamos nomear esse conceito novo antes de seguir.

Eu de fato não tinha percebido: o “cancelar” da minha frase e a Cancellation já cravada no projeto não eram a mesma coisa. Ele não só pegou — foi lá e leu o código:

O cancelOrder atual em src/orders.ts:3 só permite pedidos com status === "PLACED". Esse seu “cancelar alguns itens” — só antes do envio, ou depois também?

Minha recomendação: só antes do envio. Devolução pós-envio é, em termos de negócio, um fluxo de devolução, uma ordem de grandeza mais complexo… faça primeiro o caminho de antes do envio; a fronteira fica mais limpa.

Respondi “fechado, só antes do envio”. Aí ele fez algo mais importante — nomeou o conceito sem nome e escreveu direto no glossário:

Partial Cancellation: antes do envio, remove alguns (não todos) line items de um pedido; o estoque dos itens removidos volta pro inventário. Sem fluxo de reembolso. _Avoid_: Partial refund, Partial return, Item cancellation

Esse aqui ele escreveu de fato no arquivo CONTEXT.md, não só no chat. A metade do reembolso ele empurrou pra longe sem rodeio: “Isso é do Billing — não fica aqui.”

Sabatinando rumo às fronteiras, ele parou pra decidir se valia deixar um rastro, e aí gerou de fato um ADR:

ADR registrado em docs/adr/0001-partial-cancellation-no-refund.md: “Partial Cancellation não dispara reembolso; reembolsos ficam inteiramente a cargo do contexto Billing. … A alternativa era disparar o reembolso dentro do Ordering, fazendo de ‘cancelar + reembolsar’ uma operação atômica — rejeitamos porque isso faria o Ordering depender das entranhas do Billing e quebraria a fronteira de contexto existente.”

A melhor parte é a pergunta seguinte, que citou o próprio ADR que ele tinha acabado de escrever:

Pergunta 3 / Como o Billing fica sabendo que tem que reembolsar? O cancelOrder atual não emite evento nenhum (src/orders.ts:7).

  • A. Emite um evento de domínio; o Billing assina e reembolsa.
  • B. O Ordering chama a API de reembolso do Billing direto.
  • C. Não emite nada; deixa quem chamou costurar tudo.

Minha recomendação: A. A opção B faz o Ordering depender do Billing direto — exatamente o que o ADR 0001 rejeitou.

Repare nesse ciclo: ele me obrigou a afiar uma palavra → escreveu no glossário → registrou uma decisão de fronteira como ADR → e então usou esse ADR pra barrar uma opção posterior que teria quebrado a fronteira. Ele usa a linguagem que vocês acabaram de construir juntos pra defender cada passo seguinte. É isso que significa “uma entrevista que lembra do seu projeto”.

5. O gênio dele: quando usar, quando não forçar

Ele é revigorante, mas não é cura pra tudo nem é sempre a escolha certa:

  • Ele precisa de algo pra sabatinar. Com um CONTEXT.md e algum código, ele tem material pra te prender e pra conferir. Num repositório vazio recém-criado ele monta um glossário do zero (ainda útil), mas longe da afiação que vem de furar usando a linguagem que você já tem. Por isso ele brilha pra adicionar a um projeto que já cresceu.
  • Ele afia clareza, não código. Uma sabatina te deixa com termos afiados, uns ADRs, um plano que você de fato pensou — não uma pilha de implementação. Escrever código é o próximo passo, depois que você está claro; não espere que ele faça isso por você.
  • Não sabatine o que é trivial. Cor de botão, um campo descartável — force pelo processo e ele vai obedientemente fazer o teatro, puro desperdício. O valor dele está onde uma palavra vaga vira encrenca sem fim: conceitos de domínio, fronteiras de contexto, lugares onde algumas ideias se embaralham. Marreta numa mosca: a mosca passa bem, você é que cansa.
  • Ele é pão-duro com ADR — isso é qualidade, não reclame. Ele registra um só quando os três batem: difícil de reverter, confuso depois, um trade-off de verdade. Quando você se pegar querendo que ele anote mais, pergunte: você precisa mesmo do rastro, ou só quer a cerimônia de “tá tudo documentado”? Mais ADR não é melhor; melhor é anotar os que importam.

Numa frase: adicionar uma função complexa a um projeto maduro, com aquela pulga atrás da orelha de que “algumas palavras significam coisas diferentes pra cada um” — liga. É o terreno dele.

6. Cartão de consulta rápida

Instalar: npx skills@latest add mattpocock/skills   # marque o grill-with-docs no prompt
Sabatinar: diga pra IA "sabatina meu plano com o grill-with-docs: <plano>"

O que ele faz:
  uma pergunta por vez, resposta recomendada na frente
  lê o código em vez de perguntar quando dá
  te prende ao glossário do CONTEXT.md; te trava quando uma palavra não bate
  afia palavra vaga ("conta" = Customer ou User?)
  confere contra o código; aponta divergências
  termo fechado -> escrito direto no CONTEXT.md (glossário, sem detalhe de implementação)
  decisão difícil de reverter -> um ADR (docs/adr/, só se os três critérios baterem)

CONTEXT.md: só glossário — uma ou duas linhas por termo, a palavra a usar + _Avoid_ as que evitar
Os três testes do ADR: difícil de reverter + confuso sem contexto + um trade-off de verdade (faltou um, pula)

Melhor pra: adicionar uma função complexa a um projeto maduro onde "algumas palavras significam coisas diferentes pra cada um"
Não vale a pena: repositório vazio / mudança boba / esperar que ele escreva o código por você

7. Pra ir além

  • O código-fonte: grill-with-docs (MIT), mais os dois em que ele se dividiu, grilling e domain-modeling. Os guias de formato do glossário e do ADR agora ficam no domain-modeling: formato do CONTEXT.md, formato do ADR — vale a leitura dos dois.
  • Quer ir mais fundo? Procure linguagem onipresente (ubiquitous language) e ADR (Architecture Decision Record) no domain-driven design (DDD) — o grill-with-docs é só uma casca leve que torna os dois fáceis de fazer no dia a dia.
  • Curtiu essa pegada de “colaborar com a IA por outro ângulo”? Da última vez destrinchamos o caveman (faça a IA calar a boca e ir direto ao ponto) — um par perfeito: um faz ela cortar a enrolação, o outro faz ela fazer as perguntas difíceis. A série vai continuar destrinchando outros skills do repositório do Matt.

Este texto é um tutorial original de usesuperpowers.com. O skill grill-with-docs aqui explicado vem de mattpocock/skills (source_commit: 6eeb81b), sob a licença MIT. A sabatina mostrada é uma rodada de verdade (detalhes irrelevantes omitidos); as regras citadas do projeto original pertencem ao autor original; nossa análise, demonstração e texto são originais.

Sobre versão: este texto é baseado no 6eeb81b. Nesta versão o Matt separou o grill-with-docs único em dois skills, grilling + domain-modeling, com o grill-with-docs virando a porta de entrada que combina os dois; o comportamento descrito e a sabatina de verdade acima não mudam — só ganharam uma camada a mais de “dá pra usar as metades separadas”.