Criei um CRM com IA: especificação antes do código

Esta série acompanha a construção de um CRM de cobrança do zero até uma demonstração publicada, com o código escrito por um assistente de IA e cada regra decidida antes, numa especificação. O objetivo não é mostrar que a IA programa rápido. É mostrar o que acontece antes do código: as premissas que quem especifica assume sem perceber, as decisões que numa empresa passariam por outras áreas, os impasses e as trocas que, num projeto comum, viram atraso ou “passam batido” até estourar na homologação ou na produção.

Cada artigo cobre um incremento do sistema. Este primeiro explica o que vai ser construído, como o trabalho está organizado e por que os erros vão aparecer no texto.

O que vai ser construído#

Um CRM de cobrança: um sistema para quem tem clientes em atraso organizar a carteira, registrar cada contato com o devedor, negociar e acompanhar o que foi recuperado. É diferente do CRM de vendas, que acompanha oportunidades até o fechamento; aqui o ciclo começa depois do vencimento.

O primeiro usuário é um credor, uma pequena ou média empresa que cobra os próprios clientes: escola, clínica, academia, distribuidora. Numa fase posterior, o sistema passa a atender uma assessoria de cobrança, que cobra em nome de vários credores. O modelo de dados já nasce preparado para isso, embora as primeiras telas mostrem um credor só.

Ficam de fora, por decisão:

• emissão de boleto, Pix ou qualquer movimentação de dinheiro;
• envio real de SMS, WhatsApp ou e-mail a devedores (a demonstração registra o envio, mas não envia nada);
• negativação em birôs de crédito, protesto e cobrança judicial;
• dados pessoais reais. Todo CPF e CNPJ da demonstração é gerado, válido no formato e sem dono.

A demonstração vai ficar em crm.areacli.com, com login de demonstração divulgado aqui quando estiver no ar.

A escolha do tema não foi a recomendada. Na primeira conversa, a sugestão foi um CRM de vendas para pequenas empresas, que tem mais busca e cabe facilmente numa demonstração. Preferi cobrança, que conheço por dentro. O custo é um domínio com mais regra legal, do Código de Defesa do Consumidor à LGPD. O ganho é que as armadilhas de cobrança são exatamente o tipo de história que esta série quer contar.

O método: especificar por incremento#

O projeto aplica o que defendi em spec-driven development: IA sem especificação sai caro e em especificação de software: como fazer sem travar a empresa. Na prática, são cinco regras:

1. Nenhum código sem especificação aprovada. A especificação diz o que o sistema faz, com regras, exemplos com valores e critérios de aceite no formato “dado, quando, então”. Cada critério vira um teste automatizado.
2. Especificação por incremento, não do sistema inteiro. Existe um mapa curto do todo e uma especificação detalhada só do próximo pedaço.
3. Cada decisão em aberto tem dono e prazo. Nunca “o desenvolvimento decide”.
4. Decisões técnicas ficam registradas com o contexto, as opções consideradas e o motivo da escolha.
5. Mudou a regra, muda a especificação primeiro, com o motivo, e só depois o código.

O que torna o projeto diferente de um relato comum é uma sexta regra: ao fim de cada sessão de trabalho, um diário registra o que foi feito, o que foi decidido e, principalmente, o que deu errado. É dele que saem os artigos.

Quem decide e quem escreve#

O código e os rascunhos de especificação são escritos pelo Claude Code, assistente de programação da Anthropic. As decisões são minhas. O fluxo de cada decisão é sempre o mesmo: a ferramenta apresenta as opções, o impacto de cada uma e uma recomendação, e eu escolho. Nenhuma escolha de produto, de regra de negócio ou de tecnologia é feita pela ferramenta.

Essa divisão não é decorativa. Em uma noite de trabalho, entre o escopo do produto e a especificação do primeiro incremento, foram tomadas 35 decisões. Em 9 delas, a escolha final contrariou a recomendação ou ficou fora das opções apresentadas. Em quatro casos, a recomendação partia de uma premissa errada, e a correção veio de quem conhece a operação.

Também é por isso que a série vai mostrar trechos da conversa. Uma pergunta mal formulada embute a resposta, e isso só aparece quando se lê a pergunta.

O que a série quer mostrar#

Num projeto de software, uma parte grande das regras nunca chega a ser discutida. Alguém assume, o desenvolvedor implementa o que parece razoável e a regra passa a existir sem dono. Numa empresa, várias dessas regras seriam decididas em conjunto com o jurídico, o financeiro, a operação, o comercial e a TI. Aqui, quem decide sou eu, mas cada especificação registra duas coisas que normalmente ficam implícitas:

• as premissas assumidas, com a área que as validaria e o que acontece se estiverem erradas;
• a área que decidiria cada ponto numa empresa, ao lado de quem decidiu de fato.

Um exemplo do primeiro incremento mostra por que isso importa. A carteira entra no sistema por uma planilha exportada do faturamento do credor. A pergunta parecia simples: o que fazer com um título que estava na carteira e não aparece no arquivo novo?

• A primeira versão da regra dizia que nada muda. Parece prudente, porque não apaga nada. Mas o título que sumiu pode ter sido pago, e o sistema continuaria mandando cobrar quem já pagou, uma cobrança indevida que o artigo 42 do Código de Defesa do Consumidor pune com devolução em dobro.
• A correção proposta foi marcar o título como “provavelmente pago ou cancelado”. Também errada: trocou uma suposição por outra.
• A versão final veio de quem conhece cobrança. A importação pode ser incremental, em que o arquivo traz só inclusões e atualizações e a ausência não significa nada, ou de batimento, em que o arquivo representa a carteira inteira. Só no batimento o título ausente é “retirado”, e o sistema não presume o motivo, porque o arquivo não traz essa informação.

Nenhuma das três versões é absurda. As duas primeiras passariam numa revisão apressada e só seriam percebidas quando um cliente reclamasse ou quando um indicador de recuperação aparecesse inflado. É esse tipo de decisão que a série vai expor, incremento por incremento.

Os sete incrementos previstos#

O mapa pode mudar. Quando mudar, o motivo vai aparecer aqui.

As restrições do projeto#

Algumas regras valem para todo o sistema e explicam escolhas que vão aparecer ao longo da série:

• Acessibilidade WCAG 2.2 nível AA em todas as telas, verificada por teste automatizado.
• Privacidade por padrão: sem cookies de rastreamento, sem serviços de terceiros sem decisão registrada e documento do devedor mascarado nas listas.
• Versões travadas e publicadas há pelo menos duas semanas, para não instalar um pacote recém-publicado com defeito ou adulterado. A exceção, decidida já no primeiro dia, são correções de segurança da mesma linha de versão: obedecer à regra à risca significaria rodar com falhas conhecidas.
• A especificação descreve comportamento, não infraestrutura. Onde o sistema roda, com quanta memória e em que servidor é decisão técnica, registrada à parte. Essa regra também nasceu de um erro, que fica para o próximo artigo.

O que cada artigo vai trazer#

Cada artigo da série vai cobrir um incremento com a mesma estrutura: o problema daquele pedaço do sistema, as decisões tomadas e as alternativas descartadas, as premissas que se mostraram erradas, o que foi construído e como verificar na demonstração.

O segundo artigo traz a especificação funcional do primeiro incremento: por que um CRM de cobrança começa por uma planilha, e não por uma tela, e quantas decisões de negócio cabem numa importação de arquivo que parecia trivial.