domain-modeling (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). Tres tareas con redacción natural que no nombra un formato: «configura el glosario de dominio del proyecto» (una app de biblioteca que llama a la misma persona member/patron/borrower/customer), «registra esta decisión de arquitectura» (el dinero como céntimos enteros) y «dos decisiones de la reunión; registra lo que merezca registrarse» (una migración a Auth0 difícil de deshacer y un renombrado de clase CSS que no lo es), partiendo de un repo con ADR 0001 y 0002. Prompt de una frase = toda la convención en una sola frase.

Comparación de tres ramas

Medido con Codex CLI en 18 ejecuciones, puntuado con comprobaciones basadas en reglas y sin juez LLM. Total 28.2 / 30, veredicto Recomendada.

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

Qué es

El skill domain-modeling (mattpocock/skills): mantiene afinado el lenguaje de dominio de un proyecto. Mantiene un GLOSSARY.md (un término canónico en negrita por concepto, una definición ajustada, sinónimos en _Avoid_:, nada de términos genéricos de programación) y escribe ADR en docs/adr/ solo para decisiones difíciles de revertir, sorprendentes y con verdaderas contrapartidas, como un párrafo breve con numeración secuencial.

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).

Tres tareas con una redacción natural que no nombra ningún formato: «prepara el glosario de dominio del proyecto» (una aplicación de biblioteca que llama a la misma persona member/patron/borrower/customer), «registra esta decisión de arquitectura» (el dinero como céntimos enteros) y «dos decisiones de la reunión; registra lo que merezca registrarse» (una migración a Auth0 que es difícil de deshacer y un cambio de nombre de clase CSS que no lo es), partiendo de un repositorio con los ADR 0001 y 0002. La frase = toda la convención en una sola frase.

1. Crear un glosario a partir de términos ambiguos — Nuestra aplicación de préstamo de biblioteca usa 'member', 'patron', 'borrower' y 'customer' para la misma persona (alguien que puede tomar libros prestados). Un 'loan' también se llama 'checkout' o 'rental'. Una 'copy' es un libro físico, un 'title' es el libro abstracto. Por favor, prepara el pr…
2. Registrar una decisión difícil de revertir — Registra esta decisión de arquitectura para el repositorio: guardamos el dinero como céntimos enteros en Postgres en lugar de NUMERIC/DECIMAL, porque la API del socio de pagos usa céntimos enteros y los errores de redondeo ya nos han pasado factura dos veces. Redáctala.
3. Registrar solo lo que merece un ADR — Dos decisiones de la reunión de hoy: (a) vamos a pasar la autenticación de nuestra propia tabla de contraseñas a un proveedor de identidad externo (Auth0): un trimestre de trabajo para deshacerlo; (b) hemos renombrado la clase CSS .btn-main a .btn-primary. Registra lo que merezca registr…

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: "Mantén afinado el lenguaje de dominio del proyecto: escribe un GLOSSARY.md con un término canónico en negrita por concepto (una definición ajustada y sinónimos _Avoid_:, sin términos genéricos de programación), y registra solo las decisiones difíciles de revertir, sorprendentes y con verdaderas contrapartidas como ADR breves numerados secuencialmente en docs/adr/ (un párrafo, no una plantilla)."

Puntuación media: 2.8 sin vs 5.0 con el skill (delta +2.2). Tokens por ejecución: 83k vs 80k (0.96x); tiempo 45s vs 35s. Grupo de una frase: 4.61 (la mejora del skill frente a la frase: +0.39; la mejora de la frase frente a no usar skill: +1.8); la frase usa 83k tokens por ejecución, así que el skill consume 0.96 veces sus tokens.

Qué ocurrió

• Control 2.80, frase 4.61, skill 5.00 (n=6 cada uno). El control hace lo sensato pero a su manera: un DOMAIN*GLOSSARY.md (no GLOSSARY.md) con una tabla o prosa, sin líneas \_Avoid* en ninguna de las dos ejecuciones, y ADR de 263 y 355 palabras con encabezados Context/Decision/Consequences cuando la convención quiere un párrafo breve; un ADR del control fue a docs/decisions/ en lugar de docs/adr/.
• Las dos decisiones de criterio del skill son acertadas: en las dos ejecuciones con skill de la tercera tarea registró solo el cambio a Auth0 como ADR 0003 (numeración correcta tras los 0001/0002 existentes) y dijo que se saltaba el cambio de nombre de CSS por ser fácil de revertir. El control y la frase también se saltaron el cambio de nombre, pero control-2 y frase-2 dieron una razón que mi regex no reconoció (cambio rutinario, no registrado), así que la comprobación de «me dice por qué» les da menos crédito del debido.
• La frase alcanza casi todo el formato (glosario 3.75 y 5.0, ADR 5.0, 5.0) pero un glosario de la frase usó un diseño diferente, así que falló la comprobación de estructura _Avoid_.
• Sin coste: 80k tokens por ejecución para el skill, 83k para el control y la frase. El skill se leyó en 6/6 ejecuciones con skill sin ser nombrado.

Puntuación por dimensiones

Límites de esta prueba

• Comprobaciones basadas en reglas sobre nombres de archivo, encabezados, recuentos de términos en negrita, recuentos de palabras y líneas _Avoid_. Varias son comprobaciones de forma que un control no puede cumplir sin que se le diga la forma; las comprobaciones miden el cumplimiento de esta convención de la casa, no la calidad general de la escritura.
• Suavicé los patrones de nombre de archivo y diseño después de ver que el control escribió DOMAIN_GLOSSARY.md y la frase escribió entradas con viñetas (el nombre de archivo sigue siendo una comprobación aparte), y volví a puntuar todas las ejecuciones con las mismas reglas. La regex de «por qué se omitió (b)» sigue siendo estricta.
• Repositorios sintéticos pequeños; no hay un glosario de larga vida que haya que actualizar con el tiempo.
• 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

Para un equipo que quiera esta convención de glosario y ADR, el skill lo acierta a la primera y mantiene los ADR escasos, sin tokens extra. Una instrucción de una frase consigue casi todo, así que el skill sobre todo te ahorra pegar la convención cada vez.