Construindo Aplicações com LLM Usando Claude
Esta habilidade ajuda você a construir aplicações baseadas em LLM com o Claude. Escolha a superfície certa com base em suas necessidades, detecte a linguagem do projeto e leia a documentação específica da linguagem.
Antes de Começar
Examine o arquivo alvo (ou, se não houver arquivo alvo, o prompt e o projeto) em busca de marcadores de provedor 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 habilidade gera código do SDK Claude/Anthropic; pergunte se ele deseja migrar o arquivo para Claude ou se prefere uma implementação que não use 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 provedor não-Anthropic em seu relatório e nunca propõe migrar um arquivo não-Anthropic para o SDK Anthropic.)
Requisito de Saída
Quando o usuário solicitar que você adicione, modifique ou implemente um recurso do Claude, seu código deve chamar Claude através de uma das seguintes formas:
- O SDK oficial da Anthropic para a linguagem do projeto (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Esta é a opção padrão sempre que existir um SDK compatível para o projeto. - HTTP puro (
curl,requests,fetch,httpx, etc.) — apenas quando o usuário solicitar explicitamente 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 use requests/fetch em um projeto Python ou TypeScript apenas por parecer 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}/ desta habilidade ou dos repositórios oficiais do SDK ou links de documentação listados em shared/live-sources.md. Se a vinculação necessária não estiver documentada explicitamente nos arquivos da habilidade, use WebFetch para buscar o repositório do SDK relevante em shared/live-sources.md antes de escrever código. Não deduza APIs de Ruby/Java/Go/PHP/C# a partir de formatos cURL ou de SDKs de outras linguagens.
Se o WebFetch ou o acesso ao repositório falhar (restrições de rede, timeouts, clone bloqueado): não fique tentando novamente — escreva o código com base nos padrões e nas tabelas de namespace/package do arquivo {lang}/, execute o compilador ou interpretador no código e itere com base na saída de erro. Para SDKs com tipo estático (C#, Java, Go), um ciclo de compilação-correção contra erros locais chega ao código funcional mais rápido do que uma pesquisa bloqueada pela rede.
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 de modelo exata claude-opus-5-5. Por padrão, use pensamento adaptativo (thinking: {type: "adaptive"}) para qualquer coisa remotamente complicada. E, por fim, ative o streaming por padrão para qualquer requisição que possa envolver entrada longa, saída longa ou max_tokens alto — 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 tratar eventos individuais do stream. Quando uma requisição em streaming definir ferramentas definidas pelo usuário (cliente), defina eager_input_streaming: true em cada uma dessas ferramentas para que entradas grandes (conteúdo de arquivos, 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 é responsável pela validação: os parsers tolerantes dos SDKs podem retornar uma entrada silenciosamente truncada em vez de gerar um erro, portanto valide cada entrada de ferramenta parseada contra seu esquema antes de executá-la (os helpers de runners tipados, como betaZodTool / @beta_tool tipado, fazem isso; ferramentas betaTool() baseadas em JSON Schema e loops manuais devem se validar), trate uma falha como JSON inválido (erro INVALID_JSON tool_result quando você mantém 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-o desligado para requisições sem streaming, para ferramentas de servidor e quando a requisição passar por um proxy ou por uma implantação de modelo Bedrock mais antiga que rejeite o campo.
Aviso: Deriva de API — Seu Conhecimento de Treinamento Pode Estar Desatualizado
Várias formas comuns da API Claude mudaram entre 2025 e 2026. Se você se lembrar de um padrão do treinamento, verifique-o nos arquivos {lang}/ desta habilidade antes de escrever código — as linhas abaixo são os pontos de deriva 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á obsoleto 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 pré-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 web_search_20250305 básico está disponível (web fetch não está no Vertex) — veja a Referência Rápida de Ferramentas de Servidor abaixo. |
| Nomes de parâmetros em PHP | Nomes wire snake_case como argumentos nomeados (max_tokens) | Argumentos nomeados de nível superior são camelCase (maxTokens). As chaves de arrays aninhados 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 Managed Agents | Manter segredos no lado do host via ferramentas personalizadas (a única opção antes do lançamento dos vaults) | 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 continuam sendo a alternativa para sandboxes auto-hospedados. |
| Files API / Skills | client.beta.files.* / client.beta.skills.* com cabeçalhos 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 -> Files API / Skills Guide. |
Os arquivos {lang}/ desta habilidade são autoritativos em relação a padrões lembrados.
Subcomandos
Se a Solicitação do Usuário no final deste prompt for uma string de subcomando simples (sem prosa), pesquise em todas as tabelas de Subcomandos neste documento — incluindo 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-o em ordem: Etapa 0 (confirme o escopo — pergunte quais arquivos/diretórios antes de qualquer edição), Etapa 1 (classifique cada arquivo), depois 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 de destino, pergunte para qual modelo migrar na mesma rodada da pergunta de escopo. Após as alterações por destino serem aplicadas, audite o texto do prompt, as descrições das ferramentas e o código de requisição dentro do escopo contra shared/prompt-audit.md — a escrita de prompts para o modelo de origem faz parte de cada migração, e isso não se anuncia. |
prompt-audit | Auditar prompts existentes, descrições de ferramentas, habilidades e arquivos de configuração de agentes (CLAUDE.md, arquivos de regras, comandos, subagentes) em busca de padrões desatualizados ("cruft"): texto escrito para modelos antigos e instruções que o repositório superou ou que se contradizem. Leia shared/prompt-audit.md imediatamente e siga-o em ordem: Etapa 0 (estabeleça escopo e modelo de destino 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, depois 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 pediu explicitamente. Não resuma o guia — execute-o. |
upgrade | Atualizar a dependência do SDK Anthropic do projeto em uma versão major — atualmente o SDK Python, anthropic 0.x -> 1.x. Palavras posteriores podem nomear a linguagem e/ou um escopo (upgrade python, upgrade python sdk src/). Leia python/claude-api/sdk-upgrade.md imediatamente e siga-o em ordem: Etapa 0 (confirme o escopo, depois estabeleça as versões atual e alvo — uma 1.x publicada deve existir antes de você escrever um pin), o inventário da Etapa 1, cada seção numerada, depois a 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 habilidade, informe que nenhum guia de upgrade de versão major está disponível 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 do código existente da API Claude sem sacrificar a qualidade da saída. Leia shared/cost-optimization.md imediatamente e siga-o em ordem: Etapa 0 (estabeleça escopo, barra 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 de response.usage do próprio aplicativo quando ele os possui (pergunte), ou estimado a partir do código caso contrário — depois uma lista de alavancas classificadas por economia (cotadas em dólares, % da conta ou buckets relativos, dependendo de qual dessas fontes de dados você tiver), ganhos gratuitos (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 que cobre o tráfego que ele afeta quando o usuário solicita 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 faltar contexto para uma alavanca, trabalhe interativamente com o usuário — espera-se que este fluxo de trabalho não acerte a auditoria de uma só 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 / sintetizados), Etapa 2 (método de classificação), Etapa 3 (script executável + custo medido). Obtenha a aprovação explícita do usuário sobre as entradas, o método de classificação e o custo antes de produzir a avaliação. |
preserved-thinking-migration | Tornar uma integração existente compatível com 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-o em ordem: Etapa 0 (escopo, classes de tráfego, plataforma e modelo, status de aplicação, barra de qualidade, linha de base), Etapa 0.5 (prove 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 solicitar — depois remedir, manter ou reverter; o protocolo de três braços quando uma avaliação existir), a seção de troca de modelo (em shared/preserved-thinking-migration/causes.md, com a tabela de causas e a lista de manutenção) quando o harness roteia entre modelos, Etapa 4 (o perfil de quebra 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 acréscimo sob um beta mais novo (manter-cauda e compactação de segundo plano: compact-2026-09-04; mudanças de ferramenta com mesmo nome: inline-tools-2026-09-15) são, onde esse beta não estiver 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 acréscimo), 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-o: Etapa 0 (confirme que existe uma avaliação executável — se não, redirecione para build-eval), Etapa 1 (o que mudar / o que é proibido), Etapa 2 (orçamento + condição de parada com base no custo medido por execução), obtenha a aprovação do plano, depois o loop 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):
- Examine os arquivos do projeto para inferir a linguagem:
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile-> Python — leia depython/*.ts,*.tsx,package.json(com dependências TypeScript),tsconfig.json-> TypeScript — leia detypescript/*.go,go.mod-> Go — leia dego/*.java,pom.xml,build.gradle(.kts),gradle.properties-> Java — leia dejava/*.rb,Gemfile,*.gemspec-> Ruby — leia deruby/*.php,composer.json-> PHP — leia dephp/*.cs,*.csproj,*.sln-> C# — leia decsharp/*.sh,*.bash,Dockerfile,Makefile-> Shell — leia deshell/
- Se a linguagem não puder ser inferida, primeiro confirme com o usuário. Ao obter a resposta, leia o diretório de linguagem correspondente.
O código de exemplo e as instruções na resposta devem corresponder à linguagem detectada. Sempre verifique se o diretório {lang}/ existe nesta habilidade. Se a linguagem não for suportada, avise e ofereça ajuda geral.
Conteúdo Estrutural da Habilidade
Esta habilidade contém:
- Diretórios de linguagem com documentação atualizada do SDK (
python/,typescript/,go/,java/,ruby/,php/,csharp/,shell/) - Documentação compartilhada para fluxos avançados (migração, auditoria, otimização de custos, avaliações)
shared/live-sources.md— links oficiais para repositórios SDK, changelogs e guias- Informações detalhadas sobre ferramentas de servidor para busca web e fetch web
Para comandos de uso geral ou limpeza de prompt, consulte: shared/prompt-audit.md
Para guias de migração de modelos: shared/model-migration.md
Para estratégias de otimização de custos: shared/cost-optimization.md
Para criação de conjuntos de avaliação: shared/evals/
Esta habilidade é mantida pela Anthropic. Para problemas ou sugestões, consulte os repositórios oficiais do SDK.