Escríbelo para la máquina

Lo más útil que puedes hacer para que los agentes de programación con IA funcionen mejor no es un prompt mejor ni un modelo mejor. Es un archivo de texto plano en la raíz de tu repo llamado AGENTS.md, y la mayoría de quienes construyen con agentes todavía no han escrito uno.

Esta es la razón por la que importa ahora. Hace un año cada herramienta tenía su propio archivo especial — .cursorrules, CLAUDE.md, una config de Copilot, lo que quisiera Devin. Escribías las convenciones de tu proyecto cinco veces o no las escribías. Eso se acabó. A principios de 2026, AGENTS.md lo leen de forma nativa Claude Code, el Codex CLI de OpenAI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, Windsurf y Amazon Q — lo más cercano a un formato universal de instrucciones para agentes de programación que tiene la industria. Un solo archivo, y casi todos los agentes que abren tu repo lo leen primero.

Déjame defender por qué deberías escribirlo de verdad, porque la ventaja es despareja.

Qué es, en pocas palabras

AGENTS.md es un archivo Markdown que pones en la raíz de tu proyecto. Es la nota que le dejarías a un colaborador nuevo y competente que nunca ha visto tu base de código: cómo compilarla, cómo correr los tests, cuáles son las convenciones, qué no tocar. El agente lo lee antes de empezar a trabajar y lo trata como instrucciones permanentes — así escribes el contexto una vez, en lugar de volver a teclearlo en cada prompt durante el resto del proyecto.

Ese es todo el truco. No es un framework nuevo ni un prompt ingenioso. Es escribir las cosas que ya sabes sobre tu proyecto para que la máquina también las sepa.

Por qué funciona tan bien

Los agentes no fallan porque sean tontos. Fallan porque trabajan a ciegas — no pueden ver las reglas no escritas que todos los humanos de tu equipo absorbieron por osmosis. El agente no sabe que siempre usas pnpm, nunca npm. No sabe cuál es el único módulo que nadie toca sin una revisión. No sabe que tus tests tienen que pasar un umbral de cobertura antes de que algo salga a producción. Así que adivina, y un tercio de las veces adivina mal.

Un buen AGENTS.md elimina el adivinar. Es la misma idea detrás de por qué una spec le gana a un prompt: el artefacto duradero y reutilizable es el contexto escrito, no la instrucción desechable. Y se acumula — cada ejecución de un agente, en cada herramienta, en cada rama, parte del mismo entendimiento compartido en lugar de arrancar de cero.

Qué va dentro de verdad

Mantenlo corto y concreto. Los que funcionan se leen como una lista de verificación, no como un ensayo:

• Cómo compilar y ejecutar. Los comandos exactos — instalar, servidor de desarrollo, build. Deja claro pnpm vs npm, la versión correcta de Node, cualquier paso de configuración que no sea obvio.
• Cómo testear. El comando de tests, el umbral de cobertura, «todo verde antes de hacer commit». Los agentes son mucho más útiles cuando pueden correr los tests y ver el fallo real por sí mismos.
• Las convenciones que importan. Nombres, las reglas de lint/formato, «imita el código de alrededor». Lo que de otro modo un revisor te devolvería.
• Qué no tocar. Archivos generados, el único módulo frágil, los secretos, cualquier cosa donde «lo refactoricé para ayudar» sea un desastre.
• La forma del proyecto. Un mapa de una línea de dónde vive cada cosa, para que el agente no tenga que reconstruir tu estructura por ingeniería inversa en cada tarea.

Sáltate la filosofía. El agente no necesita tu declaración de misión; necesita los comandos, las restricciones y las minas.

La conclusión

Gastamos mucha energía en prompts, que son por tarea y desaparecen, y casi nada en el único artefacto que es por proyecto y permanece. AGENTS.md pasó de ser un truco específico de cada herramienta a un estándar casi universal precisamente porque el problema que resuelve es el de verdad: los agentes trabajan a ciegas, y la solución es dejar de obligarlos a adivinar lo que tú ya sabes.

Así que antes de la próxima vez que apuntes un agente a tu repo, dedica la hora. Escribe cómo compilarlo, cómo testearlo, cuáles son las reglas y qué dejar en paz. Es uno de esos raros consejos de IA que casi no cuesta nada, funciona en todas las herramientas que vayas a usar y se paga solo en cada ejecución. Escríbelo para la máquina — la está leyendo.