Claude Code es un bucle: edita archivos, ejecuta comandos en tu terminal, lee la salida y decide qué hacer a continuación. Entonces, ¿por qué tus pruebas de API no están en ese bucle? Permanecen en Apidog detrás de una interfaz gráfica de usuario y se ejecutan cuando alguien se acuerda de hacer clic. Tu agente nunca las toca.
La solución es un bloque de configuración. La CLI de Apidog es un paquete npm, apidog-cli, que ejecuta los escenarios de prueba que creaste en Apidog directamente desde una terminal. Una vez que la CLI está instalada y Claude Code sabe que existe, tu agente ejecuta un escenario de Apidog de la misma manera que ejecuta tus pruebas unitarias: dispara el comando, lee el código de salida, corrige el código si está en rojo.
Esta guía cubre la parte específica de Claude Code que la guía de instalación genérica omite: la línea exacta para tu CLAUDE.md, cómo Claude Code ejecuta apidog run bajo su modelo de permisos, y cómo leer el resultado dentro de su propio bucle de edición-prueba-corrección.
Si aún no has instalado la CLI, hazlo primero. Cómo instalar la CLI de Apidog con un agente de codificación de IA explica la instalación de npm y la primera ejecución, con el agente haciendo la escritura. Este artículo asume que apidog --version imprime un número y que tu cuenta de Apidog está autenticada.
De qué Claude Code se trata
Este es la CLI de Claude Code, el agente de codificación de Anthropic que se ejecuta en tu terminal (o aplicación de escritorio). Lee tu repositorio, edita archivos y ejecuta comandos de shell, solicitando aprobación según tu modo de permisos. No es la aplicación de chat de Claude ni una simple llamada a la API. Si ejecutas claude en un repositorio y obtienes un agente interactivo que propone ediciones y ejecuciones de comandos, estás en el lugar correcto. Los comandos que escribes para la terminal viven en tus comandos slash de Claude Code y su archivo de reglas, y ese archivo de reglas es donde pertenece la CLI de Apidog.
La distinción importa porque Claude Code tiene su propia forma de aprender las reglas del proyecto, y ese mecanismo convierte un "ejecutar mis pruebas" único en algo que Claude busca por sí solo. Ese mecanismo es CLAUDE.md.
Paso 1: Añade el bloque de Apidog a CLAUDE.md
Claude Code lee los archivos CLAUDE.md al inicio de cada sesión. Esto es la contraparte directa de AGENTS.md para Codex; de hecho, la documentación de Anthropic señala que Claude Code lee CLAUDE.md, no AGENTS.md, y sugiere importar un AGENTS.md existente con @AGENTS.md si mantienes uno para otro agente. Si ya configuraste la CLI de Apidog en Codex, esta es la misma idea con un nombre de archivo diferente.
Coloca un CLAUDE.md en la raíz de tu repositorio (Claude Code también acepta ./.claude/CLAUDE.md, y un ~/.claude/CLAUDE.md global para configuraciones predeterminadas personales). Claude Code recorre el árbol de directorios desde donde lo lanzaste y carga cada CLAUDE.md que encuentra, por lo que un archivo en la raíz del repositorio llega a cada sesión. Añade un bloque corto como este:
## Pruebas de API con la CLI de Apidog
Este proyecto tiene escenarios de prueba de Apidog. Para verificar la API, ejecuta:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- El código de salida 0 significa que todas las aserciones pasaron. Un valor distinto de cero significa que algo falló; abre el informe y corrígelo antes de continuar.
- La máquina ya está autenticada a través de `apidog login`. Nunca añadas un indicador `--access-token` y nunca pongas un token en este archivo.
- Si un indicador es desconocido, ejecuta `apidog run --help` y usa el indicador exacto de allí.
Por eso escribes la CLI en CLAUDE.md en lugar de mencionarla en el chat. Un ID de escenario introducido en una sesión se pierde cuando termina esa sesión. Uno en CLAUDE.md está ahí para cada compañero de equipo y cada ejecución de Claude Code de ahora en adelante. El archivo se carga por completo al inicio y sobrevive a un /compact, por lo que la instrucción permanece activa durante toda la sesión.
Paso 2: Obtén el comando de Apidog
Los <scenario_id> y <env_id> en ese bloque no son valores que se adivinan. Abre tu escenario de prueba en Apidog, ve a la pestaña CI/CD y copia el comando apidog run ... generado. Ya tiene el ID de escenario real, el ID de entorno y el reportero -r cli rellenos. Pega esos IDs exactos en tu bloque de CLAUDE.md.
El reportero -r cli imprime un resultado paso a paso y un resumen directamente en la terminal, que es exactamente la salida que Claude Code lee para decidir su siguiente paso. Para un desglose completo de cada indicador, consulta la guía completa de la CLI de Apidog y la referencia del comando apidog run.
Paso 3: Haz que Claude Code ejecute la prueba
Con el bloque en su lugar, inicia Claude Code en tu repositorio:
claude
Claude Code carga CLAUDE.md al iniciarse, por lo que ya sabe que la CLI está allí. Haz un cambio que afecte a tu API, o simplemente pídele que ejecute la verificación. Claude Code emite el comando apidog run de tu CLAUDE.md.
Aquí el modelo de permisos importa. En su modo predeterminado, Claude Code pregunta antes de ejecutar un comando de shell que no ha visto aprobado. Aprueba el comando apidog run cuando se lo solicite. Para que no se te pregunte por un comando en el que confías, añade una regla de permiso para que la CLI se ejecute sin un aviso: ejecuta /permissions dentro de la sesión, o añade una regla de permiso para Bash(apidog run *) en .claude/settings.json. Un escenario de prueba de solo lectura contra un entorno de pruebas (staging) es un comando seguro para permitir. Para ejecuciones desatendidas existe --dangerously-skip-permissions, que omite las solicitudes por completo; guárdalo para CI, no para tu uso diario.
Deseas ver la ejecución y que Claude Code informe tanto el resumen como el código de salida, no solo una frase que declare éxito.
Paso 4: Lee el informe dentro de Claude Code
Cuando una ejecución da error, el informe tiene la respuesta. Con -r cli, Claude Code obtiene un desglose legible en la terminal: cada solicitud, cada aserción y cuál falló con el valor esperado frente al real. La aserción fallida nombra el campo o código de estado exacto, lo que suele ser suficiente para que Claude Code encuentre la solución.
Para un informe que puedas abrir en un navegador o entregar a un compañero de equipo, añade el reportero HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
El reportero html escribe un archivo autocontenido en ./apidog-reports. Mantén cli en la lista para que Claude Code siga obteniendo la salida en línea que lee para decidir su siguiente paso. Para el formato JUnit que los paneles de CI analizan y los otros reporteros, consulta Informes de pruebas de la CLI de Apidog.
Claude Code probando dentro de su propio bucle
El punto es lo que sucede cuando dejas de preguntar y Claude Code ejecuta el escenario por sí solo porque CLAUDE.md se lo indicó.
Imagina a Claude Code editando un controlador que construye una respuesta de pago. Su bucle cambia: edita el código, luego, en lugar de declarar victoria, ejecuta tu escenario de Apidog contra el entorno de staging, lee el código de salida y actúa en consecuencia. Si es verde, sigue adelante. Si es rojo, abre el informe, lee qué aserción falló (el código de estado, el campo faltante, el valor incorrecto), intenta una solución y vuelve a ejecutar. La prueba de API se convierte en parte del mismo bucle de edición-prueba-corrección por el que Claude Code ya ejecuta tus pruebas unitarias. Escribiste una instrucción y Claude incorporó el comando a su funcionamiento.
Este es el modelo de delegar y verificar que hace que cualquier flujo de trabajo de agente sea seguro. Claude Code ejecuta el comando y lee el resultado; tú sigues creando escenarios visualmente en Apidog y verificas que el agente lee los códigos de salida honestamente. Para el patrón más amplio, consulta cómo usar agentes de IA para pruebas de API y el arnés de pruebas de IA de Apidog.
Verifica que Claude Code realmente esté ejecutando la CLI
Los agentes reportan éxitos que no se ganaron, y Claude Code no es una excepción. Tres comprobaciones, en orden de la frecuencia con la que detectan problemas.
Primero, confirma que el comando se ejecutó en absoluto. Claude Code muestra los comandos que ejecutó y su salida en línea. Busca la línea literal apidog run ... y un resultado debajo. Si Claude dice que ejecutó las pruebas pero no ves el comando, resumió algo que nunca hizo. Pídele que lo ejecute de nuevo y muestre la salida en bruto.
Segundo, confirma el código de salida, el que importa. Pregúntale directamente: "¿Cuál fue el código de salida de ese comando apidog run?". apidog run sale con 0 cuando todas las aserciones pasan y con un valor distinto de cero cuando algo falla. Ese único comportamiento permite a Claude Code, o a una tubería, tratar la ejecución como una puerta limpia. Cuando la prosa de Claude dice "pruebas pasaron" pero el código de salida no es cero, el código de salida tiene la razón.
Tercero, confirma que usó el escenario real. Si una ejecución falla con "escenario no encontrado", Claude puede haber inventado o recordado mal un ID. Vuelve a verificar los valores -t y -e contra CLAUDE.md y el comando que Apidog generó en la pestaña CI/CD. Los IDs en CLAUDE.md son la verdad.
Opcional: conecta el servidor MCP de Apidog
Ejecutar apidog run desde CLAUDE.md cubre la mayor parte de lo que necesitas. Para ir un paso más allá, conecta un servidor MCP para que Claude Code pueda leer tu especificación de API mientras escribe código, no solo probar después de los hechos.
Claude Code soporta el Protocolo de Contexto del Modelo (MCP). Añades un servidor con claude mcp add ... o cometiendo un archivo .mcp.json en la raíz de tu proyecto y eligiendo --scope project para que todo el equipo lo tenga. El servidor MCP de Apidog expone tus especificaciones de API a través de MCP, para que Claude lea tu esquema mientras codifica. Piensa en ello como una división del trabajo: la CLI ejecuta las pruebas, MCP alimenta la especificación al agente.
Cuando Claude Code se equivoca
Algunos fallos aparecen a menudo durante la configuración.
Ignora el bloque CLAUDE.md. Si Claude ejecuta un comando genérico o ninguno en absoluto, es posible que el bloque no se esté cargando. Confirma que el archivo se llama exactamente CLAUDE.md y se encuentra en la raíz de tu repositorio o en un directorio padre de tu directorio actual. Ejecuta /memory dentro de la sesión para listar los archivos que Claude realmente cargó; si el tuyo no está ahí, Claude no puede verlo. Reiniciar la sesión fuerza una nueva lectura.
De todos modos, pasa un token de acceso. Si Claude intenta añadir --access-token, está adivinando a partir de ejemplos públicos. El bloque ya le dice que no lo haga, ya que la máquina está autenticada a través de apidog login. Refuerza la línea y nunca pongas un token real en CLAUDE.md. Para saber cómo se autentica la máquina una vez, consulta autenticación de la CLI de Apidog.
Inventa un indicador. Un error de "opción desconocida" significa que Claude adivinó un indicador que tu versión no tiene. Dile que ejecute apidog run --help y copia el indicador exacto de ahí, que siempre es correcto para tu versión instalada.
Reporta un pase en una ejecución fallida. Es el más costoso, y la razón por la que la regla del código de salida está en tu CLAUDE.md y en tu paso de verificación. Cuando el resumen y el código de salida no coinciden, el código de salida es el que manda.
De un agente diario a un bucle probado
Esa es la configuración. Instala apidog-cli una vez siguiendo la guía de instalación, añade un bloque corto de Apidog a tu CLAUDE.md del repositorio, y Claude Code sabrá cómo ejecutar tus pruebas de API y leer el resultado dentro del mismo bucle que ya usa para editar código. Un endpoint roto se detecta mientras Claude aún está trabajando en el cambio, no después de que se haya lanzado.
Una prueba detrás de una GUI se ejecuta cuando un humano hace clic; un comando de una línea se ejecuta cuando Claude lo decide. Tú sigues construyendo escenarios visualmente en Apidog, y tu agente los ejecuta donde no estás mirando. Descarga Apidog, construye un escenario, suelta su comando apidog run en CLAUDE.md, y observa cómo Claude lo recoge en el siguiente cambio. Cuando estés listo para ejecutar el mismo comando en una pipeline sin la presencia de Claude, La CLI de Apidog en Acciones de GitHub cubre los secretos, los reporteros y la exclusión por código de salida.