🗣️ Qué es el Lenguaje Ubicuo
Lenguaje ubicuo es un término acuñado por Eric Evans en Domain-Driven Design (2003). La idea es sencilla: el equipo, el código y la documentación comparten exactamente el mismo vocabulario. Sin traducciones entre "término del negocio" y "término técnico". Sin sinónimos. Sin ambigüedad. Una palabra, un concepto.
En el contexto del trabajo con agentes (Claude Code, Codex, Copilot), el lenguaje ubicuo deja de ser «una buena práctica» y se convierte en infraestructura crítica. Cada término ambiguo cuesta tokens, atención e iteraciones. Cada término bien definido reduce los prompts en órdenes de magnitud.
💡 Tip: la regla de 20→1
La heurística práctica es: si necesitas 20 palabras para explicar un concepto al agente cada vez que aparece, ese concepto merece un nombre. Defínelo una vez en CONTEXT.md, y usa ese nombre de ahí en adelante.
El resultado es impresionante: cambias 20 tokens repetidos en cada turno por 1 token con nombre y una línea de definición en el contexto inicial.
Ejemplo: "cascada de materialización"
✗ ANTES (sin nombre)
Cada vez que aparecía el bug, alguien escribía en el chat:
"Cuando el usuario actualiza un campo derivado, todos los demás campos que dependen de él deben recalcularse en orden, y si alguno falla, los siguientes quedan inconsistentes y tenemos que volver a ejecutar todo desde el principio..."
→ Más de 40 palabras, repetidas en 12 conversaciones diferentes.
✓ DESPUÉS (con nombre)
Definimos en CONTEXT.md:
materialization cascade: recálculo secuencial de campos derivados tras una mutación.
"El bug está en la cascada de materialización cuando falla el paso 3."
→ 12 palabras, cero ambigüedad.
📑 Anatomía de CONTEXT.md
O CONTEXT.md es el archivo donde vive el lenguaje ubicuo de tu proyecto. Es el primer archivo que lee un agente cuando empieza a trabajar. Estructura mínima recomendada:
# MeuProjeto ## Language **materialization cascade**: recálculo sequencial de campos derivados após mutação de um campo-raiz. _Avoid_: "recálculo em cadeia", "refresh", "update propagation" **handoff**: documento estruturado escrito ao fim de uma sessão pra continuar contexto em outra. Não confundir com "resumo". _Avoid_: "summary", "transferência", "wrap-up doc" **flagged ambiguity**: termo ou comportamento ainda não definido que aparece >2x em conversas — candidato a virar entrada aqui. _Avoid_: "TODO", "open question" ## Decisions - Ver pasta /adrs para decisões arquiteturais. - Mudanças em Language exigem ADR se afetam código.
Secciones obligatorias
- •Language — términos del dominio
- •Decisions — referencia a los ADR
- •Encabezado con el nombre del proyecto
Secciones opcionales (úsalas cuando sean útiles)
- •Constraints — límites técnicos/regulatorios
- •Conventions — estilo, nombres de archivos
- •Ambigüedades señaladas — cosas por resolver
📐 El patrón "término + Avoid"
Cada entrada de Language tiene 2 partes: la definición positiva y la lista de sinónimos que deben evitarse. ¿Por qué? Porque, sin eso, todos (personas y agentes) vuelven a introducir el sinónimo en 2 semanas.
O Avoid es lo que evita la entropía. Es la regla que cita el agente cuando escribes "refresh" en un PR y te responde "¿quisiste decir materialization cascade?".
🏛️ ADRs (Architecture Decision Records)
Uno ADR es un documento breve que registra una decisión arquitectónica: qué se decidió, en qué contexto y cuáles son las consecuencias. Término acuñado por Michael Nygard en 2011. El formato elegido es minimalista: 4 secciones, 1 página.
🧱 Estructura canónica de un ADR
- 1. Estado — proposed / accepted / deprecated / superseded by ADR-NNN
- 2. Context — ¿cuál era la situación? ¿Qué problema queríamos resolver?
- 3. Decision — lo que decidimos hacer (frase activa, en presente).
- 4. Consequences — compromisos asumidos, qué quedó peor y qué quedó mejor.
Ejemplo: ADR-007 — Postgres en lugar de Mongo
# ADR-007: Usar Postgres em vez de Mongo para o catálogo de produtos ## Status Accepted — 2025-11-12 ## Context O catálogo cresceu pra ~2M de itens com relações fortes (SKU ↔ variantes ↔ preços regionais ↔ promoções). Mongo nos forçou a duplicar dados pra evitar joins manuais, e a materialization cascade ficou frágil. Precisamos de JOINs nativos, transações ACID e queries analíticas ad-hoc. ## Decision Migrar o catálogo para Postgres 16. Mantemos Mongo apenas para session blobs (efêmeros, schema-less). ## Consequences + JOINs e CTEs viáveis; analytics direto no DB. + materialization cascade vira VIEW materializada (uma única fonte da verdade). - Migração custa ~3 semanas + 1 freeze de 4h. - Time precisa subir nível em índices Postgres. - 2 bancos em produção (overhead operacional).
💡 Tip: un ADR se congela, no se edita
Los ADRs son inmutables después de aceptados. ¿Cambiaste de idea? Crea un ADR nuevo con status "supersedes ADR-007". Así preservas la historia: en 6 meses, cuando alguien pregunte "¿por qué elegimos Postgres?", la respuesta original seguirá intacta, junto con la justificación del cambio.
🔥 Ejemplo real: cascada de materialización
Cómo un equipo descubrió un bug, le dio nombre al concepto y vio cómo ese nombre se propagaba desde CONTEXT.md hasta el código de producción en 2 semanas. Historia real, anonimizada.
Día 0 — bug en producción
Síntoma: los campos del precio final quedaban inconsistentes después de un cambio en el impuesto regional.
Cada ingeniero describía el bug con palabras diferentes: «cascade», «recalc bug», «chain refresh issue». Ningún agente podía ayudar: el problema era invisible porque no tenía nombre.
Día 3 — bautismo
El tech lead abre CONTEXT.md y escribe la entrada.
materialization cascade: recálculo secuencial de campos derivados tras la mutación de un campo raíz. Avoid: cascade, recalc, refresh.
A partir de ese momento, Claude Code empieza a usar el término en sus respuestas. En 24h, 4 PR ya mencionan "materialization cascade" en el título.
Día 7 — código renombrado
Refactor: refreshPrices() → runMaterializationCascade().
La función, la clase, el módulo, la métrica de Prometheus, el evento de log: todo empezó a usar el mismo nombre. Buscar "materialization cascade" en el repo empezó a mostrar todos los puntos relevantes.
Día 14 — ADR + decisión
Nace el ADR-007: sustituir la cascada imperativa por una VIEW materializada en Postgres.
El agente, con CONTEXT.md + ADR como contexto, propone el patch en una sola conversación. Sin que nadie tenga que explicar el problema de nuevo. El término se convirtió en palanca.
📊 Métricas del antes y el después
- Antes: ~14 días por iteración de fix, 3 PRs revertidos.
- Después: 1 PR, mergeado en 36h, cero rollbacks.
- Tokens en los prompts: caída de ~70% en las conversaciones sobre el sistema de precios.
🔄 Mantenimiento continuo
El lenguaje ubicuo no es un acto único: es una práctica. Sin mantenimiento, CONTEXT.md se vuelve un fósil en 3 meses: términos obsoletos, definiciones inconsistentes con el código y sinónimos que vuelven a la vida. El ciclo saludable tiene 4 pasos:
Cada nueva feature → revisa el CONTEXT.md
Antes de programar, pregunta: "¿esta funcionalidad introduce algún término nuevo? ¿Algún término existente cambia de significado?". Si es así, actualízalo ANTES del código.
Ambigüedades señaladas → revisar semanalmente
La sección "Flagged Ambiguities" enumera términos que aparecieron >2x sin una definición clara. Una vez por semana, alguien promueve los más usados a entradas formales.
Decisión importante → ADR nuevo
Cada vez que un cambio altera los trade-offs o supera una decisión anterior, crea un ADR. Marca el anterior como «superseded by ADR-NNN» — nunca lo elimines.
El lenguaje evoluciona: tú documentas esa evolución
¿Término en desuso? Márcalo como "deprecated, sustituido por X". ¿Término refinado? Actualiza la definición con la fecha. El CONTEXT.md también es la historia semántica del proyecto.
✓ Mantenerlo vivo
- ✓Actualizar junto con cada PR relevante
- ✓Revisar las ambigüedades marcadas cada viernes
- ✓Citar el término en los commits ("fix: materialization cascade reorder")
- ✓Enlaza los ADRs en la descripción del PR cuando corresponda
✗ Dejar que se deteriore
- ✗Crear y no volver a abrir
- ✗Aceptar sinónimos en los PRs sin cuestionarlos
- ✗Editar ADR antiguos en vez de crear nuevos
- ✗Dejar que Flagged Ambiguities crezca indefinidamente
📈 Beneficios medibles
El lenguaje ubicuo no es estética: es una palanca operativa. Las 4 ventajas que aparecen en los equipos que adoptan CONTEXT.md + ADRs de verdad:
🎯 Los 4 beneficios concretos
-
1.
Nombres coherentes en toda la stack. Función, clase, log, métrica, dashboard, ticket y PR usan la misma palabra. Buscar = encontrar.
-
2.
Código navegable para principiantes. Un product manager lee el nombre del método y entiende el dominio. La incorporación pasa de semanas a días.
-
3.
Menos tokens en el thinking. El agente no necesita "inferir lo que quisiste decir". Reduce los prompts largos y elimina los turnos de aclaración. En proyectos complejos, reduce el consumo entre un 40 y un 70%.
-
4.
Alineación entre humanos y agentes. Claude Code y el ingeniero usan el mismo vocabulario. El pull request se convirtió en un diálogo entre iguales, no en una traducción.
🛠️ Ejercicio práctico
Es hora de hacerlo. El ejercicio tiene 3 pasos y lleva ~15 minutos. Hazlo AHORA, antes de pasar al módulo 1.4.
🎯 Paso a paso
-
1.
Crea el archivo
En la raíz del proyecto actual (cualquiera — puede ser personal), crea
CONTEXT.mdcon la plantilla de la Sección 2. -
2.
Define 3 términos de tu dominio
Piensa en conversaciones recientes en las que tuviste que explicar lo mismo más de una vez. Esos son candidatos obvios. Para cada término, escribe: definición (1 frase) + Avoid (los sinónimos que quieres eliminar).
-
3.
Ejecuta
/grill-with-docsEn Claude Code, ejecuta el comando con algún plan o idea en mente. El grill usará tu CONTEXT.md como referencia y cuestionará las inconsistencias. Observa cuántas veces menciona tus términos.
💡 Consejo: empieza poco a poco, evoluciona cada semana
No intentes listar 50 términos el primer día: es la receta para abandonar el archivo. Empieza con 3, úsalos durante 1 semana y agrega 2-3 nuevos. En 1 mes tendrás un glosario vivo y útil en vez de un documento muerto.
✅ Lista de verificación del ejercicio
- ☐CONTEXT.md creado en la raíz
- ☐3 términos con definición + Avoid
- ☐
/grill-with-docsejecutado al menos 1x - ☐¿Notaste alguna diferencia en la respuesta del agente?
📝 Resumen + Próximos pasos
Siguiente módulo:
1.4 — Skills, subagentes y el ecosistema Claude Code