Modelagem de Domínio
Construa e refine ativamente o modelo de domínio do projeto enquanto você projeta. Esta é a disciplina ativa: desafiar termos, inventar cenários de borda e escrever o glossário e as decisões no momento em que eles se cristalizam. (Apenas ler o GLOSSARY.md para vocabulário não é esta skill: isso é um hábito de uma linha que qualquer skill pode fazer. Esta skill é para quando você está mudando o modelo, não apenas consumindo-o.)
Estrutura de arquivos
A maioria dos repositórios tem um único contexto:
/
├── GLOSSARY.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
Se existir um GLOSSARY-MAP.md na raiz, o repositório tem múltiplos contextos. O mapa aponta para onde cada um deles está:
/
├── GLOSSARY-MAP.md
├── docs/
│ └── adr/ ← decisões do sistema como um todo
├── src/
│ ├── ordering/
│ │ ├── GLOSSARY.md
│ │ └── docs/adr/ ← decisões específicas do contexto
│ └── billing/
│ ├── GLOSSARY.md
│ └── docs/adr/
Crie arquivos de forma preguiçosa: apenas quando você tiver algo a escrever. Se não existir GLOSSARY.md, crie um quando o primeiro termo for resolvido. Se não existir docs/adr/, crie-o quando o primeiro ADR for necessário.
Durante a sessão
Desafie contra o glossário
Quando o usuário usar um termo que conflita com a linguagem existente no GLOSSARY.md, aponte isso imediatamente. "Seu glossário define 'cancelamento' como X, mas você parece estar falando de Y. Qual é o correto?"
Refine linguagem vaga
Quando o usuário usar termos vagos ou sobrecarregados, proponha um termo canônico preciso. "Você está dizendo 'conta': você quer dizer Cliente ou Usuário? Essas são coisas diferentes."
Discuta cenários concretos
Quando relações de domínio estiverem sendo discutidas, teste-as com cenários específicos. Invente cenários que investiguem casos de borda e forcem o usuário a ser preciso sobre os limites entre os conceitos.
Cruze referências com o código
Quando o usuário afirmar como algo funciona, verifique se o código concorda. Se encontrar uma contradição, traga-a à tona: "Seu código cancela Pedidos inteiros, mas você acabou de dizer que cancelamento parcial é possível. Qual está certo?"
Atualize GLOSSARY.md inline
Quando um termo for resolvido, atualize o GLOSSARY.md ali mesmo. Não acumule essas atualizações: capture-as conforme acontecem. Use o formato em GLOSSARY-FORMAT.md.
O GLOSSARY.md deve ser totalmente desprovido de detalhes de implementação. Não trate o GLOSSARY.md como uma especificação, um bloco de rascunho ou um repositório para decisões de implementação. Ele é um glossário e nada mais.
Ofereça ADRs com moderação
Só se ofereça para criar um ADR quando todas as três condições forem verdadeiras:
- Difícil de reverter: o custo de mudar de ideia mais tarde é significativo
- Surpreendente sem contexto: um leitor futuro se perguntará "por que eles fizeram assim?"
- Resultado de uma troca real: havia alternativas genuínas e você escolheu uma por razões específicas
Se qualquer uma das três estiver faltando, pule o ADR. Use o formato em ADR-FORMAT.md.