Tu repo no está listo para un agente de IA

Le pedís al agente que arregle un bug. Vuelve a los dos minutos con los archivos cambiados y una frase: “los tests deberían pasar ahora”. Deberían. No los corrió. Probó npm test, le falló por un motivo que no entendió, y siguió adelante igual. Así que el que tiene que verificar sos vos — que era exactamente el trabajo que querías delegar.

Eso no se arregla escribiendo un prompt mejor. Se arregla del otro lado, en lo que el agente se encuentra cuando abre tu proyecto: si puede correr los tests sin adivinar, si el error le dice qué pasó, si el mismo concepto se llama igual en todos lados.

Abajo están las seis cosas que más diferencia hacen, ordenadas por lo que rinden. Ninguna es una reescritura y ninguna lleva más de una tarde; la primera son treinta minutos y es la que habilita a todas las demás. Y sirven igual con Claude Code, Codex, Copilot o Cursor, porque los cuatro trabajan del mismo modo: leen, ejecutan un comando, miran qué devolvió y corrigen.

1. Un comando por tarea, y que funcione recién clonado

Un agente no sabe que los tests de tu proyecto necesitan una variable de entorno cargada, un contenedor de base de datos levantado y un parámetro extra para que no corran en paralelo y se pisen entre sí. Va a probar npm test, va a ver que falla, y a partir de ahí hace una de dos cosas: inventa otra forma de correrlos, o directamente entrega el código sin verificarlo — el caso del principio.

La regla es que las cuatro operaciones básicas sean un solo comando, sin pasos previos:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "test": "vitest run",
    "check": "astro check && eslint ."
  }
}

Si hace falta levantar algo antes, que lo levante el script, no el que lo ejecuta. El agente corre comandos; no lee el README para enterarse de que antes hay que hacer otra cosa.

2. Tests que terminen en segundos

El bucle de un agente es escribir, correr, mirar el resultado y corregir. Ese bucle es lo que hace que entregue algo verificado en vez de algo plausible. Y es lo primero que se rompe cuando la suite tarda cuatro minutos: el agente igual la corre, pero cada iteración te cuesta cuatro minutos de espera y un contexto lleno de salida de tests.

Lo que más rinde es separar la suite rápida de la lenta:

{
  "test": "vitest run test/unit",
  "test:todo": "vitest run"
}

Con eso el agente itera contra los tests unitarios —segundos— y la suite completa queda para el final, o para la integración continua, que la corre sin que nadie espere. No hace falta que todo sea rápido: alcanza con que exista un subconjunto rápido y confiable que se pueda correr después de cada cambio.

3. Errores que dicen qué pasó

Esto es lo que más se subestima. Cuando algo falla, lo único que el agente tiene para trabajar es el texto del error. No ve tu pantalla, no tiene intuición sobre el proyecto, no sabe que ese módulo siempre da problemas los lunes. Si el mensaje no dice qué pasó, va a adivinar — y adivina como cualquiera: probando cosas.

// El agente no puede hacer nada con esto:
throw new Error('Configuración inválida');

// Con esto arregla el problema en un intento:
throw new Error(
  `Falta PUBLIC_API_URL en .env (leído desde ${rutaEnv}). ` +
  `Definidas: ${Object.keys(config).join(', ')}`
);

La pregunta para escribir un mensaje de error es: ¿alcanza esto para saber qué hacer, sin abrir el código? Si la respuesta es no, le falta el valor que falló, el lugar donde falló, o ambos. Es la misma regla de siempre para cualquiera que reciba una alerta a las tres de la mañana; lo que cambia es que ahora también la lee un agente, muchas más veces por día.

4. Un concepto, un nombre

Si en tu proyecto lo mismo se llama user en la base, usuario en el dominio, account en la API y cuenta en el front, vos te acostumbraste. El agente no: cada búsqueda le trae la mitad de los lugares, tiene que leer tres archivos de más para entender que son la misma cosa, y cuando escribe código nuevo elige cualquiera de los cuatro nombres — sumando un quinto dialecto al problema.

Un proyecto donde cada concepto tiene un solo nombre, y una búsqueda de texto lo encuentra entero al primer intento, le ahorra al agente la parte más cara de su trabajo: localizar dónde está lo que tiene que tocar. Y de paso se lo ahorra al próximo que entre al equipo.

No hace falta una migración masiva para arreglarlo: alcanza con elegir el nombre bueno de cada concepto, dejarlo escrito en el AGENTS.md que veremos en un momento, y renombrar lo que se vaya tocando. El refactor de renombrar de tu editor lo hace de forma exacta y gratis — y esa es una de las tareas donde no conviene usar IA, porque no hay nada que interpretar.

5. Tipos y validación en los bordes

Todo lo que el compilador puede garantizar es una clase de error que el agente no puede cometer en silencio. No es un argumento sobre tipado estático: es que el chequeo de tipos es una verificación que corre en segundos, no necesita que nadie la interprete, y le dice al agente exactamente qué línea está mal.

Donde más rinde es en los bordes del sistema —lo que entra por una API, lo que se lee de un archivo de configuración, lo que viene de un formulario—, porque es justo donde un agente no tiene forma de saber qué forma real tiene el dato:

// El borde sin validar: el agente asume que `precio` es número
// porque en el ejemplo que vio era número. A veces llega como "12.50".
const { precio } = await respuesta.json();

// El borde declarado, acá con Zod (sirve cualquier librería de validación):
// si llega un texto donde esperabas un número, falla en esta línea y dice por qué.
const Pedido = z.object({ precio: z.number(), moneda: z.enum(['ARS', 'USD']) });
const { precio, moneda } = Pedido.parse(await respuesta.json());

La segunda versión convierte un bug silencioso —el que aparece tres pantallas después, cuando alguien suma dos precios y obtiene "12.5010.00"— en un error con nombre y apellido, en la línea donde entró el dato. Esa es la clase de error que un agente arregla solo.

6. Un AGENTS.md, y corto

AGENTS.md es un archivo en la raíz del proyecto donde va lo que el agente no puede deducir leyendo el código: los comandos, las convenciones que se salen de lo estándar, las decisiones propias del proyecto. La gracia es que hoy lo leen las distintas herramientas del mercado, así que no queda atado a la que uses vos: si un compañero prefiere otra, encuentra las mismas reglas.

Si usás Claude Code, CLAUDE.md cumple la misma función y tiene prioridad; lo más simple es tener uno de los dos y, si necesitás ambos, que uno sea un enlace al otro.

La tentación es escribir tres pantallas. Es exactamente lo que no hay que hacer: todo lo que ponés ahí se carga en cada conversación, y cuanto más largo, más se diluyen las reglas que importan entre las que no. Ya escribimos en detalle qué conviene poner y qué no, pero el resumen es una pregunta por línea: si saco esto, ¿el agente se equivoca? Si no, se borra.

Lo que no hace falta

• Documentar el proyecto archivo por archivo. Es lo primero que se le ocurre a todo el mundo y es trabajo perdido: el agente lee el código más rápido de lo que vos escribís la descripción, y la descripción queda desactualizada en dos semanas.
• Reescribir el proyecto para que sea “amigable con la IA”. Nada de esta lista es una reescritura. Son seis cosas que ya querías tener por razones que no tienen nada que ver con la IA.
• Un AGENTS.md por carpeta. Salvo que tengas varios proyectos grandes dentro del mismo repositorio, uno solo en la raíz alcanza y se mantiene.

El repo es la mitad del prompt

Lo que se le puede pedir a un agente está limitado por lo que el repositorio le deja hacer. Sin un comando para correr los tests, no hay forma de pedirle que verifique. Sin errores que digan qué pasó, no hay forma de pedirle que arregle sin adivinar.

Si vas a hacer una sola de las seis, que sea que test y check funcionen en un comando, recién clonado el repositorio. Es media hora de trabajo y es la que habilita todo lo demás: a partir de ahí el agente puede verificar lo que escribió, que es la diferencia entre revisar código terminado y revisar código plausible.