Conversando com Seu Código: Como o Modelith Dá Vida aos Modelos de Domínio

Vamos ser sinceros — a maioria dos projetos começa com boas intenções. Alguém desenha o modelo de domínio no quadro branco, todo mundo concorda, e aí... o modelo morre silenciosamente em uma página do Confluence que ninguém atualiza.

O problema não é o conceito de modelagem de domínio em si. É que modelos de domínio normalmente são:

• Escritos uma vez e esquecidos
• Mantidos separadamente do código
• Legíveis apenas em ferramentas específicas
• Difíceis de validar automaticamente

O Modelith pega outro caminho. Em vez de tratar seu modelo de domínio como um entregável que você produz e arquiva, ele treating it as a living artifact que convive com seu código, é criado através de conversa e validado automaticamente no CI.

O Que Diabos É um Modelo de Domínio?

Antes de continuar, vamos alinhar expectativas. Um modelo de domínio é o mapa conceitual do seu sistema — os substantivos (entidades), seus relacionamentos e as regras que os governam. Não é um schema de banco de dados nem uma especificação de API. É a expressão canônica, em linguagem simples, de o que seu sistema é.

Pense nele como o vocabulário que toda sua equipe compartilha. Quando todo mundo lê do mesmo modelo, as conversas ficam mais afiadas, o onboarding fica mais rápido e adicionar novos serviços ou funcionalidades deixa de ser uma escavação arqueológica em código legado.

O Workflow do Modelith: Descreva, Drafte, Valide, Renderize

É aqui que as coisas ficam interessantes. Com o Modelith, você não escreve YAML diretamente. Você nem pensa em YAML. Você descreve seus conceitos de domínio em linguagem simples para um agente de IA (especificamente, um skill do Claude Code), e o agente cria o YAML por baixo dos panos.

O fluxo funciona assim:

1. Descreva — Você conversa sobre seu domínio em português claro. "Temos clientes que podem fazer pedidos, e pedidos contêm vários produtos, mas clientes só podem ter três pedidos ativos por vez."

2. Authorize — O plugin do Claude Code traduz sua descrição em um arquivo modelith.yaml, validando no caminho.

3. Valide — Rode modelith lint para verificar completude e consistência. Isso vira seu gate de CI.

4. Renderize — Rode modelith render para gerar Markdown com diagramas Mermaid. Faça commit disso junto com o YAML.

O Markdown renderizado é legível por humanos sem nenhuma ferramenta. O YAML é a fonte de verdade legível por máquina. E o CI garante que eles nunca se desviem — pense nisso como um check de código gerado, mas para seu modelo de domínio.

Por Que Essa Abordagem Funciona

Linguagem simples reduz a barreira

Nem todo mundo na equipe se sente confortável lendo JSON Schema ou diagramas UML. Mas todo mundo consegue ler português claro. Ao fazer da linguagem simples o ponto de entrada, o Modelith democratiza a modelagem de domínio. Seu product manager pode contribuir. Seu QA pode revisar. Seu dev júnior realmente consegue entender o panorama geral.

IA lida com as partes tediosas

Escrever YAML na mão é propenso a erros e, francamente, chato. Deixar um agente de IA cuidar da tradução da sua descrição para YAML válido significa tirar essa carga cognitiva do seu prato enquanto mantém a precisão.

Validação no CI previne desvio

Essa é a funcionalidade matadora para equipes. Seu modelo de domínio vira um cidadão de primeira classe no seu workflow de desenvolvimento. Todo PR que muda o domínio é validado automaticamente. Se alguém atualizar o YAML mas esquecer de regenerar os docs, o CI pega.

O modelo fica perto do código

Quando seu modelo de domínio vive no mesmo repositório que seu código, ele permanece relevante. Ele é revisado nos pull requests. É atualizado quando funcionalidades mudam. Não vira documentação obsoleta em algum outro sistema que ninguém lembra de consultar.

Começando

O Modelith foi projetado para ser acessível. Você não precisa entender todo o schema de uma vez. Comece pequeno:

• Instale o plugin do Claude Code
• Descreva alguns conceitos core do seu domínio
• Deixe a IA criar o draft do YAML
• Rode modelith lint para ver o que está faltando
• Itere

O projeto inclui exemplos práticos (o exemplo de estacionamento é um bom ponto de partida) que te guiam construindo um modelo real do zero.

O Quadro Maior

O Modelith representa uma tendência mais ampla em desenvolvimento assistido por IA: usar linguagem natural como camada de interface enquanto mantém artefatos legíveis por máquina por baixo. Você escreve o que quer dizer; as ferramentas garantem consistência e validação.

Para equipes construindo sistemas complexos — especialmente em domínios onde o vocabulário importa (fintech, saúde, logística, qualquer coisa com regras de negócio significativas) — essa abordagem pode ser transformadora. Um modelo de domínio compartilhado, validado e vivo significa menos mal-entendidos, onboarding mais rápido e sistemas melhor desenhados.

A ferramenta ainda está evoluindo, mas a ideia central é sólida. Seu modelo de domínio não deveria ser uma reflexão tardia ou um relicário do kickoff do projeto. Deveria ser um documento vivo que evolui com seu código, criado através de conversa e validado automaticamente.

Se você já sofreu para manter modelos de domínio relevantes nos seus projetos, o Modelith vale a pena explorar. Às vezes a melhor ferramenta não é a mais poderosa — é aquela que torna o comportamento certo o caminho de menor resistência.

Confira modelith.sh para começar.