Existe una costumbre perezosa en la adopción de agentes de IA en equipos de ingeniería: crear un AGENTS.md (o CLAUDE.md, o .cursorrules) con una línea del tipo "OBEY Clean Code by Robert C. Martin" y considerar el trabajo hecho. La intuición es razonable, el modelo conoce el libro, fue entrenado en miles de blogs sobre el tema, debería bastar con mencionarlo. No basta. Y ahora hay medición.
Maciej Ciemborowicz, autor del repositorio ciembor/agent-rules-books (1.4k stars, MIT), publicó un experimento incómodamente claro. Misma codebase de partida (un helpdesk CLI deliberadamente vibe-coded), mismo modelo (GPT-5.5, reasoning alto), mismo plan de refactor, solo cambia el contenido del AGENTS.md. Una branch usa solo la línea "obey Clean Code". La otra usa el conjunto de reglas mini destilado del libro. El resultado, juzgado por ChatGPT ante la pregunta "¿qué código implementa mejor los principios de Ousterhout?", fue 74 contra 46. Veintiocho puntos de calidad arquitectónica más, por el único costo de cambiar una línea de texto por unas 50 líneas de reglas concretas.
Por qué solo citar el libro no funciona
El reflejo intuitivo es pensar que el modelo "sabe" Clean Code porque el libro entero está en el corpus de entrenamiento. Saber y aplicar consistentemente no son la misma cosa. El LLM tiene activaciones dispersas sobre el libro, referencias, citas, ejemplos aislados, blogs sobre el libro, posts que discrepan del libro, contradicciones entre el Uncle Bob de 2008 y el Uncle Bob de 2020. Pedir "obedece Clean Code" deja que el modelo navegue esa nube entera sin ancla operativa. Lo que sale es un promedio ponderado de lo que circula en el corpus, no las decisiones específicas que el libro defiende.
En cambio, un conjunto de reglas concretas hace tres cosas que la mención sola no hace. (1) Reduce la entropía, el modelo no necesita adivinar qué interpretación de "clean" usar, recibe la interpretación lista. (2) Cabe en la atención, 50 líneas de reglas están siempre en el contexto, el libro entero nunca lo está. (3) Resiste la dilución de sesiones largas, cuanto más itera el agente, más se aleja la mención al libro del span de atención actual; una regla explícita en AGENTS.md vuelve a ser releída en cada decisión de archivo.
Lo que el repo entrega en la práctica
El agent-rules-books destila 13 libros canónicos de ingeniería de software en conjuntos de reglas listos para pegar en AGENTS.md, en CLAUDE.md, en Cursor rules, o para volverse skills de Claude Code. La lista es exactamente la que esperarías ver en el estante de quien se toma la ingeniería en serio:
- Clean Code (Robert C. Martin), legibilidad local, nombres, funciones pequeñas, responsabilidad única
- Clean Architecture (Martin), fronteras estables, regla de dependencia, aislamiento de detalles
- A Philosophy of Software Design (Ousterhout), módulos profundos, interfaces simples, reducción de carga cognitiva
- Code Complete (McConnell), construcción disciplinada, defensive programming, control de flujo
- Refactoring (Fowler), pasos pequeños, code smells, separación de refactor y feature
- Refactoring.Guru, catálogo práctico de smells y técnicas de tratamiento
- Patterns of Enterprise Application Architecture (Fowler), Repository, Unit of Work, Data Mapper, etc.
- Domain-Driven Design (Evans), modelado de dominio, bounded contexts, ubiquitous language
- Domain-Driven Design Distilled (Vernon), DDD sin ceremonia excesiva
- Implementing DDD (Vernon), aggregates, eventos de dominio, integraciones
- Designing Data-Intensive Applications (Kleppmann), replicación, partición, consistencia, schema evolution
- Release It! (Nygard), circuit breaker, bulkhead, timeout, backpressure
- The Pragmatic Programmer (Hunt/Thomas), DRY, ortogonalidad, automatización, feedback rápido
- Working Effectively with Legacy Code (Feathers), characterization tests, seams, dependency breaking
Cada uno viene en tres tamaños: full (canónico, 12-60KB), mini (recomendado para uso real, 3-8KB) y nano (fallback de presupuesto ajustado, 1-3KB). Esta estratificación no es estética. Es la admisión honesta de que el contexto es un recurso finito y que cada byte del system prompt compite con la tarea real.
Full vs Mini vs Nano: la economía del presupuesto de contexto
Aquí está el detalle que mucha gente ignora: el tamaño del conjunto de reglas altera la economía de la sesión entera. Un AGENTS.md con 60KB de Clean Architecture full + DDD full + DDIA full es impresionante de leer, y patológicamente caro de usar. Cada turno del agente paga esos tokens en latencia y en accuracy points desplazados de la tarea real. Es exactamente el mismo patrón que el post sobre el costo de la abstracción ritualística denunció: ceremonia que no cabe en el presupuesto se vuelve un impuesto recurrente.
El mini resuelve esto con un pragmatismo digno de respeto. En unos 5KB por libro, entrega: cuándo usarlo, sesgo primario a corregir, reglas de decisión (12-15 ítems), reglas de disparo (cuándo aplicar), y un checklist final. Es la destilación operativa que cabe en la atención del modelo durante una sesión larga. La elección entre full/mini/nano debe hacerse exactamente como la elección de cualquier otra dependencia: cuánto valor entrega, cuánto presupuesto consume, ¿vale el trade?
El detalle metodológico que más importa: Reek casi no vio la diferencia
Este es el punto que separa el experimento del marketing puro. Cuando Ciemborowicz corrió el linter Reek (analizador de code smells para Ruby) en ambas branches, el resultado fue 1.083 smells en la branch "solo menciona el libro" contra 1.077 smells en la branch con reglas mini. Prácticamente un empate técnico en el medidor automático. La ganancia no estaba en la superficie, no era una variable mejor nombrada, una función más corta, o un import más limpio. Era arquitectónica: profundidad de módulo, fronteras de responsabilidad, ocultación de información, cantidad de código que el lector necesita entender de una vez para cambiar algo.
Este hallazgo tiene una implicación práctica enorme para quien mide calidad solo con SonarQube, ESLint o similares: si tu único criterio es el conteo de warnings estáticos, eres ciego a la ganancia real de las reglas de arquitectura. El linter mide lo que cabe en un AST. La regla de diseño mide lo que cabe en la cabeza del próximo ingeniero que va a tocar el código. Los dos miden cosas diferentes, y la industria, desde hace dos décadas, optimiza solo el primero.
Cómo elegir los libros correctos para tu equipo (no copies todos)
La tentación al mirar 13 libros es pegarlos todos en el AGENTS.md. No hagas eso. Los libros entran en conflicto entre sí en puntos importantes, DDD pesado vs DDD Distilled vs A Philosophy of Software Design tienen visiones diferentes sobre cuánta abstracción introducir. Apilar conflicto no le da al agente "lo mejor de todos"; le da un promedio confuso.
La heurística sana es elegir de 2 a 3 libros en función del caso de uso dominante del repositorio. Patrones útiles:
- Codebase de producto nuevo, sin deuda grande: Clean Code (mini) + A Philosophy of Software Design (mini). Foco en legibilidad + módulos profundos.
- Codebase legado con baja cobertura de tests: Working Effectively with Legacy Code (mini) + Refactoring (mini). Seams primero, transformaciones después.
- Servicio crítico de producción (pagos, autenticación): Release It! (mini) + Clean Architecture (mini). Resiliencia operativa + fronteras inmutables.
- Sistema con dominio rico y reglas complejas de negocio: DDD Distilled (mini) + Implementing DDD (mini). DDD en la dosis justa, sin ceremonia academicista.
- Pipeline de datos, ETL, eventos: DDIA (mini) + Pragmatic Programmer (mini). Consistencia semántica + automatización.
Combinar más de 3 conjuntos suele ser síntoma de indecisión arquitectónica, es más fácil elegir todo que mirar la realidad del código. Resiste.
Los límites del experimento, y por qué todavía importa
El propio Ciemborowicz es honesto sobre las limitaciones: fue un solo caso, juzgado por un LLM (ChatGPT) con un prompt subjetivo, sobre un proyecto deliberadamente malo para servir de conejillo de indias. No es un benchmark. No está pareado contra otros conjuntos de reglas (Cursor official, awesome-prompts, etc.). No tiene replicaciones en lenguajes diferentes. Como él mismo escribió, debe tratarse como "early qualitative signal, not benchmark".
Aun así, la dirección de la señal es demasiado fuerte para ignorarla. Duplicar la especificidad de la instrucción mejoró sustancialmente la salida arquitectónica, y eso coincide con la intuición que cualquiera que haya hecho prompt-engineering por más de seis meses ya tiene: ser específico le gana a ser elegante. El costo de adopción es absurdamente bajo (copiar 50 líneas de markdown), y el downside es despreciable (si las reglas entran en conflicto con tu estilo, las editas o las remueves). Es la definición de asymmetric upside.
Adopción pragmática, el camino de 30 minutos
La mayoría de los equipos se traba en la fase de "voy a estudiar todas las opciones antes de elegir". Sáltate esa fase. El ciclo corto es el siguiente:
- Elige 1 libro que encaje con el dolor más visible del repositorio ahora. Clean Code si el problema es la legibilidad. Release It! si el problema es la estabilidad. DDD Distilled si el problema es un modelo confuso.
- Pega el conjunto mini en el
AGENTS.md(oCLAUDE.md, o Cursor rules). No lo edites la primera vez, observa al agente operando con el conjunto crudo. - Haz una feature real con el agente siguiendo las reglas. Compárala con un PR equivalente de la semana pasada, hecho sin las reglas. Mira específicamente: profundidad de módulo, número de archivos abiertos, tamaño de función, claridad de frontera.
- Itera: edita el conjunto removiendo reglas que entran en conflicto con el estilo de tu equipo, agregando 2-3 específicas de tu dominio.
- Solo ahora considera agregar un segundo libro, si sientes que falta algo. Más de 3 libros es señal de que estás huyendo de la decisión.
El juego cambió: AGENTS.md ya no es decoración
Durante dos años, AGENTS.md fue un archivo que los equipos creaban por completitud, "vamos a poner algunas reglas genéricas". El agent-rules-books hace lo que había que hacer: trata el archivo como un artefacto de ingeniería de primer orden, con versionado (full/mini/nano), metodología de validación, y curaduría a partir de las fuentes que la industria ya reconoce como canónicas. No es la única forma. Pero es la primera que combina rigor metodológico con licencia MIT y uso práctico inmediato.
Para quien todavía cree que basta con mencionar el libro, el número 74 contra 46 debería ser suficiente. Para quien ya sospechaba, el repo entrega el atajo. El costo de adopción es una mañana. La ganancia es arquitectónica y acumulativa. En un equipo donde la mitad de las interacciones con el código pasa por un agente, ignorar esta optimización es una decisión consciente de pagar un impuesto recurrente en calidad, por el único beneficio de parecer minimalista en el AGENTS.md.