🔍 O que é grilling
Grilling é uma sessão onde o agente pergunta detalhes antes de codificar. Não é você listando requisitos. É o agente, posicionado como entrevistador adversarial, te puxando para zonas que você ainda não pensou: edge cases, decisões que você está adiando, premissas que você nem sabia que estava fazendo.
A maioria das pessoas usa LLM como autocomplete glorificado: dão um prompt vago e aceitam o primeiro código. Resultado: 3 rodadas de retrabalho. Grilling inverte isso. O agente vira o chato que pergunta "e se o usuário não tiver conexão?", "como você quer tratar duplicatas?", "isso é por tenant ou global?" — antes de uma única linha sair.
🎯 O princípio central
Código ruim não vem de modelo fraco. Vem de brief fraco. Grilling força o brief a virar bom antes de gastar tokens em implementação.
- • O agente não assume — ele pergunta.
- • Você não escreve spec — você responde.
- • O alinhamento sai escrito, não na sua cabeça.
💡 Por que a inversão muda tudo
Quando você escreve a spec, você só lista o que já pensou. Quando o agente pergunta, ele explora o espaço de decisões que você ainda não viu. O agente leu mil sistemas parecidos — ele sabe onde mora o bug.
A pergunta do agente é o mapa do que você ainda não sabia que precisava decidir.
Conceitos-chave
⚖️ /grill-me vs /grill-with-docs
Existem dois sabores. Escolher errado não quebra nada — só desperdiça contexto. O /grill-me é leve, conversacional, ótimo para decisões não-código. O /grill-with-docs é pesado, lê seu CONTEXT.md e ADRs, e atualiza-os ao final.
✓ /grill-me
- ✓Decisões de produto sem código pesado
- ✓Brainstorming de feature antes de PRD
- ✓Não-engenharia: copy, posicionamento, fluxo
- ✓Output: bullets de decisão na conversa
- ✓Não toca arquivos do projeto
✓ /grill-with-docs
- ✓Engenharia: feature, refactor, decisão técnica
- ✓Lê CONTEXT.md, ADRs e domain model
- ✓Atualiza CONTEXT.md e cria ADR ao final
- ✓Output: documentos persistentes
- ✓Usa terminologia do projeto, não genérica
Comparação direta
| Aspecto | /grill-me | /grill-with-docs |
|---|---|---|
| Input | Ideia solta | Ideia + projeto indexado |
| Lê arquivos? | Não | Sim — CONTEXT.md, ADRs, código |
| Escreve arquivos? | Não | Sim — atualiza CONTEXT.md, cria ADR |
| Duração típica | 5–10 min | 15–40 min |
| Próximo passo | Documentar manualmente | /to-prd direto |
📊 Regra prática
Se a decisão vai virar código — /grill-with-docs. Se a decisão fica só na sua cabeça — /grill-me. Quando em dúvida, escolha /grill-with-docs: o custo de gerar um ADR a mais é zero, o custo de perder contexto é alto.
Conceitos-chave
🎯 Quando usar (e quando NÃO usar)
Grilling não é grátis — custa 10 a 40 minutos. Para mudanças triviais, esse custo é maior que o retrabalho que evita. Para decisões arquiteturais, é o investimento mais barato que existe.
✓ USAR grilling
- ✓Feature nova — primeiro contato com o problema
- ✓Decisão arquitetural — escolha de banco, fila, padrão
- ✓Bug confuso — você não sabe nem como reproduzir
- ✓Refactor — antes de tocar 20 arquivos
- ✓Integração — terceiro, webhook, contratos
- ✓Migração — schema, framework, versão
✗ PULAR grilling
- ✗Typo / fix trivial — uma linha, escopo claro
- ✗Mudança de copy — texto já aprovado
- ✗Bump de versão — sem breaking changes
- ✗Padrão já documentado — segue o ADR existente
- ✗Bug com causa óbvia — stack trace claro
- ✗Sessão de pair programming — alinhamento humano já feito
⚠️ Cuidado com "parece trivial"
"Só adicionar um campo no formulário" virou refactor de validação, migration de banco e mudança de API em três projetos diferentes. Quando ouvir "é só uma coisinha" e a coisa toca persistência ou contrato — gaste 10 min de grill. Vai descobrir que não é tão "só" assim.
Conceitos-chave
💬 Exemplo de sessão completa
Diálogo realista de /grill-with-docs sobre uma feature comum: "quero adicionar autenticação". Observe como cada pergunta do agente fecha uma decisão que viraria bug se ficasse implícita.
• Modelo: B2B multi-tenant, single DB com tenant_id
• Onboarding: Admin convida por email, sem self-signup
• Auth: Magic link (fase 1), SSO (fase 2). Email único por tenant
• Roles: owner > admin > member; owner exclusivo p/ billing
• Sessão: cookie httpOnly server-side, 7d, revogação global suportada
• Lifecycle: último owner não pode sair; soft delete default
Pronto para /to-prd?
💡 Observação importante
Note como NENHUMA dessas 6 perguntas estava no prompt original "quero adicionar autenticação". Cada resposta fechou uma decisão que viraria reunião de 2h ou bug em produção. Esse é o ROI do grilling.
Conceitos-chave
🚫 Anti-padrões de grilling
Grilling é simples mas tem armadilhas. O sintoma comum: você terminou o grill, mas continua sentindo que vai ter retrabalho. Quase sempre é um dos três anti-padrões abaixo.
✓ Postura saudável
- ✓Refuta o primeiro draft do agente se sentir vago
- ✓Pede para reformular perguntas genéricas
- ✓Trata mudança "pequena" que escala como feature
- ✓Para o grill quando perceber que o problema mudou
- ✓Responde "não sei" quando for verdade — e pesquisa antes de fechar
✗ Anti-padrões
- ✗Aceitar primeiro draft sem grilling — "tá bom assim"
- ✗Engolir perguntas vagas tipo "como você quer fazer isso?"
- ✗Pular grill em mudança "trivial" que toca contrato
- ✗Responder com "depende" para fugir da decisão
- ✗Não revisar o ADR final — assina sem ler
🚨 Pergunta vaga é red flag
Se o agente perguntar "como você quer estruturar isso?" — pare. Essa não é uma pergunta de grill, é o agente jogando a decisão de volta pra você. Força especificidade:
Resposta correta: "Me dá 3 opções com tradeoffs e me pergunte o critério que importa pra eu escolher."
Conceitos-chave
🔗 Integração com PRDs
Grilling não é um evento isolado — é a primeira etapa de um pipeline. As decisões viram contexto, o contexto vira PRD, o PRD vira issues, as issues viram código. Tudo encadeado.
/grill-with-docs
Entrada: ideia solta. Saída: decisões fechadas.
O agente lê CONTEXT.md, faz 5–10 perguntas dirigidas, sintetiza as respostas em decisões nomeadas.
CONTEXT.md atualizado
Decisões viram texto permanente.
As respostas do grill são gravadas em CONTEXT.md (e quando arquiteturais, num ADR numerado em docs/adr/).
/to-prd usa o contexto
PRD nasce alinhado, não da imaginação do LLM.
O comando /to-prd lê CONTEXT.md + ADRs frescos e gera um PRD que cita as decisões. Sem grill, o PRD vira ficção.
/to-issues fatia em vertical slices
PRD vira tarefas executáveis ponta a ponta.
Cada issue é um vertical slice: UI + API + persistência + teste. Não horizontal por camada. Issues herdam terminologia do CONTEXT.md.
Implementação
Código sai com brief forte.
Quando o agente vai codar a issue, ele tem ADR + PRD + issue. O retrabalho cai em 60–80% comparado a partir de prompt vago.
📊 O encadeamento é o produto
Grilling sozinho gera um documento. O pipeline grill → ADR → PRD → issues gera previsibilidade. É a diferença entre "uso IA" e "tenho processo com IA".
Conceitos-chave
🛠️ Exercício prático
Pegue uma feature que você quer construir hoje — não daqui a duas semanas. Rode /grill-with-docs e responda com honestidade. Não trapaceie acelerando o grill.
Quero adicionar [sua feature em uma frase] ao projeto.
Faça grilling antes de eu escrever PRD. Quero perguntas específicas, justificando por que cada uma muda a implementação. Uma pergunta de cada vez. Se eu der resposta vaga, refute e refaça. Ao final, sintetize as decisões e proponha o ADR.
📝 Anote durante o exercício
- •Quantas perguntas o agente fez antes da síntese?
- •Quais 2 perguntas você não tinha pensado e te surpreenderam?
- •Qual decisão mudou de rumo durante o grill? (sinal de grill valioso)
- •Tempo total do grill — compare com a sua estimativa inicial.
- •O ADR final tem alguma decisão que você não lembra de ter tomado? Marque pra revisar.
🎯 Critério de sucesso
O exercício deu certo se ao final você consegue responder, sem olhar:
- • Quais 3 decisões irreversíveis foram tomadas;
- • Quais 2 decisões ficaram explicitamente adiadas;
- • Qual seria o próximo passo (rodar /to-prd? buscar dado externo?).
Conceitos-chave
✅ Resumo do módulo
Próximo módulo:
1.3 — Do PRD às issues: fatiando em vertical slices