Capítulo 4 — Domínio antes do prompt

Um prompt pode ser preciso e ainda estar errado

Uma especificação pode ser detalhada, conter critérios de aceitação, listar arquivos, descrever APIs e ainda assim automatizar uma compreensão errada do problema.

Isso acontece quando a linguagem usada para pedir a mudança não corresponde à linguagem usada pelo negócio, pelo código ou pela equipe.

O agente recebe instruções claras sobre conceitos ambíguos.

Nesse cenário, aumentar a qualidade do prompt não resolve a raiz do problema.

A pergunta anterior é:

o que exatamente estes termos significam neste sistema?

É por isso que, no pipeline deste livro, Domain aparece antes de Architecture, Spec e Context.

Linguagem não é decoração

Eric Evans coloca a linguagem no centro de Domain-Driven Design porque o modelo não deve existir apenas em diagramas. Ele precisa sustentar a comunicação entre desenvolvedores, especialistas do domínio e a própria implementação. ¹

Uma Ubiquitous Language útil reduz a quantidade de tradução silenciosa entre o que o usuário chama de uma coisa, o que o analista escreve, o que o desenvolvedor entende, o que a classe representa, o que a API expõe e o que o agente recebe no contexto.

Quando cada camada usa um vocabulário diferente, a engenharia depende de traduções implícitas. E tradução implícita é um lugar fértil para erro.

Com agentes, esse risco aumenta porque o sistema tende a completar lacunas com uma interpretação plausível.

O agente não descobre o significado por telepatia

Um agente de codificação pode ler milhares de linhas, buscar referências, seguir tipos e identificar padrões. Isso não garante que ele compreenda o significado de negócio correto.

Se customer, account, member, subscriber e user aparecem como quase sinônimos em diferentes documentos, o agente pode produzir uma implementação tecnicamente coerente e semanticamente errada.

O problema não está na capacidade de gerar. Está no contrato semântico fornecido ao sistema.

Nossa regra será:

ambiguidades de domínio não devem ser resolvidas silenciosamente pelo agente.

Quando uma tarefa depende de um termo cujo significado altera comportamento, dados, permissões ou regras, essa ambiguidade deve ser escalada antes da implementação.

Modelo e implementação precisam conversar

DDD também rejeita uma separação rígida entre modelagem e programação. O código participa da expressão do modelo, e mudanças de implementação podem alterar o próprio entendimento do domínio. ²

Para Engenharia Agêntica, isso tem uma consequência direta.

Não basta criar um glossário e abandoná-lo. O modelo precisa aparecer em artefatos que o agente realmente consome: nomes de entidades, APIs, schemas, testes, specs, ADRs, contexto files, exemplos e documentação do domínio.

Bounded Context não é pasta

Um dos erros mais comuns ao aplicar DDD é tratar Bounded Context como sinônimo de módulo, diretório ou serviço.

Evans define o Bounded Context como a fronteira de aplicabilidade de um modelo: dentro dela, termos e regras precisam permanecer coerentes; fora dela, outros modelos podem existir. ³

Isso é especialmente importante para agentes porque uma mesma palavra pode ter significados válidos diferentes em contextos diferentes.

Account pode significar credencial de autenticação, conta financeira, cadastro comercial ou tenant de uma organização. Nenhuma dessas definições é universalmente correta.

A pergunta correta é:

em qual contexto estamos trabalhando?

Domain Context Card

Para tornar isso operacional, usaremos um artefato simples antes de mudanças relevantes: um Domain Context Card.

Ele pode existir dentro de DOMAIN.md e deve registrar, quando necessário:

• nome do contexto;
• propósito;
• atores principais;
• termos canônicos;
• termos proibidos ou ambíguos;
• invariantes;
• eventos importantes;
• entradas e saídas;
• contextos vizinhos;
• traduções necessárias;
• fonte de verdade.

O objetivo não é documentar todo o negócio. É fornecer a menor estrutura suficiente para impedir que significado crítico seja improvisado durante a geração.

Invariantes são limites de significado

Algumas regras são mais importantes que nomes.

Uma reserva não pode terminar antes de começar. Um pagamento confirmado não pode voltar silenciosamente para estado pendente. Um usuário sem autorização não pode aprovar a própria elevação de privilégio.

No nosso método, invariantes devem migrar da conversa para artefatos verificáveis sempre que possível: acceptance criteria, testes, constraints, schemas, policies e checks.

Essa passagem é importante porque um agente pode interpretar linguagem natural, mas um gate mecânico pode provar uma propriedade concreta.

Domínio vem antes dos artefatos downstream

A ordem importa. Se escrevemos primeiro a Spec e só depois discutimos domínio, podemos especificar com precisão uma abstração errada.

O fluxo preferido é:

Intent → Domain → Architecture → Spec

Intent explica por que a mudança existe. Domain fixa significado. Architecture define onde responsabilidades e dependências podem viver. Spec transforma isso em comportamento verificável.

A mesma regra vale para Context: não adianta otimizar seleção, compressão ou recuperação se o material recuperado usa conceitos contraditórios. Por isso, o contexto de domínio reaparece mais adiante como a primeira camada do modelo de Context deste livro.

O papel deste capítulo é mais restrito: reduzir ambiguidade semântica antes que ela seja transformada em arquitetura, especificação ou contexto.

Domain drift

Domínio não é estático. Termos, regras e produtos mudam.

O problema aparece quando o código, a documentação e os agentes evoluem em velocidades diferentes.

Chamaremos isso de domain drift quando o vocabulário ou as regras operacionais já não refletem o modelo vigente.

Sinais comuns incluem termos antigos em APIs novas, duas features usando palavras diferentes para o mesmo conceito, specs contradizendo schemas, testes preservando regras abandonadas ou prompts que precisam explicar exceções cada vez maiores.

Domain drift deve gerar trabalho explícito de alinhamento, não mais instruções ad hoc.

Perguntas que bloqueiam implementação

Antes de delegar uma mudança sensível, algumas perguntas devem ter resposta:

• Qual Bounded Context está sendo alterado?
• Quais termos têm significado canônico?
• Que regras nunca podem ser violadas?
• Quais estados e transições são válidos?
• Há termos iguais com significados diferentes em contextos vizinhos?
• Quem é a fonte de verdade?
• A mudança exige tradução entre modelos?

Se essas respostas não existem, o problema não é falta de prompt engineering. É falta de modelagem suficiente para delegar com segurança.

Domain before prompt

A frase deste capítulo não significa que toda tarefa exige workshop de DDD.

Significa algo mais prático:

antes de pedir que um agente transforme o sistema, torne explícito o significado que ele não deve inventar.

Para uma correção pequena, isso pode caber em três linhas. Para uma mudança de negócio central, pode exigir DOMAIN.md, exemplos, eventos, invariantes e um mapa de contexto.

A profundidade varia. A responsabilidade não.

Do domínio à arquitetura

Depois que o significado está delimitado, surge a próxima pergunta:

como impedir que a velocidade de geração atravesse fronteiras arquiteturais que deveriam permanecer estáveis?

Esse será o próximo capítulo.

Domínio define significado. Arquitetura transforma esse significado em limites de dependência e responsabilidade.

Fronteira de confiança

O agente pode inferir detalhes de implementação dentro de conceitos já delimitados. Não deve decidir silenciosamente o significado de termos de negócio, criar novas regras ou fundir contextos semanticamente distintos.

Evidência exigida

Para mudanças de domínio relevantes, exigir conforme o caso: DOMAIN.md atualizado, termos canônicos, Bounded Context identificado, invariantes explícitos, acceptance criteria derivados das regras, testes que exercitem estados ou transições críticas e revisão humana quando houver ambiguidade semântica.

Rollback e recuperação

Rollback técnico não corrige automaticamente uma interpretação de domínio errada. Quando o erro é semântico, a recuperação pode exigir reverter dados, contratos, migrações e integrações. Por isso, ambiguidades devem ser resolvidas antes de ampliar o blast radius.

Proveniência das fontes

Rastreabilidade deste capítulo:

• CLM-002 — Evans, Ubiquitous Language como linguagem compartilhada;
• CLM-023 — Evans, Bounded Context como fronteira explícita de aplicabilidade do modelo;
• CLM-024 — Evans, vínculo entre modelo, implementação e linguagem.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

• DOMAIN.md;
• futura Domain/Language Check;
• futura visualização de Bounded Contexts;
• integração do Domain Context Card ao Spec Builder.

---

Footnotes

1. Eric Evans, Domain-Driven Design (2004), Communication and the Use of Language, pp. 56–57. Rastreabilidade interna: CLM-002. ↩

2. Eric Evans, Domain-Driven Design (2004), HANDS-ON MODELERS, pp. 93–95. Rastreabilidade interna: CLM-024. ↩

3. Eric Evans, Domain-Driven Design (2004), BOUNDED CONTEXT, pp. 369–371. Rastreabilidade interna: CLM-023. ↩