pedro-oscar/shorts-ai

Modelagem de Domínio

Construa e refine ativamente o modelo de domínio do projeto enquanto 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 cristalizam. (Apenas ler 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-pedidos-originais-por-eventos.md
│       └── 0002-postgres-para-modelo-de-escrita.md
└── src/

Se um GLOSSARY-MAP.md existir na raiz, o repositório tem múltiplos contextos. O mapa aponta para onde cada um reside:

/
├── GLOSSARY-MAP.md
├── docs/
│   └── adr/                          ← decisões de todo o sistema
├── src/
│   ├── ordering/
│   │   ├── GLOSSARY.md
│   │   └── docs/adr/                 ← decisões específicas do contexto
│   └── billing/
│       ├── GLOSSARY.md
│       └── docs/adr/

Crie arquivos de forma lazy: apenas quando tiver algo para escrever. Se nenhum GLOSSARY.md existir, crie um quando o primeiro termo for resolvido. Se não houver docs/adr/, crie-o quando o primeiro ADR for necessário.

Durante a sessão

Desafie o glossário

Quando o usuário usar um termo que conflita com a linguagem existente em GLOSSARY.md, aponte imediatamente. "Seu glossário define 'cancelamento' como X, mas você parece estar querendo dizer Y. Qual é o correto?"

Afie linguagem imprecisa

Quando o usuário usar termos vagos ou sobrecarregados, proponha um termo canônico preciso. "Você está dizendo 'conta': você quer dizer o Cliente ou o Usuário? 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 explorem casos de borda e forcem o usuário a ser preciso sobre os limites entre 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 o cancelamento parcial é possível. Qual está correto?"

Atualize GLOSSARY.md inline

Quando um termo for resolvido, atualize GLOSSARY.md ali mesmo. Não acumule: capture-os conforme acontecem. Use o formato em GLOSSARY-FORMAT.md.

GLOSSARY.md deve ser totalmente desprovido de detalhes de implementação. Não trate GLOSSARY.md como uma especificação, um rascunho ou um repositório de decisões de implementação. É um glossário e nada mais.

Ofereça ADRs com moderação

Só ofereça criar um ADR quando todas as três condições forem verdadeiras:

1. Difícil de reverter: o custo de mudar de ideia depois é significativo
2. Surpreendente sem contexto: um leitor futuro se perguntará "por que eles fizeram assim?"
3. 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.