Exemplo de especificação funcional: um CRM de cobrança

Uma especificação funcional diz o que o sistema faz, para quem e com que regras, sem dizer como ele é construído. Este artigo traz uma especificação real e completa: a do primeiro incremento do CRM de cobrança da série Criei um CRM, aprovada antes de qualquer linha de código. Ela tem 29 regras com exemplos, 26 critérios de aceite e 9 premissas registradas. A maior parte deste texto, porém, trata das decisões: as alternativas apresentadas, os prós e contras de cada uma e o que foi escolhido. É nelas que uma especificação ganha ou perde valor.

O incremento: a carteira chega por planilha#

O primeiro incremento resolve um problema concreto. O credor, uma escola ou uma clínica, por exemplo, tem os clientes em atraso numa planilha exportada do sistema de faturamento. Enquanto a lista fica ali, ninguém sabe ao certo quanto está vencido, há quanto tempo, com quem e quanto ainda vai vencer.

O objetivo é que o gestor envie a planilha e, em poucos segundos, veja a carteira organizada: quantos devedores, quanto está vencido e a vencer, em que faixa de atraso, e a ficha de cada devedor com seus contratos e títulos. O critério de sucesso também está escrito: uma planilha de 10 mil títulos fictícios entra sem intervenção manual, cada linha recusada aparece com o motivo, e os totais da tela batem com os da planilha.

O formato do arquivo faz parte da especificação: CSV separado por ponto e vírgula, que é o padrão do Excel em português, com números e datas no formato brasileiro. As colunas obrigatórias são documento, nome, título, vencimento e valor; telefone, e-mail, contrato e descrição são opcionais.

A estrutura da especificação#

O documento segue o modelo descrito em especificação de software: como fazer sem travar a empresa: problema e objetivo, quem usa, regras de negócio com exemplos, critérios de aceite, casos de exceção, fora do escopo, restrições e decisões. Duas seções foram acrescentadas por causa do objetivo da série:

• Premissas assumidas. O que foi dado como certo sem passar pela área que validaria, e o que acontece se estiver errado.
• Área que decidiria cada ponto numa empresa. Ao lado de cada decisão, quem a tomaria numa organização com jurídico, financeiro, operação, comercial e TI. Aqui, quem decide sou eu. Numa empresa, essa coluna mostra quem precisa estar na reunião.

Uma regra entrou no meio do caminho e virou regra do projeto: a especificação descreve comportamento, não infraestrutura. A primeira versão citava memória, contêiner e o servidor em que a demonstração iria rodar. Uma especificação assim fica presa a um ambiente e precisa ser reescrita quando o sistema muda de lugar. O desempenho continua na especificação, mas só como tempo percebido pelo usuário.

Regras escritas com valores#

Cada regra tem um exemplo concreto. É a diferença entre “o sistema valida o CPF” e uma regra que o desenvolvedor, humano ou IA, não consegue interpretar de dois jeitos. Algumas das 29:

O CNPJ alfanumérico é um exemplo de regra que passaria batido. Pela Instrução Normativa RFB nº 2.229, de outubro de 2024, a Receita Federal passou a atribuir CNPJ com letras às novas inscrições a partir de julho de 2026; os números já existentes não mudam. Uma validação “só números”, copiada de qualquer exemplo antigo, recusaria esses clientes, e o defeito só apareceria quando o primeiro deles entrasse na carteira.

Critérios de aceite no formato dado, quando, então#

Cada critério vira um teste automatizado, com o mesmo nome. Três dos 26:

Dado uma carteira com os títulos A, B e C ativos quando o gestor escolhe batimento e confere um arquivo com os títulos B e D então a conferência informa que A e C serão retirados, com quantidade e valor, antes de qualquer gravação.

Dado um título a vencer em 18/10/2026, com vencimento 20/10/2026 quando o operador abre a ficha em 21/10/2026 então o título aparece como vencido, com 1 dia de atraso, sem nova importação.

Dado um usuário inexistente quando alguém tenta entrar com ele então a mensagem é exatamente a mesma de uma senha errada.

As decisões, com alternativas#

Todas as decisões seguiram o mesmo formato: a ferramenta de IA que escreve o código e os rascunhos (o Claude Code) apresentava as opções, o impacto de cada uma e uma recomendação, e eu escolhia. Abaixo estão as que mudaram o sistema de forma visível.

O título que some do arquivo novo#

Foi a decisão com mais versões erradas. A pergunta: um título estava na carteira e não aparece na planilha nova. O que acontece?

A versão aprovada não estava entre as opções. Ela veio de quem conhece cobrança: a carga pode ser incremental, em que o arquivo traz só inclusões e atualizações, ou de batimento, em que o arquivo representa a carteira inteira. Na incremental, um título ausente não significa nada. No batimento, ele passa a retirado, e só isso: o sistema não presume pagamento, cancelamento ou renegociação, porque o arquivo não traz essa informação.

A proteção contra um batimento com arquivo incompleto#

O batimento resolveu um problema e criou o oposto. Se alguém exportar a carteira com um filtro esquecido, só um mês ou só uma unidade, o batimento retira em massa títulos ainda devidos, e a cobrança deles para.

Escolhi a praticidade, e a especificação diz isso com todas as letras: a conferência é a única barreira. Numa empresa, essa troca passaria pela operação, pela TI e provavelmente pela auditoria interna.

O modo que vem marcado#

Títulos a vencer#

O rascunho recusava títulos a vencer: “o título tem que estar em atraso”. A pergunta apresentou a recusa como a opção mais segura. A resposta foi uma correção: “E se o credor tem por regra negociar todo o contrato? Você não pode assumir que tem erro ou risco.”

A regra mudou: títulos a vencer são parte legítima da carteira. A correção trouxe duas regras que não existiam. A primeira é a coluna opcional contrato, sem a qual o acordo do incremento 4 não conseguiria negociar o contrato inteiro. A segunda é uma configuração por credor para o lugar do a vencer nos totais:

O mesmo documento com nomes diferentes#

Esta decisão foi tomada e revista na mesma noite.

A primeira escolha foi feita sem as causas comuns de divergência à vista: acento, abreviação, sobrenome de casada. A pergunta não as trazia. Quando vieram, a regra ganhou a normalização: “MARIA DA SILVA” e “Maria da Silva” passam a ser o mesmo nome.

A decisão que só apareceu combinando regras#

Ao montar o questionário, apareceu uma decisão que nenhuma regra isolada mostrava. No batimento, um título existente cuja linha foi recusada, por uma data digitada errada, por exemplo, some do conjunto válido e seria retirado. Somado à regra anterior, um erro de grafia no nome retiraria todas as dívidas daquele devedor.

Faixas de atraso, limites e tempo de espera#

O tempo de espera teve uma pergunta no meio: “esses números são realistas?”. A resposta honesta foi que nenhum dos dois tinha sido medido, e que 5 minutos era folgado demais. A meta final vai ser verificada por teste automatizado com uma carteira fictícia de 200 mil linhas.

O login que mudou de incremento#

O mapa original deixava o login para o segundo incremento. Quando decidi que o ambiente de desenvolvimento seria a própria demonstração publicada, o primeiro incremento ficaria aberto na internet sem login. A recomendação foi proteger pela infraestrutura, com uma senha no servidor web, e manter a especificação como estava. Preferi antecipar o login. A especificação aprovada ganhou uma revisão com o motivo, seis regras e sete critérios novos, antes de qualquer código.

A regra de senha segue a linha das diretrizes de identidade digital do NIST (SP 800-63B), que desaconselham regras de composição e troca periódica obrigatória, porque levam a senhas previsíveis como “Senha@2026”.

As que seguiram a recomendação#

As premissas que ficaram registradas#

Cada premissa diz a área que a validaria e o custo de estar errada. Algumas delas:

Nenhuma delas impede o desenvolvimento. Todas ficam visíveis, com dono, em vez de virarem uma regra que ninguém lembra de ter decidido.

O que ficou fora#

O que não está no incremento também está escrito: perfis de gestor e operador, recuperação de senha por e-mail, verificação em duas etapas, cadastro manual de devedor, multa e juros, baixa de pagamentos, exportação e o motivo da retirada de um título. A seção de fora do escopo é a que mais evita discussão depois: quando alguém perguntar por que o sistema não calcula juros, a resposta está no documento, com o incremento em que isso vai entrar.

Em números#

A especificação foi aprovada antes do plano técnico, que escolhe linguagem, banco e arquitetura. O próximo artigo da série trata dessas escolhas e de um conflito entre duas regras do próprio projeto: usar só versões publicadas há pelo menos duas semanas e não rodar com falha de segurança conhecida.