Construindo endpoints de API com Claude: Lições práticas de engenharia de prompts de um projeto com mais de 70 endpoints

Engenharia de prompts prática para agentes que executam ações

Um desenvolvedor construindo uma API de automação do LinkedIn com mais de 70 endpoints, execução no lado do servidor e autenticação por extensão do Chrome usou o Claude para escrever aproximadamente 80% do código. O projeto revelou lições específicas sobre como estruturar prompts para agentes que executam ações como chamadas de API, extração de dados e árvores de decisão versus agentes que apenas conversam.

A abordagem de contrato para prompts

O desenvolvedor descobriu que instruções em linguagem natural como "encontre leads relevantes no LinkedIn e envie um pedido de conexão personalizado" levavam a problemas: o Claude alucinava campos, pulava validações e encadeava chamadas de API desnecessárias. O que funcionou foi tratar cada prompt de agente como uma assinatura de função com restrições explícitas:

• ENTRADAS: Exatamente o que o agente recebe (esquema, tipos, casos extremos)
• LIMITES: O que o agente NÃO deve fazer (sem suposições de fallback, sem campos pulados, sem dados inventados)
• CONTRATO DE SAÍDA: Formato exato do que retorna, incluindo estados de erro
• REGRAS DE DECISÃO: Se X então Y, se Z então pare — sem ambiguidade

Lições específicas aprendidas

"Seja criativo" é problemático para agentes de ação: Toda vez que espaço para interpretação era deixado em prompts de execução de ações, o Claude produzia resultados inesperados. Para agentes que executam ações reais, zero criatividade é preferível, reservando a criatividade para tarefas de geração de conteúdo.

Tratamento de erros é essencial: Aproximadamente 40% dos tokens dos prompts foram dedicados a "o que fazer quando as coisas dão errado". Sem isso, o Claude ou tentaria infinitamente ou silenciosamente ignoraria erros e retornaria dados parciais como se tudo estivesse bem.

Compromissos da cadeia de raciocínio: Forçar cada agente a produzir uma etapa de raciocínio antes de agir custa cerca de 15% mais tokens, mas economiza horas de depuração. Quando algo quebra, o desenvolvedor pode ler exatamente por que o agente decidiu fazer o que fez.

Correspondência de padrões sobre prompts de persona: Em vez de usar prompts como "você é um engenheiro sênior", o desenvolvedor cola um exemplo real de boa saída e diz "corresponda exatamente a este padrão". O Claude tem melhor desempenho na correspondência de padrões do que na atuação de papéis.

Estratégia de seleção de modelo: Tarefas simples de extração e formatação são direcionadas para o Sonnet (ou mesmo Haiku), enquanto apenas tomadas de decisão complexas usam o Opus. Essa abordagem reduziu os custos de API de dolorosos para gerenciáveis, pois a maioria das tarefas dos agentes não requer o Opus.