Guia de especificação
Um guia prático complementar aos Padrões de Execução. Os Padrões definem as camadas e os primitivos. Este guia mostra como usá-los.
Quando você precisa de uma spec?
Nem toda interação com IA requer uma especificação formal. Use esta árvore de decisão:
Use um prompt quando:
- A tarefa é um único passo com critérios de sucesso óbvios
- Você vai avaliar o output imediatamente
- A falha não custa nada (você pode simplesmente re-promtar)
Use um prompt + arquivo de contexto quando:
- A tarefa requer conhecimento de domínio (terminologia, voz de marca, restrições técnicas)
- Você já fez esse tipo de tarefa antes e a qualidade importa
- O output será usado por outros
Use uma especificação completa quando:
- A tarefa tem múltiplas etapas ou dependências
- Múltiplas pessoas ou agentes vão trabalhar em partes dela
- A falha é custosa (código em produção, output voltado ao cliente, ações irreversíveis)
- Você precisa que outra pessoa verifique o resultado sem fazer perguntas a você
- A tarefa vai se repetir e deve produzir resultados consistentes
O limiar não é a complexidade – é o custo da falha. Uma tarefa simples com alto risco precisa de uma spec. Uma tarefa complexa com risco zero pode começar com um prompt.
Escrever uma spec leva tempo. Mas as pesquisas mostram que vale a pena: enriquecer uma declaração de problema antes de um agente iniciar o trabalho gera uma melhoria de 20% nas taxas de resolução, e os agentes mais fracos obtêm os maiores ganhos. É mais barato melhorar a spec do que melhorar o agente.
As quatro camadas na prática
Os Padrões definem quatro camadas obrigatórias. Essas camadas formam uma progressão cumulativa de maturidade – cada nível constrói sobre o anterior. Veja como cada uma parece quando bem feita.
Camada 1 – Criação de prompts
A base. Você está escrevendo uma instrução clara.
Parece razoável mas tem lacunas:
Escreva uma sequência de 3 e-mails de onboarding para usuários de trial que ainda não ativaram. Faça amigável e útil. Inclua CTAs.
Melhor – específico o suficiente para verificar:
Escreva uma sequência de 3 e-mails de nutrição para usuários de trial que se cadastraram mas não completaram o onboarding em 7 dias. Objetivo: fazê-los completar seu primeiro projeto. Tom: útil, não insistente. Cada e-mail deve ter menos de 100 palavras com um CTA claro. E-mail 1 (dia 3): destaque a forma mais fácil de começar. E-mail 2 (dia 5): compartilhe um template que eles podem personalizar. E-mail 3 (dia 7): ofereça uma chamada de onboarding de 15 minutos. Linhas de assunto devem ser conversacionais, não promocionais.
O primeiro prompt parece completo mas deixa questões críticas em aberto: o que significa "ativado"? Quantos e-mails? Quanto tempo? Para onde aponta o CTA? O agente vai preencher essas lacunas com suposições – e as suposições são onde a qualidade quebra.
A regra dos ≤20% de correção: Se você consistentemente precisa corrigir mais de 20% do output de IA, o problema é o seu prompt, não o modelo. Invista na instrução, não em editar o resultado.
Camada 2 – Engenharia de contexto
Contexto é tudo que o agente precisa saber e que não está no prompt. Andrej Karpathy define engenharia de contexto como "a arte e ciência delicada de preencher a janela de contexto com exatamente a informação certa para o próximo passo."
A pergunta-chave não é "o que poderia ser relevante?" – é "o que o agente precisa ver agora?" Mais contexto não é melhor contexto. Pesquisas mostram que os modelos atingem paredes de desempenho quando sobrecarregados de informação, independentemente do tamanho da janela de contexto.
Cinco critérios de qualidade (Vishnyakova, 2026):
- Relevante – apenas o necessário para a etapa atual. Dados irrelevantes degradam ativamente o output.
- Suficiente – tudo necessário para tomar uma decisão sem adivinhar. Contexto faltando é a causa arquitetônica primária de alucinação.
- Isolado – cada etapa ou sub-agente vê apenas seu próprio contexto. Compartilhar tudo causa falhas compostas (veja Modos de falha de contexto).
- Econômico – tokens mínimos preservando qualidade. A Anthropic enquadra isso como encontrar "o menor conjunto possível de tokens de alto sinal".
- Rastreável – cada parte do contexto atribuível a uma fonte. Quando algo dá errado, você precisa saber qual entrada o causou.
Um arquivo de contexto de equipe não é um despejo de informações. É um conjunto curado de fatos que o agente precisa para tarefas recorrentes. Mantenha-o conciso e focado em gotchas – ele carrega em cada sessão, então cada linha deve ser universalmente aplicável.
# Contexto da Equipe de Customer Success
## Objetivos
- Reter clientes existentes (retenção > aquisição)
- Reduzir tempo de resolução para tickets de suporte
- Identificar oportunidades de expansão em contas existentes
## Restrições
- Nunca compartilhar dados de clientes entre contas
- Nunca prometer funcionalidades que não foram lançadas
- Escalar disputas de faturamento acima de R$2.500 para um gestor
- SLA de tempo de resposta: primeira resposta em até 4 horas
## Terminologia
- "Parceiro" = conta de revendedor (não um cliente regular)
- "White-label" = versão da plataforma com a marca do cliente
- "Link branding" = domínio personalizado para links de rastreamento
## Padrões de qualidade
- Respostas devem abordar a pergunta específica, não FAQ genérico
- Incluir próximos passos em cada resposta
- Se não tiver certeza, diga – não adivinhe
Just-in-time vs antecipado: Não carregue tudo antecipadamente. Use uma estratégia híbrida – sempre carregue o arquivo de contexto da equipe e terminologia; carregue dados específicos (registros de clientes, histórico de tickets, documentação) sob demanda. O agente deve saber onde encontrar informações, não memorizá-las todas.
Para um tratamento mais aprofundado de engenharia de contexto, veja Effective Context Engineering for AI Agents da Anthropic.
Camada 3 – Engenharia de intenção
A intenção responde: "Para o que o agente deve otimizar, e quais trade-offs ele tem permissão de fazer?"
Sem intenção explícita, os agentes otimizam a métrica mais mensurável disponível – que raramente é o que você realmente quer. O caso Klarna ilustra isso: seu agente de IA tratou dois terços das consultas de clientes e economizou $60M, mas o CEO reconheceu publicamente que a qualidade havia sofrido porque o agente otimizou custo por token, não o valor dos relacionamentos com clientes. Como um pesquisador disse: "Contexto sem intenção é ruído."
Intenção para um fluxo de trabalho de suporte:
## Hierarquia de objetivos (em ordem de prioridade)
1. Precisão – nunca fornecer informações incorretas
2. Resolução – resolver o problema real do cliente,
não apenas responder à pergunta dele
3. Tom – seguir a voz da marca (amigável, competente)
4. Eficiência – manter respostas concisas
## Regras de trade-off
- Precisão vs velocidade → escolha precisão
- Tom vs eficiência → mantenha cordialidade, mesmo que mais longo
- Dúvida sobre uma resposta técnica → diga,
não adivinhe
## Condições de escalada
- Cliente menciona ação legal → imediatamente
- Disputa de faturamento acima de R$2.500 → gestor
- Problema técnico afetando múltiplos clientes
→ engenharia
- Mesma pergunta feita três vezes → suporte sênior
## Autoridade de decisão
Pode: rascunhar respostas, consultar detalhes da conta,
citar base de conhecimento
Não deve: prometer reembolsos, compartilhar dados de
outros clientes, comprometer-se com funcionalidades futuras
Intenção para um fluxo de trabalho de engenharia:
## Hierarquia de objetivos (em ordem de prioridade)
1. Correção – o código deve passar em todos os testes existentes
2. Manutenibilidade – legível por um desenvolvedor
desconhecido da codebase
3. Desempenho – atender aos requisitos de SLA
4. Simplicidade – prefira menos linhas a abstração
## Regras de trade-off
- Correção vs velocidade → escolha correção
- Manutenibilidade vs desempenho → favoreça legibilidade
a menos que o SLA esteja em risco
- Quando múltiplas abordagens são válidas → escolha a
com menos acoplamento a outros módulos
## Condições de escalada
- Mudança requer modificar uma API pública → escale
- Impacto no desempenho excede 10% em caminhos críticos
→ escale
- Solução requer migração de banco de dados → escale
## Autoridade de decisão
Pode: refatorar dentro do escopo da tarefa,
adicionar funções auxiliares, atualizar testes relacionados
Não deve: alterar APIs públicas, modificar código não relacionado,
pular cobertura de testes
Camada 4 – Engenharia de especificação
Uma especificação é um conjunto de instruções completo e auto-suficiente para uma tarefa não trivial. Inclui tudo que o agente precisa e nada que não precisa.
Os sete componentes obrigatórios (dos Padrões):
- Declaração do problema – o que precisa acontecer e por quê
- Escopo – o que está incluído e explicitamente o que não está
- Entradas – ao que o agente tem acesso
- Restrições – as categorias Deve / Não Deve / Prefira / Escale
- Critérios de aceitação – como verificar que o output está correto (como é "pronto", objetivamente)
- Condições de falha – o que conta como uma tentativa falha
- Testes de sucesso – cenários específicos que o output deve tratar
Os cinco primitivos com exemplos
Primitivo 1 – Declarações de problema auto-suficientes
O teste: alguém sem contexto sobre seu projeto poderia executar essa tarefa usando apenas o que está escrito?
Parece completo mas não é:
O agendador de jobs está lento para lotes grandes. Corrija o sistema de prioridade para que jobs menores não fiquem presos atrás dos grandes. Use BullMQ.
Auto-suficiente:
O agendador de jobs (src/jobs/queue.ts) processa tarefas sequencialmente. Jobs grandes (50K+ itens) bloqueiam jobs menores na fila – usuários com jobs pequenos esperam 30+ minutos para o processamento começar. A correção deve adicionar agendamento baseado em prioridade: jobs abaixo de 5K itens recebem prioridade maior. A configuração do rate limiter (100 req/s) não deve mudar. O recurso de prioridade BullMQ existente deve ser usado se possível. Se a solução exigir mudar o schema do job, escale antes de implementar.
A primeira versão parece acionável mas esconde perguntas: qual arquivo? O que é "lento" em números? Quais são as restrições? O agente vai fazer suposições sobre tudo isso – e podem estar erradas.
Pesquisas sobre agentes de codificação confirmam isso: fornecer contexto arquitetônico, dependências entre arquivos e dicas de exploração antecipadamente evita que os agentes desperdicem etapas em travessias de repositório sem foco.
Versão de marketing – parece completo mas não é:
Crie uma campanha de e-mail drip para usuários de trial que não converteram. Foque em mostrar o valor do produto. 3 e-mails, tom amigável, com CTAs.
Auto-suficiente:
A conversão trial-to-paid é 12%. O benchmark do setor é 18%. Usuários que completam o onboarding em 72 horas convertem em 31%. Projete uma sequência de 3 e-mails acionada quando um usuário de trial não completou seu primeiro projeto até o dia 3. Objetivo: fazê-los completar o onboarding. Cada e-mail com menos de 100 palavras, um CTA por e-mail, funciona em PT e EN. Sem menções de preço, sem táticas de urgência.
A primeira versão produziria uma campanha drip genérica. A segunda dá ao agente o contexto de negócio (por que isso importa) e as restrições (o que evitar) que produzem um resultado direcionado.
Primitivo 2 – Critérios de aceitação
Escreva três frases que permitam que outra pessoa verifique o output sem fazer perguntas a você.
Parece testável mas não é:
O dashboard deve exibir métricas-chave com precisão e carregar rapidamente em todos os navegadores.
Realmente testável:
O dashboard exibe MRR, taxa de churn e usuários ativos para o período selecionado. O MRR corresponde ao número da equipe de finanças com margem de R$500. A página carrega em menos de 2 segundos numa conexão padrão. Os gráficos renderizam sem erros no Chrome e Firefox.
A primeira versão usa palavras que parecem precisas ("com precisão", "rapidamente", "todos os navegadores") mas que ninguém pode verificar sem perguntas de acompanhamento. A segunda versão define números específicos, métricas específicas e navegadores específicos.
Primitivo 3 – Arquitetura de restrições
Quatro categorias. Preencha todas as quatro para cada tarefa não trivial.
Exemplo: Sistema de resposta automática a tickets de suporte
| Categoria | Regras |
|---|---|
| Deve | Endereçar o cliente pelo nome. Referenciar o problema específico dele. Incluir um próximo passo. |
| Não deve | Nunca compartilhar credenciais ou detalhes internos do sistema. Nunca prometer um tempo específico de resolução. Nunca fechar um ticket automaticamente. |
| Prefira | Linkar para artigos relevantes da base de conhecimento quando existirem. Usar o idioma do cliente com base nas configurações da conta. Manter respostas com menos de 200 palavras. |
| Escale | Cliente menciona cancelamento. Problema envolve perda de dados. Mesmo problema reportado 3+ vezes em 24 horas. Cliente está em um plano enterprise. |
Primitivo 4 – Decomposição
Divida as tarefas em partes independentes com entradas e outputs claros. Alvo: subtarefas que levam ≤2 horas e podem ser verificadas sozinhas.
Parece decomposto mas ainda está acoplado:
- Projete o modelo de dados e construa a API
- Construa o frontend que usa a API
- Escreva testes e implante
Realmente independente:
| Etapa | Entrada | Output | Verificação |
|---|---|---|---|
| 1. Migração de schema | Schema atual + documento de requisitos | Arquivo de migração + arquivo de rollback | Migração roda para frente e para trás sem erros |
| 2. Endpoint de API | Migração + spec da API | Handler de rota com validação | Todos os 5 casos de teste passam, retorna status codes corretos |
| 3. Formulário frontend | Spec da API + mockup de design | Componente React com validação de formulário | Formulário envia com sucesso, erros de validação exibem corretamente |
| 4. Teste de integração | Todos os três acima | Teste de ponta a ponta | Usuário pode completar o fluxo completo no staging |
A primeira versão tem dependências ocultas (etapa 1 agrupa dois conceitos, etapa 2 não pode começar antes que a etapa 1 esteja totalmente pronta, etapa 3 agrupa teste com implantação). A segunda versão tem entradas, outputs e verificação claros em cada etapa. A Anthropic recomenda esse padrão orquestrador-trabalhadores para tarefas com múltiplos componentes.
Primitivo 5 – Design de avaliação
Construa 3-5 casos de teste com outputs conhecidos e bons. Execute-os após cada mudança.
Exemplo: Gerador de linha de assunto de e-mail
| Caso de teste | Entrada | Características esperadas do output |
|---|---|---|
| 1. E-mail de boas-vindas | Novo usuário, cadastrado hoje, nome: Marie | Contém o nome do usuário. Menos de 50 caracteres. Sem palavras de gatilho de spam. |
| 2. Re-engajamento | Usuário inativo há 30 dias | Referencia um período específico ou a última atividade. Cria curiosidade. Sem culpa. |
| 3. Anúncio de funcionalidade | Nova funcionalidade de editor, todos os usuários | Destaca o benefício, não o nome da funcionalidade. Sem jargão técnico. |
| 4. Locale em português | Igual ao #1 mas locale do usuário é PT | Português gramaticalmente correto. Não é uma tradução palavra por palavra. |
| 5. Caso extremo: sem nome | Usuário sem nome no cadastro | Não diz "Olá null" ou "Olá ". Usa uma saudação genérica. |
Você não testa o output exato (a IA é não determinística). Você testa as características do output. Isso é avaliação, não testes unitários. A Anthropic recomenda combinar cada prompt de avaliação com resultados verificáveis e rastrear precisão, tempo de execução e taxas de erro ao longo do tempo.
Modos de falha de contexto
Quando o output de IA dá errado, diagnostique qual falha de contexto o causou antes de repetir. Esses quatro modos de falha são bem documentados na literatura de engenharia de contexto:
Envenenamento
Um erro entra no contexto e se compõe ao longo das conversas. O agente alucionou um nome de função na etapa 2, depois continua chamando essa função inexistente nas etapas 3-5.
Correção: Limpe o contexto entre etapas. Não deixe os outputs de ferramentas de etapas iniciais persistir fundo na conversa. Resuma nos limites em vez de carregar histórico bruto.
Distração
O contexto é tão longo que o agente repete padrões do histórico em vez de raciocinar sobre a etapa atual. Pesquisas observaram essa degradação após exceder 100K tokens.
Correção: Comprima ou resuma o contexto mais antigo. Quando a conversa fica longa, crie uma nova sessão com um resumo das decisões tomadas até agora.
Confusão
Muitas ferramentas ou muita documentação no contexto. O agente escolhe a ferramenta errada ou cita documentação irrelevante porque não consegue distinguir o que é relevante.
Correção: Reduza o que é carregado. Exponha apenas ferramentas e documentos relevantes para a tarefa atual. Como a Anthropic coloca: "Se um humano não consegue definitivamente escolher a ferramenta correta, um agente não pode ter desempenho melhor."
Conflito
Informação contraditória no contexto. O guia de estilo diz "seja conciso" mas o template diz "inclua uma explicação detalhada". Um estudo Microsoft/Salesforce mostrou uma queda de 39% na qualidade quando informações contraditórias estavam presentes.
Correção: Audite seu contexto para contradições. Ao atualizar arquivos de contexto, remova a orientação antiga – não apenas adicione nova orientação ao lado dela. Uma fonte de verdade por tópico.
Escrevendo specs para diferentes funções
Spec de engenharia
## Problema
O agendador de jobs processa tarefas sequencialmente. Jobs grandes
(50K+ itens) bloqueiam jobs menores na fila. Usuários com
jobs pequenos esperam 30+ minutos para o processamento começar.
## Escopo
- Modificar a fila de jobs para suportar agendamento baseado em prioridade
- Jobs pequenos (< 5K itens) recebem prioridade maior
- NÃO alterar os limites de taxa de processamento ou o
pipeline de renderização
## Entradas
- Implementação da fila de jobs: src/jobs/queue.ts
- Modelo de job: src/models/job.ts
- Testes atuais: src/jobs/__tests__/queue.test.ts
## Restrições
- Deve: manter ordem FIFO dentro do mesmo tier de prioridade
- Deve: processar todos os jobs dentro dos limites de taxa existentes
- Não deve: descartar ou reordenar jobs já em andamento
- Não deve: exigir migração de banco de dados
- Prefira: usar o recurso de prioridade BullMQ existente
- Escale: se a solução exigir alterar o schema do job
## Critérios de aceitação
1. Um job de 1K itens enfileirado após um job de 100K começa
a processar em 5 minutos, não 30+
2. Nenhum job fica faminto – todos os jobs completam em 2x
sua duração esperada
3. Testes existentes passam sem modificação
4. Novos testes cobrem ordenação de prioridade e prevenção de fome
## Condições de falha
- Qualquer job processado com entradas incorretas
- Qualquer job processado duas vezes
- Deadlock da fila sob envios concorrentes
## Testes de sucesso
1. Enfileire 3 jobs: 100K, 1K, 500. Verifique que 1K e 500
começam antes do 100K completar.
2. Enfileire 20 jobs pequenos e 1 grande. Verifique que todos completam.
3. Envie jobs concorrentemente de 3 clientes API.
Verifique que não há duplicatas ou jobs perdidos.
Spec de marketing
## Problema
A conversão trial-to-paid é 12%. O benchmark do setor é 18%.
Usuários que completam o onboarding em 72 horas convertem em 31%.
A maioria dos usuários de trial nunca completa o onboarding.
## Escopo
Projete uma sequência de 3 e-mails de onboarding acionada quando um
usuário de trial não completou seu primeiro projeto até o dia 3. Objetivo:
fazê-los completar o onboarding. Isso é apenas o conteúdo do e-mail
– o gatilho de automação já existe.
## Entradas
- E-mail de boas-vindas atual (anexo)
- Top 3 templates por uso (anexo)
- Guia de voz de marca: amigável, competente, nunca corporativo
- Produto: editor visual, biblioteca de templates, gestão de projetos
## Restrições
- Deve: cada e-mail com menos de 100 palavras
- Deve: um CTA claro por e-mail
- Deve: funcionar tanto em PT quanto em EN
- Não deve: mencionar preços ou limitações de planos
- Não deve: usar táticas de urgência ("seu trial está expirando!")
- Prefira: mostre, não conte (link para um template, não uma lista
de funcionalidades)
- Escale: se a sequência precisar de mais de 3 e-mails
## Critérios de aceitação
1. Cada e-mail tem exatamente um CTA linkando para uma ação
específica no produto
2. Tom corresponde ao guia de voz de marca
3. Nenhum e-mail excede 100 palavras
4. Linhas de assunto têm menos de 50 caracteres
5. Uma pessoa externa consegue entender a proposta de valor
sem conhecimento prévio do produto
## Condições de falha
- Qualquer e-mail excede 100 palavras
- CTA linka para uma página genérica em vez de uma ação específica
- Linguagem de urgência aparece ("tempo limitado", "expirando",
"última chance")
- Versão em inglês é uma tradução literal em vez de prosa natural
## Testes de sucesso
1. Leia o e-mail 1 frio. Você consegue identificar o que o produto
faz e qual ação tomar? (sim/não)
2. Leia todos os 3 em sequência. A progressão parece
natural, não repetitiva? (sim/não)
3. Versões em inglês leem naturalmente, não como traduções.
(verificado por falante nativo)
Spec de suporte
## Problema
O tempo médio de resposta do suporte é 6 horas. 40% dos tickets são
perguntas já respondidas na base de conhecimento. Os agentes
gastam tempo procurando respostas que já existem.
## Escopo
Construa um sistema de rascunho de resposta assistido por IA. Quando um ticket
chegar, o sistema pesquisa a base de conhecimento e rascunha
uma resposta para o agente de suporte revisar e enviar.
O agente sempre revisa antes de enviar – sem respostas automáticas.
## Entradas
- Artigos da base de conhecimento (~200 artigos)
- Histórico de tickets (últimos 90 dias, anonimizado)
- Dados da conta do cliente (tipo de plano, tempo de contrato, atividade recente)
- Templates de resposta padrão (32 templates)
## Restrições
- Deve: humano revisa cada resposta antes de enviar
- Deve: citar o artigo da base de conhecimento usado
- Deve: sinalizar quando nenhum artigo relevante existe
(sinal para criar um)
- Não deve: acessar dados de clientes de outras contas
- Não deve: prometer tempos de resolução
- Não deve: fechar tickets automaticamente
- Prefira: usar o idioma do cliente
- Prefira: manter rascunhos com menos de 200 palavras
- Escale: disputas de faturamento acima de R$2.500, menções de
cancelamento, problemas de perda de dados
## Critérios de aceitação
1. Rascunhos são gerados em 30 segundos após a criação do ticket
2. 70%+ dos rascunhos exigem menos de 20% de edição
3. Artigos da base de conhecimento citados são relevantes para a pergunta
4. Agentes podem substituir ou descartar qualquer rascunho com um clique
## Condições de falha
- Resposta enviada sem revisão humana
- Dados do cliente A aparecem na resposta do cliente B
- Rascunho cita um artigo da KB depreciado ou incorreto
- Sistema gera rascunho para um ticket que deveria escalar
## Testes de sucesso
1. "Como configuro domínios personalizados?" → Rascunho referencia
o artigo KB de configuração de domínio com instruções corretas
2. "Fui cobrado duas vezes" → Rascunho sinaliza para escalada,
não tenta resolver o faturamento
3. Pergunta em inglês → Rascunho é em inglês,
referencia passos relevantes de troubleshooting
4. Entrada de lixo → Sistema sinaliza como pouco claro, não
gera rascunho
O loop de melhoria da spec
Uma spec nunca está pronta na primeira tentativa. Use o modelo de responsabilidade por falha:
- Escreva a spec usando os cinco primitivos
- Execute-a – deixe o agente executar
- Avalie o output em relação aos seus critérios de aceitação
- Diagnostique falhas por camada:
| O que deu errado | Qual camada corrigir |
|---|---|
| Output está errado ou de baixa qualidade | Camada 1 – melhore o prompt |
| Output ignora conhecimento de domínio | Camada 2 – melhore o contexto |
| Output otimiza a coisa errada | Camada 3 – esclareça a intenção |
| Output está incompleto ou perde requisitos | Camada 4 – ajuste a spec |
- Corrija uma camada por vez. Nunca mude múltiplas camadas simultaneamente – você não vai saber o que funcionou.
- Atualize a spec com o que aprendeu. As melhores specs são escritas por pessoas que viram agentes falhar.
Essa abordagem iterativa se alinha com a recomendação da Anthropic de "começar minimal com o melhor modelo, depois adicionar instruções iterativamente baseadas em modos de falha observados."
Erros comuns
Sobre-especificar. Uma spec que descreve cada detalhe de implementação é apenas pseudocódigo. Especifique o quê e as restrições, não o como. Deixe o agente escolher a abordagem dentro dos seus limites.
Sub-especificar. "Melhore" não é uma spec. Se você não consegue descrever o pronto, não está pronto para delegar.
Despejo de contexto. Carregar todo documento que você tem no contexto "por precaução". Informação irrelevante degrada ativamente o output. O princípio central da Anthropic: encontre o menor conjunto de tokens de alto sinal, não o máximo de tokens.
Otimizar prompts quando o problema é de contexto. Se o agente continua produzindo output irrelevante, adicionar "seja mais relevante" ao prompt não vai ajudar. O agente precisa de informações diferentes, não de melhores instruções. Use o modelo de responsabilidade por falha para diagnosticar a camada certa.
Pular o design de avaliação. Sem casos de teste, você está dependendo de feeling para julgar a qualidade do output. Construa os casos de teste primeiro – eles forçam você a esclarecer o que realmente quer.
Repetir em vez de diagnosticar. Quando o output falha, o instinto é regenerar. Pare. Descubra qual camada causou a falha. Corrija essa camada. Então tente novamente.
Referência rápida
Antes de delegar, confirme:
- Consigo descrever o problema sem referenciar coisas que o agente não sabe
- Consigo escrever três frases que verificam o sucesso
- Listei o que deve acontecer, o que não deve acontecer e quando parar e perguntar
- Dividi a tarefa em partes pequenas o suficiente para verificar independentemente
- Tenho casos de teste com características conhecidas e boas
Quando o output falha, diagnostique:
| Sintoma | Causa provável | Ação |
|---|---|---|
| Output está errado | Prompt | Melhore as instruções, adicione exemplos |
| Output ignora seu domínio | Contexto | Adicione ou atualize o arquivo de contexto |
| Output otimiza a coisa errada | Intenção | Defina hierarquia de objetivos e trade-offs |
| Output está incompleto | Especificação | Adicione requisitos faltando, ajuste o escopo |
Leituras complementares
- Building Effective Agents – Guia da Anthropic sobre padrões de arquitetura de agentes
- Effective Context Engineering for AI Agents – Gerenciando o estado completo de tokens em loops de agentes
- Writing Tools for Agents – Princípios de design de ferramentas e metodologia de avaliação
- Context Engineering for Agents – Framework de quatro operações da LangChain (Escrever, Selecionar, Comprimir, Isolar)
- A Survey of Context Engineering for LLMs – Survey acadêmico estabelecendo uma taxonomia formal
- CodeScout: Contextual Problem Statement Enhancement – Pesquisa mostrando melhoria de 20% com especificações melhores antecipadamente
← Voltar para o início · Padrões de Execução · O framework de referência · Glossário