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.
La idea
Ese contexto reduce una clase de errores muy comun: el agente hace algo razonable en abstracto pero incorrecto para tu repo. Ejecuta el test equivocado, ignora un generador, edita codigo generado o aplica una convencion que el equipo no usa.
Que debe contener
- Comandos de instalacion, test y lint realmente usados.
- Estructura del repo y ownership basico.
- Patrones que debe copiar antes de crear abstracciones nuevas.
- Archivos generados o zonas que no debe editar manualmente.
- Politica de migraciones, seeds, fixtures y datos sensibles.
- Reglas de Git: ramas, commits, PRs y mensajes.
- Criterios de verificacion antes de dar una tarea por terminada.
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.
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.
Ejemplo de seccion util
Tests: usa npm test -- --runInBand para cambios en backend; usa npm run test:ui solo cuando cambien componentes. No ejecutes suites E2E completas salvo que el cambio toque checkout, login o permisos.
Este tipo de instruccion es mejor que ejecuta tests adecuados, porque reduce decision ambigua. El agente no necesita adivinar que significa adecuado en tu equipo.
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.
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.
Conclusion
Los archivos de instrucciones son infraestructura de colaboracion humano-agente. No sustituyen tests ni revision, pero hacen que el agente empiece cada tarea con el mapa correcto.
Un buen archivo no dice 'se cuidadoso'. Dice exactamente como se construye, prueba, revisa y limita el trabajo en ese repo.
Paraleliza investigacion y tareas acotadas. No paralelices criterio tecnico ni integracion final.
Fuentes y referencias
- OpenAI Codex: AGENTS.md
- Claude Code memory
- Claude Help: CLAUDE.md and better prompts
- Configuring Agentic AI Coding Tools
Esto es una version cross-posteada. Publicado originalmente en devaisemanal.com.
¿Te resulto util? Suscribete gratis a DevAI Semanal — cada martes, herramientas de IA para devs en espanol y sin ruido.
Top comments (0)