La habilidad /improve-codebase-architecture

Fuente: The /improve-codebase-architecture Skill — traducción comunitaria no oficial al español.

Qué hace

improve-codebase-architecture examina una base de código en busca de oportunidades de profundización: lugares donde un módulo superficial (una interfaz casi tan compleja como lo que oculta) podría convertirse en uno profundo. Las presenta como un informe HTML autocontenido, y luego te hace un interrogatorio sobre el que elijas.

Nunca cambia el código. Toda la ejecución produce un archivo HTML en el directorio temporal de tu sistema y una conversación; la refactorización ocurre después, en una sesión separada, por el flujo normal de construcción. Eso es lo que la hace un estudio y no una herramienta de refactorización, y por eso vale la pena ejecutarla sobre una base de código que aún no estás listo para tocar.

Dos filtros evitan que el informe se vuelva consejo genérico de limpieza. Cada candidata tiene que pasar la prueba de eliminación: ¿eliminar este módulo concentraría la complejidad tras una interfaz más pequeña, o solo la dispersaría entre quienes lo llaman? Solo los casos de «concentra» ganan una tarjeta. Y salvo que la apuntes a un área concreta, primero lee el historial reciente de commits y sesga el análisis hacia las rutas que están cambiando activamente, porque una profundización en código que nadie toca es una refactorización que nunca rentabilizarás.

Cuándo recurrir a ella

La invocas escribiendo /improve-codebase-architecture; el agente no la usará por su cuenta.

Está fuera del bucle de construcción: no es un paso del bucle principal sino algo que ejecutas periódicamente para encolar más trabajo de mejora de la base de código. Las cuatro situaciones en que se usa:

Situación	Cómo se usa
Mantenimiento de rutina	Ejecútala cada pocos días, o cuando aparezca un hueco, para que la estructura no se pudra entre funcionalidades.
Antes de una gran construcción	Apúntala a la especificación: «¿cómo podemos facilitar este cambio?» Este es el prompt más efectivo para ella.
Auditoría de código heredado	Ejecútala sobre un repositorio grande, sin estructura o vibe-codeado para saber en qué forma está realmente.
Trabajo de pruebas en legado	Úsala para encontrar primero las costuras que faltan, antes de escribir pruebas contra código imposible de probar.

Dónde se confunde con sus hermanas:

Para diseñar un módulo que ya elegiste, usa codebase-design: ese es el banco de trabajo, esta es el estudio que encuentra qué poner en él.
Para un esfuerzo completo demasiado grande para una sesión, usa wayfinder.
Para «esto concreto está roto», usa diagnosing-bugs. Te devuelve aquí cuando el hallazgo real es que no hay una buena costura donde fijar el error.

Requisitos previos

Ninguno para ejecutarla. Lee CONTEXT.md y cualquier ADR en docs/adr/ si existen, y habla con los sustantivos de tu propio dominio cuando los hay: una candidata se lee como «profundizar el módulo de alta de pedidos», no «refactorizar el FooBarHandler».

Escribe en dos lugares. El informe va a <tmpdir>/architecture-review-<timestamp>.html, fuera del repositorio. Durante el bucle de interrogatorio añadirá o afilará términos en CONTEXT.md, creando ese archivo si no existe, y ofrecerá registrar una candidata rechazada como ADR para que una ejecución futura no la vuelva a sugerir.

Profundidad, y el informe que la caza

La habilidad gira sobre una idea: la profundidad. Un módulo profundo pone mucho comportamiento tras una interfaz pequeña y estable. Uno superficial fuga su implementación por una interfaz casi tan ancha como el código que hay debajo. El informe caza la superficialidad en tres formas: funciones puras extraídas solo por testabilidad mientras los errores reales viven en cómo se las llama (sin localidad), módulos que fugan por sus costuras, y un concepto que no puedes entender sin abrir cinco archivos. Cierra con una propuesta de la profundización que lo arregla.

Cada candidata es una tarjeta: los archivos implicados, la fricción, una solución en lenguaje llano, el beneficio expresado en términos de localidad y apalancamiento, un diagrama de antes/después y una insignia de fuerza.

Insignia	Qué significa para ti
`Strong`	La prueba de eliminación pasa con claridad y la fricción es real. Tómalas en serio.
`Worth exploring`	Profundización plausible, pero el retorno depende de hacia dónde va el código.
`Speculative`	Mostrada por completitud. La mayoría se pueden ignorar sin riesgo.

El informe termina con una recomendación principal (la que abordaría primero), y luego la habilidad se detiene y pregunta qué candidata quieres explorar. En ese punto nada se ha decidido y ningún código se ha movido.

Qué pasa después de elegir una

Elegir una candidata inicia una sesión de interrogatorio sobre ella: restricciones, qué hay tras la costura, qué pruebas sobreviven, cómo debería verse la interfaz profundizada. La salida de esa sesión es una decisión, no un diff. Desde ahí aplica el flujo normal: lleva la decisión a to-spec, luego a to-tickets, luego a implement.

Preguntas comunes

Me interrogó una hora sobre una idea en vez de mostrarme opciones. ¿Puedo apagar eso?

Sí: dilo al invocarla («no me interrogues, solo muestra el informe»). Esta es la queja más ruidosa sobre la habilidad. Un usuario lo dijo sin rodeos: le gustaba como «una forma cómoda de obtener un análisis a fondo de mejoras», y después de añadir el bucle de interrogatorio la encontró «casi inutilizable», reportando sesiones donde proponía una sola solución y luego hacía «decenas o cientos de preguntas». La intención de diseño es que el informe va primero y el interrogatorio solo empieza sobre una candidata que elegiste, pero los modelos más débiles saltan directo a entrevistarte sobre la primera idea que tuvieron. Los reportes en ese hilo varían mucho según el modelo, y es un tema abierto: la habilidad aún no tiene un modo documentado sin interrogatorio.

El informe se abrió como HTML crudo sin estilos ni diagramas. ¿Qué pasó?

El informe carga Tailwind y Mermaid desde CDN, así que necesita acceso a red al abrirlo, y se rompe en silencio cuando algo bloquea esos scripts. El caso archivado fue un hook de seguridad que exigía hashes SRI: el agente los añadió, el CDN sirvió al navegador bytes distintos que al curl usado para calcular el hash, y el navegador bloqueó el script. Los entornos sin conexión y los bloqueados chocan con la misma pared. El agente no puede verlo, porque nunca renderiza la página. La solución es pedir CSS en línea y diagramas SVG hechos a mano en vez del andamiaje con CDN. Es un tema abierto y un borde áspero real.

Me dio doce candidatas. ¿Las trabajo en la misma sesión o empiezo una nueva?

Una candidata por sesión. Trabajar varias en una conversación llena la ventana de contexto con el informe, el interrogatorio, las ediciones del modelo de dominio y los cambios de código a la vez. El informe solo vive en un archivo temporal, así que lleva la candidata misma en vez del archivo: elige una, interrógala, lleva la decisión a /to-spec y convierte el resto en tickets que puedas retomar por separado después. Pon la mejora elegida en una especificación en vez de ir directo a la implementación. Es una pregunta recurrente sin flujo documentado en la propia habilidad.

¿Cómo debería invocarla?

Con lo próximo que vas a construir en mente. Cuando se acerca una gran construcción, apúntala a la especificación y pregunta «¿cómo podemos facilitar este cambio?» Una ejecución sin dirección analiza puntos calientes por su cuenta, lo que está bien para mantenimiento de rutina, pero nombrar una dirección es lo que hace el informe accionable.

¿Funciona en una base de código legada grande?

En parte. Es fuerte en bases de código grandes existentes sin estructura consistente, y es el mecanismo de mantenimiento recomendado tras cualquier configuración estructural puntual. El contrapeso honesto: usuarios con proyectos genuinamente fuera de control reportan que «ayudó un poco pero no termina de bastar», y un desarrollador con una base legada de ocho años reportó al modelo dando vueltas donde la misma habilidad produce un grafo limpio en un repositorio ordenado. Aún no hay una habilidad /refactor dedicada para ese caso. Si la base no tiene ningún vocabulario compartido, hacer primero grill-with-docs para establecer uno suele mejorar mucho la salida de esta habilidad.

¿En qué se diferencia de /codebase-design?

/codebase-design es una referencia, no un conductor de sesión. Aporta el vocabulario (módulo, interfaz, profundidad, costura, adaptador, apalancamiento, localidad), y esta habilidad lo toma prestado. Apuntar a un agente nuevo a /codebase-design como lo que «hacer» es un fallo conocido: sin proceso propio que seguir, el agente inventa uno, reexplora código y corre muchísimo tiempo antes de preguntarte nada. Conduce con esta habilidad; consume aquella.

¿Alguna vez me dirá que la base está bien?

Rara vez, y conviene saberlo de entrada. La habilidad está construida para producir hallazgos, así que el encuadre la empuja a producir candidatas en vez de concluir que no pasa nada. Las insignias de fuerza son la defensa: un informe donde todo es Speculative es la habilidad diciéndote que no encontró nada, de la única forma que sabe.

¿Funciona en Codex u otro entorno?

En parte. El paso de exploración nombra directamente la herramienta Agent de Claude Code con subagent_type=Explore, así que un entorno sin esa herramienta puede saltarse la exploración paralela en vez de sustituirla por la suya. La habilidad sigue corriendo; el análisis es solo menos exhaustivo. Se ha propuesto una reescritura neutral al entorno pero no está fusionada.

¿Cómo implemento realmente módulos profundos en TypeScript?

No hay una buena respuesta distribuida con la habilidad. La petición recurrente es un TYPESCRIPT.md con diseños concretos de archivos y módulos para los principios, y no existe. La habilidad te dirá dónde corresponde una profundización y qué debería quedar tras la costura; traducirlo a una estructura de paquetes o directorios hoy corre por tu cuenta.

Funciona si

Las candidatas nombran los conceptos de tu dominio, no nombres de clases inventados: «el módulo de alta de pedidos», no «el FooBarHandler».
Las candidatas se agrupan en archivos que editaste recientemente, no en rincones dormidos del repositorio.
Ningún código cambió durante la ejecución. El único archivo nuevo es el informe HTML en tu directorio temporal.
Se detiene tras el informe y pregunta qué candidata quieres, en vez de seguir por su cuenta.
Cada tarjeta explica el retorno como localidad o apalancamiento, y dice qué pruebas se simplifican, no solo «esto es más limpio».
Rechazar una candidata por una razón duradera te ofrece registrar un ADR, para que la próxima ejecución no la vuelva a sugerir.

Dónde encaja

improve-codebase-architecture es mantenimiento periódico: ejecútala cada pocos días, fuera de cualquier cadena, para encolar trabajo en vez de hacerlo. Sus vecinas son codebase-design, dueña del vocabulario de profundidad y costuras en que está escrita cada candidata, grilling, que recorre el árbol de decisión una vez elegida una candidata, y domain-modeling, que mantiene CONTEXT.md y los ADR al día mientras la decisión se asienta. Lo que produce es una idea, que reentra al flujo principal de construcción en grill-with-docs o to-spec. Para saber qué habilidad encaja en cada situación, ask-matt es el enrutador sobre todo el conjunto.