Blog Desarrollo IA para desarrollo
GuíaTu agente programa sin conocer tu proyecto: qué poner en AGENTS.md y CLAUDE.md
Qué instrucciones conviene conservar para que un asistente trabaje con las reglas reales del proyecto.
Un agente necesita conocer cómo funciona el proyecto, qué debe respetar y cómo comprobar un cambio. Un archivo de instrucciones mantiene ese contexto disponible entre tareas.
Dos nombres que conviene reconocer
AGENTS.md es un formato abierto en Markdown para orientar agentes de programación. Puede describir estructura, comandos de ejecución, pruebas y convenciones. Complementa la documentación destinada a las personas.
CLAUDE.md proporciona instrucciones persistentes a Claude Code. La documentación actual también contempla AGENTS.md, aunque su carga depende de la versión, la configuración y los archivos existentes. Tener ambos no garantiza que se lean los dos: hay que comprobar el comportamiento de la herramienta utilizada.
Qué información pondría primero
- Contexto: qué hace el sistema y dónde están sus partes importantes.
- Reglas: restricciones del negocio y decisiones que deben conservarse.
- Ejecución: comandos comprobados para iniciar y validar el proyecto.
- Alcance: archivos generados, componentes heredados y límites de cada tarea.
Por ejemplo, «no cambies el formato de este identificador porque lo consume otra aplicación» aporta más contexto que «escribe código de calidad». La instrucción debe explicar una condición verificable.
Un documento breve que se mantiene
Evitaría copiar manuales completos o acumular instrucciones contradictorias. Mantendría las reglas compartidas en una referencia principal y señalaría documentos específicos cuando el contexto lo requiera.
También comprobaría que los comandos continúan funcionando. Una guía antigua puede dirigir al agente hacia una prueba que ya no representa el proyecto.
Las instrucciones no sustituyen los controles
Escribir una regla no demuestra que un cambio la respete. Revisaría las diferencias y ejecutaría las comprobaciones relevantes. Los permisos del entorno y las decisiones de publicación deben seguir definidos fuera del texto.
No incluiría claves, contraseñas ni datos personales como contexto de trabajo. El archivo debe orientar el proceso y ayudar al equipo a revisar lo realizado, no convertirse en un depósito de información sensible.
Fuentes consultadas el 4 de octubre de 2026. Los ejemplos son ilustrativos; las recomendaciones expresan una lectura profesional.