English

Haz que el agente descubra los comandos propios del proyecto

Tu agente de IA está ejecutando el comando de tests equivocado. Escribe npm test en un repo que bloquea los merges con npm run test:ci, o pytest a secas en un proyecto cuya suite real corre con tox. Un comando adivinado puede pasar mientras la suite real falla — o saltarse justo los chequeos que protegen el repo. Lo canónico siempre le gana a lo adivinado.

Por qué los comandos adivinados mienten

Un comando genérico no es "más o menos correcto". Puede estar mal de formas que se ven en verde:

• Ejecuta un subconjunto: pytest sin la cobertura, el lint o el chequeo de tipos que el CI exige.
• Corre con el entorno equivocado: el Python del sistema en lugar del venv del proyecto, o sin las variables de entorno que el CI define.
• No ejecuta nada que importe: npm test imprime Error: no test specified y sale con error en un repo cuyos chequeos reales viven en un Makefile.

El resultado es un agente que reporta "los tests pasan" sobre trabajo que el repo rechazaría. La solución no es adivinar mejor: es decirle al agente que deje de adivinar.

La pasada de descubrimiento

Antes de que el agente ejecute algo genérico, haz que lea la superficie del proyecto y registre los comandos exactos que encuentra. Una sola instrucción alcanza:

Antes de ejecutar cualquier comando de build, test o lint, inspecciona las definiciones propias del repo — manifiestos de paquetes, task runners y CI — y usa los comandos exactos definidos ahí. Nunca sustituyas por un equivalente genérico.

Dónde suele vivir la verdad:

Los workflows de CI son la fuente de mayor autoridad: lo que corre en el job que bloquea el merge es la definición de "verde" para ese repo.

Regístralo, no lo redescubras

Descubrir es barato una vez y un desperdicio cada vez. Después de la primera pasada, haz que el agente lo deje por escrito — en tu archivo de instrucciones del agente (AGENTS.md, CLAUDE.md o el equivalente de tu herramienta):

## Commands (discovered from CI + Makefile)
- Build: npm run build
- Type check: npm run typecheck
- Lint: npm run lint
- Tests (what CI runs): npm run test:ci

Ahora cada sesión futura arranca con los comandos canónicos ya en contexto, y un resultado en verde de verdad significa listo.

Movidas de usuario avanzado

• Compara lo local contra el CI. Pide al agente que liste cada paso run: del workflow que bloquea merges y marque cualquier chequeo que no estaba corriendo localmente. Los pasos faltantes son exactamente el origen de "pasa para el agente, falla en CI".
• Prefiere el wrapper del repo sobre sus piezas. Si existe make check y el CI lo invoca, ejecuta make check — no tu propia reconstrucción de sus partes. Los wrappers codifican orden y setup de entorno que no se ve desde afuera.
• Redescubre ante el drift. Los comandos cambian. Si un comando registrado falla con "unknown script" o "no such target", lo correcto es una nueva pasada de descubrimiento — no volver a un genérico adivinado.
• Captura el entorno, no solo el verbo. Anota el gestor de paquetes (npm vs pnpm vs yarn — revisa el lockfile), el punto de entrada de Python (tox, nox, hatch, pytest a secas) y las variables de entorno que exige el CI.

Recursos

• npm scripts — el campo scripts de package.json
• Writing your pyproject.toml — Python Packaging User Guide
• Manual de GNU Make — introducción a Makefiles y reglas
• Workflow syntax for GitHub Actions — jobs y pasos run
• AGENTS.md — un formato abierto para dar instrucciones de proyecto a agentes de código

Read this article in English