MÓDULO 1.3

📖 Linguagem Ubíqua: CONTEXT.md + ADRs

1 palavra no lugar de 20.

8
Seções
~40
Minutos
Básico
Nível
Prática
Tipo
1

🗣️ O que é Linguagem Ubíqua

Linguagem Ubíqua é um termo cunhado por Eric Evans em Domain-Driven Design (2003). A ideia é simples: time, código e documentação compartilham exatamente o mesmo vocabulário. Sem traduções entre "termo do negócio" e "termo técnico". Sem sinônimos. Sem ambiguidade. Uma palavra, um conceito.

No contexto de trabalho com agentes (Claude Code, Codex, Copilot), a linguagem ubíqua deixa de ser "boa prática" e vira infra-estrutura crítica. Cada termo ambíguo custa tokens, atenção e iterações. Cada termo bem definido reduz prompts em ordens de magnitude.

💡 Tip: a regra dos 20→1

A heurística prática é: se você precisa de 20 palavras pra explicar um conceito ao agente toda vez que ele aparece, esse conceito merece um nome. Defina-o no CONTEXT.md uma vez, e use o nome dali em diante.

O retorno é absurdo: você troca 20 tokens repetidos a cada turno por 1 token nomeado e uma linha de definição no contexto inicial.

Exemplo: "materialization cascade"

✗ ANTES (sem nome)

Toda vez que o bug aparecia, alguém escrevia no chat:

"Quando o usuário atualiza um campo derivado, todos os outros campos que dependem dele precisam ser recalculados em ordem, e se um falhar, os subsequentes ficam inconsistentes, e a gente precisa rodar de novo do topo..."

→ 40+ palavras, repetidas em 12 conversas diferentes.

✓ DEPOIS (com nome)

Definimos no CONTEXT.md:

materialization cascade: recálculo sequencial de campos derivados após mutação.

"O bug é na materialization cascade quando o passo 3 falha."

→ 12 palavras, zero ambiguidade.

Origem
Eric Evans, DDD (2003)
Princípio
1 conceito = 1 nome
Ganho
Menos tokens, menos retrabalho
Onde mora
CONTEXT.md + ADRs
2

📑 Anatomia do CONTEXT.md

O CONTEXT.md é o arquivo onde mora a linguagem ubíqua do seu projeto. É o primeiro arquivo que um agente lê quando começa a trabalhar. Estrutura 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.

Seções obrigatórias

  • •Language — termos do domínio
  • •Decisions — ponteiro pros ADRs
  • •Cabeçalho com nome do projeto

Seções opcionais (use quando útil)

  • •Constraints — limites técnicos/regulatórios
  • •Conventions — estilo, nomes de arquivos
  • •Flagged Ambiguities — coisas a resolver

📐 O padrão "termo + Avoid"

Cada entrada de Language tem 2 partes: a definição positiva e a lista de sinônimos a evitar. Por quê? Porque sem isso, todo mundo (humano e agente) reintroduz o sinônimo em 2 semanas.

O Avoid é o que evita a entropia. É a regra que o agente cita quando você escreve "refresh" num PR e ele responde "você quis dizer materialization cascade?".

Localização
Raiz do repo
Formato
Markdown simples
Tamanho ideal
200-500 linhas
Atualização
A cada feature
3

🏛️ ADRs (Architecture Decision Records)

Um ADR é um documento curto que registra uma decisão arquitetural: o que foi decidido, em que contexto, e quais as consequências. Cunhado por Michael Nygard em 2011. O formato vencedor é minimalista — 4 seções, 1 página.

🧱 Estrutura canônica de um ADR

  • 1. Status — proposed / accepted / deprecated / superseded by ADR-NNN
  • 2. Context — qual era a situação? Qual problema queríamos resolver?
  • 3. Decision — o que decidimos fazer (frase ativa, presente).
  • 4. Consequences — trade-offs assumidos, o que ficou pior, o que ficou melhor.

Exemplo: ADR-007 — Postgres em vez 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: ADR é congelado, não editado

ADRs são imutáveis depois de aceitos. Mudou de ideia? Crie um ADR novo com status "supersedes ADR-007". Isso preserva a história — em 6 meses, quando alguém perguntar "por que escolhemos Postgres?", a resposta original ainda está intacta, junto com a justificativa da mudança.

4

🔥 Exemplo real: materialization cascade

Como uma equipe descobriu um bug, deu nome ao conceito, e viu o nome se propagar do CONTEXT.md até o código de produção em 2 semanas. História real, anonimizada.

1

Dia 0 — bug em produção

Sintoma: campos de preço final ficavam inconsistentes após mudança de imposto regional.

Cada engenheiro descrevia o bug com palavras diferentes: "cascade", "recalc bug", "chain refresh issue". Nenhum agente conseguia ajudar — o problema era invisível porque não tinha nome.

2

Dia 3 — batismo

Tech lead abre CONTEXT.md, escreve a entrada.

materialization cascade: recálculo sequencial de campos derivados após mutação de um campo-raiz. Avoid: cascade, recalc, refresh.

A partir desse momento, o Claude Code começa a usar o termo nas respostas. Em 24h, 4 PRs já citam "materialization cascade" no título.

3

Dia 7 — código renomeado

Refactor: refreshPrices() → runMaterializationCascade().

A função, a classe, o módulo, a métrica de Prometheus, o evento de log: tudo passou a usar o mesmo nome. Pesquisar "materialization cascade" no repo passou a retornar todos os pontos relevantes.

4

Dia 14 — ADR + decisão

ADR-007 nasce: substituir cascata imperativa por VIEW materializada no Postgres.

O agente, alimentado pelo CONTEXT.md + ADR, propõe o patch em uma única conversa. Sem que ninguém tenha que explicar o problema de novo. O termo virou alavanca.

📊 Métricas do antes/depois

  • Antes: ~14 dias por iteração de fix, 3 PRs revertidos.
  • Depois: 1 PR, mergeado em 36h, zero rollbacks.
  • Tokens em prompts: queda de ~70% em conversas sobre o sistema de preços.
5

🔄 Manutenção contínua

Linguagem ubíqua não é um ato único — é uma prática. Sem manutenção, o CONTEXT.md vira fóssil em 3 meses: termos obsoletos, definições inconsistentes com o código, sinônimos voltando à vida. O ciclo saudável tem 4 batidas:

1

Cada feature nova → revisita o CONTEXT.md

Antes de codar, pergunte: "essa feature introduz algum termo novo? Algum termo existente muda de significado?". Se sim, atualize ANTES do código.

2

Flagged ambiguities → revisitar semanalmente

A seção "Flagged Ambiguities" lista termos que apareceram >2x sem definição clara. Uma vez por semana, alguém promove os mais usados a entradas formais.

3

Decisão importante → ADR novo

Sempre que uma mudança altera trade-offs ou supera uma decisão antiga, crie um ADR. Marque o antigo como "superseded by ADR-NNN" — nunca delete.

4

A linguagem evolui — você documenta a evolução

Termo aposentado? Marque "deprecated, substituído por X". Termo refinado? Atualize a definição com data. O CONTEXT.md é também a história semântica do projeto.

✓ Manter vivo

  • ✓Atualizar junto com cada PR relevante
  • ✓Revisar Flagged Ambiguities toda sexta
  • ✓Citar o termo nos commits ("fix: materialization cascade reorder")
  • ✓Linkar ADRs no PR description quando aplicável

✗ Deixar apodrecer

  • ✗Criar e nunca mais abrir
  • ✗Aceitar sinônimos nos PRs sem desafiar
  • ✗Editar ADRs antigos em vez de criar novos
  • ✗Deixar Flagged Ambiguities crescer indefinidamente
6

📈 Benefícios mensuráveis

Linguagem ubíqua não é estética — é alavanca operacional. Os 4 ganhos que aparecem em times que adotam CONTEXT.md + ADRs de verdade:

🎯 Os 4 benefícios concretos

  • 1.
    Nomes consistentes em toda a stack. Função, classe, log, métrica, dashboard, ticket e PR usam a mesma palavra. Buscar = encontrar.
  • 2.
    Código navegável por leigos. Um produto-manager lê o nome do método e entende o domínio. Onboarding cai de semanas pra dias.
  • 3.
    Menos tokens em thinking. O agente não precisa "inferir o que você quis dizer". Reduz prompts longos e elimina turnos de clarificação. Em projetos densos, queda de 40-70% no consumo.
  • 4.
    Alinhamento humano-agente. O Claude Code e o engenheiro usam o mesmo vocabulário. Pull request virou diálogo em pé de igualdade, não tradução.
Buscas
+90% precisão grep/IDE
Onboarding
2 semanas → 3 dias
Tokens
-40 a -70%
Iterações
-50% retrabalho
7

🛠️ Exercício prático

Hora de fazer. O exercício tem 3 passos e leva ~15 minutos. Faça AGORA, antes de ir para o módulo 1.4.

🎯 Passo a passo

  1. 1.
    Crie o arquivo

    Na raiz do projeto atual (qualquer um — pode ser pessoal), crie CONTEXT.md com o template da Seção 2.

  2. 2.
    Defina 3 termos do seu domínio

    Pense em conversas recentes onde você precisou explicar a mesma coisa >1x. Esses são candidatos óbvios. Para cada termo, escreva: definição (1 frase) + Avoid (os sinônimos que você quer matar).

  3. 3.
    Rode /grill-with-docs

    No Claude Code, rode o comando com algum plano ou ideia em mente. O grill vai usar seu CONTEXT.md como referência e desafiar inconsistências. Observe quantas vezes ele cita seus termos.

💡 Dica: comece pequeno, evolua semanal

Não tente listar 50 termos no primeiro dia — é receita pra abandonar o arquivo. Comece com 3, use por 1 semana, adicione 2-3 novos. Em 1 mês você terá um glossário vivo e útil em vez de um documento morto.

✅ Checklist do exercício

  • ☐CONTEXT.md criado na raiz
  • ☐3 termos com definição + Avoid
  • ☐/grill-with-docs rodado pelo menos 1x
  • ☐Observou diferença na resposta do agente?

📝 Resumo + Próximos passos

✓
Linguagem ubíqua = 1 conceito, 1 nome — herança DDD de Eric Evans, vital com agentes.
✓
CONTEXT.md é o lar da linguagem — seções Language + Decisions, padrão "termo + Avoid".
✓
ADRs registram decisões arquiteturais — Status / Context / Decision / Consequences, imutáveis.
✓
Manutenção é semanal, não anual — revisitar Flagged Ambiguities, atualizar junto com cada feature.
✓
Ganho mensurável — menos tokens, onboarding mais rápido, alinhamento humano-agente.

Próximo Módulo:

1.4 — Skills, sub-agentes e o ecossistema Claude Code

← Voltar para Trilha Próximo Módulo →