Un archivo AGENTS.md que consigue que Claude Code y Codex
Un archivo AGENTS.md que consigue que Claude Code y Codex se comporten con el rigor de un ingeniero senior.
Establece un conjunto de normas para que el agente organice mejor su enfoque, realice modificaciones más acotadas y compruebe los resultados antes de considerar una tarea completada.
¿Qué normas recoge el archivo?
– Pensar y planificar antes de escribir ninguna línea de código
– Aplicar únicamente el cambio estrictamente necesario
– Repartir el trabajo entre subagentes
– Asumir la responsabilidad del bug
– Revisar el resultado antes de cerrar la tarea
– Registrar cada corrección relevante
Codex lo interpreta de forma nativa; Claude Code también puede aprovecharlo cuando no existe un CLAUDE.md en el proyecto.
Cada corrección importante puede convertirse en una regla nueva, de modo que el archivo evoluciona y se ajusta progresivamente a tu forma de trabajar.
Puedes copiarlo directamente en tu AGENTS.md desde aquí: plantilla de AGENTS.md para Claude Code y Codex.
Si utilizas Claude Code o Codex y quieres mejorar cómo se comportan dentro de tus proyectos, compártelo con tu red.AGENTS.md: instrucciones estructuradas para que Claude Code y Codex operen como ingenieros senior
Resumen técnico
El archivo AGENTS.md define reglas de comportamiento que leen de forma nativa Codex y, en ausencia de CLAUDE.md, también Claude Code. Las reglas establecen: planificación obligatoria antes de modificar código, aplicación del cambio mínimo necesario, delegación de tareas mediante subagentes, trazabilidad del bug hasta su resolución, verificación explícita antes de marcar la tarea como completada y persistencia de cada corrección relevante como nueva regla. El archivo es acumulativo: cada corrección importante se convierte en una regla adicional, ajustando el comportamiento del agente al workflow específico del equipo.
Análisis de implicaciones
Introducir AGENTS.md en un repositorio traslada parte del control de calidad al propio agente, reduciendo la dependencia de revisiones manuales repetitivas. La capacidad de dividir trabajo entre subagentes permite paralelizar tareas de refactorización o testing. La limitación más relevante: el comportamiento resultante depende directamente de la calidad y precisión de las reglas definidas. Un archivo mal redactado genera instrucciones ambiguas que el agente interpreta de forma inconsistente. La compatibilidad cruzada entre Codex y Claude Code reduce la duplicidad de configuración entre herramientas.
Aplicación práctica
El archivo se coloca en la raíz del repositorio como AGENTS.md. Codex lo lee de forma nativa en cada sesión. Claude Code lo toma como referencia cuando no existe un CLAUDE.md. Ejemplo de regla concreta: «Antes de modificar cualquier función, describe el cambio y su impacto en dependencias». Otro caso real: tras identificar un bug recurrente en manejo de errores asíncronos, se añade la regla «Verifica siempre el manejo de promesas rechazadas antes de cerrar la tarea». El archivo crece con el proyecto y acumula criterio técnico del equipo de forma directa.
Contexto del sector
La estandarización del comportamiento de agentes mediante archivos de configuración en repositorio sigue el mismo patrón que ESLint, .editorconfig o Prettier: reglas versionadas junto al código. Con la proliferación de herramientas como Codex, Claude Code, Devin o GitHub Copilot Workspace, definir comportamiento explícito en repositorio se convierte en práctica estándar para mantener consistencia entre agentes y equipos distribuidos.
Artículo relacionado