Grill Me – Compreensão Compartilhada Através de Interrogação Sistemática
Filosofia
O objetivo da 'grillagem' é construir compreensão compartilhada entre o agente e o usuário. Todo plano contém suposições implícitas, restrições não declaradas e decisões ambíguas. A grillagem percorre cada ramo da árvore de decisão, um por um, até que ambas as partes estejam totalmente alinhadas.
O objetivo é zero suposições não examinadas antes do início da implementação.
Diretrizes Primordiais
- Use AskUserQuestion para cada pergunta. Todas as perguntas de interrogação devem passar pela ferramenta
AskUserQuestion. Nunca emita uma pergunta como texto simples. - Agrupe dentro de domínios. Agrupe até 4 perguntas relacionadas dentro do mesmo domínio de interrogação em uma única chamada
AskUserQuestion. Nunca misture perguntas de domínios diferentes em uma única chamada. - Lide com sua recomendação. Sua resposta recomendada é sempre a primeira opção, com
(Recommended)anexado ao rótulo. - Explore antes de perguntar. Se uma pergunta puder ser respondida lendo o código, lendo a documentação ou verificando padrões existentes — faça isso em vez de perguntar. Pergunte ao usuário apenas sobre decisões que exigem seu julgamento.
- Resolva dependências em ordem. Algumas decisões dependem de outras. Identifique a cadeia de dependências e resolva as decisões a montante primeiro.
- Registre tudo com registros estruturados. Mantenha um registro de decisões como uma tabela estruturada. Para cada pergunta resolvida, registre: domínio, tópico (cabeçalho), rótulo da opção selecionada e qualquer texto personalizado se 'Outro' foi escolhido. Apresente o registro no contexto da conversa — sem I/O de arquivo.
- Nenhuma suposição sobrevive. Se algo está implícito mas não declarado, traga à tona. Se algo parece óbvio, confirme. Compreensão compartilhada significa acordo explícito, não silêncio confortável.
- Mantenha-se concreto. Enquadre as perguntas em torno de comportamentos específicos, fluxos de dados e resultados visíveis ao usuário — não conceitos abstratos.
Configuração Pré-Interrogação
Antes de fazer qualquer pergunta, construa contexto silenciosamente:
- Leia o plano ou documento de design que o usuário deseja que seja grilled
- Explore o repositório em busca de padrões existentes, restrições e código relevante
- Verifique o histórico recente do git para contexto sobre o trabalho atual
- Leia project.md e CLAUDE.md para convenções do projeto
Em seguida, apresente um breve resumo do que você entende até agora, organizado pelos domínios de interrogação. Isso dá ao usuário a chance de corrigir grandes mal-entendidos antes de mergulhar na sondagem ramo a ramo.
Domínios de Interrogação
Trabalhe através dos domínios definidos em references/interrogation-domains.md. Adapte a ordem ao plano — comece com o domínio mais central ao que está sendo construído e vá para fora. Pule domínios que são claramente irrelevantes.
Processo de Interrogação
1. Leia e resuma seu entendimento do plano
2. O usuário confirma ou corrige o resumo
3. Para cada domínio de interrogação (ordenado por relevância):
a. Identifique todos os pontos de decisão e suposições neste domínio
b. Agrupe pontos de decisão relacionados em lotes de até 4 perguntas
c. Para cada lote, invoque uma única chamada AskUserQuestion
(recomendação primeiro para cada pergunta). Registre todas as opções selecionadas.
d. Após resolver todos os pontos em um domínio, resuma as decisões tomadas
Apresente as decisões do domínio como linhas no formato de tabela estruturada.
4. Após todos os domínios serem cobertos:
- Apresente o registro completo de decisões como uma tabela estruturada:
| # | Domínio | Tópico | Decisão | Notas |
|---|---------|--------|---------|-------|
| 1 | Intenção | Meta | Outro | Dashboard interno para equipe de operações, não voltado para clientes |
- Sinalize quaisquer itens não resolvidos ou adiados
- Pergunte se algum domínio precisa ser revisitado
Formato da Pergunta
Toda pergunta DEVE ser feita através da ferramenta AskUserQuestion. Estruture cada chamada da seguinte forma:
{
"question": "Quando a API do Oura retorna um 429, como devemos lidar com a limitação de taxa?",
"header": "Limites",
"options": [
{
"label": "Backoff exponencial (Recommended)",
"description": "Repetir com backoff exponencial (1s, 2s, 4s). Lida com limites transitórios graciosamente e corresponde ao padrão de repetição já usado em src/api_client.py."
},
{
"label": "Enfileirar para próxima execução",
"description": "Pular a solicitação e adicioná-la à próxima execução programada. Mais simples, mas atrasa os dados em um ciclo."
}
],
"multiSelect": false
}
Depende de: Indique quaisquer decisões anteriores nas quais esta se baseia no texto da pergunta, ou anote "Sem dependências" se for independente.
Exemplo de perguntas em lote
{
"questions": [
{
"question": "Qual é o alvo principal de implantação?",
"header": "Implantação",
"options": [
{
"label": "Docker + ECS (Recommended)",
"description": "Corresponde à infraestrutura existente. O pipeline de implantação já existe."
},
{
"label": "Kubernetes",
"description": "Mais flexível, mas requer nova configuração de infraestrutura."
},
{
"label": "Serverless",
"description": "Menor carga operacional, mas preocupações com latência de inicialização a frio."
}
],
"multiSelect": false
},
{
"question": "Quais abordagens de monitoramento devemos incluir?",
"header": "Monitoramento",
"options": [
{
"label": "Registro estruturado (Recommended)",
"description": "Logs JSON no CloudWatch. Pesquisáveis e alertáveis."
},
{
"label": "Rastreamento APM",
"description": "Rastreamento distribuído para visibilidade do fluxo de solicitações."
},
{
"label": "Métricas personalizadas",
"description": "Contadores e medidores específicos de negócio no Datadog."
}
],
"multiSelect": true
}
]
}
Usando pré-visualizações
Use o campo preview nas opções quando o usuário precisar comparar visualmente artefatos concretos — trechos de código, diagramas de arquitetura, formatos de esquema ou exemplos de configuração. O conteúdo da pré-visualização é renderizado como markdown em uma caixa monoespaçada com comparação lado a lado.
Quando usar pré-visualizações:
- Comparar dois padrões de código ou implementações
- Mostrar diferentes formatos de esquema ou estruturas de dados
- Apresentar alternativas de arquitetura com diagramas ASCII
Restrição: Pré-visualizações são apenas de seleção única (multiSelect: false). Se precisar de seleção múltipla, omita pré-visualizações e use descrições.
Exemplo com pré-visualizações:
{
"question": "Qual padrão devemos usar para o pipeline de dados?",
"header": "Pipeline",
"options": [
{
"label": "Pipeline gerador (Recommended)",
"description": "Avaliação preguiçosa, eficiente em memória para grandes conjuntos de dados.",
"preview": "def pipeline(source):\n for record in source:\n cleaned = clean(record)\n validated = validate(cleaned)\n yield validated"
},
{
"label": "Pipeline em lote",
"description": "Processa todos os registros de uma vez. Mais simples, mas maior uso de memória.",
"preview": "def pipeline(source):\n records = list(source)\n cleaned = [clean(r) for r in records]\n validated = [validate(r) for r in cleaned]\n return validated"
}
],
"multiSelect": false
}
Regras para Fazer Perguntas
- Use AskUserQuestion para cada pergunta. Ponto final.
- Primeira opção = recomendação. A primeira opção sempre tem
(Recommended)no rótulo. - Agrupe perguntas relacionadas. Agrupe até 4 perguntas relacionadas do mesmo domínio em uma chamada AskUserQuestion. Perguntas de domínios diferentes devem ser chamadas separadas.
- Respeite as restrições da ferramenta. 2-4 opções por pergunta. Cabeçalhos com no máximo 12 caracteres. Use
multiSelect: truequando as opções não são mutuamente exclusivas (por exemplo, 'Quais abordagens de teste devemos usar?' ou 'Quais domínios precisam de cobertura?'). - Filtre opções. Quando houver mais de 4 escolhas válidas, apresente as 3 mais relevantes com base no contexto do repositório. Os usuários selecionam "Outro" para qualquer coisa não listada.
- Seja específico. "Como devemos lidar com erros?" é muito vago. "Quando a API do Oura retorna um 429, devemos repetir com backoff ou enfileirar para a próxima execução?" é específico.
- Mostre seu trabalho. Se sua recomendação for baseada em algo que você encontrou no repositório, faça referência ao arquivo e linha.
- Aceite a resposta. Quando o usuário decidir, registre e siga em frente. Não reabra discussão a menos que uma decisão posterior crie conflito com uma anterior.
Fallback (sem AskUserQuestion disponível)
Se AskUserQuestion não estiver disponível no ambiente de execução, recorra a este formato de texto:
[Cabeçalho] — [Tópico]
[Declaração clara da pergunta]
Recomendado: [Sua recomendação e porquê]
Alternativas:
- (A) [Opção] — [Troca]
- (B) [Opção] — [Troca]
Quando Parar
A grillagem está completa quando:
- Cada domínio de interrogação relevante foi coberto
- Todos os ramos de decisão foram resolvidos ou explicitamente adiados
- O usuário confirma compreensão compartilhada