grill-with-docs y domain-modeling: glosario y ADR

grill-with-docs es la versión de grill-me para cuando trabajas dentro de un repositorio: el mismo interrogatorio por rondas, pero mientras hablas el agente mantiene un glosario del proyecto (GLOSSARY.md) y registra las decisiones difíciles de revertir como ADR. La disciplina que hace ese trabajo es otra skill, domain-modeling, y por eso las tratamos juntas. Ambas son del repositorio mattpocock/skills, con licencia MIT.

Es la cuarta parte de la guía de las skills de Matt Pocock. Su autor dice de esta técnica que "puede que sea la más potente del repositorio".

El problema: el agente usa 20 palabras donde basta una

Al empezar un proyecto, los desarrolladores y la gente para la que construyen hablan idiomas distintos. Con los agentes pasa lo mismo: entran en un proyecto sin conocer su jerga y la van deduciendo sobre la marcha, así que dan rodeos para describir lo que el equipo nombra con una palabra.

El README pone un ejemplo de uno de sus proyectos:

Antes: "Hay un problema cuando una lección dentro de una sección de un curso se hace 'real' (es decir, se le da un sitio en el sistema de ficheros)".
Después: "Hay un problema con la cascada de materialización".

La solución viene del *Domain-Driven Design* de Eric Evans: un lenguaje ubicuo, un vocabulario único que comparten las personas, el código y ahora también el agente. Las ventajas que enumera el repositorio:

Las variables, funciones y ficheros se nombran de forma coherente.
El código es más fácil de navegar para el agente.
El agente gasta menos tokens pensando, porque tiene un lenguaje más conciso.

Cómo se reparten el trabajo

grill-with-docs es otra skill de una línea: "llama a la skill grilling y a la skill domain-modeling". La primera pone el interrogatorio por rondas; la segunda, la disciplina de vocabulario.

Skill	Tipo	Qué hace
`grill-with-docs`	La invocas tú	Lanza las dos de abajo a la vez
`grilling`	La invoca el modelo	Árbol de decisiones, rondas, frontera, una recomendación por pregunta
`domain-modeling`	La invoca el modelo	Cuestiona términos, prueba escenarios, escribe `GLOSSARY.md` y ADR

domain-modeling también funciona sola. El agente la carga cuando hablas de la terminología del código o editas un GLOSSARY.md o un ADR.

Lo que hace domain-modeling durante la sesión

El SKILL.md define cinco comportamientos activos:

Contrastar con el glosario. Si usas un término que choca con GLOSSARY.md, lo dice en el momento: "Tu glosario define 'cancelación' como X, pero parece que quieres decir Y. ¿Cuál es?".
Afinar el lenguaje difuso. Ante un término vago o con varios significados, propone uno canónico: "Dices 'cuenta': ¿el Cliente o el Usuario? Son cosas distintas".
Probar con escenarios concretos. Inventa casos límite para obligarte a definir dónde acaba un concepto y empieza otro.
Comparar con el código. Si dices cómo funciona algo, comprueba si el código está de acuerdo: "Tu código cancela Pedidos enteros, pero acabas de decir que la cancelación parcial es posible. ¿Qué es lo correcto?".
Actualizar GLOSSARY.md en el momento, sin acumular cambios para el final.

Y una regla estricta: el glosario no lleva ningún detalle de implementación. No es un spec ni un bloc de notas. Es un glosario y nada más.

El formato del GLOSSARY.md

Cada término lleva una definición de una o dos frases y una línea _Avoid_ con los sinónimos que no se deben usar:

snippettext

# Pedidos

Recibe y sigue los pedidos de los clientes.

## Language

**Pedido**:
Solicitud de compra de un cliente que el almacén debe preparar.
_Avoid_: Compra, transacción

**Factura**:
Petición de pago enviada al cliente después de la entrega.
_Avoid_: Recibo, cobro

Las reglas del formato: sé opinable (elige una palabra y manda las demás a _Avoid_), definiciones de una o dos frases, solo términos propios del proyecto (nada de "timeout" o "caché") y agrupa por subtítulos cuando aparezcan familias de términos.

En un repositorio normal hay un único GLOSSARY.md en la raíz. En un monorepo con varios contextos, un GLOSSARY-MAP.md en la raíz apunta al glosario de cada uno y describe cómo se relacionan.

Cuándo merece un ADR

Un ADR (Architecture Decision Record) registra *que* se tomó una decisión y *por qué*. Viven en docs/adr/0001-slug.md, 0002-slug.md... y pueden ser un solo párrafo. domain-modeling solo ofrece crear uno cuando se cumplen las tres condiciones:

Difícil de revertir: cambiar de idea más tarde cuesta de verdad.
Sorprendente sin contexto: alguien leerá el código y se preguntará "¿por qué lo hicieron así?".
Fruto de un compromiso real: había alternativas y elegiste una por motivos concretos.

Ejemplos que sí cumplen: "usamos SQL a mano en lugar de un ORM por X", "no podemos usar AWS por cumplimiento normativo", "Pedidos y Facturación se comunican por eventos, no por HTTP síncrono". Si la decisión es fácil de revertir o no sorprende a nadie, no hay ADR.

GLOSSARY.md real creado por grill-with-docs en un repositorio de ejemplo de un taller de bicicletas, con los términos Cita, Reprogramar, Capacidad diaria y Orden — El glosario que escribió el agente tras la segunda ronda, sin que se lo pidiéramos · codigoagente

Prueba real: reprogramar citas en un taller de bicicletas

Creamos un repositorio mínimo con dos ficheros TypeScript, con el desorden típico de un proyecto real:

src/citas.tstypescript

export type Turno = { id: string; clienteId: string; bici: string; fecha: Date; estado: "pendiente" | "confirmada" | "cancelada" };

export function crearReserva(clienteId: string, bici: string, fecha: Date): Turno { /* ... */ }

export function cancelarCita(t: Turno): Turno { /* ... */ }

src/ordenes.tstypescript

// Orden de trabajo: se crea cuando la bici llega al taller
export type Orden = { id: string; turnoId: string; mecanico: string; repuestos: string[]; total: number };

Lanzamos en Claude Code 2.1.316 (Sonnet 5.5), con permisos de escritura en esa carpeta:

snippettext

/mattpocock-skills:grill-with-docs Quiero que los clientes puedan reprogramar su cita desde un enlace en el WhatsApp de confirmación, sin llamar al taller.

Ronda 1: primero el vocabulario

Antes de preguntar, el agente leyó el código y detectó que había tres palabras para lo mismo: Turno, Reserva y Cita. Su primera pregunta fue elegir una:

Q1 - Vocabulario: ¿Cita, Turno o Reserva? Hoy el código mezcla los tres. ¿Dejamos Cita como único término canónico (el que usa el cliente), renombramos Turno/crearReserva a Cita, y lo registramos en el glosario?

La segunda ya usaba el código para cuestionar el diseño: si reprogramar cambia la misma cita o crea otra, porque una Orden apunta a turnoId y crear otra cita rompería esa relación. Le siguieron estados reprogramables, antelación mínima, límite de cambios, seguridad del enlace y disponibilidad.

Ronda 2: el glosario aparece

Respondimos (cambiando la antelación de 24 a 12 horas) y el agente creó GLOSSARY.md con cuatro términos: Cita (evitar Turno, Reserva), Reprogramar (evitar "cancelar y volver a reservar", "mover"), Capacidad diaria (evitar cupo, aforo) y Orden (evitar ticket, trabajo). Dejó fuera a propósito los términos sin resolver.

La ronda 2 siguió con preguntas que el glosario hacía más precisas: cómo cuenta la capacidad diaria al reprogramar, si una cita tiene hora o solo día, qué pasa con un enlace caducado.

Lo que hizo bien y lo que no

Bien: detectó el problema de vocabulario sin que se lo dijéramos y lo convirtió en la primera decisión.
Bien: no creó ningún ADR. Ninguna decisión de estas dos rondas cumplía las tres condiciones.
Mejorable: la definición de Capacidad diaria incluía el valor "(8)". Es un dato de configuración, justo lo que la skill prohíbe meter en el glosario. Revisa el GLOSSARY.md en cada commit como revisarías código.

Coste de las dos rondas: 0,24 USD.

grill-with-docs frente a grill-me

	`grill-me`	`grill-with-docs`
Interrogatorio	Igual	Igual
Lee el código	Si hay código, sí	Sí, y lo contrasta con lo que dices
Escribe ficheros	No	`GLOSSARY.md` y `docs/adr/`
Uso recomendado	Planes, decisiones, textos sin repositorio	Cualquier cambio dentro de un repositorio

El autor lo dice sin rodeos: si hay un directorio de trabajo, grill-with-docs es estrictamente mejor.

Cómo encaja con el resto de skills

El glosario no se queda en la sesión. tdd, diagnosing-bugs, to-spec, to-tickets, triage y pr leen GLOSSARY.md para nombrar tests, tickets y PR con el mismo vocabulario. wait-what lo usa para explicarte de nuevo algo que no entendiste. Cuanto antes exista el glosario, más rinden las demás.

Errores frecuentes

Usar el glosario como documentación técnica. Nada de rutas, valores de configuración ni decisiones de implementación.
Pedir ADR para todo. Si la decisión se revierte en una tarde, no necesita registro.
No dar permisos de escritura. Sin Write o Edit, el agente hace el interrogatorio pero no puede guardar el glosario.
Olvidar el _Avoid_. Es la parte que impide que vuelvan los sinónimos.

Preguntas frecuentes

¿Tengo que crear el GLOSSARY.md antes? No. Se crea solo cuando se resuelve el primer término, y docs/adr/ cuando hace falta el primer ADR.

¿Puedo tener el glosario en español? Sí. El formato usa encabezados en inglés (## Language, _Avoid_), pero los términos y definiciones van en el idioma del proyecto.

¿Qué pasa con un CONTEXT.md antiguo? Versiones anteriores usaban ese nombre. /setup-matt-pocock-skills ofrece renombrarlo a GLOSSARY.md.

Siguiente paso

Lanza /grill-with-docs en tu próximo cambio y revisa el GLOSSARY.md que deja. En la parte 5 de la guía convertimos el resultado de un interrogatorio en trabajo ejecutable con to-spec y to-tickets.