improve-codebase-architecture (mattpocock/skills)

Reseña

Codex CLI 0.166 (gpt-6-astra, razonamiento bajo) en un PC de pruebas Windows dedicado, con un proyecto temporal nuevo y HOME/TMPDIR/cachés temporales en cada ejecución, la skill instalada (grupo con skill), ausente (control) o ausente con el requisito central de la skill comprimido en una frase añadida al prompt (grupo del prompt de una frase), 2 ejecuciones por grupo y tarea, sin red y con las escrituras en /tmp bloqueadas. Los prompts nunca mencionan la skill (salvo la redacción indicada abajo). Tres tareas sobre un pequeño backend de tienda en Python con fricción sembrada (validadores y funciones auxiliares de dinero poco profundos, un servicio de inventario que solo reenvía a su repositorio, un único adaptador de pago, lógica de descuentos duplicada en cart y orders, y pruebas que solo cubren las funciones auxiliares): una revisión de arquitectura de todo el código escrita como report.html, la misma limitada a pagos e inventario, y «por qué es doloroso testear place_order» respondida en el chat. Los prompts del grupo con skill empiezan por $improve-codebase-architecture (invocación explícita); los prompts de control y de una frase no la nombran.

Comparación de tres ramas

Medido con Codex CLI en 18 ejecuciones, puntuado con comprobaciones basadas en reglas y sin juez LLM. Total 23.0 / 30, veredicto Según el caso.

Veredicto: Según el caso (23.0 / 30). Fuente: mattpocock/skills, skills/engineering/improve-codebase-architecture, skills/engineering/codebase-design, fijada en el commit 4ae2317. Instalación: npx skills@latest add mattpocock/skills --skill improve-codebase-architecture. Licencia: MIT (LICENSE del repositorio).

Qué es

La skill improve-codebase-architecture de mattpocock/skills. Busca «oportunidades de profundización» en un código: módulos superficiales cuya interfaz es tan compleja como su implementación, capas de paso, costuras de un solo adaptador que solo son hipotéticas, lógica duplicada, comportamiento que solo se prueba a través de helpers. Escribe un informe HTML con un antes/después por candidato y una recomendación principal. Se apoya en una skill hermana, codebase-design, para el vocabulario. Solo Markdown, sin scripts.

Cómo lo probamos

Codex CLI 0.166 (gpt-6-astra, razonamiento bajo) en un PC de pruebas Windows dedicado, un proyecto temporal nuevo y HOME/TMPDIR/cachés temporales por ejecución, skill instalada (tratamiento) o ausente (control) o ausente con el requisito central de la skill comprimido en una frase añadida al final del prompt (grupo de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan la skill (salvo la formulación indicada abajo).

Tres tareas sobre un pequeño backend de tienda en Python con fricción sembrada (validadores y helpers de dinero superficiales, un servicio de inventario que solo reenvía a su repositorio, un único adaptador de pago, lógica de descuentos duplicada en carrito y pedidos, pruebas que solo cubren helpers): una revisión de arquitectura de todo el código escrita como report.html, la misma limitada a pago e inventario, y «por qué place_order es tan difícil de probar» respondido en el chat. Los prompts del grupo de la skill empiezan por $improve-codebase-architecture (invocación explícita); los del control y los de una frase no la nombran.

1. Escaneo de arquitectura de todo el repositorio — Revisa este pequeño backend de tienda en busca de mejoras de arquitectura: ¿dónde haría la reestructuración que el código fuera más fácil de cambiar y de probar? Escribe tus hallazgos como un informe HTML autocontenido llamado report.html en esta carpeta (no abras un navegador ni inicies un se…
2. Solo pagos e inventario — Mira solo las partes de pago e inventario de este backend y dime qué reestructuraciones valdrían la pena. Escribe tus hallazgos como un informe HTML autocontenido llamado report.html en esta carpeta (no abras un navegador ni inicies un servidor) y no cambies ningún co…
3. ¿Por qué es difícil probar place_order? — Me resulta doloroso escribir una prueba decente para place_order en este backend. ¿Por qué, y qué reestructuración lo arreglaría? No cambies ningún archivo; responde en tu mensaje final.

La puntuación es programática (pruebas ocultas / detección de problemas sembrados / comprobaciones de restricciones / renderizado+OCR cuando corresponde), 0–5 por ejecución. Ningún juez LLM decidió ninguna puntuación.

Resultados

La frase única que recibió el tercer grupo: "Busca oportunidades de profundización: módulos superficiales cuya interfaz es tan compleja como su implementación (aplica la prueba de borrado: ¿eliminarlo concentraría la complejidad o solo la movería?), capas de paso, costuras de un solo adaptador que solo son hipotéticas, lógica duplicada entre módulos y lógica que solo se prueba a través de helpers en vez de la interfaz real; presenta cada candidato con archivos, problema, solución, beneficios y un antes/después, y nombra una recomendación principal."

Puntuación media: 3.2 sin vs 4.12 con la skill (delta +0.92). Tokens por ejecución: 115k vs 208k (1.80x); tiempo 112s vs 135s. Grupo de una frase: 3.91 (ganancia de la skill sobre la frase única: +0.2; ganancia de la frase única sobre sin skill: +0.72); tokens de la frase única 120k por ejecución, así que la skill cuesta 1.73x la frase única.

Qué ocurrió

• La revisión de todo el código es donde se nota: la skill y la versión de una frase encontraron 6/6 puntos sembrados con vocabulario de arquitectura, antes/después y una recomendación principal en las cuatro ejecuciones; Codex a secas encontró 2/6 en una ejecución y 5 de 6 comprobaciones en la otra, y ninguna de las dos tuvo una «recomendación principal» clara.
• La revisión enfocada (solo pago e inventario) es difícil para todos: el mejor grupo encontró de media uno de los dos puntos sembrados. Control 2/4 comprobaciones, una frase 3/4, skill 3/4. La skill no lo hizo mejor que la frase.
• En «por qué es difícil probar place_order», los tres grupos encontraron las causas sembradas (PaymentAdapter oculto, stock compartido a nivel de módulo, lógica de descuentos duplicada, pruebas que se quedan en los helpers). La respuesta de la skill usó su vocabulario («interfaz», «localidad»); la del control era igual de correcta con palabras llanas.
• Puntuación media 3.20 control, 3.91 una frase, 4.12 skill. La skill añade 0.21 sobre la frase con 1.7x los tokens (208k vs 120k por ejecución) porque además lee la skill hermana; el grupo de una frase cuesta lo mismo que el control (115k).
• Como la skill instala dos carpetas de skill, las ejecuciones de tratamiento crearon archivos extra en la carpeta .agents del proyecto; se excluyeron de la comprobación de «no se cambió ningún archivo de código» (una primera pasada los suspendió por error y se corrigió un fallo específico de Windows en la comprobación antes de las cifras finales).

Puntuaciones por dimensión

Límites de esta prueba

• Un único fixture pequeño de Python con problemas sembrados de manual; no se mide si el informe es útil en un repositorio real y grande.
• No se puntuaron la calidad del informe, los falsos positivos ni el estilo HTML (carga Tailwind y Mermaid desde CDN al abrirlo en un navegador); no se ejerció el comportamiento de subagente que describe la skill.
• El prompt de una frase reformula la propia lista de comprobación de la skill, así que es un límite superior para un prompt breve.
• n = 2 por grupo y tarea: las diferencias de menos de 1 punto son ruido.
• La puntuación basada en reglas mide lo que las comprobaciones pueden ver; no puede juzgar el gusto ni si un resultado es el mejor posible.

Seguridad

Consulta security.md. Escaneo: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredicto: seguro para ejecutar (sandbox sin red). Un escaneo limpio no demuestra que una skill sea segura.

En resumen

Frente a no hacer nada, la skill mejora claramente una revisión de arquitectura de todo el código, sobre todo al imponer la estructura y el vocabulario del informe, y cuesta 1.8x tokens. Una sola frase que enumere los mismos olores consigue la mayor parte de la ganancia, así que merece la pena instalarla sobre todo si quieres el mismo formato de informe todas las veces.