Um requisito chega com uma frase aparentemente simples: criar um módulo de assinaturas. No SDD, essa entidade central precisa ficar clara antes da IA transformar a ideia em tabelas, telas, endpoints e testes. O problema aparece depois, quando ninguém sabe se o centro do módulo é cliente, plano, contrato, cobrança ou assinatura.

Esse ponto transforma a decisão em algo concreto. Se a especificação não escolhe o objeto principal do módulo, o agente de código completa as lacunas com uma estrutura provável. O resultado pode funcionar em demonstração e falhar na primeira regra real de negócio.

Direto ao ponto

Defina a entidade central no SDD antes da IA respondendo qual objeto o módulo existe para representar, proteger ou transformar. Essa decisão vem antes de tela, banco, API e tarefa de implementação. Sem entidade central clara, a especificação fica vulnerável a ambiguidade, e a IA pode misturar responsabilidades que deveriam ficar separadas.

Como definir a entidade central no SDD antes da IA

Entidade central é o objeto de domínio que dá sentido ao módulo. Ela não é automaticamente a primeira tabela, a tela principal ou a palavra que o cliente mais repete. Ela é a coisa que carrega estado, histórico, regra e consequência.

Eu começaria perguntando: se este módulo só pudesse proteger um objeto, qual seria? Em assinatura recorrente, a resposta pode ser assinatura. Cliente e plano continuam importantes, mas entram como relações. Em uma clínica, a resposta pode ser atendimento. Paciente, agenda e faturamento orbitam essa entidade.

Esse recorte conversa com o artigo sobre IA em requisitos com GitHub Spec Kit. O GitHub Spec Kit ajuda a organizar o fluxo de especificação, plano, tarefas e implementação. Ainda assim, a ferramenta não deveria escolher por conta própria o centro do domínio.

Entidade central não é a mesma coisa que tabela

Tabela é representação técnica. Entidade central é decisão de domínio. Essa diferença importa porque uma decisão de domínio pode exigir várias tabelas, eventos, logs, permissões e históricos para existir bem implementada.

Se o módulo controla assinaturas, talvez você tenha tabelas de assinatura, cobrança, alteração de plano, suspensão e cancelamento. A entidade central continua sendo assinatura, porque é ela que organiza o ciclo.

Quando a pessoa responsável confunde entidade central com tabela, a especificação fica rasa. Ela descreve armazenamento, mas não explica a regra que sustenta aquele armazenamento. Para IA, isso é perigoso: o agente pode criar estrutura tecnicamente plausível sem preservar o significado do negócio.

O post sobre como escrever requisitos menos ambíguos no SDD aprofunda esse cuidado. Aqui, a ambiguidade começa antes: no nome do objeto que deveria orientar todas as outras decisões.

O exemplo de assinatura mostra o custo da escolha errada

Imagine que uma empresa quer um módulo para controlar assinatura de clientes. Se o requisito coloca cliente no centro, a especificação tende a puxar cadastro, perfil e histórico geral. Se coloca plano no centro, a conversa vai para oferta, preço, limites e benefícios. Se coloca assinatura no centro, o foco muda para ciclo ativo, renovação, suspensão, cancelamento e vínculo com cobrança.

As três entidades são legítimas. O problema é tratar as três como sinônimos.

Uma boa especificação diria algo assim: o módulo representa assinaturas recorrentes, com estado atual, histórico de renovação, suspensão e cancelamento. Cliente e plano são relações necessárias, mas não substituem o centro do módulo.

Essa frase curta orienta muita coisa. Ela ajuda a decidir estados, permissões, relatórios, integração de cobrança e critérios de aceite. Também reduz a chance de a IA gerar um CRUD de clientes quando o problema real era ciclo de assinatura.

Clínica, agenda e atendimento também confundem requisito

Outro exemplo simples aparece em sistemas para clínicas. “Sistema de consultas” parece claro até a especificação começar. O centro pode ser paciente, agenda, atendimento ou faturamento.

Se a entidade central for atendimento, o requisito precisa explicar que o módulo representa o encontro clínico, com profissional, data, status, desfecho e registros associados. A agenda organiza disponibilidade. O paciente participa do atendimento. O faturamento pode nascer dele. Nenhum desses elementos substitui o atendimento como centro.

Sem essa distinção, a IA pode espalhar cancelamento, retorno, encaixe, cobrança e prontuário por entidades erradas. Depois a revisão técnica vira discussão sobre remendo, quando a decisão deveria ter sido tomada no requisito.

Relação, estado, ação e quantidade vêm depois

Depois que a entidade central está definida, outras categorias ficam mais fáceis de escrever. Relação mostra com quem a entidade se conecta. Estado mostra em que condição ela pode estar. Ação mostra o que pode acontecer com ela. Quantidade mostra limite, frequência e volume.

O artigo sobre definir limites de quantidade para requisitos trata uma dessas categorias. O post sobre definir relações de domínio no SDD trata outra. A entidade central vem antes porque ela define sobre o que essas categorias estão falando.

Um estado aprovado, por exemplo, só faz sentido quando todos sabem o que está sendo aprovado. Pedido, atendimento, proposta, contrato e assinatura pedem regras diferentes. Se o objeto muda, a regra muda junto.

Sinais de que a entidade central ainda está fraca

O primeiro sinal é a mesma palavra aparecer com sentidos diferentes. Em uma reunião, cliente significa pessoa. Em outra, significa empresa. Em uma terceira, significa contrato ativo.

O segundo sinal é a tela virar o centro da conversa. “Tela de gestão” não define domínio. Ela apenas mostra uma interface possível.

O terceiro sinal é o requisito ganhar campos novos a cada revisão porque ninguém sabe qual objeto está sendo protegido. Campo novo não é problema por si. O problema é campo novo revelar que o módulo não tinha centro.

Eu também observo como as pessoas descrevem a feature. Se cada pessoa usa um substantivo diferente para explicar o mesmo módulo, a especificação ainda não está pronta para implementação com IA.

Onde a Formação IA Makers entra

Na Formação IA Makers, esse cuidado aparece quando trabalhamos com Vibe Coding, requisitos, agentes de código e revisão humana. A IA ajuda muito quando recebe especificação clara. Ela também amplia confusão quando recebe frase vaga com aparência de requisito.

Aqui na Promovaweb, no Co-work, eu prefiro que a pessoa aprenda a fazer a pergunta de domínio antes de transformar a spec em código. A revisão deve separar entidade que carrega o ciclo, estado que importa, relação de apoio e limite que muda a implementação. Quando menciono Co-work, estou falando do encontro ao vivo de trabalho acompanhado da Promovaweb; ele serve para tirar dúvidas e revisar problemas reais, e ajuda o leitor a comparar seu caso com exemplos práticos antes de avançar.

A página de formações da Promovaweb mostra como IA Makers se conecta a DevOps, Martech e Founders. No caso do SDD, o ponto principal está em transformar intenção de negócio em requisito que uma pessoa e um agente conseguem revisar.

Perguntas frequentes

O que é entidade central no SDD?

É o objeto principal que um módulo existe para representar, proteger ou transformar. A entidade central orienta estados, regras, relações, eventos, permissões e critérios de aceite.

Como definir a entidade central antes da IA?

Comece pelo objeto que carrega o significado do módulo. Depois separe o que é relação, estado, ação e limite. Se duas entidades parecem disputar o centro, o requisito ainda precisa de revisão.

Entidade central é a mesma coisa que tabela principal?

Não. Tabela é uma decisão técnica de armazenamento. Entidade central é uma decisão de domínio. Uma entidade central pode exigir várias tabelas para ser representada corretamente.

O que acontece quando a entidade central fica ambígua?

A IA pode gerar código coerente em aparência, mas baseado em premissas erradas. O retrabalho aparece em permissões, relatórios, estados, integrações e regras de negócio.

Como isso conversa com GitHub Spec Kit?

O GitHub Spec Kit organiza o fluxo de SDD em especificação, plano, tarefas e implementação. A entidade central deve estar clara antes desse fluxo ganhar volume, porque ela orienta os artefatos seguintes.

Que sinais mostram que a entidade central precisa ser revista?

Pessoas usando nomes diferentes para o mesmo módulo, campos surgindo sem critério, tela ocupando o lugar do domínio e dúvidas sobre qual objeto muda de estado são sinais de revisão.

Conclusão

Definir a entidade central no SDD antes da IA é uma decisão pequena com impacto grande. Ela fixa o objeto que o módulo representa e impede que a especificação tente resolver domínio, interface e armazenamento ao mesmo tempo.

Eu revisaria essa definição antes de qualquer implementação assistida por IA. Se o centro do módulo ainda muda conforme a conversa, o requisito não está pronto para virar código.

Quando a entidade central fica clara, o restante da especificação ganha base: relações, estados, ações, limites e critérios de aceite passam a falar sobre o mesmo objeto. A IA trabalha melhor porque recebe uma decisão de domínio, em vez de uma frase aberta para completar.