//En contra de las instrucciones generales

Voy a empezar con una herejía: estoy en contra de las instrucciones y reglas generales.

No de su existencia, sino de su abuso.

Durante meses tratamos ficheros como AGENTS.md, CLAUDE.md o copilot.instructions como si fueran tablas de la ley. Y tenía sentido: eran la forma más directa de darle contexto estable a un agente que, sin guía, se comportaba como un junior en su primer día en un monorepo de veinte años.

Pero ese patrón, llevado al extremo, empieza a romper por sitios dolorosos que penalizan la productividad.

El problema no es la idea, es la carga permanente

Los ficheros de instrucciones generales se inyectan en todas las conversaciones. Eso parece cómodo, hasta que miras métricas, como hicieron en este estudio de varias universidades: On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents

Cada línea extra compite por ventana de contexto con lo que sí importa en el turno actual: el bug que estás depurando, el diff que quieres revisar o la spec de la tarea. Lo pagas en tres monedas:

• más latencia por interacción,
• más coste por cantidad de tokens,
• menos foco efectivo del agente.

Es paradójico: escribimos reglas para mejorar la calidad y acabamos degradando rendimiento y precisión en tareas concretas.

Y esto no es solo teoría, como te decía, lo han medido y se nota cuando el agente tarda más en entrar en materia, repite obviedades o se aferra a mandamientos desactualizados mientras ignora pistas frescas del código. Es decir, como era de esperar, se comporta peor con ficheros grandes o defectuosos que sin nada.

La segunda trampa: el contexto también envejece

Porque hay otro elefante rosa en el que no debes pensar: esos ficheros mienten.

No porque el equipo quiera engañar, sino porque la realidad cambia antes que la documentación. Como nos pasa a los humanos: contamos una verdad que fue válida ayer, pero ya no describe el sistema de hoy.

Contexto falso es peor que contexto ausente.

Sin contexto, el agente pregunta o explora. Con contexto incorrecto, ejecuta con confianza en la dirección equivocada. El error llega más tarde y cuesta más corregirlo.

Esta es la razón por la que tantos repositorios “bien documentados” producen salidas mediocres con IA: el problema ya no es la cantidad de guía, es su nivel de verdad.

Entonces, ¿los borramos?

La respuesta corta: no; trabaja un poco y conviértelos en contratos mínimos y vivos.

Un buen fichero global no intenta explicar todo. Solo define lo que debe ser estable entre tareas:

• qué problema resuelve el producto (en dos o tres líneas),
• qué stack y herramientas son no negociables,
• cómo se compila, valida y empaqueta el trabajo (build, test, lint, cargo, make),
• qué convenciones de arquitectura y estilo sí son críticas,
• qué límites operativos del entorno no se deben violar.
• qué rarezas o usos especiales hemos adoptado o legado en este proyecto.

El resto no pertenece al nivel global. Pertenece a skills, specs, ADRs o la auténtica y única verdad: el código.

Manual + automático: el equilibrio que sí escala

Aquí está el punto práctico: estos ficheros deben crearse a mano y mantenerse a máquina.

Crearlos a mano, porque necesitas criterio de producto y oficio técnico para decidir qué es verdaderamente transversal. Evita los comandos /init que te ofrecen los agentes. Si ellos lo pueden detectar al principio, lo podrán hacer también más tarde; luego escribe tú, eso que no es tan evidente.

Mantenerlos a máquina, porque los cambios frecuentes del repositorio no pueden depender de memoria humana ni de disciplina heroica. Una vez creado, sí que conviene pedir a un agente que revise los cambios de una sesión y vea qué le hubiera sido útil saber para próximas ocasiones.

Si tu flujo con agentes ya puede:

• detectar comandos que cambian,
• resumir nuevas convenciones de carpetas,
• actualizar enlaces internos rotos,
• proponer diffs de instrucciones tras un PR grande,

entonces también puede mantener la parte mecánica del contexto global sin inflarlo.

Y aún así, recuerda el mantra human in the loop: revisa y decide si ese cambio puede ir en una skill de menor nivel. O mejor todavía, si esa rareza se puede evitar cambiando algo en el código o en el tooling.

El tip 100*100

Si quieres una regla simple para empezar, yo uso el 100*100:

• menos de 100 líneas,
• y cada línea por debajo de 100 caracteres.

No es una ley física, sino una restricción de diseño que te debe hacer reflexionar si estás metiendo demasiado contenido en todos los contextos.

Te obliga a priorizar, evita párrafos manifiesto y reduce el riesgo de meter detalles que deberían vivir en otro artefacto más cercano a la tarea.

Además, tiene un efecto secundario muy sano: cuando no cabe, discutes qué sobra. Y esa conversación mejora más al equipo que cualquier prompt brillante.

Señales de que tu AGENTS.md se está volviendo tóxico

Si se cumplen dos o más de estas, toca podar:

• contiene decisiones que el código ya contradice,
• replica documentación de README o de la wiki,
• mezcla normas estables con tickets temporales,
• nadie en el equipo sabe quién lo actualizó por última vez,
• el agente cita reglas globales para justificar malas decisiones locales.

Un fichero global no debería competir con la realidad del repositorio. Debería ayudar a encontrarla antes.

Conclusión

Estamos dejando atrás la fase de entusiasmo donde todo se resolvía con mejor prompt y más context. Entramos en una fase más profesional, de context engineering donde la clave está en tener las instrucciones correctas, en el nivel correcto y con mantenimiento continuo.

No estamos eliminando reglas. Estamos dejando de idolatrarlas y sustituyéndolas por habilidades.

Por cierto próximamente le caerá rant también a los skills. Stay tuned.