AGENTS.md, CLAUDE.md y memoria de proyecto: cómo dar contexto a agentes de código
Los agentes de codigo no fallan solo por el modelo. Fallan porque no saben como se trabaja en tu repo. Las instrucciones de proyecto son parte del sistema.
Los agentes de codigo no fallan solo por el modelo. Fallan porque no saben como se trabaja en tu repo. Las instrucciones de proyecto son parte del sistema.
Un buen `AGENTS.md` o `CLAUDE.md` no intenta ensenar a programar al modelo. Le ensena como se trabaja en ese proyecto: comandos, limites, convenciones, arquitectura, pruebas, estilo de commits y zonas que no debe tocar sin permiso.
Que no debe contener
No metas documentacion completa. Un archivo de instrucciones demasiado largo se convierte en ruido. Tampoco incluyas secretos, tokens, informacion personal o decisiones temporales que caducan rapido.
La memoria de proyecto debe ser estable. Si una regla solo aplica hoy, mejor ponerla en el ticket o en el prompt. Si aplica siempre, merece vivir en el archivo de contexto.
Checklist
Precedencia y alcance
El problema dificil no es escribir instrucciones, sino saber cuales aplican cuando hay varias. Codex, Claude Code y otros agentes pueden leer instrucciones globales, de proyecto o de subdirectorio. Eso permite precision, pero tambien conflictos.
La regla practica es jerarquia clara: global para preferencias personales, raiz del repo para normas de proyecto, subdirectorios para excepciones locales. Si dos archivos se contradicen, el agente puede improvisar. Evitalo escribiendo instrucciones concretas y no filosoficas.
Mantenimiento
Revisa las instrucciones cada vez que cambie el workflow. Si migras de Jest a Vitest y el archivo sigue diciendo Jest, el agente obedecera una mentira. Si cambias arquitectura y no actualizas ownership, empezara a tocar sitios equivocados.
Puntos a revisar
Lo que conviene comprobar
Tambien conviene auditar instrucciones despues de fallos repetidos. Cuando un agente comete el mismo error dos veces, no siempre hace falta un prompt mas largo; a veces falta una regla de proyecto corta y verificable.
Fuentes y referencias
También te puede interesar
Claude Code: guia completaSerena MCP: busqueda semanticaVS Code y Copilot Co-authored-byRecibe una lectura semanal de herramientas IA para devs
Cada martes: Claude Code, Cursor, Copilot, MCP, agentes y herramientas nuevas. En español y sin ruido.
Suscribirme gratis
