La habilidad /domain-modeling

Fuente: The /domain-modeling Skill — traducción comunitaria no oficial al español.

Qué hace

domain-modeling construye y afina el lenguaje ubicuo de un proyecto mientras diseñas: cuestiona un término que choca con el glosario, exige una palabra precisa donde usaste una vaga, y somete una relación a un escenario concreto hasta que los límites quedan exactos.

Es la disciplina activa, no la pasiva. Leer CONTEXT.md para tomar prestado su vocabulario es un hábito de una línea que cualquier habilidad puede hacer; esta habilidad es para cuando estás cambiando el modelo. Eso es lo que la hace interrumpir. Escribe un término resuelto en CONTEXT.md en el momento en que se resuelve, en medio de la conversación, en vez de producir un glosario ordenado al final, porque la versión en lote es un resumen de una sesión, y la versión inline es la salida real de la sesión.

Cuándo usarla

Escribe /domain-modeling, o el agente la usará automáticamente cuando una tarea encaje. En la práctica, la invocación automática es la parte más débil de la habilidad: cuando grill-with-docs o wayfinder dicen que la cargue, los modelos con frecuencia cargan grilling y omiten esta. Si una sesión de interrogatorio corre y CONTEXT.md queda intacto al final, eso fue lo que pasó; invócala por nombre junto a la otra habilidad.

Úsala cuando las palabras son el problema:

La situación	El movimiento
Dos personas entienden distinto «cancelación»	domain-modeling: elige el término canónico, lista el otro bajo _Avoid_
«Cuenta» está haciendo tres trabajos en tres archivos	domain-modeling: divídelo en Customer y User
Acabas de tomar una decisión arquitectónica difícil de revertir	domain-modeling: ofrece un ADR, si la decisión supera la vara
La forma del módulo es el problema: dónde va la costura, qué tan profunda es la interfaz	codebase-design
Quieres que todo el plan sea interrogado antes de construir	grill-with-docs, que dirige esta habilidad por debajo
Quieres consultar un término, no cambiarlo	Nada. Lee CONTEXT.md. Es un archivo.

Requisitos previos

Ninguno por adelantado. La habilidad escribe en dos lugares y crea ambos de forma perezosa:

• CONTEXT.md en la raíz del repo, creado por el primer término resuelto. En un repo con CONTEXT-MAP.md en la raíz, los términos van en cambio al CONTEXT.md por contexto que el mapa señale.
• docs/adr/, creado por el primer ADR que supere la vara.

Nada necesita existir antes de empezar, y nada se crea de forma especulativa.

Dos artefactos, dos varas

El glosario y el ADR se someten a estándares distintos, y confundirlos es de donde viene la mayor parte de los problemas de esta habilidad.

	CONTEXT.md	docs/adr/NNNN-slug.md
Contiene	Términos. Lo que una cosa es, en una o dos oraciones, con sinónimos rechazados bajo _Avoid_	Una decisión, en una a tres oraciones: contexto, elección, razón
Vara para escribir	Un término vago se volvió canónico	Las tres: difícil de revertir, sorprendente sin contexto, resultado de un trade-off real
Se escribe	Inline, en el momento en que el término se acuerda	Se ofrece, no se asume
Nunca contiene	Detalles de implementación, una spec, un bloc de notas, conceptos generales de programación	Un diario de cada decisión tomada en esta sesión

Si falla cualquiera de las tres pruebas del ADR, no hay ADR. Una decisión fácil de revertir simplemente se revertirá; una no sorprendente no es pregunta de nadie; una sin alternativa real registra que hiciste lo obvio.

La regla de CONTEXT.md es la que realmente hay que sostener, porque es la que se rompe en terreno. Es un glosario y nada más. Sin control, los modelos tratan «escribe en CONTEXT.md» como permiso para persistir cada respuesta que das, y el archivo se convierte en una spec en curso. Este es el problema más reportado de la habilidad, en varios modelos.

Referencias cruzadas, y dónde se detienen

El movimiento que hace clic en la habilidad: cuando afirmas cómo funciona algo, verifica el código y muestra la contradicción. «Tu código cancela Orders completas, pero acabas de decir que la cancelación parcial es posible, ¿cuál es la correcta?» El lenguaje y el código se hacen concordar, en voz alta, antes de cambiar cualquiera de los dos.

El límite vale conocerse. Referencia de forma cruzada código y el CONTEXT.md/ADRs commiteados, y nada más. No busca en tu gestor de pendientes, así que una colisión de nombres que se discutió y se resolvió deliberadamente en un issue cerrado hace meses reaparece como si fuera nueva. Hay una solicitud abierta para corregirlo; hasta entonces, la solución es poner la instrucción en tu propio docs/agents/domain.md, que las habilidades ya leen.

Preguntas frecuentes

Mi CONTEXT.md tiene 500 líneas. 1.000. 3.000. ¿Qué hago? El tamaño es un síntoma, no la enfermedad: el archivo ha absorbido detalle de implementación y decisiones que nunca fueron material de glosario. La corrección es una instrucción directa: /grill-with-docs make my CONTEXT.md more concise and remove any implementation details from it. Ejecútalo contra un archivo inflado y la mayor parte se va. Solo recurre a una división con CONTEXT-MAP.md cuando el archivo sea genuinamente escueto y aún cubra dos dominios que un lector no querría sostener a la vez; dividir un archivo inflado solo te da varios archivos inflados. La guía de la habilidad aquí aún no es lo bastante fuerte para prevenir el crecimiento en primer lugar, y el issue que lo rastrea sigue abierto.

¿Por qué es CONTEXT.md y no GLOSSARY.md? Esta es la pregunta de nombres más discutida de todo el conjunto y no tiene respuesta asentada. El caso contra el nombre actual es bueno: si es «un glosario y nada más», GLOSSARY.md lo dice, y, como lo dijo un lector, «with ai agents everything is context». El caso a favor es el mapa: CONTEXT-MAP.md apuntando a varios archivos CONTEXT.md se lee natural de un modo que GLOSSARY-MAP.md no, y context es la palabra DDD establecida para un área acotada del modelo. Al menos una persona mantiene una bifurcación local solo para renombrar el archivo. Puedes hacer lo mismo, pero cada otra habilidad del conjunto busca CONTEXT.md, así que renombrar significa parchearlas todas.

¿A dónde fue /ubiquitous-language? Se eliminó, y no se deprecó. Su trabajo se mudó a domain-modeling, que mantiene todo el modelo de forma continua en vez de volcar un glosario desde una conversación. La imposición de vocabulario se volvió más determinante, no menos: ahora corre bajo interrogatorio, triaje y mapeo en vez de ser una pasada separada que recuerdas hacer.

¿Cómo obtengo un glosario para una base de código que no tiene ninguno? Pídelo explícitamente en vez de esperar a que se acumule. /grill-with-docs help me scaffold my existing repo with a CONTEXT.md es la ruta documentada; espera un interrogatorio largo: un usuario reportó más de 50 preguntas antes de que el archivo quedara en forma. El uso incidental construye el glosario demasiado lento en un repo brownfield.

¿Puedo mantener el modelo de dominio y usar mi propio formato de ADR? Hoy no limpiamente. La mitad de glosario y la mitad de ADR vienen en una habilidad, así que un equipo con una convención ADR establecida (distinta plantilla, distinta ubicación, distinto nombrado) recibe instrucciones que chocan con su estilo de casa. Las opciones actuales son copiar la habilidad localmente y editarla, o sobrescribir las convenciones ADR en los propios docs de agente de tu repo. Separar ambas es una solicitud abierta.

¿Un glosario realmente compensa? Es un artefacto más que revisar, y puede quedar obsoleto. A veces no, y vale ser honesto sobre dónde. DDD es menos útil cuanto más cerca está de la implementación: el retorno está aguas arriba, en nombres y alineación de conceptos, no en ceremonia de agregados y capas. El control de sinónimos importa en límites de nombrado: nombres de módulos, nombres de tablas, enums de estado, títulos de issues, comandos CLI. Importa mucho menos en prosa ordinaria. También hay una objeción viva de que los términos de dominio comprimen la comunicación entre humanos que ya los comparten, y que un agente responde igual ante la descripción en lenguaje simple. En esa lectura, el valor del glosario es mantenerte a ti y a tus revisores alineados con lo que el agente hace, no hacer mejor al agente. En una construcción de un día, omítelo. Y un glosario no revisado y autorado por un agente es peor que ninguno: se vuelve lore convincente que sesiones posteriores tratan como verdad.

¿Puede convertir mis prompts vagos en lenguaje de dominio por mí? No, y no hay planes de una habilidad que lo haga. Un lenguaje de dominio que tú mismo no entiendes se vuelve palabrería sin sentido una vez escrito. Esta habilidad impone precisión una vez que tienes el entendimiento; no fabrica vocabulario que no tienes. La trampa relacionada es usar palabras de dominio sin hacer el modelado: sustantivos correctos sobre la estructura conceptual equivocada producen salida que se lee correcta y no lo es.

Funciona si

• Te detiene a mitad de oración para preguntar cuál de dos cosas quisiste decir, en vez de elegir una y seguir.
• CONTEXT.md cambia durante la conversación, no en una ráfaga al final.
• Se niega a escribir un ADR para algo que podrías deshacer mañana, y dice cuál de las tres pruebas falló.
• Las entradas nuevas definen lo que una cosa es en una o dos oraciones y nombran las palabras que abandonas bajo _Avoid_.
• Te cita tu código cuando tu código y tu oración discrepan.
• CONTEXT.md se acorta tan a menudo como se alarga.

Dónde encaja

domain-modeling es una referencia invocada por el modelo que corre bajo otras habilidades más a menudo de lo que corre sola. grill-with-docs la dirige durante una sesión de interrogatorio, wayfinder la carga mientras traza un mapa, triage la usa para mantener los tickets en las propias palabras del proyecto, e improve-codebase-architecture la llama a medida que las decisiones cristalizan. Su hermana más cercana es codebase-design: ambas son la capa de vocabulario bajo todo lo demás, esta para el dominio, aquella para la forma del módulo. También es alcanzable directamente, cuando quieres la disciplina sin comprometerte con los pasos de la habilidad que normalmente la traería. Cuando no sabes qué habilidad encaja, ask-matt te enruta.