Divide las instrucciones en varios archivos
Te pusiste serio con el harness y metiste todas las reglas en un AGENTS.md. Seiscientas líneas después, el agente va peor. Bienvenido a la trampa del archivo gigante.
Un buen cocinero no deja todas las especias, sartenes y cacharros en la encimera. Las tres cosas que usa a todas horas están a mano; el resto vive en cajones etiquetados que abre solo cuando una receta lo pide. El archivo de entrada es la encimera, corto y esencial. Los docs por tema son los cajones.
Por qué se pudre el monolito
El ciclo parece razonable: el agente comete un error, añades una regla, repites. Pero el efecto acumulado es destructivo:
- Presupuesto de contexto, un archivo de 600 líneas puede quemar 10, 20k tokens antes de que el agente lea un solo archivo de código.
- Perdido en el medio, una restricción dura enterrada en la línea 300 se ignora de forma fiable; los modelos usan el inicio y el final de un texto largo mucho mejor que el medio.
- Colapso de prioridad, una regla innegociable («nunca usar
eval()») se ve igual que una mera preferencia, así que el agente no distingue una línea roja de una sugerencia. - Deriva de contradicciones, reglas añadidas con meses de diferencia chocan en silencio y el agente elige una al azar.
flowchart TB Mono["Un AGENTS.md de 600 lineas"] --> Bug["Hasta un fix pequeno lee todas las reglas de deploy"] Bug --> Miss["Regla critica enterrada en el medio, ignorada"] Router["AGENTS.md corto"] --> Topic["Lee docs de API o DB solo cuando hace falta"] Topic --> Room["Mas contexto libre para el codigo real"]
El archivo de entrada es un enrutador
Mantén AGENTS.md corto, de 50 a 200 líneas, con solo un resumen del proyecto en una línea, los comandos de primer arranque, un puñado de restricciones innegociables y enlaces a docs por tema con una condición «lee esto cuando…».
# AGENTS.md, entrada / enrutador Resumen: control plane en Rust; agentes en tmux. Setup: make setup && make test Reglas duras: sin secretos en el código; todo PR pasa make check Docs por tema: docs/api.md # al añadir endpoints docs/tmux.md # al tocar sesiones docs/testing.md # al escribir tests
Cada doc por tema tiene 50, 150 líneas y solo se carga cuando la tarea lo necesita. La información que va junto al código (tipos, comentarios de interfaz) se queda en el código, donde el agente la ve de forma natural.
Gestiona las reglas como dependencias
Cada regla debe registrar por qué se añadió, cuándo aplica y cuándo se puede quitar. Audita con regularidad y borra las muertas, una regla sin usar no es gratis, es ruido que baja la relación señal-ruido de todo lo de su alrededor. Si una regla debe vivir sí o sí en el archivo de entrada, ponla arriba del todo o abajo del todo, nunca en el medio.
Cómo lo aplica Agentum
El .agentum-harness/AGENTS.md de Agentum es el archivo de entrada bien hecho: corto y centrado en el protocolo, trabaja solo la función que te entregan, haz el cambio más pequeño que pase la puerta, detente y espera, nunca toques .agentum-harness/. El detalle por función no vive ahí; vive en el campo description de cada función dentro de feature_list.json, y el motor carga exactamente una a la vez. Enrutado, no enciclopedia.
Puntos clave
- Un archivo gigante de instrucciones baja el rendimiento: presupuesto malgastado, reglas enterradas, contradicciones.
- Haz del archivo de entrada un enrutador corto; lleva el detalle a docs por tema cargados a demanda.
- Aprovecha la posición: lo crítico arriba o abajo, nunca en el medio.
- Audita las reglas como dependencias, cada una necesita un motivo, un alcance y una caducidad.
Ejercicios
- Mide el ruido. Para un fix típico, ¿qué fracción de tu archivo de instrucciones es relevante? Mueve el resto a docs por tema.
- Revisa el medio. Encuentra una regla crítica enterrada a mitad de archivo y muévela arriba o a un doc por tema.