Uma pergunta chega pelo Slack: o produto consegue fazer isso, para esse cliente, nesse caso específico?

Não é uma pergunta abstrata. Não é uma reflexão sobre a visão de cinco anos. É uma pergunta de campo, que precisa de resposta em menos de uma hora. Então alguém abre um ambiente de teste, reproduz o caso, confere. Meia hora. Paga duas vezes: pela pessoa que procura e pela pessoa que ela interrompe.

Não é um problema de documentação. Ela existe, e está atualizada. O problema é que aquilo de que o produto é feito — os objetos que ele manipula, as regras que os governam, as palavras usadas para falar deles — não está escrito em lugar nenhum de uma forma que dê para consultar. Isso existe em dois lugares: no código, que poucas pessoas sabem ler, e na cabeça dessas mesmas pessoas.

Então tentei escrever. O resultado existe: várias dezenas de objetos descritos, algumas centenas de regras, outros tantos vínculos entre eles. Este artigo conta como cheguei lá — e principalmente o que errei no caminho, porque é essa parte que se transfere.

Três avisos antes de começar.

O primeiro: este relato de experiência trata da construção do modelo de referência, não do uso dele. Ele existe, está medido, já produziu seus primeiros subprodutos. Mas a fase de exploração não começou. Então não posso afirmar nada sobre o retorno do investimento. Quem vender um número a essa altura está inventando.

O segundo: os exemplos vêm de um caso fictício — uma empresa que desenvolve um SaaS de gestão, um ERP, com seus clientes, seus pedidos, suas linhas e suas faturas. O que se transfere de um produto para outro não são as minhas descobertas, é o tipo de problema que aparece: um estado recalculado em todo lugar e definido em lugar nenhum, uma regra aplicada de um lado só, uma palavra que os clientes usam e que o produto desconhece. Esses três, você também tem. O detalhe do caso, esse não interessa a ninguém.

O terceiro: é longo, meia hora de leitura. É um relato, não um post — preferi dizer tudo a ser breve. Se você só puder ler uma seção, escolha "Três critérios de parada. Três vezes errado.": o resto é o contexto em volta. Os anexos só servem para quem quiser refazer o trabalho.

Uma ontologia não é um glossário turbinado

A palavra é uma armadilha. Para uns evoca filosofia, para outros um campo erudito com ferramentas complicadas, e para a maioria não evoca nada. Melhor definir direito.

Uma ontologia é a descrição explícita e estruturada daquilo de que um domínio é feito: - os tipos de objetos que existem, - o que os caracteriza, - o que os liga, - o que é verdadeiro a respeito deles, - as palavras pelas quais eles são designados.

Aplicada a um software, ela responde a cinco perguntas. Cada uma corresponde a uma coisa que a gente escreve, e cada uma tem um nome erudito de que você não vai precisar depois:

No resto do artigo, para evitar os termos eruditos, eu digo "objetos", "propriedades", "vínculos", "regras" e "palavras". É a mesma coisa.

Essas cinco caixas também servem de filtro: o que não entra em nenhuma não tem lugar no modelo de referência.

Por que mais um documento

Já existiam um glossário, um esquema de banco de dados e documentação. O glossário define palavras uma a uma. O esquema organiza dados segundo restrições técnicas, não segundo o negócio. A documentação narra, para um leitor humano.

O que distingue tudo isso de uma ontologia cabe em um ponto: os vínculos contam tanto quanto as definições. Um objeto descrito sozinho não ensina grande coisa. O mesmo objeto ligado a outros cinco por verbos precisos — feito por, contém, faturado em — descreve um produto.

O que ela reconcilia

Um mesmo objeto carrega três nomes dentro de uma empresa. Veja o pedido de cliente:

Esses três vocabulários evoluem separadamente, e a distância entre eles é uma informação valiosa. O modelo de referência guarda essa distância: a palavra oficial, as palavras usadas pelos clientes e as que foram abandonadas no caminho. É isso que permite traduzir a frase de um usuário em objeto do produto — e o contrário.

O que eu não fiz

Existem formas bem eruditas de fazer tudo isso: linguagens dedicadas, ferramentas que deduzem conclusões a partir das regras que você dá a elas, normas que vêm junto. É um campo de verdade, e não entrei nele (entre outras coisas, por falta de competência).

Comecei pelo que eu sabia sustentar: uma ficha por objeto, em um arquivo de texto. Um título, alguns campos, vínculos para as outras fichas. Nada que um editor de texto não consiga abrir. Enquanto eu não souber para que o modelo de referência vai servir, não sei de quanto rigor preciso — e começar simples para complicar depois sempre custa menos do que o contrário.

O código virou a fonte da verdade. O sentido ficou de fora.

Nesse produto, uma parte crescente do que o descreve é regenerada a partir do código. O raciocínio é simples: a verdade de um produto é o que roda, não o que tinha sido previsto.

Essa virada elimina um trabalho inteiro — o de manter atualizados, na mão, documentos que descrevem outra coisa que não a realidade. É um ganho considerável, e eu ainda defenderia isso.

Mas ela desloca o problema.

O que o código não dá

O código estabelece como o produto funciona. Já o sentido se constrói por cima.

Veja o pedido e seu estado. O código dá a estrutura: aqui estão os campos, aqui estão os valores possíveis. Quatro informações tornam esse pedido realmente utilizável, e nenhuma delas está ali:

• a regra — um pedido faturado não recebe mais linhas. O produto aplica isso, mas a regra não está escrita em lugar nenhum: a verificação está espalhada por cinco arquivos e cada um faz só um pedaço. Para enunciar a regra em uma frase, é preciso ter lido os cinco;
• os casos particulares — um pedido urgente é um pedido, com restrições a mais;
• o vocabulário — os usuários dizem "negócio", e outro termo foi abandonado três anos atrás;
• o alcance — o produto tem duas aplicações, que vou chamar de A e B, e cada uma coloca o próprio sentido atrás da mesma palavra.

Reunidas, essas quatro informações transformam uma estrutura de dados em descrição de produto. É exatamente o conteúdo de uma ficha. E nenhuma está no mesmo lugar: elas se repartem entre o núcleo do código, o banco de dados, as telas e as traduções.

O custo real é pago em outro lugar

A pergunta do começo é só um caso entre outros. Tudo o que descreve o produto para alguém é uma reconstrução, refeita toda vez, em paralelo, por cada setor: a documentação, as respostas a licitações, o treinamento dos recém-chegados, o discurso do suporte. Cada um parte de novo do código, ou da memória de alguém.

É essa despesa que se trata de eliminar. Ela não aparece em orçamento nenhum, o que explica por que ela vem sendo paga há anos sem ninguém ver.

Uma IA não consegue perguntar. Ela adivinha.

Até aqui, o que o produto realmente é passava de boca em boca. A gente perguntava para a pessoa certa, obtinha a regra, seguia em frente. O modelo do produto vivia em algumas cabeças, e isso funcionava porque sempre dava para bater na porta.

Uma IA não bate em porta nenhuma.

Quando a gente entrega uma melhoria para ela, descreve em algumas frases. Na nossa cabeça existe um modelo completo: o que é um pedido, por quais estados ele passa, o que é proibido e a partir de quando. O agente só tem as nossas poucas frases, mais o que ele consegue ler no código. O resto, ele preenche — de um jeito plausível, coerente e às vezes falso.

A distância entre o que a gente queria e o que a gente recebe é exatamente a parte do nosso modelo mental que não foi escrita.

Um modelo de referência é esse modelo mental escrito. Dar esse modelo a um agente não torna o agente mais inteligente: impede que ele invente onde já existe uma regra. Disso decorrem três usos, e são eles que me interessam.

Pedir uma melhoria sem explicar o produto de novo. "Adiciona um desconto nos pedidos." Com o modelo de referência no contexto, o agente sabe que um pedido faturado não recebe mais linhas, que um desconto tem um teto e que "pedido" cobre também os pedidos urgentes e os pedidos recorrentes. Sem ele, o agente vai descobrir uma dessas três coisas na revisão — no melhor dos casos.

Analisar mais rápido. Investigar um bug começa sempre por reconstruir o modelo da área envolvida. Essa reconstrução é refeita toda vez, por cada pessoa e por cada agente. Escrita uma vez, ela é lida em alguns segundos. E algumas centenas de fichas cabem em um contexto onde milhares de arquivos de código não cabem: o agente lê o que precisa em vez de vasculhar ao acaso.

Escrever os testes e decidir sobre os relatos. Uma regra é uma afirmação verificável. "Um pedido faturado não recebe mais linhas" é um teste, do jeito que está, formulado em linguagem de negócio. Algumas centenas de regras são outros tantos testes candidatos que ninguém precisa deduzir do código. E diante de um relato de cliente, a pergunta fica mecânica: isso contradiz uma regra escrita — então é um bug; ou é uma regra que ninguém tinha estabelecido — então é uma decisão de produto, não um defeito. Hoje, esse veredito sai da experiência, da pessoa mais antiga do time.

Nada disso está medido, conforme o aviso do começo. O mecanismo me parece sólido — a parte adivinhada é eliminada — mas não fiz o teste. O teste que vou fazer: pegar umas trinta demandas, tratar metade com o modelo de referência no contexto e a outra metade sem, comparar o tempo gasto e a quantidade de retrabalho. Enquanto isso não for feito, esta seção é uma expectativa, não um resultado.

O método: esboçar para saber o que procurar

Um dilema aparece logo de cara. Sem um modelo, mesmo grosseiro, você não sabe que material recolher — e passa ao lado de informações importantes sem perceber. Sem material, você não sabe que modelo sustentar.

Iterar, não sequenciar. A gente esboça o suficiente para saber o que procurar, procura, e retoma o modelo com o que aprendeu. Uma restrição atravessa essas idas e vindas: o que é recolhido fica guardado na forma mais simples possível, e sempre com a indicação de onde veio. Uma mudança de modelo nunca pode obrigar a voltar atrás para buscar o que já foi recolhido.

Por onde começar: umas vinte perguntas que já tinham sido feitas para a gente

Um produto tem dezenas de áreas — o faturamento, as compras, as permissões de acesso, a busca, as notificações. Por qual começar? A resposta teórica é conhecida: primeiro você escreve as perguntas que o modelo de referência terá de responder, e elas delimitam o terreno. O problema é que perguntas escritas a frio, numa sala, sempre se parecem com aquilo que a gente acha importante.

Então não as escrevi. Fui buscá-las.

As perguntas de produto que chegam até nós ficam arquivadas com a resposta. Reli todas elas e condensei em umas vinte perguntas genéricas. Nenhuma saiu da minha imaginação: cada uma cobre um conjunto de perguntas realmente feitas.

Transpostas para o ERP fictício, elas se parecem com isto:

• Quais são os estados de um pedido, e quais passagens de um para o outro são permitidas?
• O que ainda dá para cancelar, e a partir de que momento deixa de dar?
• O que é o saldo de um cliente, e por quais movimentos ele evolui?
• A quem pertence um pedido gerado automaticamente, e o que acontece com ele se essa pessoa sair da empresa?
• Em quais casos um usuário de uma filial vê os pedidos de outra filial?
• Como os usuários chamam o pedido, e em quais idiomas?

Não são perguntas elegantes. São as que custam meia hora de alguém, várias vezes por mês.

O que isso dá na hora: a ordem de trabalho. Cada pergunta toca uma ou várias áreas do produto; basta contar. Mais da metade das perguntas caía na mesma área — ela virou a primeira. O resto se repartia em outras duas. A ordem deixa de ser uma preferência e passa a ser uma contagem.

E elas servem uma segunda vez, na chegada. Quando uma área termina, a gente retoma as perguntas dela e verifica que o modelo de referência responde sem abrir o código. A verificação feita na metade do caminho deixou só duas perguntas sem resposta completa. As duas falhavam do mesmo jeito: uma regra escrita em termos gerais onde a pergunta esperava o detalhe — "certas operações exigem isso" sem nunca dizer quais.

É o defeito mais provável nesse tipo de trabalho, e o mais difícil de enxergar. Contar as fichas nunca teria mostrado isso.

Uma ficha por objeto, e vínculos entre elas

Uma ficha por objeto do negócio, em um arquivo de texto com o nome dele. Toda vez que uma ficha menciona outro objeto, ela faz isso por um vínculo.

Esse detalhe parece cosmético. Não é. As fichas e seus vínculos formam uma rede, e essa rede pode ser visualizada: cada ficha é um ponto, cada vínculo é um traço. Um vínculo que aponta para uma ficha que ainda não existe aparece na hora — é o sinal de que falta descrever um objeto.

A rede deixa então de ser uma imagem bonita e vira a fila de trabalho: enquanto sobrarem vínculos no vazio, sobram fichas para escrever.

A realidade de um lado, a intenção do outro

Um modelo de referência pode descrever duas coisas bem diferentes: o que o produto faz ou o que ele deveria fazer. Cada uma sozinha é incompleta. A primeira nunca permite fazer aparecer um defeito. A segunda perde o rastro do que existe de verdade.

Eu guardo as duas, em dois lugares distintos da mesma ficha. O corpo da ficha descreve a realidade, tal como ela está no código. Um bloco separado, no fim da ficha, lista os desvios: cada ponto em que essa realidade diverge do que a gente gostaria.

Regra absoluta: um desvio nunca modifica o corpo da ficha.

O que justifica a separação é que as duas partes não têm a mesma duração de vida:

O corpo se deduz do código: dá para jogar fora e refazer sem perder nada. Já os desvios carregam julgamento — não se encontram em lugar nenhum se forem perdidos. Separar os dois é proteger a parte que custa caro para produzir.

Um ponto que costuma ser entendido ao contrário: quando está tudo certo, não se escreve nada. Se o produto faz o que deve fazer, a regra fica simplesmente no corpo da ficha. O bloco dos desvios contém só as divergências. Uma ficha sem desvio sinaliza um objeto conforme, e isso já é uma informação.

Cinco naturezas de desvio bastam, e são elas que transformam o modelo de referência em material de trabalho:

O ponto de partida: uma foto, tirada em um instante dado

A gente descreve o produto tal como ele está em um instante dado. Uma versão do código, e tudo o que roda com ela: o banco como está nessa versão, as telas dessa versão, as traduções dessa versão. Essa é a foto.

O que aparece nela é o estado inicial, sem data de nascimento: não procuro saber quando cada campo apareceu. Reconstruir a história do produto exigiria vasculhar anos de arquivos para um benefício nulo.

Mais tarde, você tira uma nova foto e atualiza as fichas com o que mudou entre as duas. É todo o mecanismo.

A única coisa a vigiar, e eu caí nessa: uma fonte que não vem da foto não é uma fonte. Volto a isso mais abaixo.

Quatro lugares para ler, nenhum opcional

Um mesmo objeto é descrito em quatro lugares do produto, e cada um diz o que os outros calam:

Uma área do produto só está terminada quando os quatro foram lidos. Uma regra pode muito bem existir em um só deles.

As telas são lidas depois do núcleo do código, e antes de encerrar o assunto. Não é uma exigência de completude, é uma máquina de encontrar desvios:

Uma regra presente apenas na tela é quase sempre um desvio.

Ou é uma regra de negócio de verdade, mal colocada — um incômodo. Ou dá para contorná-la passando por fora da tela, por uma importação de arquivo ou pela interface que o produto expõe aos desenvolvedores externos — sua API. E aí é um defeito, com implicação de segurança: o que a tela proíbe, outro caminho autoriza.

O caso inverso existe e se trata do mesmo jeito. Uma regra aplicada pelo núcleo do código mas que a tela não reflete produz uma mensagem de erro incompreensível: o usuário tem a ação recusada sem ver o que fez de errado.

Duas constatações sobre essa leitura das telas.

Primeiro, o recorte das telas não coincide com o do código. Várias zonas da interface não tinham zona equivalente do lado do servidor. A aproximação se faz, portanto, objeto por objeto, nunca pasta por pasta.

Depois, um truque que vale ouro nas partes do código menos bem arrumadas: os nomes das mensagens de erro técnicas costumam ser a melhor fonte de regras. Um desenvolvedor que recusa uma ação cria um caso de erro, e dá um nome a ele. Um erro chamado CannotEditInvoicedOrder — "não dá para editar um pedido faturado" — enuncia uma regra sozinho. Basta ler a lista desses nomes, o que não exige saber programar.

Nada disso é original

Talvez seja o ponto mais útil desta seção. Construir ontologias é uma profissão constituída, com sua literatura, e o método acima só retoma o que já está estabelecido:

• O iterativo em vez da cascata. Os métodos históricos encadeavam as etapas em ordem: especificar, conceber, formalizar, realizar. Eles foram substituídos por abordagens feitas de pequenos pedaços recombináveis. O debate está encerrado há uns quinze anos.
• O enquadramento por perguntas. Escrever primeiro as perguntas que o modelo de referência terá de responder é o dispositivo padrão; ele até tem nome, competency question. Ir buscá-las no suporte em vez de escrevê-las a frio não está nos manuais. Não custa nada, e muda o que você encontra.
• Partir do meio. A gente começa pelos objetos mais centrais do negócio, depois sobe para as categorias mais amplas e desce para os casos particulares. As outras duas formas de fazer fracassam: partir do banco de dados equivale a copiar a estrutura técnica como está, com suas tabelas que não dizem nada para o negócio; partir de uma teoria geral do que existe dá um edifício fora de proporção com a necessidade.
• O rigor proporcional ao uso. A gente complica a vida quando precisa, não por princípio.
• Não reinventar o que já está normalizado. Na maioria das áreas existem classificações de referência. É preciso olhar para elas — e tratar qualquer divergência entre o seu próprio modelo e elas como uma questão a investigar, não como um detalhe.

Três critérios de parada. Três vezes errado.

Aqui está a parte pela qual este artigo existe.

Antes, duas estratégias descartadas

Saber o que procurar não diz em que ordem percorrer o produto. Duas abordagens aparecem naturalmente, e as duas fracassam.

Ler tudo, na ordem dos arquivos. Sem prioridade, não há nem ordem de chegada nem estrutura que emerja. A organização das pastas não tem nenhuma relação com a importância para o negócio, e o que está ali só por razões técnicas é descrito no mesmo nível dos objetos de negócio de verdade. Você acaba com uma massa de fichas sem saber quais importam.

Partir do banco de dados e fazer uma ficha por tabela. Útil, mas insuficiente, e baseado em uma confusão: uma tabela não é um objeto do negócio. Muitas tabelas só servem para ligar duas outras tabelas, para guardar um rastro técnico, para armazenar tokens de conexão ou resultados temporários. Elas não têm sentido nenhum para quem fala do produto.

Fiquei então com um terceiro caminho: uma área do produto por vez, indo do núcleo do negócio para a periferia, apoiado no recorte que o próprio código já traz. Um software um pouco grande é dividido em módulos — zonas de código que correspondem grosso modo a áreas do negócio: o faturamento, as compras, as permissões de acesso. Esse recorte foi feito por desenvolvedores, mas já constitui uma descrição parcial do negócio, de graça e validada pelo uso.

Foi a decisão certa. Ela não impediu o que veio depois.

Primeiro critério: "a rede de fichas está fechada"

Todas as fichas citadas existem, nenhum vínculo aponta mais para o vazio. Logo, acabou.

É falso, e a razão é mecânica. Um conjunto de fichas que só cita a si mesmo fecha sua rede bem antes de ter coberto o produto. A rede se fechou no meu caso quando uma minoria dos módulos tinha dado origem a uma ficha.

O que essa verificação provava de verdade: que o conjunto se sustenta. Nada mais. É uma boa verificação, vale a pena manter — mas ela não responde à pergunta feita.

A verificação de cobertura feita em seguida revelou dois objetos centrais do negócio que nada, na rede, reclamava.

Segundo critério: "percorri todas as minhas fontes"

O código das duas aplicações, o banco de dados, a API, o glossário, os relatórios de entrevistas, os tickets de suporte. Não sobrou nada para abrir.

É verdade, e não prova nada. É uma afirmação sobre o que eu abri, não sobre o que existe. "Li a minha pilha inteira" não diz nada sobre a biblioteca: enquanto o produto não estiver enumerado, "tudo" não tem denominador. Um módulo que nunca esteve na minha lista também não está no meu "tudo".

Terceiro critério: "cada área foi lida nos quatro lugares"

O núcleo do código, o banco de dados, as telas, as traduções.

Também verdade, e insuficiente pela mesma razão: isso só vale para as áreas que eu tinha identificado. O critério mede a profundidade, não diz nada sobre a largura. Dá para ler quatro lugares em uma minoria dos módulos e ignorar todo o resto — foi exatamente o que aconteceu.

O diagnóstico

Vamos retomar os três, e o que cada um provava de verdade.

Os três dizem a mesma coisa: terminei o que tinha começado. Nenhum diz: não sobrou nada.

A gente escolhe um critério que consegue satisfazer, em vez de um critério que prova o trabalho feito.

É a diferença entre "arrumei tudo o que estava largado na minha mesa" e "aqui está a lista do que eu devia arrumar, tudo marcado". A primeira frase é verdadeira e não compromete com nada. A segunda supõe ter feito a lista antes de começar.

Não é desonestidade, é uma questão de custo.

Um critério que dá para satisfazer já está à mão: basta olhar o que você acabou de fazer e constatar que está feito. Já um critério que prova exige fabricar mais alguma coisa — a lista do que existe, uma forma de contar essa lista, um número que outra pessoa poderia recalcular. É trabalho a mais, exigido justamente no momento em que você acha que terminou.

Daí a única defesa que eu conheço: escolher o critério de parada no começo, não no fim. Procurá-lo no fim é escolhê-lo entre aqueles que você já tem certeza de satisfazer.

O único critério que se sustenta

Enumerar o produto sob vários ângulos independentes, e medir, para cada um, a parte que corresponde a uma ficha.

Cada ângulo vê o que os outros não conseguem ver:

E principalmente: o sinal útil é a discordância entre dois ângulos. Um objeto presente em um e ausente dos outros ou é um objeto do negócio que passou batido, ou é parte puramente técnica. A questão se resolve em uma linha — mas se resolve explicitamente, nunca por omissão.

Os outros erros

Quatro, menores, todos caros.

Ler uma fonte que não estava na foto. A exportação do banco de dados que eu tinha em mãos tinha sido produzida vários meses antes da versão de código que eu descrevia. Eu a li como se descrevesse o mesmo produto. Ela descrevia um produto mais antigo: em uma área inteira, os objetos estavam lá no código sem nenhuma tabela correspondente na exportação, e concluí que eles não existiam.

A regra é mais simples do que eu achava na hora. Não é "verificar a data antes de concluir" — é que uma fonte que não vem da foto não é uma fonte. Você a substitui por uma versão atualizada, ou passa sem ela.

E a precisão que importa, porque eu tinha errado nela primeiro: quando duas partes da mesma foto se contradizem — o código de um lado, o banco ou a tela do outro, no mesmo instante, em produção —, isso não é defasagem. É uma incoerência do produto. É exatamente o que a gente procura.

Confundir uma busca com um inventário. Eu tinha indexado todo o código em um motor de busca por sentido — o princípio do RAG: você faz a pergunta em linguagem corrente e a ferramenta traz os trechos mais próximos. É tremendamente eficaz para reencontrar uma regra enterrada no meio de um arquivo, que nada no nome sinalizava.

Mas um motor desse tipo responde sempre, e responde sempre por um ranking: aqui estão os dez trechos mais próximos da sua pergunta. Ele nunca diz "não existe nenhum". Uma busca que não traz nada interessante pode então querer dizer duas coisas — a coisa não existe, ou eu fiz a pergunta errada. Impossível decidir.

Daí a regra: enumerar primeiro, buscar depois. No sentido contrário, você obtém um modelo de referência feito do que o motor resolveu trazer.

Dois detalhes que custam caro. O motor tinha data própria, uma versão atrás do código. E é preciso fazer a pergunta no idioma do código: uma consulta em português sobre um código escrito em inglês dá resultados medíocres, mesmo quando a resposta está lá.

Escrever a mesma regra em três lugares. No caminho, três documentos se formaram: - o modelo de ficha a preencher, - o documento de método, - as instruções de trabalho que eu dava ao agente.

Uma mesma regra — por exemplo "um desvio nunca modifica o corpo da ficha" — acabou escrita nos três, cada vez com palavras um pouco diferentes.

Enquanto nada muda, isso não incomoda ninguém. No dia em que a regra evolui, você corrige um, esquece os outros dois, e três documentos se contradizem sem que ninguém saiba qual vale. E uma IA, menos ainda do que as pessoas: ela lê os três sem perceber que divergem e baseia a análise naquele que abriu primeiro.

Cada regra vive agora em um único lugar. O modelo de ficha descreve só a forma — quais campos, quais valores permitidos — e remete ao método para todo o resto. Uma única fonte por regra.

A ironia não me ocorreu na hora: eu construía um modelo de referência destinado a eliminar as definições duplicadas, duplicando as próprias regras dele em três arquivos.

Contar errado. Eu queria saber quais palavras os clientes realmente usam, e com que frequência. Contei então as ocorrências de cada termo de negócio em várias centenas de relatórios de entrevistas.

Primeiro resultado: uma sigla de duas letras aparecia vários milhares de vezes. Na realidade havia duas. A busca contava todas as vezes em que essas duas letras estavam dentro de outra palavra. Procure "CA" desse jeito e você colhe "caso", "escaneado", "aplicação".

É preciso, portanto, contar palavras inteiras, e levar em conta as maiúsculas quando o termo é uma sigla. Um contador errado é pior do que contador nenhum: ele tem cara de dado.

O erro inverso também existe, e é mais traiçoeiro. Um termo que eu achava ausente do produto estava lá, mas empregado em um sentido totalmente diferente, num canto técnico sem relação com o negócio. Verificar uma ausência antes de concluir que falta alguma coisa.

E um desvio que não era desvio

Eu tinha registrado um desvio afirmando que certo tipo de vínculo entre objetos não estava corretamente descrito no produto. Feita a verificação, estava.

O desvio continua na ficha, marcado como rejeitado, com o motivo da rejeição. Errar faz parte do trabalho, desde que o erro deixe um rastro aproveitável — senão o mesmo erro será refeito daqui a seis meses por outra pessoa.

O agente capta. O humano reabre.

O trabalho foi conduzido por um agente — uma IA a quem se confia uma tarefa longa — sob a minha direção. É provavelmente a parte mais transferível deste relato, porque ela não fala só de ontologia.

Uma precisão de método: esta seção não se apoia na memória de ninguém. O registro das decisões do projeto é o diário das minhas intervenções — cada entrada traz o motivo, ou seja, o que corrigi e por quê. O diário de avanço mostra o que o agente produziu entre duas arbitragens. Tudo o que vem a seguir está nesses dois rastros.

O que um agente faz notavelmente bem: enumerar, cruzar, contar, manter um acompanhamento linha a linha, e ler as traduções da décima segunda área com o mesmo esmero das da primeira. Esse trabalho é massivamente repetitivo, e era exatamente isso que o tornava inviável até agora.

O que ele faz mal: declarar o trabalho terminado. Os três critérios de parada falsos não vieram do nada — cada um foi proposto como prova de conclusão, e foi preciso recusá-los todas as vezes. O viés é o mesmo de um humano cansado no fim do projeto, só que ele não tem o cansaço como desculpa: confundir reportar e entregar.

As minhas intervenções, tais como aparecem nos motivos das decisões, se organizam em três categorias:

• Ampliar um escopo que ele tinha reduzido implicitamente. O agente lia o núcleo do código e parava por ali. A regra dos quatro lugares, com as telas incluídas, vem daí — e é justamente nas telas que estão os desvios mais interessantes.
• Corrigir uma estrutura que ia divergir. A mesma regra escrita em três lugares: ele tinha copiado por zelo, e era exatamente o que não se devia fazer.
• Recusar um critério de parada cômodo demais. Três vezes.

O que torna essa arbitragem possível cabe em quatro dispositivos, e eles valem para qualquer trabalho delegado — tanto a uma máquina quanto a outra pessoa:

1. Um critério de parada verificável por um terceiro. Não "li tudo", mas uma lista e uma taxa.
2. Uma medição que dá para rodar de novo, em vez de uma afirmação. Entre "está coberto" e "aqui está o comando que verifica isso" existe toda a distância entre uma promessa e um fato.
3. Um acompanhamento escrito, na granularidade certa. Uma linha por área e por lugar a ler, atualizada à medida que o trabalho avança. Ele sobrevive à interrupção do trabalho, e é ele que evita refazer duas vezes a mesma coisa.
4. A enumeração antes da busca. O que é certo primeiro, o que é provável depois e como complemento.

O resultado, e sete formas de verificar que não falta nada

O que isso deu, uma vez aplicado o critério certo.

Várias dezenas de objetos do negócio descritos. Algumas centenas de regras. Outros tantos vínculos entre eles. Muitos desvios registrados. Nenhum vínculo apontando para o vazio.

As perguntas de partida encontram resposta sem abrir o código.

A cobertura, medida

O princípio cabe em três operações. Listo os objetos de um ângulo — os módulos, as tabelas, os eventos, as telas, os recursos expostos pela API. Olho, para cada um, se corresponde a uma ficha. Conto.

Os sete ângulos escolhidos: os módulos da aplicação A, as tabelas do banco de dados, os eventos emitidos pelo software, as telas da aplicação A, os módulos e os objetos da aplicação B, os recursos expostos pela API.

As taxas obtidas ficam entre 70 e 95 % conforme o ângulo.

A medição pode ser refeita por um pequeno programa. Esse é o ponto importante: não é uma afirmação, é uma verificação que outra pessoa consegue rodar de novo.

E é uma medição fraca, o que precisa ser dito na mesma frase. A aproximação se faz pelos nomes: uma tabela sales_order é reconhecida como a ficha "Sales Order", deixando de lado maiúsculas, hifens e plurais.

Isso funciona mais ou menos uma vez em cada duas. No resto, os nomes não se parecem em nada — uma tabela pode se chamar so_header onde a ficha se chama "Sales Order". Mantive então, ao lado, uma lista de correspondências, escrita linha a linha à medida que eu esbarrava nelas: essa tabela aqui é esse objeto ali.

Essa lista é um julgamento, não uma regra. Se eu esqueço uma linha, o objeto aparece como não coberto quando está coberto. Se acrescento uma linha duvidosa — "vai, essa tabela deve corresponder a essa ficha" —, eu inflo a minha própria nota. E mesmo quando os nomes coincidem, pode ser acaso: duas coisas diferentes com a mesma palavra.

A medição, portanto, não prova nada. Ela aponta para onde olhar.

Por que não busco chegar a 100 %

É a objeção imediata: se eu sei a proporção dos módulos sem ficha, sei quais são — basta descrevê-los.

Só que a lacuna não é uma tarefa, é uma pergunta. Cada objeto sem ficha ou é um objeto do negócio que passou batido, ou é parte puramente técnica sem sentido algum para o negócio: uma fila técnica, um redimensionador de imagens, uma tabela de tokens de conexão, uma tela de navegação. Chegar a 100 % suporia criar uma ficha "Fila" e uma ficha "Token" — ou seja, poluir o modelo de referência para fazer um número subir.

O contador tem, então, três estados, e não dois:

O que deve chegar a 100 % é a terceira linha em zero — nada que não tenha sido examinado. Já a porcentagem exibida não sobe até 100 e não precisa subir.

Aqui, o resto foi revisado à mão: parte técnica, mecanismos internos, telas sem objeto de negócio próprio. Nenhum objeto do negócio estava escondido ali. Mas é uma verificação manual, a refazer a cada mudança no produto — e essa é a fraqueza que permanece.

O número serve, portanto, para outra coisa que não medir avanço. Ele serve para comparar os ângulos entre si. A mais baixa das sete taxas, nos objetos da aplicação B, contra a mais alta, nos eventos: a diferença não quer dizer "sobra todo esse trabalho", ela quer dizer "a aplicação B manipula coisas que o resto do produto ignora, vá olhar desse lado". Foi essa discordância que trouxe as quatro descobertas a seguir.

O que os ângulos renderam

Quatro objetos que nenhum outro caminho teria encontrado:

• Pelas tabelas do banco. Um objeto que o produto exibe mas que não pertence a nenhuma área do código — no ERP fictício, seria a parcela de faturamento futura: o cliente a vê no cronograma de cobranças, mas ela só existe de verdade no momento em que a fatura é emitida. Essa ambiguidade explica uma família inteira de reclamações de clientes.
• Pelos eventos. Um subconjunto inteiro de uma área que a gente achava coberta, revelado pelos eventos que ela emitia e que ninguém tinha ligado a coisa alguma.
• Pela API. Alguns objetos repartidos por vários módulos — portanto invisíveis enquanto se avança área por área, e mesmo assim expostos contratualmente para fora.
• Pela aplicação B. Dois objetos que ela manipula e que a aplicação A desconhece.

Os problemas que aparecem em todo lugar

Aqui estão as descobertas, transpostas para o ERP fictício. São tipos de problema, não casos isolados — e eu apostaria que nenhum deles está ausente do seu produto.

Um estado recalculado em todo lugar, definido em lugar nenhum. O status de um pedido deduzido de algumas datas e do estado das suas linhas, recalculado em cada tela, sem regra central. Duas telas acabam não dizendo mais a mesma coisa, e ninguém sabe qual está certa.

Um objeto que o usuário vê e não consegue reencontrar. A parcela de faturamento futura de que eu falava: exibida no cronograma de cobranças, ausente dos resultados de busca, porque ainda não existe como documento. O usuário, por sua vez, viu na tela — então procura, não encontra, e abre um ticket. O suporte responde caso a caso há anos sem que a causa esteja escrita em lugar nenhum.

Um valor que não é valor. O saldo de um cliente não é um número guardado em algum lugar: é o resultado de um cálculo sobre todas as faturas, os pagamentos, as notas de crédito e os lançamentos de ajuste dele. Enquanto isso ficar implícito, cada nova funcionalidade que "lê o saldo" erra de objeto e dá um número ligeiramente diferente, conforme os movimentos que lembrou de incluir. Três telas, três saldos.

Uma regra aplicada de um lado só. O teto de desconto verificado no formulário de preenchimento, e em nenhum outro lugar — portanto contornável por uma importação de arquivo ou pela API. É a máquina de desvios de que falei mais acima, e o rendimento dela é notável.

Uma permissão calculada a partir de seis fontes sem nenhum lugar que as reúna. O papel da pessoa, o plano contratado, as opções ativadas, a restrição do período de teste, o alcance da filial dela, uma lista de exceções. Nenhum lugar do produto diz "é assim que se calcula uma permissão". Cada nova funcionalidade redescobre isso à própria custa.

Um mesmo objeto nomeado de forma diferente em cada andar. "Pedido" na tela, uma palavra no código, outra na segunda aplicação, "negócio" no dia a dia dos clientes. Quatro vocabulários para o objeto mais central do produto.

Uma palavra que os clientes usam o tempo todo e que o produto desconhece. Nesse corpus de entrevistas, uma noção volta várias dezenas de vezes, outra um pouco menos. Nem uma nem outra existe no produto, sob nome nenhum. Não são desvios de vocabulário, são faltas de concepção — e elas só aparecem quando se compara o que os clientes dizem com o que o produto faz.

Os subprodutos

Nenhum era o objetivo. Todos caíram do trabalho.

Bugs candidatos. O produto contradiz uma expectativa escrita em algum lugar. Cada um chega com a sua prova e a sua consequência, não com uma intuição.

Um vocabulário de cliente, com as frequências. Contando as palavras em um corpus grande de relatórios de entrevistas e tickets de suporte, você obtém, para cada objeto do produto, os termos realmente usados e o peso de cada um. Quem fala com o cliente passa a saber qual palavra usar. Um termo volta mais de cem vezes para designar um alcance que o produto chama de outro jeito; outro quase tanto para o objeto central.

E esses dois corpus não dizem a mesma coisa. As entrevistas dizem o que os clientes querem construir. Os tickets dizem o que quebra. Uma mesma palavra pode dominar um e estar ausente do outro. Contar os dois juntos é priorizar torto.

Um panorama das traduções. O glossário multilíngue cobre apenas uma minoria dos objetos descritos. Entre os ausentes, alguns são exibidos ao usuário em todos os idiomas: não existe tradução de referência para eles. E do conjunto de idiomas do glossário, só uma pequena parte foi revisada.

O que isso custa, e o que o método continua não dizendo

O custo

Menos de seis horas. É o tempo que o conjunto levou: as fichas, as regras, as medições de cobertura. Uma sessão, de ponta a ponta.

Antes de começar, eu tinha estimado algumas dezenas de horas, distribuíveis área por área. Errei por uma ordem de grandeza — e esse erro de estimativa talvez seja a verdadeira razão pela qual ninguém tinha feito esse trabalho antes: a gente acha que está fora de alcance, então não começa.

Três ressalvas sobre esse número, para que ele continue honesto. É uma medição sobre um produto, uma vez, não uma média. As fontes já estavam reunidas e indexadas localmente; o tempo de montagem não está incluído. E o número diz tanto sobre o ferramental quanto sobre o método: o mesmo trabalho na mão teria levado semanas, o que é precisamente a razão de nunca ter sido feito.

A condição de rentabilidade, por sua vez, é clara: terminar uma área antes de abrir outra. Um modelo de referência completo sobre um escopo serve imediatamente todos os times desse escopo. Um modelo de referência pela metade em cinco escopos não serve ninguém.

A manutenção

É a pergunta que sempre vem em segundo, e ela é legítima: um modelo de referência sobre o qual não se diz como ele se mantém vivo não interessa a ninguém.

A versão de referência serve de marcador: ela dá, por um simples comando, a lista exata do que mudou no produto desde a última atualização — portanto a lista do que falta registrar.

Cada ficha tem um diário em que se acrescentam entradas sem nunca corrigir as anteriores. Uma entrada que cita uma versão do código sinaliza que o produto mudou. Uma entrada que não cita nenhuma sinaliza outra coisa: foi a nossa compreensão que mudou, não o produto. A distinção parece menor; é ela que permite, seis meses depois, saber se corrigimos uma ficha ou se o software evoluiu.

Dois movimentos merecem menção porque nenhuma ferramenta os conta: a fusão de dois objetos que se acreditava distintos, e a divisão de um objeto que escondia dois. São os movimentos mais frequentes quando um modelo de referência amadurece.

Por fim, quando um objeto é repensado do zero, a ficha dele não é modificada: uma nova ficha é criada, e a antiga permanece. Ela descreve o que o produto foi, e continua necessária para interpretar os dados e as trocas anteriores à mudança.

O que decidi não fazer

• Nada de reconstruir a história passada do produto.
• Escopo fechado quanto às exportações de dados, que são visões derivadas do produto e não o produto em si.
• Nada de ferramental erudito enquanto nenhum uso exigir isso.

O que o método ainda não diz

• Até onde levar o rigor do formato. Depende do uso, e o uso não começou.
• Como ligar um dado antigo ao estado certo de um objeto, quando esse objeto foi repensado nesse meio-tempo.
• Quem revisa uma ficha, e segundo quais critérios, antes que ela entre no modelo de referência.
• Em que ritmo atualizar o ponto de partida, e portanto alcançar o que mudou desde então.

Um documento de método que se diz completo está mentindo. Este aqui tem uma seção "o que ele ainda não diz", e ela encolhe à medida que as questões são resolvidas.

Conclusão: o critério de parada é o verdadeiro entregável

Se eu tivesse de guardar uma única coisa deste projeto, seria a frase que explica as três largadas falsas:

A gente escolhe um critério que consegue satisfazer, em vez de um critério que prova o trabalho feito.

Ela não diz respeito só às ontologias. Ela vale para uma auditoria, uma migração, uma revisão de segurança, uma retomada de dívida técnica. Toda vez que um trabalho termina com "olhei tudo", a pergunta a fazer é: tudo o quê, exatamente? Você tem a lista?

Duas verificações, nunca uma só. Que o conjunto se sustenta, você verifica olhando as fichas entre si. Que ele está completo, você verifica enumerando o produto. Confundir as duas custou, aqui, uma parte importante do produto.

Falta o mais interessante, e ele não está feito: os desvios. Todos esperam ser investigados — os bugs candidatos primeiro, depois aqueles que um pedido de cliente já apoia, depois as faltas, depois a dívida de concepção. Isso já não é descrição, é decisão de produto.

É outro artigo, e ele só poderá ser escrito depois.

Anexo A — Com o que uma ficha se parece

Este anexo é o mais técnico do artigo; dá para parar antes sem perder nada do argumento.

A ficha abaixo está transposta para o ERP fictício. Ela descreve a forma — as regras que a governam vivem no documento de método, em um único lugar.

O que uma ficha contém

A ficha em si

O arquivo leva o nome do objeto — é isso que permite que os vínculos entre fichas se resolvam sozinhos.

---
concept: Sales Order
definition: Compromisso de entrega assumido com um cliente, acompanhado desde o registro até o faturamento.
parent:
enfants: ["[[Rush Order]]", "[[Standing Order]]"]
attributs:
  - nom: status
    type: enum
    valeurs: [draft, confirmed, shipped, invoiced]
relations:
  - verbe: placed-by
    cible: "[[Customer]]"
    cardinalite: 1..1
  - verbe: contains
    cible: "[[Order Line]]"
    cardinalite: 1..n
axiomes:
  - Um pedido faturado não pode mais receber linhas
lexique:
  fr: [commande, commande client]
  en: [sales order]
  es: [pedido]
  synonymes_terrain: [affaire, dossier]
  deprecies: [bon de commande client]
sources:
  - erp.sql:table `sales_order`
  - fr.json:order.status.draft
ecarts:
  - id: E1
    nature: manque
    portee: relations
    attendu: um vínculo para "[[Attachment]]", como o que "[[Customer]]" tem
    consequence: impossível anexar um pedido de compra assinado
    statut: confirme
    date: 2026-08-10
historique:
  - date: 2026-08-10
    action: creation
    motif: descrição inicial, sobre a versão de referência
---

# Sales Order

Compromisso de entrega assumido com um cliente, acompanhado desde o registro até o faturamento.

## Vínculos

- *placed-by* → [[Customer]] (um só)
- *contains* → [[Order Line]] (pelo menos uma)
- casos particulares → [[Rush Order]], [[Standing Order]]

## Histórico

| Data | O que aconteceu | Versão do código | Motivo |
|---|---|---|---|
| 2026-08-10 | criação | — | descrição inicial |

Uma única coisa está escrita duas vezes: os vínculos. Uma vez no cabeçalho, para que as ferramentas consigam ler; uma vez no corpo, para que eles apareçam na visão em rede. Todo o resto existe em um único lugar.

Três critérios de qualidade, oponíveis a qualquer ficha: a definição cabe em uma frase e não morde o próprio rabo; cada vínculo é nomeado por um verbo preciso, nunca por "está relacionado a"; o vocabulário é multilíngue e carrega as palavras usadas pelos clientes.

Anexo B — A grade dos desvios

O que se anota para cada desvio:

As cinco naturezas:

O que acontece quando o desvio desaparece. A gente o marca como resolvido, e ele continua na ficha. O corpo da ficha é atualizado para descrever a nova realidade, e uma linha é acrescentada ao diário. Os dois se respondem: os desvios carregam a intenção, o diário carrega o movimento.

Um cuidado. Um desvio descreve uma divergência estrutural, não um incidente. Uma linha, um vínculo para o ticket. As capturas de tela, os passos de reprodução e o detalhe ficam na ferramenta de acompanhamento. Uma ficha não é uma ferramenta de gestão de bugs.

Anexo C — Os ângulos de enumeração

Todos devem ser percorridos, e confrontados dois a dois.

Três regras de uso:

1. O sinal é a discordância entre dois ângulos, não a nota de um ângulo tomado sozinho.
2. Cada objeto não vinculado é decidido explicitamente — objeto do negócio, ou parte puramente técnica. Nunca por omissão.
3. Dois corpus de cliente, contados separadamente: as entrevistas dizem o que os clientes querem construir, os tickets dizem o que quebra. Levar as duas frequências para o vocabulário — uma orienta o roadmap, a outra a documentação e o treinamento.

Onde estão as regras, por ordem de rendimento decrescente:

1. Os nomes das mensagens de erro técnicas. Nas partes menos bem arrumadas do código, costuma ser a única fonte — e ela se lê sem saber programar.
2. As verificações feitas no início de uma operação, antes que qualquer coisa seja modificada.
3. As restrições do banco de dados — o que precisa ser único, o que não pode ficar vazio. Elas às vezes contradizem o negócio, e essa distância é um defeito.
4. As validações de preenchimento nas telas — a parte mais frequentemente esquecida, e a que produz os desvios mais interessantes.

Um objeto descrito sem regra nenhuma sinaliza uma descrição superficial, nunca um negócio sem regras.