codebase-design (mattpocock/skills)

Reseña

Codex CLI 0.166 (gpt-6-astra, razonamiento bajo) en un PC Windows dedicado a pruebas, 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 condensado en una frase añadida al prompt (grupo del prompt de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan la skill (salvo el texto indicado abajo). Un backend pequeño de tienda con seis puntos de fricción plantados (validadores y envoltorios de dinero superficiales, un servicio de inventario que solo delega, un único adaptador de pago, lógica duplicada y otros). Tareas: escribir un informe HTML de mejoras de arquitectura, un informe limitado a pago e inventario, y «por qué place_order es difícil de testear y cómo lo arreglarías» (respuesta en el chat). Los prompts no nombran términos de diseño. El prompt de una frase indica la idea de profundidad y las cosas que hay que señalar.

Comparación de tres ramas

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

Veredicto: Situacional (23.6 / 30). Fuente: mattpocock/skills, skills/engineering/codebase-design, fijado en el commit 4ae2317. Instalación: npx skills@latest add mattpocock/skills --skill codebase-design. Licencia: MIT (LICENSE del repositorio).

Qué es

El skill codebase-design (mattpocock/skills): una forma de revisar la arquitectura por la profundidad de los módulos: módulos profundos con una interfaz pequeña que oculta mucho comportamiento; señalar módulos superficiales que solo hacen de paso, seams de un solo adaptador que solo son hipotéticos, lógica duplicada y comportamiento probado solo mediante helpers; indicar dónde encaja un seam para que el comportamiento se pruebe a través de la interfaz.

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 en cada ejecución, skill instalado (grupo con skill), ausente (grupo de control) o ausente con el requisito central del skill comprimido en una frase añadida al prompt (grupo de una frase), 2 ejecuciones por grupo y tarea, red desactivada, escrituras en /tmp bloqueadas. Los prompts nunca mencionan el skill (salvo la formulación indicada abajo).

Un pequeño backend de tienda con seis puntos de fricción sembrados (validadores y envoltorios de dinero superficiales, un servicio de inventario que solo hace de paso, un único adaptador de pago, lógica duplicada y otros). Tareas: escribir un informe HTML de mejoras de arquitectura, un informe limitado a pagos e inventario, y «por qué es difícil de probar place_order y cómo lo arreglarías» (respuesta en el chat). Los prompts no nombran ningún término de diseño. La frase enuncia la idea de profundidad y las cosas que hay que señalar.

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 una reestructuración que hiciera el código más fácil de cambiar y de probar? Escribe tus conclusiones en un informe HTML autocontenido llamado report.html en esta carpeta (no abras un navegador ni inicies un se…
2. Solo pagos e inventario — Fíjate solo en las partes de pago e inventario de este backend y dime qué reestructuraciones valdrían la pena. Escribe tus conclusiones en 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 de probar place_order? — Me resulta doloroso escribir una prueba adecuada 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 (tests ocultos / detección de problemas sembrados / comprobaciones de restricciones / renderizado+OCR cuando corresponde), de 0 a 5 por ejecución. Ningún juez LLM decidió ninguna puntuación.

Resultados

La frase única que recibió el tercer grupo: "Juzga los módulos por su profundidad: un módulo profundo tiene una interfaz pequeña que oculta mucho comportamiento; señala los módulos superficiales que solo hacen de paso, los seams hipotéticos de un solo adaptador, la lógica duplicada y el comportamiento que solo se prueba mediante helpers, e indica dónde encaja un seam para que el comportamiento se pruebe a través de la interfaz."

Puntuación media: 3.21 sin vs 3.92 con el skill (delta +0.71). Tokens por ejecución: 119k vs 133k (1.12x); tiempo 154s vs 158s. Grupo de una frase: 4.54 (la mejora del skill frente a la frase: -0.63; la mejora de la frase frente a no usar skill: +1.34); la frase usa 114k tokens por ejecución, así que el skill consume 1.17 veces sus tokens.

Qué ocurrió

• Control 3.21, skill 3.92, frase 4.54 (n=6 cada uno). Sin orientación, los informes HTML no usaron casi nada del vocabulario de arquitectura (0-2 usos de deep/shallow/seam/interface, cuando la comprobación quiere 6) en 4 de 4 ejecuciones de informe. Los informes del skill lo usaron en las 4 ejecuciones, igual que la frase.
• Escaneo de todo el backend: skill 4.24 y 3.41, frase 3.41 y 3.86, control 2.88 y 2.2. Ambos grupos guiados encontraron 3-4 de los 6 puntos sembrados; los envoltorios superficiales de validadores y el único adaptador de pago se pasaron por alto en varias ejecuciones en todos los grupos.
• Tarea centrada en pagos e inventario: skill 3.75 en ambas ejecuciones, control 2.5 en ambas, frase 5.0 en ambas. Todas las ejecuciones del skill y del control encontraron solo uno de los dos puntos (se pasó por alto el adaptador de pago único hipotético); la frase encontró ambos.
• Por qué place_order es difícil de probar: todos los grupos están cerca (control 4.17 y 5.0, skill 4.17 y 4.17, frase 5.0 y 5.0); las ejecuciones del skill se perdieron una causa (pruebas solo con helpers) en una ejecución y las capas de paso en otra.
• Tokens: skill 133k, frase 114k, control 119k por ejecución (1.12x el control). El skill se leyó en 6/6 ejecuciones con skill.

Puntuación por dimensiones

Límites de esta prueba

• Comprobaciones de recuperación basadas en reglas sobre el texto del informe (palabras clave cerca de nombres de archivo) y un recuento de vocabulario; no se juzgó si las reestructuraciones propuestas son sólidas y los informes no se abrieron en un navegador.
• La comprobación de vocabulario premia los propios términos del skill, que la frase también nombra, y favorece a los grupos guiados.
• La comprobación de «antes/después» solo aparece en 2 ejecuciones que fallan en la tarea de escaneo; no es un diferenciador.
• n=2 por celda; un único código base pequeño.
• 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

Véase security.md. Escaneo: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredicto: seguro de ejecutar (sandbox sin red). Un escaneo limpio no demuestra que un skill sea seguro.

Conclusión

El skill aporta claramente a la revisión el marco de profundidad de módulos que un prompt sin más no tiene, con una pequeña mejora de puntuación frente al control, pero la misma idea en una frase encuentra más problemas sembrados con menos tokens, así que la mejora es sobre todo estilística.