SDK do Claude Code

 (docs.anthropic.com)
1 pontos por GN⁺ 2025-05-20 | 1 comentários | Compartilhar no WhatsApp
  • O SDK do Claude Code oferece recursos para integrar ferramentas de programação baseadas em IA a aplicações
  • Desenvolvedores podem executar o Claude Code como subprocesso, com suporte prioritário ao uso pela linha de comando
  • Inclui recursos de gerenciamento de contexto conversacional, definição de prompts de sistema personalizados e integração com ferramentas externas (MCP)
  • Permite diversidade de formatos de saída (texto, JSON, JSON em streaming) e uso detalhado de opções de CLI
  • Como caso prático, mostra a possibilidade de integração com fluxos de desenvolvimento reais, como revisão automática de código e criação de PRs em conjunto com GitHub Actions

Introdução

O SDK do Claude Code é uma ferramenta de desenvolvimento open source que permite integrar programaticamente os recursos do Claude Code diretamente em aplicações. O SDK executa o Claude Code como um processo separado, oferecendo extensibilidade para incorporá-lo a vários fluxos de desenvolvimento, como assistentes de código com IA, ferramentas de automação e sistemas de revisão de código.

Atualmente, ele oferece suporte a uma interface baseada em linha de comando (CLI), e os SDKs para TypeScript e Python devem ser lançados em breve.

Uso básico do SDK

O SDK do Claude Code oferece suporte à execução não interativa. Por exemplo, é possível chamar o Claude Code de dentro de um programa com argumentos de linha de comando para obter automaticamente a saída desejada.

Uso avançado

Continuar uma sessão de conversa com múltiplos turnos

  • Ao trocar mensagens em várias rodadas, ele oferece um recurso para manter e continuar o contexto da conversa usando uma sessão anterior ou um ID de sessão específico
  • O desenvolvedor pode continuar a conversa a partir da sessão mais recente ou carregar uma sessão específica

Prompt de sistema personalizado

  • É possível ajustar o comportamento padrão do Claude com um prompt de sistema personalizado pelo desenvolvedor
  • Também é possível anexar instruções adicionais ao prompt de sistema padrão para alterar a orientação de trabalho e o escopo de comportamento do assistant

Configuração de MCP (Model Context Protocol)

  • MCP é um protocolo de integração com servidores externos para expandir os recursos do Claude Code
  • Com a flag --mcp-config e um arquivo de configuração JSON, é possível adicionar recursos fornecidos por servidores externos, como acesso a banco de dados, integração com APIs e ferramentas customizadas
  • Ao usar ferramentas MCP, somente ferramentas explicitamente permitidas podem ser usadas (flag --allowedTools), e o padrão de nome é mcp__<serverName>__<toolName>

Opções de CLI disponíveis

No SDK do Claude Code, é possível configurar o ambiente de execução usando diversas flags de linha de comando

  • --print, -p : executa no modo não interativo
  • --output-format : seleciona o formato de saída (texto, JSON, stream JSON etc.)
  • --resume, -r : continua a conversa com um ID de sessão específico
  • --continue, -c : continua a sessão mais recente
  • --verbose : exibe logs detalhados
  • --max-turns : limita o número máximo de rodadas de conversa no modo não interativo
  • --system-prompt : sobrescreve o prompt de sistema
  • --append-system-prompt : anexa instruções adicionais ao prompt de sistema
  • --allowedTools : define a lista de ferramentas permitidas (incluindo ferramentas MCP)
  • --disallowedTools : define a lista de ferramentas proibidas
  • --mcp-config : carrega o arquivo de configuração do servidor MCP
  • --permission-prompt-tool : define a ferramenta MCP para processar prompts de permissão

Para todas as opções disponíveis e exemplos de uso, consulte a documentação oficial da CLI.

Formatos de saída

O SDK oferece suporte a vários formatos de saída

Saída em texto (padrão)

  • Retorna apenas o texto da resposta

Saída em JSON

  • Retorna metadados e dados estruturados, o que facilita o parsing programático
  • As mensagens de resposta da API seguem uma estrutura de tipos rigorosa, e no futuro os tipos também deverão ser definidos no formato JSON Schema

Saída em JSON em streaming

  • Transmite cada mensagem em tempo real por stream
  • Durante o andamento da sessão de conversa, objetos JSON separados são enviados na ordem: mensagem de inicialização (init), mensagens do usuário/assistant e a mensagem final result com estatísticas

Esquema de mensagens

  • As mensagens de resposta da API JSON são estruturadas de acordo com um esquema preciso
  • Atualizações periódicas do esquema e versionamento devem ser realizados futuramente

Exemplos

  • Integração com script simples
  • Processamento de arquivos com Claude
  • Suporte a fluxos de conversa complexos com gerenciamento de sessão

Boas práticas

  1. Usar formato de saída JSON para parsing de respostas
  2. Tratamento de erros: verificar código de saída e stream de erro
  3. Gerenciamento de sessão: manter o contexto em conversas de múltiplas rodadas
  4. Considerar timeouts: garantir segurança em tarefas de longa duração
  5. Ajustar o intervalo entre requisições: evitar chamadas excessivas e manter a estabilidade do serviço

Casos de uso reais

O SDK do Claude Code oferece recursos poderosos de automação e integração em ambientes reais de desenvolvimento

  • Como exemplo representativo, ele pode ser combinado com GitHub Actions para automatizar totalmente fluxos de desenvolvimento como revisão automática de código, criação de PRs e classificação de issues

Leituras relacionadas

1 comentários

 
GN⁺ 2025-05-20
Comentários do Hacker News

  • Quero destacar que a direção que o Claude Code busca é exatamente a forma da filosofia "unix toolish" de uma ferramenta de programação baseada em agentes que eu queria. Uso o Claude Code desde o preview público inicial e acompanhei sua evolução. Acho que o "padrão-ouro" para um agente de programação é um nível em que você insere uma solicitação de recurso, por exemplo um ticket do Jira, e recebe um PR para eu mesmo revisar e dar feedback. Vejo limitações em Cursor, Windsurf e afins por serem editores locais e não poderem ser integrados a ambientes de CI. Se você quer otimizar um codebase para IA (MCP, regras etc.), é importante mirar em uma tecnologia que também possa ser usada em modo headless. O Claude Code pode ser usado de forma simples junto com ferramentas de automação, então agora ele virou o padrão quando penso em agentes de programação. Penso de forma parecida sobre o pacote npm do Codex. Vale dizer que eu trabalho ajudando pessoas a montar esse tipo de configuração ideal de ferramentas, então naturalmente posso ter uma visão mais favorável a ferramentas que sejam fáceis de configurar

    • O "estado final dourado" que eu imagino é estar no meio de uma sala cercado por agentes de IA, por exemplo agentes que escrevem código, fazem design e executam testes. No centro disso, eu quase não tocaria no teclado e apenas daria direção, critérios estéticos e orientações por conversa. Estou ansioso por esse futuro

    • Quero mencionar que a Anthropic anunciou hoje em beta um recurso parecido com isso. Quero compartilhar a documentação relacionada. https://docs.anthropic.com/en/docs/claude-code/github-actions

    • O "estado final dourado" de um agente de programação, na minha visão, é usar um agente de programação gratuito e open source que possa rodar livremente no meu computador, ou onde eu quiser. Assim como parece absurdo imaginar pagar toda vez que executo comandos como ls, ps, kill no terminal, acho que o mesmo vale para LLMs. Não estou dizendo para "proibir" LLMs proprietários, mas espero que as pessoas chamadas de hackers nessa área usem ferramentas open source como ferramenta principal

    • Você apontou que Cursor, Windsurf e afins são difíceis de usar em CI por serem editores locais, mas eu tentei isso com a combinação de Cursor e MCP. Consegui usar com sucesso por um dia inteiro, mas logo bati no rate limit e a ferramenta mudou para o modelo mais lento e mais burro. Também tentei com Claude, mas em pouco tempo acabei estourando o limite. Além disso, só uns 25% dos PRs ficam em nível de "uso imediato", e muitas vezes é mais rápido fazer eu mesmo do que descobrir onde a IA errou

    • Minha impressão é que essa automação baseada em CI já é possível. Se você registrar o Aider CLI como uma GitHub Action para rodar automaticamente quando uma issue for criada, essa estrutura já pode ser implementada

  • O Claude Code é minha forma preferida de usar LLMs para programação. Mas acho que o que realmente falta é uma versão open source do Claude Code. Precisamos de um ambiente em que possamos aplicar o modelo que quisermos e comparar diretamente as respostas de modelos diferentes. Sinto que outras alternativas, como o Aider, não entregam uma experiência no nível do Claude Code. Dá para imaginar por que a Anthropic não gostaria disso, já que enfraqueceria sua defesa competitiva. Mas, do ponto de vista do consumidor, eu quero usar o melhor modelo e não ficar preso a um único ecossistema. Imagino que esse seja o maior medo do lado dos provedores de LLM

    • O OpenAI codex é o open source mais próximo do que você descreveu. Dá para usar modelos do provedor que você quiser. Por enquanto ele é inferior ao Claude Code, mas acho que vai alcançá-lo em breve. https://github.com/openai/codex/tree/main

    • Você pode usar o Claude Code como servidor MCP para montar, em certa medida, o ambiente que deseja

  • O Aider já oferecia suporte a Python e shell scripting há bastante tempo. Recentemente, também produziu um screencast que inclui um aide de bash scripting ad-hoc como parte do processo de adicionar suporte a 130 novas linguagens de programação. Dá para sentir na prática o quão poderosa é essa abordagem de estilo de scripting. https://aider.chat/docs/scripting.html, https://aider.chat/docs/recordings/tree-sitter-language-pack.html

    • Gosto muito do Aider. O suporte a MCPs também deve chegar em breve e está sendo testado na branch de desenvolvimento. Quando isso acontecer, desenvolvimento end-to-end com PRs, tickets etc. usando apenas modelos em que você confia vai realmente se tornar possível

    • Fico curioso se o Aider consegue chegar a um nível em que eu goste dele tanto quanto do Claude Code. Gosto da UX do Claude Code, mas não uso porque prefiro o Gemini 2.5 Pro. O que me atrai nele não são tanto recursos como commits, e sim a boa UX. Queria ouvir sua opinião sobre isso

    • Acho que, se o Aider deixar o workflow de integração com GitHub Actions mais polished, ele pode crescer muito. Bastaria adicionar um único arquivo ao repositório para poder conversar por issue com o modelo desejado

  • Quero compartilhar um contexto adicional divulgado pelo próprio time do Claude Code. http://latent.space/p/claude-code Resumindo os pontos principais: funcionários da Anthropic usam, em média, cerca de 6 dólares por dia de Claude ilimitado. Um Claude Code headless, tipo um utilitário "linux" para CI, é muito atraente. Também existe a direção de virar uma plataforma extensível para usuários. O roadmap futuro inclui sandboxing, branching e recursos de planning. Também está previsto um modelo agentic contínuo chamado sonnet 3.7

    • Você mencionou "funcionários da Anthropic usam em média US$ 6/dia com Claude ilimitado", mas no artigo também aparece o relato de um engenheiro que gastou US$ 1.000 em um único dia. Mais do que a média, eu queria ver a distribuição, como P50, P75 e P95

    • Já tive várias experiências em que usei o Claude Code por umas 2 horas e a conta passou fácil dos 20 dólares. Para projetos pessoais, fica caro demais e eu simplesmente não consigo usar

    • Ouvi recentemente o podcast do latent space e achei realmente muito bom. É raro ver pessoas ou podcasts que mantêm um SNR tão alto e ao mesmo tempo publicam conteúdo público com tanta consistência e produtividade. É impressionante manter esse nível de produção pública enquanto tocam vários negócios ao mesmo tempo. Acho que seria ótimo se mais gente pudesse experimentar esse tipo de gradient de produtividade. A pessoa até compartilha os segredos, mas não é fácil reproduzir isso na prática

  • Se eu criasse um assistente de código com IA, nunca o prenderia a um fornecedor específico de foundation model. Isso só faria sentido como estratégia se o efeito dos modelos já tivesse praticamente atingido o teto, com desempenho muito parecido entre eles, e restassem apenas pequenas diferenças no nível de um SDK já conhecido

    • Acho que o lock-in na prática não é tão grave, porque no fim mudam só os comandos ou argumentos. Continua sendo basicamente uma função de entrada e saída, então dá para trocar só a parte necessária ou encapsular. Estruturalmente não é algo complexo

    • Neste momento, acho que o Claude Code está servindo como diferencial no mercado de programação baseada em agentes. Estou desenvolvendo um AI code assistant e a primeira integração que vou tentar é com o Claude Code. Não sinto que este seja o momento de me preocupar com lock-in no início. Acho que é preciso escolher o melhor e começar a desenvolver em cima disso

  • Quero enfatizar que o Claude Code já podia ser usado em modo non-interactive, então já era fácil integrá-lo a outros apps como um utilitário de linha de comando no estilo UNIX. Este SDK novo também parece suportar apenas uso por linha de comando, então sinceramente não entendo muito bem o que muda em essência em relação ao que já existia. Fico curioso sobre o que estou deixando passar

  • Cito os termos de uso da Anthropic, que "proíbem desenvolver, treinar ou revender qualquer produto ou serviço que concorra com inteligência geral". Se praticamente todo software puder ser considerado como algo que "concorre" com inteligência geral, então, numa interpretação rígida, isso não significaria que não pode ser usado para nada? Acho esse tipo de formulação jurídica tão vaga que acaba sendo inaplicável. Você é dono dos resultados da IA, mas desde que não concorram com inteligência geral? Fico me perguntando por que proibir isso de forma tão ampla. A ideia é só dizer que a responsabilidade legal é do usuário? Isso levanta várias dúvidas

    • É isso que acontece quando deixam advogados escreverem as regras do jeito que querem

  • Fiquei muito feliz porque a nova GitHub Action corresponde exatamente ao que eu estava procurando. https://docs.anthropic.com/en/docs/claude-code/github-action... Só que, pelo visto, ainda não há como usar isso vinculado ao plano Max do Claude Code. A estrutura parece aceitar apenas api key, o que é um pouco decepcionante

  • Quero destacar que especialmente a integração com GitHub Actions e com issues/PRs é a funcionalidade que eu queria há muito tempo. https://docs.anthropic.com/en/docs/claude-code/github-action...

  • Quando o suporte ao Claude chegar via Copilot, com certeza vou testar. Pelas políticas da empresa, ainda não posso usar outras ferramentas