Claude Code é um ciclo: ele edita arquivos, executa comandos no seu terminal, lê a saída e decide o que fazer em seguida. Então, por que seus testes de API não estão nesse ciclo? Eles ficam no Apidog, atrás de uma GUI, e são executados quando alguém se lembra de clicar. Seu agente nunca os toca.
A solução é um único bloco de configuração. O CLI do Apidog é um pacote npm, apidog-cli, que executa os cenários de teste que você construiu no Apidog diretamente de um terminal. Uma vez que o CLI esteja instalado e o Claude Code saiba que ele existe, seu agente executa um cenário do Apidog da mesma forma que executa seus testes unitários: dispara o comando, lê o código de saída, corrige o código se estiver vermelho.
Este guia aborda a parte específica do Claude Code que o guia de instalação genérico omite: a linha exata para seu CLAUDE.md, como o Claude Code executa apidog run sob seu modelo de permissão e como ler o resultado dentro de seu próprio ciclo de edição-teste-correção.
Se você ainda não instalou o CLI, faça isso primeiro. Como instalar o CLI do Apidog com um agente de codificação de IA detalha a instalação do npm e a primeira execução, com o agente digitando. Este artigo assume que apidog --version imprime um número e que sua conta Apidog está autenticada.
Sobre qual Claude Code estamos falando
Este é o Claude Code CLI, o agente de codificação da Anthropic que é executado no seu terminal (ou aplicativo de desktop). Ele lê seu repositório, edita arquivos e executa comandos de shell, pedindo aprovação com base no seu modo de permissão. Não é o aplicativo de chat Claude e não é uma chamada de API simples. Se você executar claude em um repositório e obtiver um agente interativo que propõe edições e execuções de comandos, você está no lugar certo. Os comandos que você escreve para o terminal ficam nos seus comandos slash do Claude Code e em seu arquivo de regras, e é nesse arquivo de regras que o CLI do Apidog se encaixa.
A distinção importa porque o Claude Code tem sua própria maneira de aprender as regras do projeto, e esse mecanismo transforma um "execute meus testes" pontual em algo que o Claude busca por conta própria. Esse mecanismo é o CLAUDE.md.
Passo 1: Adicione o bloco Apidog ao CLAUDE.md
O Claude Code lê arquivos CLAUDE.md no início de cada sessão. Este é o equivalente direto ao AGENTS.md para o Codex; de fato, a documentação da Anthropic observa que o Claude Code lê CLAUDE.md, não AGENTS.md, e sugere importar um AGENTS.md existente com @AGENTS.md se você mantiver um para outro agente. Se você já configurou o CLI do Apidog no Codex, esta é a mesma ideia com um nome de arquivo diferente.
Coloque um CLAUDE.md na raiz do seu repositório (o Claude Code também aceita ./.claude/CLAUDE.md e um ~/.claude/CLAUDE.md global para padrões pessoais). O Claude Code percorre a árvore de diretórios de onde você o iniciou e carrega todos os CLAUDE.md que encontra, então um arquivo na raiz do repositório alcança todas as sessões. Adicione um bloco curto como este:
## Testes de API com Apidog CLI
Este projeto possui cenários de teste Apidog. Para verificar a API, execute:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- O código de saída 0 significa que todas as asserções foram aprovadas. Diferente de zero significa que algo falhou; abra o relatório e corrija antes de prosseguir.
- A máquina já está autenticada via `apidog login`. Nunca adicione uma flag `--access-token` e nunca coloque um token neste arquivo.
- Se uma flag for desconhecida, execute `apidog run --help` e use a flag exata de lá.
É por isso que você escreve o CLI no CLAUDE.md em vez de mencioná-lo no chat. Um ID de cenário digitado em uma sessão se perde quando a sessão termina. Um no CLAUDE.md está lá para cada colega de equipe e cada execução do Claude Code a partir de agora. O arquivo é carregado por completo no lançamento e sobrevive a um /compact, então a instrução permanece ativa durante toda a sessão.
Passo 2: Obtenha o comando do Apidog
Os <scenario_id> e <env_id> nesse bloco não são valores que você adivinha. Abra seu cenário de teste no Apidog, vá para a aba CI/CD e copie o comando apidog run ... gerado. Ele já contém o ID do cenário real, o ID do ambiente e o reporter -r cli preenchidos. Cole esses IDs exatos no seu bloco CLAUDE.md.
O reporter -r cli imprime um resultado passo a passo e um resumo diretamente no terminal, que é exatamente a saída que o Claude Code lê para decidir seu próximo passo. Para uma análise completa de cada flag, consulte o guia completo do CLI do Apidog e a referência do comando apidog run.
Passo 3: Peça ao Claude Code para executar o teste
Com o bloco no lugar, inicie o Claude Code em seu repositório:
claude
O Claude Code carrega o CLAUDE.md ao iniciar, então ele já sabe que o CLI está lá. Faça uma alteração que afete sua API, ou apenas peça para ele executar a verificação. O Claude Code emite o comando apidog run do seu CLAUDE.md.
Aqui, o modelo de permissão é importante. Em seu modo padrão, o Claude Code pergunta antes de executar um comando shell que ele não viu aprovado. Aprovado o comando apidog run quando ele solicitar. Para parar de ser perguntado sobre um comando em que você confia, adicione uma regra de permissão para que o CLI seja executado sem um prompt: execute /permissions dentro da sessão ou adicione uma regra de permissão para Bash(apidog run *) em .claude/settings.json. Um cenário de teste somente leitura contra um ambiente de homologação é um comando seguro para permitir. Para execuções não supervisionadas, existe --dangerously-skip-permissions, que ignora os prompts completamente; guarde isso para CI, não para o seu uso diário.
Você vai querer ver a execução e o Claude Code relatando tanto o resumo quanto o código de saída, não apenas uma frase alegando sucesso.
Passo 4: Leia o relatório dentro do Claude Code
Quando uma execução fica vermelha, o relatório contém a resposta. Com -r cli, o Claude Code obtém um detalhamento legível no terminal: cada requisição, cada asserção e qual falhou com o valor esperado versus o valor real. A asserção com falha nomeia o campo exato ou o código de status, o que geralmente é suficiente para o Claude Code encontrar a correção.
Para um relatório que você pode abrir em um navegador ou entregar a um colega de equipe, adicione o reporter HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
O reporter html escreve um arquivo autocontido em ./apidog-reports. Mantenha cli na lista para que o Claude Code ainda receba a saída inline que ele lê para decidir seu próximo passo. Para o formato JUnit que os painéis de CI analisam e os outros reporters, consulte relatórios de teste do CLI do Apidog.
Claude Code testando dentro de seu próprio ciclo
O importante é o que acontece quando você para de perguntar e o Claude Code executa o cenário por conta própria porque o CLAUDE.md o instruiu a fazê-lo.
Imagine o Claude Code editando um manipulador que constrói uma resposta de checkout. Seu ciclo muda: ele edita o código, então, em vez de declarar vitória, executa seu cenário Apidog contra o ambiente de homologação, lê o código de saída e age sobre ele. Verde, ele avança. Vermelho, ele abre o relatório, lê qual asserção falhou (o código de status, o campo ausente, o valor errado), tenta uma correção e executa novamente. O teste de API se torna parte do mesmo ciclo de edição-teste-correção que o Claude Code já usa para seus testes unitários. Você escreveu uma instrução e o Claude incorporou o comando em como ele já funciona.
Este é o modelo de delegar-e-verificar que torna qualquer fluxo de trabalho de agente seguro. O Claude Code executa o comando e lê o resultado; você continua criando cenários visualmente no Apidog e verifica se o agente lê os códigos de saída honestamente. Para o padrão mais amplo, consulte como usar agentes de IA para testes de API e o arnes de teste de IA do Apidog.
Verifique se o Claude Code está realmente executando o CLI
Os agentes relatam sucesso que não conquistaram, e o Claude Code não é exceção. Três verificações, em ordem de quão frequentemente elas detectam problemas.
Primeiro, confirme se o comando foi executado. O Claude Code mostra os comandos que executou e sua saída inline. Procure pela linha literal apidog run ... e um resultado abaixo dela. Se o Claude disser que executou os testes, mas você não vir o comando, ele resumiu algo que nunca fez. Peça para ele executar novamente e mostrar a saída bruta.
Segundo, confirme o código de saída, o que realmente importa. Pergunte diretamente: “Qual foi o código de saída daquele comando apidog run?” apidog run sai com 0 quando todas as asserções passam e diferente de zero quando algo falha. Esse único comportamento permite que o Claude Code, ou um pipeline, trate a execução como uma porta de qualidade limpa. Quando a descrição do Claude diz “testes aprovados” mas o código de saída é diferente de zero, o código de saída está correto.
Terceiro, confirme se ele usou o cenário real. Se uma execução falhar com "cenário não encontrado", o Claude pode ter inventado ou se lembrado incorretamente de um ID. Verifique novamente os valores de -t e -e em relação ao CLAUDE.md e ao comando que o Apidog gerou na aba CI/CD. Os IDs em CLAUDE.md são a verdade.
Opcional: conecte o servidor Apidog MCP
Executar apidog run a partir do CLAUDE.md cobre a maior parte do que você precisa. Para ir um passo além, conecte um servidor MCP para que o Claude Code possa ler sua especificação de API enquanto escreve código, não apenas testar depois do fato.
O Claude Code suporta o Protocolo de Contexto do Modelo (Model Context Protocol - MCP). Você adiciona um servidor com claude mcp add ... ou commitando um arquivo .mcp.json na raiz do seu projeto e escolhendo --scope project para que toda a equipe o utilize. O servidor MCP do Apidog expõe suas especificações de API via MCP, para que o Claude leia seu esquema enquanto codifica. Pense nisso como uma divisão de trabalho: o CLI executa os testes, o MCP alimenta o agente com a especificação.
Quando o Claude Code erra
Algumas falhas aparecem frequentemente durante a configuração.
Ele ignora o bloco CLAUDE.md. Se o Claude executa um comando genérico ou nenhum, o bloco pode não estar sendo carregado. Confirme se o arquivo tem o nome exato CLAUDE.md e está na raiz do seu repositório ou em um diretório pai do seu diretório atual. Execute /memory dentro da sessão para listar os arquivos que o Claude realmente carregou; se o seu não estiver lá, o Claude não consegue vê-lo. Reiniciar a sessão força uma nova leitura.
Ele passa um token de acesso de qualquer forma. Se o Claude tenta adicionar --access-token, ele está adivinhando a partir de exemplos públicos. O bloco já o instrui a não fazê-lo, pois a máquina está autenticada via apidog login. Reforce a linha e nunca coloque um token real no CLAUDE.md. Para saber como a máquina se autentica uma vez, consulte autenticação do CLI do Apidog.
Ele inventa uma flag. Um erro de "opção desconhecida" significa que o Claude adivinhou uma flag que sua versão não possui. Peça para ele executar apidog run --help e copiar a flag exata de lá, que é sempre correta para a sua versão instalada.
Ele relata um sucesso em uma execução falha. O mais custoso, e a razão pela qual a regra do código de saída está no seu CLAUDE.md e na sua etapa de verificação. Quando o resumo e o código de saída discordam, o código de saída prevalece.
De um agente diário a um ciclo testado
Essa é a configuração. Instale apidog-cli uma vez seguindo o guia de instalação, adicione um pequeno bloco Apidog ao CLAUDE.md do seu repositório, e o Claude Code saberá como executar seus testes de API e ler o resultado dentro do mesmo ciclo que ele já usa para editar código. Um endpoint quebrado é detectado enquanto o Claude ainda está trabalhando na mudança, e não depois de ser implementado.
Um teste por trás de uma GUI é executado quando um humano clica; um comando de uma linha é executado sempre que o Claude decide. Você continua construindo cenários visualmente no Apidog, e seu agente os executa onde você não está observando. Baixe o Apidog, construa um cenário, insira o comando apidog run no CLAUDE.md e veja o Claude incorporá-lo na próxima alteração. Quando estiver pronto para executar o mesmo comando em um pipeline sem a presença do Claude, Apidog CLI no GitHub Actions aborda os segredos, reporters e controle de código de saída.