📁 Adopta una estructura predecible
Un repositorio predecible reduce el contexto que el agente necesita cargar y la cantidad de suposiciones que hace. Lo mismo vale para quien se incorporó al equipo ayer, las dos audiencias quieren lo mismo.
Cómo leer: el AGENTS.md en el centro señala a las cuatro carpetas: no copia su contenido. Las flechas van de afuera hacia adentro porque cada carpeta es responsable de su propia verdad; el mapa solo indica dónde buscar. Un AGENTS.md que intenta contenerlo todo se convierte en otra fuente desactualizada.
Previsible
Fácil de encontrar sin una visita guiada
Convención
Por encima de la configuración
Nombre
Es infraestructura
Dos audiencias
Humano nuevo y agente
🚧 Deja explícitos los límites entre módulos
Un agente respeta los límites que puede ver. Un límite que solo existe en la mente del arquitecto se cruzará y, peor aún, se cruzará de forma consistente y bien escrita, lo que dificulta detectarlo.
Ejemplo de estructura
/docs arquitetura.md dominios.md decisoes/ playbooks/ /specs pagamentos/ usuarios/ /skills criar-migracao/ revisar-api/ corrigir-bug/ /scripts validate.sh test-changed.sh AGENTS.md README.md
Cada carpeta tiene un responsable y un propósito. Un agente que entra en este repositorio sabe dónde buscar la spec, dónde buscar decisiones y qué ejecutar para validar.
💡 Consejo práctico
Escribe los límites como una regla ejecutable de importación (qué /pagamentos se puede importar, qué no). Así se convierte en un gate en el CI, no en una recomendación en un documento: exactamente el principio del módulo 3.3.
Visible
Si no, se pasa por alto
Verificable
Regla de importación
Contrato
Entre dominios
Alcance
La frontera limita la tarea
📚 Mantén la documentación cerca del código
La documentación versionada en el repositorio se revisa junto con el código y forma parte del contexto del agente sin esfuerzo. La documentación en herramientas externas se convierte en folclore en tres meses.
✓ Documentación que se mantiene viva
- ✓Vive en el repositorio y cambia en el mismo PR que el código
- ✓Registra decisiones y el porqué, no la sintaxis del framework
- ✓Lo bastante breve para leerlo completo
- ✓Hace referencia al código en lugar de repetir lo que hace
✗ Documentación que estorba
- ✗Describe el sistema que se pretendía tener, no el que existe
- ✗Duplica información que ya está en el código
- ✗Está en tres lugares, con tres versiones diferentes
- ✗Nadie sabe cuál es la actual, ni siquiera el agente
En el repo
Inicia la revisión
Decisión
Registra el porqué
Desactualizada
Peor que no tenerlo
Breve
La que se lee es la que sirve
⌨️ Estandariza los comandos y las pruebas locales rápidas
Un comando por intención, igual en la máquina de todos y en CI. Es lo que permite al agente cerrar el ciclo por su cuenta, sin un comando predeterminado, inventa uno, y lo inventa mal.
🧪 Ejercicio copiable — auditar la legibilidad de tu repositorio
Objetivo: descubrir qué no puede deducir hoy un agente de tu repo. Ejecútalo en una sesión limpia, sin dar ninguna explicación previa.
Você acabou de entrar neste repositório e não tem nenhum contexto além dele. Não pergunte nada agora; responda com o que conseguir deduzir dos arquivos. 1. o que este sistema faz? (3 linhas) 2. como eu instalo, testo, linto e builduei? (comandos exatos) 3. onde ficam: regras de negócio, decisões de arquitetura, specs? 4. quais são as fronteiras entre módulos e o que NÃO pode importar o quê? 5. o que eu NÃO devo alterar sem aprovação? 6. liste tudo que você teve que SUPOR para responder acima. Seja honesto no item 6 — é o item mais importante da resposta.
Cómo verificar: la lista del punto 6 es tu backlog de legibilidad. Cada suposición es algo en lo que el siguiente agente (y la próxima persona contratada) se equivocará. Corrige el repositorio, no el prompt.
Un comando
Por intención
Local = CI
Mismo resultado
Rápido
Habilita el ciclo
Suposición
Es tu backlog
📄 Escribe el AGENTS.md como mapa
El AGENTS.md puede contener una visión general del sistema, los comandos principales, las reglas del proyecto, la ubicación de la documentación, las limitaciones, los criterios de calidad, las acciones prohibidas y referencias a skills y playbooks. No debe concentrar todo el conocimiento — debe funcionar como un mapa.
🧭 Prueba del buen AGENTS.md
- •¿Cabe en una pantalla y media? Si no, estás duplicando otra fuente.
- •¿Incluye los comandos exactos, listos para copiar, sin «probablemente sea npm test»?
- •¿Las prohibiciones están explícitas y destacadas?
- •¿Apunta a dónde está la verdad de cada tema, en lugar de repetirla?
- •¿Se revisó el último trimestre?
⚠️ Atención
Un AGENTS.md de 900 líneas no se lee por completo, ni por humanos ni de manera provechosa por un agente que necesita encontrar rápido lo que importa. Una instrucción que nadie lee es una instrucción que no existe, con el agravante de dar una falsa sensación de control.
Mapa
Apunta, no describe
Comandos
Exactos y fáciles de copiar
Prohibiciones
Destacado
Revisado
Como código
🎯 Garantiza fuentes únicas de verdad
Ante dos fuentes en conflicto, el agente elige una —en silencio. Descubres cuál durante la revisión, y normalmente en el peor momento posible.
Un responsable por tema
Los comandos van en AGENTS.md; el contrato, en la spec; la decisión, en /docs/decisoes. Quien necesite el tema consulta al responsable.
Hacer referencia en lugar de copiar
Toda copia diverge: es cuestión de tiempo. Un enlace al archivo correcto envejece mucho mejor que un fragmento pegado.
Eliminar lo obsoleto es trabajo de verdad
Un documento antiguo no desaparece por sí solo y sigue entrando en el contexto del agente. Eliminar la versión vieja vale más que escribir la nueva.
Verificación rápida: ¿cuál es el mejor AGENTS.md?
Un responsable
Por tema
Hacer referencia
Nunca copiar
Eliminar
Lo obsoleto estorba
Conflicto
Él elige por su cuenta
📌 Resumen del módulo
Próximo módulo:
4.3 - Overengineering y deuda técnica generada por IA.