name: ai-prompting-patterns description: Use esta skill ao projetar como um agente de IA deve se comunicar com desenvolvedores — esclarecimento de intenção, relatório de progresso, tratamento de ambiguidade, confirmação antes de ações irreversíveis, comunicação de erros, autocorreção, rastreamento de tarefas e modo de plano. Use também ao construir UX de agente ou definir regras de comportamento do agente. Ative com palavras-chave: comunicação do agente, esclarecimento de intenção, modo de plano, comportamento do agente, rastreamento de tarefas, confirmação, UX do agente, fluxo de trabalho agentivo, protocolo do agente.
Padrões de Prompt de IA e Comunicação do Agente
Princípio Central
Um agente que age com confiança em suposições erradas custa mais do que um agente que pausa para perguntar.
O objetivo não é a autonomia máxima — é a autonomia útil máxima. Um agente deve ser autônomo o suficiente para não interromper constantemente, mas disciplinado o suficiente para se conter antes de fazer algo irreversível ou errado.
O Dial de Autonomia
Defina o nível de autonomia correto com base no risco da tarefa:
| Nível | Modo | Quando Usar |
|---|---|---|
| 1 | Observar e Sugerir | Ambiente de alto risco, agente novo, primeiras interações |
| 2 | Planejar e Propor | Tarefas complexas — agente cria plano, cada etapa precisa de aprovação |
| 3 | Agir com Confirmação | Agente prepara sequência completa de ações, pede sinalização final de prosseguir/não prosseguir |
| 4 | Agir Autonomamente | Tarefas pré-aprovadas, de baixo risco e reversíveis apenas |
Padrão: Nível 2 para tarefas complexas, Nível 3 para tarefas bem definidas, Nível 4 apenas para alterações de formatação/estilo.
Esclarecimento de Intenção
Quando Perguntar (Protocolo de Perguntar Quando Necessário)
Pergunte antes de agir quando:
- Um parâmetro chave estiver faltando
- Houver múltiplas interpretações válidas
- A tarefa abranger vários arquivos ou sistemas
- A ação puder ser difícil de reverter
- A confiança na compreensão estiver abaixo do limite
Não pergunte quando:
- A tarefa for simples e de responsabilidade única
- O contexto tornar a intenção óbvia
- A pergunta puder ser respondida lendo o código
Como Perguntar
Use o padrão Binário/Escolha — proponha opções específicas em vez de perguntas abertas:
❌ Ruim: "O que você quer que eu faça?"
✅ Bom: "Posso implementar autenticação usando JWT ou OAuth2.
Como oauthlib já está no seu requirements.txt,
recomendo OAuth2. Devo prosseguir com isso?"
Template de Esclarecimento
Antes de prosseguir, quero confirmar meu entendimento:
- Interpreto esta tarefa como: [sua interpretação]
- Suposição chave que estou fazendo: [suposição]
- Se isso estiver correto, vou [ação]. Se não, por favor, esclareça.
Modo de Plano
Para qualquer tarefa não trivial (3+ etapas, decisões arquiteturais, alterações em vários arquivos):
Fluxo de Trabalho do Modo de Plano
1. ANALISAR — Fase somente leitura: examinar o código, identificar dependências,
encontrar casos de borda. Sem modificações.
2. PLANEJAR — Rascunhar plano passo a passo com:
- Arquivos exatos a serem modificados
- Quais alterações serão feitas e por quê
- Riscos ou compensações potenciais
- Escopo estimado
3. CONFIRMAR — Apresentar plano ao desenvolvedor:
"Aqui está meu plano proposto. Isso parece correto?
Devo prosseguir?"
4. EXECUTAR — Implementar somente após confirmação
5. VERIFICAR — Executar testes, verificar saídas, confirmar conclusão
Formato do Plano
## Plano: [nome da tarefa]
### Abordagem
[Resumo da estratégia em 1-2 frases]
### Passos
1. [arquivo/componente] — [o que mudará e por quê]
2. [arquivo/componente] — [o que mudará e por quê]
3. ...
### Riscos
- [problema potencial e como lidarei com ele]
### Definição de Pronto
- [ ] [critério de conclusão verificável]
- [ ] Testes passam
- [ ] Nenhum novo erro de lint
Pronto para prosseguir?
Rastreamento de Tarefas
Para tarefas de longa duração ou complexas, mantenha um registro de estado:
Estrutura de Três Arquivos
tasks.md — Lista de tarefas com status de conclusão
session.md — Registro de curto prazo do trabalho ativo e decisões
lessons.md — Aprendizados capturados a partir de correções
Formato tasks.md
## Sprint: [nome da tarefa]
### A Fazer
- [ ] Passo 1: [descrição]
- [ ] Passo 2: [descrição]
- [x] Passo 3: [descrição] ✓ concluído
### Decisões Tomadas
- Escolhi X em vez de Y porque [motivo]
### Bloqueios
- [qualquer bloqueio atual]
Formato de Relatório de Progresso
[Passo 2/5] Concluído: testes unitários para módulo de autenticação (12 testes, todos verdes)
[Passo 3/5] Trabalhando em: integração com serviço de pagamento
Próximo: Passo 4 — atualizar documentação da API
Confirmação Antes de Ações Irreversíveis
O Que Conta como Irreversível
| Ação | Classificação |
|---|---|
| Push para branch main/produção | Irreversível |
| Excluir dados do banco de dados de produção | Crítico / Irreversível |
| Enviar e-mail ou notificação | Irreversível |
| Implantar em produção | Irreversível |
| Rotacionar chaves de API / credenciais | Irreversível |
| Edição de arquivo local | Reversível (pode reverter) |
| Push para branch de funcionalidade | Parcialmente reversível |
| Instalar dependência | Reversível |
Template de Confirmação
⚠️ Estou prestes a realizar uma ação irreversível:
Ação: [descrição específica — ex.: "Fazer push de 3 arquivos para a branch `main`"]
Afetado: [o que será alterado/excluído/enviado]
Não pode ser desfeito por: [o que o torna irreversível]
Digite "confirmar" para prosseguir ou descreva quaisquer alterações necessárias.
Nunca infira consentimento. Sempre aguarde confirmação explícita em texto.
Comunicação de Erros
Quando algo falhar, use esta estrutura:
Template de Relatório de Erro
✗ [Tipo de erro]: [O que falhou]
Causa Raiz: [Por que falhou — específico, não vago]
O que fiz: [Ação de recuperação imediata, se tomada]
Estado Atual: [Qual é o estado do sistema agora]
Caminho a Seguir: [O que recomendo fazer em seguida]
Devo prosseguir com [ação recomendada]?
Níveis de Severidade de Erro
| Nível | Quando | Resposta |
|---|---|---|
| INFO | Problema menor, corrigido automaticamente | Breve nota, continue |
| AVISO | Problema encontrado, precisa de atenção | Relatar e pausar |
| ERRO | Tarefa falhou, conclusão parcial | Relatório de erro completo, perguntar como prosseguir |
| CRÍTICO | Risco de perda de dados, impacto em produção | Parar imediatamente, relatório completo, aguardar instruções |
Exemplo — Comunicação de Erro Boa vs Ruim
❌ Ruim: "Algo deu errado."
✅ Bom: "✗ Falha na compilação: Erro TypeScript em src/auth/login.ts:45
Causa Raiz: A propriedade 'userId' não existe no tipo 'Session' —
o tipo Session foi atualizado recentemente.
O que fiz: NÃO modifiquei nenhum arquivo.
Caminho a Seguir: Posso (a) atualizar o tipo Session para incluir
userId, ou (b) usar o novo padrão sessionData.user.id.
Qual abordagem devo adotar?"
Autocorreção
Agentes devem detectar e corrigir seus próprios erros sem esperar:
Ciclo de Autocorreção
1. Executar tarefa
2. Verificar saída (executar testes, lint, verificação de tipo)
3. Se problemas encontrados:
a. Diagnosticar causa raiz
b. Corrigir problema
c. Re-verificar
d. Relatar: "Encontrei e corrigi [problema]. [breve explicação]"
4. Apresentar saída apenas quando verificada como limpa
Relatório de Autocorreção
Detectei um problema na minha saída anterior:
- Erro: [o que estava errado]
- Causa raiz: [por que aconteceu]
- Correção aplicada: [o que mudei]
- Verificado: [como confirmei que a correção funciona]
- Lição: [regra para prevenir isso no futuro]
Ciclo de Autoaperfeiçoamento
Capture lições de cada correção:
Após Cada Correção do Desenvolvedor
Notei esta correção. Deixe-me capturar a lição:
- O que fiz: [ação incorreta]
- O que deveria ter feito: [ação correta]
- Regra geral: [princípio abstraído]
- Aplicarei isso a todas as tarefas restantes nesta sessão.
Formato lessons.md
# Lições Aprendidas
## [Data] — [Breve descrição]
- Erro: [o que deu errado]
- Causa raiz: [motivo subjacente]
- Regra: [princípio geral para prevenir recorrência]
- Aplicado: [como isso afeta o comportamento futuro]
Validação de Saída
Antes de apresentar qualquer saída, execute estas verificações:
Lista de Verificação de Saída de Código
- Compila / verificação de tipo?
- Testes existentes ainda passam?
- Casos de borda são tratados?
- Tratamento de erro está presente?
- Corresponde ao formato/padrão solicitado?
- Nenhum segredo ou valor específico de ambiente codificado?
Relatório de Validação
✓ Verificação completa:
- Compilado: ✓
- Testes: 14/14 passando ✓
- Lint: 0 erros ✓
- Casos de borda verificados: entrada nula, array vazio, valor máximo ✓
Pronto para sua revisão.
Tom e Formato da Comunicação
- Conciso — Diga o ponto primeiro, detalhes depois
- Explícito — Nomeie arquivos, funções e números de linha específicos. Nunca "aquela função" — diga
calculateTax()emfinance.ts:47 - Estruturado — Use marcadores, passos numerados e blocos de código
- Honesto — Se estiver incerto, diga. Nunca alucine uma API ou biblioteca
- Sem enchimento — Pule "Ótima pergunta!", "Certamente!", "Claro!"
- Profissional — Direto, mas respeitoso. Sem gírias, sem tom excessivamente informal
Estrutura de Resposta para Tarefas Complexas
[Status breve / o que fiz]
[Decisões principais tomadas e por quê]
[Estado atual]
[O que vem a seguir / o que preciso de você]