Construindo Aplicações com LLM e Claude
Esta skill ajuda você a construir aplicações com LLM usando Claude. Escolha a superfície certa com base nas suas necessidades, detecte a linguagem do projeto e leia a documentação específica da linguagem relevante.
Antes de Começar
Verifique o arquivo alvo (ou, se não houver arquivo alvo, o prompt e o projeto) em busca de marcadores de provedores não-Anthropic - import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, nomes de arquivo como agent-openai.py ou *-generic.py, ou qualquer instrução explícita para manter o código neutro em relação ao provedor. Se encontrar algum, pare e informe ao usuário que esta skill produz código para o SDK Claude/Anthropic; pergunte se ele deseja migrar o arquivo para Claude ou prefere uma implementação não-Claude. Não edite um arquivo não-Anthropic com chamadas do SDK Anthropic. (Exceção: o subcomando prompt-audit é não interativo e não para aqui - ele registra marcadores de provedores não-Anthropic em seu relatório nas suposições declaradas e nunca propõe a troca de um arquivo não-Anthropic para o SDK Anthropic.)
Requisito de Saída
Quando o usuário pedir para adicionar, modificar ou implementar um recurso do Claude, seu código deve chamar o Claude através de uma das seguintes opções:
- O SDK oficial da Anthropic para a linguagem do projeto (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Este é o padrão sempre que existir um SDK suportado para o projeto. - HTTP puro (
curl,requests,fetch,httpx, etc.) - apenas quando o usuário explicitamente pedir cURL/REST/HTTP puro, o projeto for um projeto shell/cURL, ou a linguagem não possuir SDK oficial.
Nunca misture os dois - não recorra a requests/fetch em um projeto Python ou TypeScript só porque parece mais leve. Nunca recorra a shims compatíveis com OpenAI.
Nunca adivinhe o uso do SDK. Nomes de funções, nomes de classes, namespaces, assinaturas de métodos e caminhos de importação devem vir de documentação explícita - seja dos arquivos {lang}/ nesta skill ou dos repositórios oficiais do SDK ou links de documentação listados em shared/live-sources.md. Se a ligação que você precisa não estiver explicitamente documentada nos arquivos da skill, use WebFetch no repositório relevante do SDK em shared/live-sources.md antes de escrever código. Não infira APIs de Ruby/Java/Go/PHP/C# a partir de formatos cURL ou de SDKs de outras linguagens.
Se o WebFetch ou acesso ao repositório falhar (rede restrita, timeouts, clone bloqueado): não continue tentando - escreva código a partir dos padrões e tabelas de namespace/pacote no arquivo {lang}/, execute o compilador ou interpretador e itere sobre a saída de erro. Para SDKs de tipagem estática (C#, Java, Go), um ciclo de compilar-corrigir contra erros locais leva a código funcional mais rápido do que pesquisa de rede bloqueada.
Padrões
A menos que o usuário solicite o contrário:
Para a versão do modelo Claude, use Claude Opus 5.5, que pode ser acessado através da string exata do modelo claude-opus-5-5. Use por padrão o pensamento adaptativo (thinking: {type: "adaptive"}) para qualquer coisa remotamente complicada. E, finalmente, use streaming por padrão para qualquer requisição que possa envolver entrada longa, saída longa ou alto max_tokens - isso evita timeouts de requisição. Use o helper .get_final_message() / .finalMessage() do SDK para obter a resposta completa se você não precisar manipular eventos individuais de stream. Quando uma requisição de streaming define ferramentas definidas pelo usuário (cliente), defina eager_input_streaming: true em cada uma dessas ferramentas para que entradas grandes de ferramentas (conteúdos de arquivo, código, documentos) sejam transmitidas à medida que são geradas, em vez de chegarem em uma rajada após o servidor terminar de armazená-las em buffer; o cliente então é dono da validação: os parsers tolerantes dos SDKs podem retornar uma entrada silenciosamente truncada em vez de levantar exceção, então valide cada entrada de ferramenta analisada contra seu esquema antes de executá-la (os helpers de runner tipados como betaZodTool / @beta_tool tipado fazem isso; ferramentas betaTool() com esquema JSON e loops manuais devem se validar), trate uma falha como JSON inválido (erro INVALID_JSON tool_result quando você segura o bloco, reemita caso contrário), verifique as razões de parada max_tokens / refusal antes de executar ferramentas, e capture apenas o erro JSON do SDK, nunca seus erros de API tipados - padrão em shared/tool-use-concepts.md -> Eager input streaming. Deixe desligado para requisições não-streaming, para ferramentas de servidor e quando a requisição passar por um proxy ou uma implantação de modelo Bedrock mais antiga que rejeita o campo.
Aviso: Desvio de API - Seu Conhecimento de Treinamento Pode Estar Desatualizado
Várias formas comuns da API Claude mudaram em 2025-2026. Se você lembrar de um padrão do treinamento, verifique-o nos arquivos {lang}/ desta skill antes de escrever - as linhas abaixo são os pontos de desvio mais frequentes:
| Área | Conhecimento desatualizado | API Atual |
|---|---|---|
| Pensamento estendido | thinking: {type: "enabled", budget_tokens: N} | Em modelos Claude 4.6+: thinking: {type: "adaptive"}. budget_tokens está depreciado no Opus 4.6 / Sonnet 4.6 e rejeitado com 400 no Fable 5/5.1 / Sonnet 5.5 / Sonnet 5 / Opus 5.5 / 5 / 4.8 / 4.7. Modelos anteriores a 4.6 ainda usam budget_tokens. |
| Tipo de ferramenta de busca web / fetch web | web_search_20250305, web_fetch_20250910 | web_search_20260209, web_fetch_20260209 (filtragem dinâmica) no Opus 5.5/5/4.8/4.7/4.6, Sonnet 5.5, Sonnet 5 e Sonnet 4.6. Modelos mais antigos mantêm as variantes básicas; no Vertex AI apenas a básica web_search_20250305 está disponível (web fetch não está no Vertex) - veja a tabela de Ferramentas de Servidor abaixo. |
| Nomes de parâmetros PHP | snake_case nomes wire como argumentos nomeados (max_tokens) | Argumentos nomeados de nível superior são camelCase (maxTokens). Chaves de array aninhadas variam por recurso (ex.: 'taskBudget', 'skillID', 'mcp_server_name') - copie a chave exata do exemplo documentado; não faça conversão em massa. |
| Credenciais de Agentes Gerenciados | Mantenha segredos no lado do host via ferramentas personalizadas (a única opção antes dos vaults serem lançados) | Credenciais Vault environment_variable - armazenadas pela Anthropic, substituídas na saída, nunca visíveis no sandbox (shared/managed-agents-tools.md -> Vaults). Ferramentas personalizadas no lado do host permanecem como fallback para sandboxes auto-hospedados. |
| API de Arquivos / Skills | client.beta.files.* / client.beta.skills.* com cabeçalho beta files-api-2025-04-14 / skills-2025-10-02 | Fora do beta: client.files.* / client.skills.*, sem cabeçalho beta. Nos SDKs atuais, client.beta.files / client.beta.skills têm mudanças de forma que quebram compatibilidade com versões anteriores, correspondendo aos namespaces estáveis - migre conforme shared/live-sources.md -> API de Arquivos / Guia de Skills. |
Os arquivos {lang}/ nesta skill são autoritativos sobre padrões lembrados.
Subcomandos
Se a Solicitação do Usuário no final deste prompt for uma string de subcomando simples (sem prosa), pesquise cada tabela de Subcomandos neste documento - incluindo qualquer uma em seções anexadas abaixo - e siga a coluna Ação correspondente diretamente. Isso permite que os usuários invoquem fluxos específicos via /claude-api <subcomando>. Se nenhuma tabela no documento corresponder, trate a solicitação como prosa normal.
| Subcomando | Ação |
|---|---|
migrate | Migrar código existente da API Claude para um modelo mais novo. Leia shared/model-migration.md imediatamente e siga em ordem: Etapa 0 (confirmar escopo - perguntar quais arquivos/diretórios antes de qualquer edição), Etapa 1 (classificar cada arquivo), então a seção de mudanças que quebram compatibilidade por destino. Não resuma o guia - execute-o. Se o usuário não nomeou um modelo alvo, pergunte para qual modelo migrar na mesma rodada que a pergunta de escopo. Após as alterações por destino serem aplicadas, audite o texto do prompt no escopo, descrições de ferramentas e código de requisição contra shared/prompt-audit.md - a promptagem escrita para o modelo de origem faz parte de cada migração, e ela não se anuncia. |
prompt-audit | Auditar prompts existentes, descrições de ferramentas, skills e arquivos de configuração de agente (CLAUDE.md, arquivos de regras, comandos, subagentes) em busca de padrões datados ("cruft"): texto escrito para modelos mais antigos, e instruções que o repositório superou ou que se contradizem. Leia shared/prompt-audit.md imediatamente e siga em ordem: Etapa 0 (estabelecer escopo e modelo alvo a partir da solicitação e do repositório - declare as suposições no relatório, não pare para perguntar), inventário, proveniência, então a varredura de padrões. Produza ambos os entregáveis na íntegra - o relatório de auditoria (descobertas com arquivo:linha, padrão, por que está obsoleto, confiança) e um diff proposto - sem pausar para confirmação; aplique edições apenas se a solicitação explicitamente as pediu. Não resuma o guia - execute-o. |
upgrade | Atualizar a dependência do SDK Anthropic do projeto em uma versão principal - atualmente o SDK Python, anthropic 0.x -> 1.x. Palavras subsequentes podem nomear a linguagem e/ou um escopo (upgrade python, upgrade python sdk src/). Leia python/claude-api/sdk-upgrade.md imediatamente e siga em ordem: Etapa 0 (confirmar escopo, então estabelecer as versões atual e alvo - um 1.x publicado deve existir antes de você escrever um pin), o inventário da Etapa 1, cada seção numerada, então verificação e o relatório. Não resuma o guia - execute-o. Se a linguagem detectada ou nomeada não tiver sdk-upgrade.md nesta skill, diga que nenhum guia de atualização de versão principal está incluído para esse SDK ainda e aponte o usuário para o CHANGELOG desse SDK (repositórios em shared/live-sources.md); não improvise um a partir do guia Python. Isso não é migração de modelo - para mover código para um modelo Claude mais novo, use migrate. |
cost-optimize | Reduzir o custo de execução de código existente da API Claude, sem sacrificar a qualidade da saída. Leia shared/cost-optimization.md imediatamente e siga em ordem: Etapa 0 (estabelecer escopo, nível de qualidade e linha de base), o perfil de tokens - medido através da API de Uso e Custo Admin quando o usuário tem uma chave de API Admin, a partir dos logs próprios response.usage do aplicativo quando ele os tiver (pergunte), ou estimado a partir do código caso contrário - então uma lista de prioridades de alavancas classificadas por economia (cotadas em dólares, % da conta ou baldes relativos dependendo de qual dessas fontes de dados você tem), vitórias gratuitas (cache, higiene de tokens de entrada, higiene de loops, higiene de tokens de saída, lote) antes de trade-offs (orçamentos, esforço, escolha de modelo, multi-modelo); qualquer alavanca que ganhe um lugar se torna seu próprio diff - proposto por padrão, aplicado e medido contra a avaliação cobrindo o tráfego que toca quando o usuário pede e aprova - e "nenhuma alteração recomendada" é um resultado válido. Duas regras permanentes: cada execução que exercita o modelo gasta dinheiro real, então obtenha a aprovação do usuário primeiro; e quando o contexto para uma alavanca estiver faltando, trabalhe interativamente com o usuário - este fluxo de trabalho não deve fazer a auditoria de uma vez. Não resuma o guia - execute-o; apresentar o perfil e o plano classificado ao usuário faz parte da execução. |
build-eval | Ajudar o usuário a construir um conjunto de avaliação para seu aplicativo com Claude. Leia shared/evals/build-eval.md imediatamente e execute sua entrevista: Etapa 0 (o que está sendo avaliado), Etapa 1 (origem dos prompts - avaliação existente / transcrições / sintetizado), Etapa 2 (método de avaliação), Etapa 3 (script executável + custo medido). Obtenha a aprovação explícita do usuário sobre as entradas, o método de avaliação e o custo antes de produzir a avaliação. |
preserved-thinking-migration | Tornar uma integração existente compatível com o pensamento preservado - a verificação que mantém um bloco de pensamento válido apenas na conversa que o produziu. Leia shared/preserved-thinking-migration.md imediatamente e siga em ordem: Etapa 0 (escopo, classes de tráfego, plataforma e modelo, status de aplicação, nível de qualidade, linha de base), Etapa 0.5 (provar que a verificação está rodando com o autoteste de três requisições), Etapa 1 (capturar corpos de requisição, diferenciar pares consecutivos com shared/preserved-thinking-migration/prefix_diff.py, escanear o código em busca das causas, nomear cada edição e se é deliberada), Etapa 2 (reproduzir uma fatia de teste com prefix_mismatch_behavior: "drop_block" sob o cabeçalho thinking-binding-controls-2026-08-01, contar novos blocos descartados por conversa, ler o cabeçalho de diagnóstico quando presente), Etapa 3 (uma causa por diff em ordem de raciocínio perdido - proposto por padrão, aplicado quando o usuário pedir - então remedir, manter ou reverter; o protocolo de três braços quando uma avaliação existe), a seção de troca de modelo (em shared/preserved-thinking-migration/causes.md, com a tabela de causas e a lista de manter) quando o harness roteia entre modelos, Etapa 4 (o perfil de quebras e as mudanças). Duas regras permanentes: cada reprodução gasta dinheiro real, então obtenha a aprovação do usuário para o orçamento de medição primeiro; e "nenhuma alteração recomendada" - a fatia reproduziu pensamento e nada foi descartado - é um resultado válido. Causas que têm uma forma somente de anexação apenas sob um beta mais novo (keep-tail e compactação em segundo plano: compact-2026-09-04; mudanças de ferramenta de mesmo nome: inline-tools-2026-09-15) são, onde esse beta não está disponível, medidas e decididas, não reescritas. Para o porquê (a verificação de três etapas, a tabela de edição somente de anexação) ele encadeia para shared/model-migration.md -> Mudança que quebra compatibilidade 3; não resuma o guia - execute-o. |
hillclimb | Melhorar iterativamente o aplicativo do usuário contra uma avaliação existente. Leia shared/evals/eval-hillclimb.md imediatamente e siga: Etapa 0 (confirmar que uma avaliação executável existe - se não, redirecione para build-eval), Etapa 1 (o que mudar / o que é proibido), Etapa 2 (orçamento + condição de parada a partir do custo medido por execução), obtenha o plano aprovado, então o loop de ler->propor->aplicar->executar->registrar com estado em disco e uma divisão treino/validação/teste. |
Detecção de Linguagem
Antes de ler exemplos de código, determine em qual linguagem o usuário está trabalhando (exceção: para o subcomando prompt-audit, pule as etapas de pergunta desta seção - a auditoria é não interativa e seu inventário é independente de linguagem; quando nenhuma linguagem for inferível, prossiga sem perguntar e declare a suposição no relatório):
- Olhe os arquivos do projeto para inferir a linguagem:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile-> Python - leia depython/*.ts,*.tsx, `packag
...
[truncado para tradução]