improve-codebase-architecture y codebase-design: módulos profundos para que tu código no sea una bola de barro

Los agentes aceleran la programación, y con ella la entropía del código: los proyectos hechos con IA se vuelven complejos y difíciles de cambiar a una velocidad nunca vista. Es el cuarto fallo que ataca el repositorio mattpocock/skills, y su respuesta es "radicalmente nueva" según su autor: preocuparse por el diseño del código. codebase-design pone el vocabulario y los principios; improve-codebase-architecture recorre tu código buscando dónde aplicarlos.

Es la octava parte de la guía de las skills de Matt Pocock. Ambas tienen licencia MIT.

La idea central: módulos profundos

Todo parte de una cita de *A Philosophy of Software Design* de John Ousterhout: "Los mejores módulos son profundos. Permiten acceder a mucha funcionalidad a través de una interfaz simple".

• Módulo profundo: interfaz pequeña y mucha implementación detrás. Quien lo usa aprende poco y obtiene mucho.
• Módulo superficial: la interfaz es casi tan compleja como la implementación. Solo pasa cosas de un lado a otro.

Para un agente esto importa el doble. Un código lleno de módulos superficiales obliga a saltar entre muchos ficheros para entender un concepto, y cada salto gasta contexto. Un módulo profundo se entiende por su interfaz y se prueba por ella.

codebase-design: el vocabulario

codebase-design es una skill de referencia que el agente carga cuando diseña o cambia la interfaz de un módulo, y que usan tdd e improve-codebase-architecture. Su primera regla es usar siempre los mismos términos y no sustituirlos por "componente", "servicio", "API" o "frontera":

Los cuatro principios

• La profundidad es propiedad de la interfaz, no de la implementación. Un módulo profundo puede estar hecho por dentro de piezas pequeñas e intercambiables; simplemente no forman parte de su interfaz.
• La prueba del borrado. Imagina que borras el módulo. Si la complejidad desaparece, solo hacía de paso. Si reaparece repartida entre sus llamadas, se ganaba el sueldo.
• La interfaz es la superficie de test. Quien llama y quien prueba cruzan la misma costura. Si necesitas probar "por detrás" de la interfaz, el módulo tiene la forma equivocada.
• Un adaptador es una costura hipotética; dos adaptadores, una real. No metas una costura si nada varía a través de ella (normalmente, producción y test).

La skill añade tres pautas de testabilidad con ejemplos en TypeScript: acepta dependencias en lugar de crearlas, devuelve resultados en lugar de producir efectos secundarios y mantén la superficie pequeña.

Profundizar según las dependencias

El fichero DEEPENING.md clasifica las dependencias de un módulo en cuatro categorías, porque cada una se prueba distinto:

1. En proceso (cálculo puro, memoria): siempre se puede profundizar; se prueba directamente.
2. Sustituibles en local (PGLite en lugar de Postgres, sistema de ficheros en memoria): se prueba con el sustituto.
3. Remotas pero tuyas (tus microservicios): puerto en la costura, adaptador HTTP en producción y adaptador en memoria en los tests.
4. Externas de verdad (Stripe, Twilio): puerto inyectado y adaptador simulado en los tests.

Y una regla de tests: reemplazar, no apilar. Cuando existen tests en la interfaz del módulo profundo, los viejos tests de los módulos superficiales sobran y se borran.

improve-codebase-architecture: buscar oportunidades

/improve-codebase-architecture es la skill que invocas tú "cuando tengas un rato libre". Su autor recomienda pasarla cada pocos días y avisa: es un estudio, no un rescate. En un código viejo encontrará candidatos reales, pero no desenredará el barro por ti.

1. Explorar con criterio

Antes de mirar, decide dónde mirar. Si le das una dirección (un módulo, un dolor), la usa. Si no, recorre el historial de git log buscando los puntos calientes: los ficheros que más cambian, porque profundizar un módulo compensa cuando ese módulo se va a seguir tocando (YAGNI).

Después lanza un subagente con contexto limpio que recorre el código y anota la fricción: conceptos que obligan a saltar entre muchos módulos pequeños, módulos superficiales, funciones puras extraídas solo para poder testearlas mientras los bugs viven en cómo se llaman, módulos acoplados que se filtran por sus costuras y zonas sin tests o difíciles de probar.

2. Un informe HTML con antes y después

Los candidatos se presentan en un fichero HTML autocontenido en el directorio temporal del sistema (nada entra en el repositorio), con Tailwind y Mermaid desde CDN, y se abre solo. Cada candidato es una tarjeta con:

• Ficheros implicados.
• Problema y solución en lenguaje llano.
• Beneficios en términos de localidad, apalancamiento y tests.
• Un diagrama de antes y después dibujado a medida.
• Una etiqueta de fuerza: Strong, Worth exploring o Speculative.

El informe acaba con una recomendación principal. Si un candidato contradice un ADR, solo aparece si la fricción justifica reabrir la decisión, y lo marca con un aviso.

3. Decidir con grilling

Cuando eliges un candidato, la skill lanza el interrogatorio de grilling sobre restricciones, dependencias, forma del módulo profundo y qué tests sobreviven. Mientras, domain-modeling mantiene el glosario: si el módulo nuevo se nombra con un concepto que no estaba en GLOSSARY.md, lo añade. Si rechazas el candidato por un motivo de peso, te ofrece un ADR para que futuros análisis no lo vuelvan a sugerir.

Si quieres comparar interfaces alternativas, entra en juego Design It Twice (DESIGN-IT-TWICE.md): tres o más subagentes en paralelo diseñan la interfaz de formas radicalmente distintas (mínima, flexible, optimizada para el caso común, puertos y adaptadores) y el agente las compara por profundidad, localidad y posición de la costura antes de dar su recomendación.

Cómo se combinan

improve-codebase-architecture encuentra el dónde; codebase-design es el banco de trabajo del cómo. El resultado no es código: es una idea que entra en el flujo principal por grill-with-docs, sigue por to-spec y to-tickets y se construye con implement.

También cierran un círculo con diagnosing-bugs: cuando un bug no tiene ninguna costura donde fijar un test de regresión, ese hallazgo es justo el tipo de fricción que esta skill convierte en candidato.

Errores frecuentes

• Pedir que lo arregle todo de una vez. La skill presenta candidatos y espera a que elijas uno.
• Introducir puertos con un solo adaptador. Es indirección sin beneficio; la propia skill lo desaconseja.
• Mezclar vocabularios. "Servicio", "componente" y "módulo" para lo mismo devuelven el problema de la parte 4.
• Conservar los tests viejos de los módulos superficiales después de profundizar.

Preguntas frecuentes

¿Solo sirve para TypeScript? No. Los ejemplos están en TypeScript, pero el vocabulario vale para cualquier lenguaje.

¿Escribe en el repositorio? El informe va al directorio temporal. Solo escribe GLOSSARY.md o ADR si se resuelven términos o decisiones durante el grilling.

¿Cada cuánto pasarla? El autor sugiere cada pocos días, centrada en lo que más ha cambiado últimamente.

Siguiente paso

Lanza /improve-codebase-architecture sobre el área que más has tocado este mes y aplica la prueba del borrado a su primer candidato. En la parte 9 vemos prototype y research, la pareja para responder preguntas de diseño antes de construir.