Mejorar la arquitectura de la base de código: reestructurar módulos poco profundos en módulos profundos

Modo de falla: "IA deambulando en una base de código incorrecta"

El cuarto modo de fracaso en la charla de Matt es una metáfora pictórica:

"Los módulos superficiales en una base de código se ven así: tienes un montón de pequeñas manchas y la IA tiene que revisar un montón de módulos y comprender todas las dependencias antes de poder corregirlas".

"AI is really good at creating codebases like this. So you'll have a situation where AI doesn't understand what your code is doing. It will attempt to explore the code, but because it's poorly laid out, filled with shallow modules, it doesn't get to the right module in time, or doesn't understand all the dependencies."

Este es un círculo vicioso exclusivo de la programación de IA:

AI 写代码倾向于产生 shallow 模块（小、多、互相依赖）
    ↓
代码库变得 shallow
    ↓
下次 AI 进来探索更难，更容易写错
    ↓
更多 shallow 模块被加进去
    ↓
代码库越来越烂，AI 越来越无能

Para romper este ciclo, se debe realizar periódicamente una refactorización inversa manual, fusionando módulos poco profundos en módulos profundos. Eso es exactamente lo que hace /improve-codebase-architecture.

Teoría clásica: los módulos profundos de Ousterhout

John Ousterhout es profesor de informática en Stanford (y autor de los artículos sobre lenguaje Tcl y Raft). Su libro de 2018 "A Philosophy of Software Design" propone una regla simple pero poderosa:

La "profundidad" del módulo = la complejidad oculta de la interfaz

El módulo ideal es profundo: los usuarios sólo necesitan ver la interfaz corta y la complejidad está oculta en su interior. Un contraejemplo extremo es el módulo superficial: la interfaz es casi tan compleja como la implementación, lo que significa que no hay encapsulación. Los usuarios también podrían mirar la implementación directamente.

Juicio de Ousterhout: ** Las buenas bases de código se componen de una pequeña cantidad de módulos profundos; Las bases de código incorrecto se componen de una gran cantidad de módulos poco profundos**. Esto es completamente opuesto al dogma tradicional de "mantener las funciones lo más pequeñas posible, los archivos lo más cortos posible y los módulos tantos como sea posible"; él cree que ese tipo de dogma produce módulos exactamente superficiales.

Extensión de Matt: Prueba de eliminación

Matt tradujo la teoría de Ousterhout en una prueba de ingeniería operativa, a la que llamó prueba de eliminación:

Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.

Palabras humanas:

• Elimínelo, la complejidad desaparece → Este módulo es originalmente un paso (tránsito), no funciona, así que córtelo
• Elimínalo y la complejidad se extenderá a N personas que llaman → Originalmente te ayuda a ocultar la complejidad, es muy profunda, déjalo

Lo bueno de esta prueba es que es bidireccional: puede identificar tanto "envoltorios delgados que deben eliminarse" como "lógica común que debe extraerse". Si descubre que después de eliminar un fragmento de código, la complejidad se extenderá a 5 lugares, significa que vale la pena extraer este código en un módulo profundo.

Términos clave (definición precisa de Matt)

Hay un glosario en improve-codebase-architecture/SKILL.md que requiere el uso estricto de estas palabras; no se desvíe hacia "componente", "servicio", "API" y "límite":

Varios principios básicos:

• Prueba de eliminación: ver arriba
• La interfaz es la superficie de prueba: las pruebas solo se pueden ejecutar a través de la interfaz; esta es la base para la capacidad de prueba profunda del módulo.
• Un adaptador = costura hipotética. Dos adaptadores = costura real.: Una interfaz con una sola implementación es una costura falsa. Las uniones reales requieren al menos dos adaptadores

El último es particularmente contrario a la intuición: muchos equipos abstraerán una interfaz de antemano "para una futura expansión", pero en realidad solo hay una implementación. Juicio de Matt: inútil, eliminar. Espere hasta que el segundo se haga realidad. Este tiene el mismo origen que YAGNI.

Flujo de trabajo de habilidades

1. Explorar

La habilidad primero permite que AI lea CONTEXT.md y docs/adr/, y luego usa subagent_type=Explore para enviar un subagente a la base del código.

En lugar de una inspiración rígida, utiliza fricción como señal:

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow — interface nearly as complex as the implementation?
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
• Where do tightly-coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interface?

Cada vez que encuentre un punto sospechoso, aplique una prueba de eliminación: ¿eliminarlo hará que la complejidad desaparezca o se extienda? La respuesta "dispersarse" es una candidata digna de profundizar.

2. Candidatos presentes (Candidatos de declaración)

Presentar lista numerada de candidatos:

1. Files: src/orders/parser.ts, src/orders/validator.ts, src/orders/normalizer.ts
   Problem: 三个文件互相调用，理解 Order 入站需要在三处跳转
   Solution: 合并为单一 OrderIntake 模块，对外只暴露 parse(raw) → ValidatedOrder
   Benefits:
     - Locality: Order 入站的所有逻辑、错误处理、bug 修复集中一处
     - Leverage: 调用方从理解 3 个接口降为 1 个
     - Tests: 只需测 parse() 的输入输出，不再需要 mock 内部协作

Requisitos:

• Utilice vocabulario CONTEXT.md para hablar sobre dominios ("el módulo de admisión de pedidos", no "el FooBarHandler")
• Hablar sobre arquitectura usando vocabulario del glosario ("costura", "profundidad", "localidad")
• No proponga diseños de interfaz de inmediato: permita que los usuarios elijan candidatos interesantes primero

Si un candidato entra en conflicto con un ADR existente, menciónelo únicamente si el conflicto justifica revisar el ADR y márquelo claramente:

"contradicts ADR-0007 — but worth reopening because…"

No desenterres todas las refactorizaciones prohibidas por ADR.

3. Circuito para asar

Después de que el usuario seleccione un candidato, pase al modo de parrilla (heredado de /grill-with-docs):

• Recorrer el árbol de diseño: limitaciones, dependencias, la forma del módulo después de profundizarlo, qué se esconde detrás de las costuras, qué pruebas pueden sobrevivir.
• Los efectos secundarios ocurren inmediatamente:
• Asigne al módulo de profundización un nombre que no esté en CONTEXT.md → Agréguelo a CONTEXT.md inmediatamente
• Se agudizó un término ambiguo en la tortura → Actualice CONTEXT.md inmediatamente
• El usuario rechaza al candidato por motivos importantes (crítico, algo que los futuros exploradores deben saber) → Proponer generar ADR
• Quiere explorar los diversos diseños de interfaz de los módulos de profundización → Saltar al proceso separado INTERFACE-DESIGN.md

El mantenimiento de documentos y la transformación de la arquitectura ocurren en la misma conversación: no hay dos rondas.

Caso real: la práctica de Mejba Ahmed

El desarrollador externo Mejba Ahmed escribió un artículo ["Módulos profundos: la habilidad del código Claude guardando mi base de código"] (https://www.mejba.me/blog/improve-codebase-architecture-skill-deep-modules) para registrar en detalle su experiencia usando esta habilidad. Puntos clave:

• Originalmente tenía más de 50 archivos en un proyecto, cada archivo tenía menos de 100 líneas - Biblioteca poco profunda típica
• /improve-codebase-architecture se quedó sin 8 candidatos de profundización
• Seleccionó 3 profundizaciones (dos módulos de procesamiento de datos fusionados, un conjunto de herramientas fusionado)
• Resultado: el número de archivos se redujo de 50+ a 30+, pero el tamaño total del código sigue siendo básicamente el mismo - la complejidad se reduce a una pequeña cantidad de módulos profundos
• La tasa de aciertos de los cambios de código posteriores de Claude en esta biblioteca mejoró significativamente (dijo "del 60% al 90%", lo cual no se midió estrictamente, pero se sintió fuerte)

Mejba también tiene un recordatorio: No profundices de 8 a la vez. Elija solo uno a la vez, ejecute la prueba + confirmar + observar y luego elija el siguiente. De lo contrario, no hay forma de retroceder una vez que lo complete.

Cómo instalar y usar

npx skills@latest add mattpocock/skills

Marque improve-codebase-architecture + setup-matt-pocock-skills.

Llamar: /improve-codebase-architecture

Ritmo recomendado:

• Corre una vez por semana o al final de cada sprint
• O **ejecútelo una vez después de completar una ola de desarrollo intensivo (es especialmente fácil acumular módulos poco profundos después de escribir código de IA con alta frecuencia)
• No corras cuando tengas prisa: sugerirá grandes cambios que no tendrás tiempo de digerir cuando tengas prisa

Proceso típico:

1. /improve-codebase-architecture
2. Exploración de IA + lista de N candidatos (con argumento de prueba de eliminación)
3. Eliges el que más te sienta
4. Caída en el diseño de alineación del bucle de parrilla.
5. Refactorización de implementación de IA (se recomienda ejecutarla junto con /tdd - la refactorización debe tener protección de prueba)
6. comprometerse + observar
7. Vuelve en una semana.

¿Por qué esta habilidad es un "circuito cerrado" del flujo de trabajo de Matt?

Volvamos al diagrama de flujo de trabajo de Matt:

/grill-me → /to-prd → /to-issues → /tdd → /improve-codebase-architecture → 回到 /grill-me

Observe que regresa al punto inicial. /improve-codebase-architecture no es una herramienta que se usa una sola vez, es un mantenimiento periódico - porque:

1. La IA continúa agregando módulos poco profundos al código base (esta es su tendencia predeterminada y se acumulará si escribe demasiado)
2. A medida que el negocio siga evolucionando, las viejas costuras quedarán obsoletas.
3. Los términos en CONTEXT.md continúan perfeccionándose y la denominación anterior no se mantendrá.

Cada vez que ejecutas esta habilidad, la compatibilidad con la IA del código base se actualiza. Esta es la única forma de mantener saludable una base de código a largo plazo con LLM: si no la actualiza, la IA morirá en su base de código después de tres meses.

Este conjunto de pensamientos es más valioso que la habilidad misma.

Incluso si no instala /improve-codebase-architecture en absoluto, recuerde las siguientes tres cosas y la calidad de la revisión de relaciones públicas mejorará un nivel:

1. prueba de eliminación: cada vez que vea un módulo nuevo, pregúntese: "Si lo elimina, ¿la complejidad desaparecerá o se extenderá?".
2. Uniones verdaderas al menos dos adaptadores: interfaz de implementación única = resumen falso, eliminar
3. La interfaz es la superficie de prueba: no se puede medir = hay un problema con el diseño de la interfaz

Estos tres elementos no requieren inteligencia artificial ni habilidad; son la moneda fuerte de la estética de la ingeniería. Matt los integra en habilidades para la ejecución por lotes, pero la verdadera ventaja son los tres principios mismos.

Notas

No profundices demasiado. El propio Ousterhout dijo que el módulo profundo es un objetivo más que un dogma: una clase Util grande que agrupa todas las funciones no es un módulo profundo, sino un módulo divino. El criterio de juicio es "interfaz simple + implementación coherente", los cuales deben cumplirse.

la profundización debe tener protección de prueba. Los cambios estructurales son operaciones de alto riesgo y atreverse a refactorizar sin realizar pruebas = esperar a asumir la culpa. Si no hay pruebas actualmente, vaya a /tdd para agregar pruebas a la ruta crítica y luego regrese.

Las decisiones de ADR no deben tomarse por capricho. Cuando rechaza a un candidato durante el interrogatorio, la IA sugerirá fácilmente generar un ADR y solo lo aceptará si el motivo es realmente "las personas futuras necesitan saberlo". De lo contrario, docs/adr/ se completará con entradas de diario.

No importa si parte del código es superficial. Un contenedor de registrador, un archivo constante, un script único: son superficiales, no hay problema. Esta habilidad busca esos módulos superficiales que pretenden ayudarte con la abstracción pero que en realidad añaden caos.

Recursos de referencia

Conclusión de la serie

He leído los 6 artículos hasta ahora. Revise todo el flujo de trabajo:

/grill-me 或 /grill-with-docs   ← 谈清楚要做什么
        ↓
   /to-prd                       ← 凝固成 PRD
        ↓
   /to-issues                    ← 切成 vertical slice
        ↓
   /tdd                          ← 一个 slice 一个 slice 跑红绿
        ↓
   /improve-codebase-architecture ← 周期性深化
        ↓
        回到 /grill-me

El espíritu de este proceso se puede condensar en una frase:

**La IA es el soldado táctico en el terreno y tú eres la capa estratégica. Recupere las tres cosas de "definir el problema", "deconstruir el problema" y "probar el problema" y hágalo usted mismo, y deje "escribir código" a la IA: esta es la verdadera posición de los ingenieros en la era de la IA. **

El conjunto de habilidades de Matt no es la respuesta definitiva, sino la mejor práctica en la etapa actual. Puede que haya algo mejor tres meses después, pero el aspecto espiritual no cambiará: una buena base de código siempre es más importante que una mala, y las habilidades básicas de software siempre son valiosas.

Vuelve a Overview, o elige la habilidad más útil para instalar y probar.