Claude Code SDK + AnyCap: quando precisas de mais do que código

Última atualização: 4 de junho de 2026

O Claude Code SDK é excelente quando o trabalho ainda é maioritariamente código: verificações de CI, revisão de código, saída estruturada e automação compatível com MCP. Mas, assim que um fluxo precisa de pesquisa, media, publicação ou outras capacidades fora do código, o Claude Code SDK por si só deixa de ser suficiente.

É aí que entra o AnyCap. O AnyCap é um agent CLI que estende agentes de programação para além da execução de código, permitindo que o mesmo fluxo passe do raciocínio sobre código para investigação, geração de ativos e entrega de resultados.

Resumo rápido

• Usa o Claude Code SDK para automação centrada em código
• Adiciona AnyCap quando o fluxo precisa de pesquisa, media, publicação ou entrega
• Trata o Claude Code SDK como o runtime de programação
• Trata o AnyCap como a camada de capacidades para lá do código

O que é o Claude Code SDK?

O Claude Code SDK é uma interface programática que permite:

• Executar o Claude Code de forma não interativa a partir de scripts e pipelines
• Controlar que ficheiros, diretórios e ferramentas estão no contexto
• Analisar saída estruturada para processamento a jusante
• Encadear o Claude Code com outras ferramentas em fluxos automatizados
• Criar interfaces personalizadas sobre o raciocínio do Claude Code

Disponível como pacote Node.js:

npm install @anthropic-ai/claude-code

Ou invoca-o via CLI em modo não interativo:

claude -p "O teu prompt aqui" --output-format json

Conceitos centrais do SDK

Modo não interativo

O caso de uso mais básico do SDK: corre o Claude Code com um prompt, recebe a saída e termina.

# CLI não interativo
claude -p "Revê src/auth.ts em busca de vulnerabilidades de segurança" \
  --output-format json \
  --max-turns 5

// SDK
const { query } = require('@anthropic-ai/claude-code');

const result = await query({
  prompt: "Revê src/auth.ts em busca de vulnerabilidades de segurança",
  options: {
    maxTurns: 5,
    outputFormat: 'json'
  }
});

Configuração de ferramentas

Controla que ferramentas o Claude Code pode usar na tua chamada do SDK:

const result = await query({
  prompt: "Gera uma suíte de testes para src/utils.ts",
  options: {
    allowedTools: ['Read', 'Write', 'Bash'],
    // Desativa as ferramentas de que não precisas:
    // disallowedTools: ['WebSearch', 'mcp__custom_tool']
  }
});

Prompts de sistema personalizados

Substitui o prompt de sistema predefinido do Claude Code para comportamentos especializados:

const result = await query({
  prompt: "Refatora este módulo",
  options: {
    systemPrompt: `És um especialista em TypeScript com foco em padrões de programação funcional.
    Dá sempre preferência a estruturas de dados imutáveis. Usa tipos Result para tratamento de erros.
    Nunca uses tipos any ou unknown.`,
  }
});

Padrões práticos do SDK

1. Revisão automática de código em CI

// .github/workflows/code-review.js
const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

const diff = execSync('git diff main...HEAD').toString();

const review = await query({
  prompt: `Revê este diff de PR quanto a: problemas de segurança, problemas de desempenho e testes em falta.
  Devolve em JSON com as chaves: security[], performance[], testing[].
  
  Diff:
  ${diff}`,
  options: {
    outputFormat: 'json',
    allowedTools: ['Read'],  // só leitura em CI
    maxTurns: 3
  }
});

console.log(JSON.parse(review.result));

2. Geração automatizada de documentação

const fs = require('fs');
const { query } = require('@anthropic-ai/claude-code');

async function generateDocs(srcPath) {
  const result = await query({
    prompt: `Gera documentação JSDoc completa para todas as funções exportadas em ${srcPath}.
    Adiciona descrições de parâmetros, tipos de retorno e exemplos de utilização.
    Escreve novamente o ficheiro atualizado com a documentação adicionada.`,
    options: {
      allowedTools: ['Read', 'Write'],
      cwd: process.cwd()
    }
  });
  return result;
}

3. Fluxo multiagente com capacidades externas

É aqui que o AnyCap se torna útil. O Claude Code trata do raciocínio sobre código, enquanto o AnyCap trata das tarefas que ficam fora do runtime de programação.

const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

async function buildAndPublishDocs(repoPath) {
  // Passo 1: o Claude Code gera a documentação
  const docsResult = await query({
    prompt: "Gera um README completo para este projeto com instruções de configuração, referência da API e exemplos",
    options: {
      cwd: repoPath,
      allowedTools: ['Read', 'Write', 'Bash']
    }
  });

  // Passo 2: o AnyCap gera um diagrama hero
  execSync(`anycap image generate \
    --prompt "Diagrama de arquitetura técnica para uma ferramenta de programador, estilo limpo e minimalista" \
    --model nano-banana-2 \
    -o ${repoPath}/docs/architecture.png`);

  // Passo 3: o AnyCap publica como página web
  const pageResult = execSync(`anycap page deploy ${repoPath}/docs/`).toString();
  
  return { docs: docsResult, page: JSON.parse(pageResult) };
}

Autenticação do SDK

O SDK usa a mesma autenticação do Claude Code. Define a tua chave de API:

export ANTHROPIC_API_KEY=your_key_here

Ou, em ambientes de equipa, usa configuração específica do ambiente:

const { query } = require('@anthropic-ai/claude-code');

// O SDK obtém ANTHROPIC_API_KEY automaticamente
// Ou passa explicitamente:
process.env.ANTHROPIC_API_KEY = await getSecretFromVault('anthropic-api-key');

Formatos de saída

O SDK suporta três formatos de saída:

// A saída JSON inclui metadados
{
  "result": "A função pode ter uma vulnerabilidade de SQL injection...",
  "is_error": false,
  "session_id": "sess_xxxx",
  "cost_usd": 0.0043,
  "num_turns": 2
}

Limites de taxa e gestão de custos em fluxos do SDK

A automação baseada em SDK pode consumir tokens mais depressa do que o uso interativo. Guardrails incorporados:

const result = await query({
  prompt: "...",
  options: {
    maxTurns: 5,        // Limitar iterações de raciocínio
    timeoutMs: 30000,   // Timeout para tarefas de longa duração
  }
});

// Verifica sempre o custo em produção
if (result.cost_usd > 0.10) {
  logger.warn(`Sessão de custo elevado: $${result.cost_usd}`);
}

Para tarefas com muita necessidade de capacidades, como geração de imagens, criação de vídeo ou pesquisa na web, descarrega para o AnyCap em vez de deixar o Claude Code tratá-las no contexto. Isto mantém os custos do SDK previsíveis e evita atingir os limites de taxa do Claude em tarefas que não são de raciocínio.

Começar

# Instalar o SDK
npm install @anthropic-ai/claude-code

# Instalar o AnyCap para ampliar capacidades
curl -fsSL https://anycap.ai/install.sh | sh

# Adicionar a skill do AnyCap ao Claude Code
npx -y skills add anycap-ai/anycap -y

→ AnyCap para Claude Code → Guia para adicionar ferramentas ao Claude Code