Escrevi a ontologia de um produto. Três vezes achei que tinha terminado.

Uma pergunta chega pelo Slack: o produto sabe fazer isso, para este cliente, neste caso específico?

Não é uma pergunta abstrata. Não é uma reflexão sobre a visão de cinco anos. É uma pergunta de campo, e ela precisa de resposta dentro da 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 interrompeu.

Isso 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 para falar deles — não está escrito em nenhum lugar de uma forma que se possa 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: 52 objetos descritos, 250 regras, 208 vínculos entre eles. Este artigo conta como cheguei lá — e principalmente o que errei no caminho, porque essa é a parte que se transfere.

Três avisos antes de começar.

O primeiro: este relato é sobre a construção do modelo de referência, não sobre o uso dele. Ele existe, está medido, já produziu os primeiros subprodutos. Mas a fase de exploração não começou. Então não posso afirmar nada sobre retorno do investimento. Quem te vende um número nesse estágio está inventando.

O segundo: os exemplos vêm de um caso fictício — uma empresa que vende um SaaS de gestão, um ERP, com seus clientes, seus pedidos, seus itens 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 só de um lado, uma palavra que os clientes usam e que o produto ignora. Esses três você também tem. Já o detalhe do caso não interessa a ninguém.

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

Uma ontologia não é um glossário enriquecido

A palavra é uma armadilha. Para alguns ela sugere filosofia, para outros um campo acadêmico cheio de ferramentas complicadas, e para a maioria não sugere nada. Melhor deixar claro.

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 conecta, - o que é verdade a respeito deles, - as palavras com que os chamamos.

Aplicada a um software, ela responde a cinco perguntas. Cada uma corresponde a uma coisa que você 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 delas não tem nada que fazer no modelo de referência.

Por que mais um documento

Já existia 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 os distingue de uma ontologia se resume a um ponto: os vínculos contam tanto quanto as definições. Um objeto descrito sozinho ensina pouca coisa. O mesmo objeto ligado a cinco outros 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. Pegue o pedido do cliente:

Esses três vocabulários evoluem separadamente, e a diferença entre eles é uma informação valiosa. O modelo de referência guarda isso: a palavra oficial, as palavras usadas pelos clientes e aquelas que abandonamos no caminho. É o 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ê fornece, normas que acompanham. É um campo de verdade, e eu não entrei nele (entre outras coisas, por falta de competência).

Comecei com o que 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 sei 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.

Em volta desse produto, a documentação, o changelog, a documentação de suporte, as respostas às perguntas sobre o produto e as especificações são todas regeradas a partir do código. O raciocínio é simples: a verdade de um produto é o que roda, não o que a gente tinha planejado.

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

Mas ela desloca o problema.

O que o código não entrega

O código estabelece como o produto funciona. O sentido é construído por cima.

Pegue o pedido e o status dele. O código dá a estrutura: aqui estão os campos, aqui estão os valores possíveis. Quatro informações tornam isso realmente utilizável, e nenhuma delas está lá:

• a regra — um pedido faturado não recebe mais itens. O produto aplica isso, mas a regra não está escrita em nenhum lugar: a verificação está espalhada em cinco arquivos e cada um faz só um pedaço. Para enunciá-la em uma frase, você precisa 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 escopo — 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.

Juntas, essas quatro informações transformam uma estrutura de dados em descrição de produto. É exatamente o conteúdo de uma ficha. E nenhuma delas está no mesmo lugar: elas estão distribuídas 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 início é só um caso entre muitos. Tudo o que descreve o produto para alguém é uma reconstituição, refeita toda vez, em paralelo, por cada área: a documentação, as respostas a propostas comerciais, o treinamento de quem chega, o discurso do suporte. Cada um recomeça a partir do código, ou da memória de alguém.

É esse gasto que precisa desaparecer. Ele não aparece em nenhum orçamento, o que explica por que a gente paga por ele há anos sem ver.

Uma IA não consegue perguntar. Ela adivinha.

Até aqui, aquilo que o produto realmente é se transmitia de boca em boca. Você perguntava para a pessoa certa, recebia a regra e voltava ao trabalho. O modelo do produto morava em algumas cabeças, e funcionava porque sempre dava para bater numa porta.

Uma IA não bate em porta nenhuma.

Quando você entrega uma evolução para ela, você descreve isso em algumas frases. Na nossa cabeça existe um modelo completo: o que é um pedido, quais estados ele atravessa, 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 errado.

A diferença entre o que a gente queria e o que a gente recebe de volta é exatamente a parte do nosso modelo mental que não foi escrita.

Um modelo de referência é esse modelo mental escrito. Entregá-lo a um agente não deixa o agente mais inteligente: impede que ele invente onde já existe regra. Daí saem três usos, e são esses que me interessam.

Pedir uma evolução sem explicar o produto de novo. "Adicione um desconto nos pedidos." Com o modelo de referência no contexto, o agente sabe que um pedido faturado não recebe mais itens, que um desconto tem limite e que "pedido" cobre também pedidos urgentes e 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 sempre começa por reconstituir o modelo da área envolvida. Essa reconstituiçã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 garimpar ao acaso.

Escrever os testes e decidir os relatos. Uma regra é uma afirmação verificável. "Um pedido faturado não recebe mais itens" é um teste, do jeito que está, formulado em linguagem de negócio. 250 regras são 250 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 é bug; ou é uma regra que ninguém tinha estabelecido — então é decisão de produto, não 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 gente elimina a parte adivinhada — mas eu não fiz o teste. O que eu vou fazer: pegar umas trinta demandas, tratar metade com o modelo de referência no contexto e metade sem, comparar tempo gasto e 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 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 qual modelo sustentar.

Iterar, não sequenciar. Você esboça o suficiente para saber o que procurar, procura, revisa o modelo com o que aprendeu. Uma restrição atravessa as idas e vindas: o que você recolhe é guardado na forma mais simples possível, e sempre com a indicação de onde veio. Uma mudança de modelo nunca deve obrigar você a voltar para buscar o que já tem.

Por onde começar: vinte perguntas que já tinham nos feito

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 vai ter de responder, e elas delimitam o terreno. O problema é que perguntas escritas a frio, numa sala, sempre se parecem com o que a gente acha importante.

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

Há meses, cada pergunta sobre o produto que chega — pelo Slack, numa reunião, de um vendedor preparando uma resposta, do suporte diante de um ticket — é arquivada com a resposta. Reli todas e depois condensei em vinte perguntas genéricas. Nenhuma é inventada; cada uma cobre entre cinco e vinte perguntas reais.

Transpostas para o ERP fictício, elas ficam assim:

• 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 não dá mais?
• O que é o saldo de um cliente, e por quais movimentos ele evolui?
• De quem é um pedido gerado automaticamente, e o que acontece com ele se essa pessoa sair da empresa?
• Em que 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 entrega na hora: a ordem de trabalho. Cada pergunta toca uma ou mais áreas do produto; basta contar. Onze perguntas de vinte batiam na mesma área — ela virou a primeira. Cinco numa segunda, quatro numa terceira. A ordem deixa de ser preferência e passa a ser contagem.

E elas servem uma segunda vez, na chegada. Quando uma área termina, você 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 deu 18 respostas completas de 20. As duas que faltaram falharam do mesmo jeito: uma regra escrita de forma genérica onde a pergunta esperava o detalhe — "certas operações exigem isto" sem nunca dizer quais.

Esse é o defeito mais provável desse tipo de trabalho, e o mais difícil de ver. Contar fichas nunca teria mostrado isso.

Uma ficha por objeto, e vínculos entre elas

Uma ficha por objeto de negócio, em um arquivo de texto com o nome dele. Cada 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 fica visível na hora — é o sinal de que falta descrever um objeto.

A rede deixa então de ser uma imagem bonita e passa a ser a fila de trabalho: enquanto houver vínculos apontando para o vazio, há fichas para escrever.

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

Um modelo de referência pode descrever duas coisas muito 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 é deduzido do código: você pode jogar fora e refazer sem perder nada. Os desvios carregam julgamento — eles não são encontrados em lugar nenhum se você os perder. Separar os dois é proteger a parte que custa caro para produzir.

Um ponto que costuma ser entendido errado: quando está tudo bem, você não escreve nada. Se o produto faz o que deve fazer, a regra simplesmente fica no corpo da ficha. O bloco de desvios contém apenas as divergências. Uma ficha sem desvio sinaliza um objeto em conformidade, e essa 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 junto: o banco como ele 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 estou tentando saber quando cada campo apareceu. Reconstituir a história do produto exigiria garimpar anos de arquivos para um benefício nulo.

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

A única coisa a vigiar, e nisso eu me dei mal: uma fonte que não vem da foto não é uma fonte. Volto a isso mais abaixo.

Quatro lugares para ler, nenhum facultativo

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

Uma área do produto só termina quando os quatro foram lidos. Uma regra pode perfeitamente existir em um só deles.

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

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

Ou é uma regra de negócio de verdade, mal posicionada — um atrito. Ou ela é contornável passando ao lado da tela, por uma importação de arquivo ou pela interface que o produto expõe a desenvolvedores externos — a API. E aí é um defeito, com uma questão de segurança: o que a tela proíbe, outro caminho autoriza.

O caso inverso existe e é tratado 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: a ação do usuário é recusada sem que ele veja o que fez de errado.

Duas constatações sobre essa leitura das telas.

Primeiro, a divisão das telas não coincide com a do código. Doze áreas da interface não tinham área equivalente do lado do servidor. Então a aproximação é feita objeto por objeto, nunca pasta por pasta.

Segundo, um truque que vale ouro nas partes menos organizadas do código: 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 se pode 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 este seja o ponto mais útil da seção. Construir ontologias é uma disciplina estabelecida, com literatura própria, e o método acima só retoma resultados conhecidos:

• 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á resolvido há uns quinze anos.
• O enquadramento por perguntas. Escrever primeiro as perguntas que o modelo de referência vai ter de responder é o dispositivo padrão; tem até 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. Você 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 fracassam: partir do banco de dados equivale a copiar a estrutura técnica como ela é, com tabelas que não significam nada para o negócio; partir de uma teoria geral do que existe produz um edifício fora de proporção com a necessidade.
• Rigor proporcional ao uso. Você complica a vida quando precisa, não por princípio.
• Não reinventar o que já está normalizado. Na maioria dos setores existem classificações de referência. É preciso olhar para elas — e tratar qualquer divergência entre o seu modelo e elas como uma questão a investigar, não como detalhe.

Três critérios de parada. Errado três vezes.

Esta é a parte pela qual este artigo existe.

Primeiro, duas estratégias descartadas

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

Ler tudo, na ordem dos arquivos. Sem prioridade, não há ordem de chegada nem estrutura que emerja. A organização das pastas não tem relação alguma com a importância para o negócio, e o que só está ali 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 de negócio. Muitas tabelas só servem para ligar duas outras tabelas, guardar um rastro técnico, armazenar tokens de conexão ou resultados temporários. Elas não têm sentido nenhum para quem fala do produto.

Então adotei um terceiro caminho: uma área do produto por vez, indo do núcleo do negócio para a periferia, apoiado na divisão que o código já carrega. 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. Essa divisão foi feita por desenvolvedores, mas já constitui uma descrição parcial do negócio, gratuita 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. Então terminou.

Está errado, e a razão é mecânica. Um conjunto de fichas que só cita a si mesmo fecha a rede bem antes de ter coberto o produto. A rede fechou no meu caso quando apenas doze módulos de trinta e dois tinham gerado uma ficha.

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

A verificação de cobertura feita depois revelou dois objetos centrais do negócio que nada, na rede, estava exigindo.

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 registros de entrevistas, os tickets de suporte. Nada mais 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 toda" não diz nada sobre a biblioteca: enquanto o produto não é enumerado, "tudo" não tem denominador. Um módulo que nunca apareceu na minha lista também não aparece 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.

Verdade também, 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 doze módulos e ignorar vinte — foi exatamente o que aconteceu.

O diagnóstico

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

Os três dizem a mesma coisa: terminei o que eu tinha começado. Nenhum diz: não resta 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 na minha mesa" e "aqui está a lista do que eu tinha de arrumar, tudo marcado". A primeira frase é verdadeira e não compromete com nada. A segunda pressupõe ter feito a lista antes de começar.

Isso não é desonestidade, é uma questão de custo.

Um critério que você consegue satisfazer já está à mão: basta olhar o que você acabou de fazer e constatar que está feito. Um critério que prova exige fabricar algo a mais — a lista do que existe, uma forma de contar, um número que outra pessoa possa recalcular. É trabalho adicional, cobrado exatamente 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 resiste

Enumerar o produto por vários ângulos independentes e medir, para cada um, a parcela 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 de negócio que a gente perdeu, ou parte puramente técnica. A questão se resolve em uma linha — mas ela se resolve explicitamente, nunca de passagem.

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 havia sido gerada cinco meses antes da versão de código que eu descrevia. Eu a li como se ela 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 eu 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 dispensa.

E a precisão que importa, porque eu errei 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 mecanismo de busca por sentido — o princípio do RAG: você faz a pergunta em linguagem corrente, a ferramenta traz os trechos mais próximos. É extremamente eficaz para reencontrar uma regra enterrada no meio de um arquivo, que nada no nome sinalizava.

Mas um mecanismo desse tipo sempre responde, e sempre responde com 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 significar duas coisas — a coisa não existe, ou eu formulei mal a pergunta. Impossível decidir.

Daí a regra: enumerar primeiro, buscar depois. No sentido inverso, você obtém um modelo de referência feito daquilo que o mecanismo teve a bondade de trazer.

Dois detalhes que custam caro. O mecanismo tinha a própria data, 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 foram se formando: - 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. Uma IA menos que qualquer um: ela lê os três sem ver que divergem e baseia a análise naquele que abriu primeiro.

Cada regra agora mora em um único lugar. O modelo de ficha descreve apenas 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 atingiu na hora: eu estava construindo um modelo de referência destinado a eliminar 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. Então contei as ocorrências de cada termo de negócio em 261 registros de entrevistas.

Primeiro resultado: uma sigla de duas letras aparecia 3.525 vezes. Na realidade eram 2. A busca contava todas as vezes em que essas duas letras estavam dentro de outra palavra. Procure "CA" desse jeito e você colhe "caso", "casa", "escaneamento", "aplicação".

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

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

E um desvio que não era desvio

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

O desvio fica na ficha, marcado como rejeitado, com o motivo da rejeição. Errar faz parte do trabalho, com a condição de que o erro deixe um rastro utilizável — senão o mesmo erro vai ser refeito em seis meses por outra pessoa.

O agente capta. O humano reabre.

O trabalho foi conduzido por um agente — uma IA a quem a gente entrega uma tarefa longa — sob a minha direção. Essa é 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 de decisões do projeto é o diário das minhas intervenções — cada entrada carrega o motivo, isto é, o que eu 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 é lido nesses dois rastros.

O que um agente faz notavelmente bem: enumerar, cruzar, contar, manter um acompanhamento linha por linha e ler as traduções da décima segunda área com a mesma aplicação das da primeira. Esse trabalho é massivamente repetitivo, e é 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 cada vez foi preciso recusar. O viés é o mesmo de um humano cansado no fim de projeto, só que ele não tem o cansaço como desculpa: confundir relatar com entregar.

As minhas intervenções, tal 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 ali. A regra dos quatro lugares, telas incluídas, vem disso — 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 vontade de fazer bem feito, o que era exatamente o que não devia fazer.
• Recusar um critério de parada cômodo demais. Três vezes.

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

1. Um critério de parada verificável por um terceiro. Não "eu 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" 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 conforme o trabalho avança. Ele sobrevive à interrupção do trabalho, e é ele que evita fazer duas vezes a mesma coisa.
4. A enumeração antes da busca. O que é certo primeiro, o que é provável depois e como complemento.

52 objetos, e sete formas de verificar que não falta nenhum

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

52 objetos de negócio descritos. 250 regras. 208 vínculos entre eles. 124 desvios registrados. Nenhum vínculo apontando para o vazio.

As vinte perguntas iniciais encontram resposta sem abrir o código.

A cobertura, medida

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

A medição é reexecutada por um programinha. Esse é o ponto importante: não é uma afirmação, é uma verificação que outra pessoa pode rodar de novo.

E é uma medição fraca, o que precisa ser dito na mesma frase. A aproximação é feita 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 em uma vez de cada duas. No resto, os nomes não se parecem nem um pouco — uma tabela pode se chamar so_header onde a ficha se chama "Sales Order". Então mantive ao lado uma lista de correspondências, escrita linha por linha conforme eu ia tropeçando nos casos: essa tabela aí é esse objeto aí.

Essa lista é um julgamento, não uma regra. Se eu esquecer uma linha, o objeto aparece como não coberto quando está. Se eu adicionar uma linha duvidosa — "vai, essa tabela deve corresponder a essa ficha" —, eu inflo o meu próprio placar. E mesmo quando os nomes coincidem, pode ser coincidência: duas coisas diferentes com a mesma palavra.

Então a medição não prova nada. Ela indica onde ir olhar.

Por que eu não tento chegar a 100%

Essa é a objeção imediata: se eu sei que faltam 19% dos módulos, eu sei quais são — basta descrevê-los.

Só que a casa que falta não é uma tarefa, é uma pergunta. Cada objeto sem ficha é ou um objeto de negócio que eu perdi, ou parte puramente técnica sem sentido nenhum 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% exigiria criar uma ficha "Fila" e uma ficha "Token" — isto é, 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 precisa chegar a 100% é a terceira linha em zero — nada mais que não tenha sido examinado. Já a porcentagem exibida não sobe até 100 e não precisa.

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

O número serve então para outra coisa além de medir avanço. Ele serve para comparar os ângulos entre si. 69% nos objetos da aplicação B contra 93% nos eventos não quer dizer "faltam 31% de trabalho": quer dizer "a aplicação B manipula coisas que o resto do produto ignora, vão olhar desse lado". É essa discordância que trouxe as quatro descobertas seguintes.

O que os ângulos trouxeram

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 a vencer: o cliente a vê no cronograma de pagamentos, 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 vinculado a nada.
• Pela API. Dois objetos distribuídos por cinco módulos diferentes — portanto invisíveis enquanto você avança área por área, e ainda assim expostos contratualmente para fora.
• Pela aplicação B. Dois objetos que ela manipula e que a aplicação A não conhece.

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 falta no seu produto.

Um estado recalculado em todo lugar, definido em lugar nenhum. O status de um pedido deduzido de algumas datas e do estado dos itens dele, 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 de que eu falava: exibida no cronograma de pagamentos, ausente dos resultados de busca, porque ela 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 é um 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 fica implícito, cada nova funcionalidade que "lê o saldo" erra de objeto e devolve um número ligeiramente diferente, conforme os movimentos que ela lembrou de incluir. Três telas, três saldos.

Uma regra aplicada só de um lado. O limite 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 eu falava 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 escopo da filial dela, uma lista de exceções. Nenhum lugar do produto diz "veja como uma permissão é calculada". Cada evolução redescobre isso por conta própria.

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 campo. Quatro vocabulários para o objeto mais central do produto.

Uma palavra que os clientes usam sem parar e o produto ignora. Em 261 registros de entrevistas, uma noção volta 79 vezes, outra 29. Nem uma nem outra existe no produto, sob nome nenhum. Não são diferenças de vocabulário, são faltas de concepção — e elas só aparecem comparando 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 prova e a consequência, não com uma intuição.

Um vocabulário de cliente, com as frequências. Contando as palavras em 261 registros de entrevistas e 365 tickets de suporte, você obtém para cada objeto do produto os termos realmente usados e o peso deles. Quem fala com o cliente passa a saber que palavra usar. Um termo volta 168 vezes para designar um escopo que o produto chama de outra forma; outro, 141 vezes para o objeto central.

E esses dois corpora 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 retrato da situação das traduções. O glossário multilíngue cobre apenas 15 dos 52 objetos. Entre os ausentes, dois são exibidos ao usuário em todos os idiomas: não existe tradução de referência para eles. E dos dezenove idiomas do glossário, só dois foram revisados.

Quanto custa, e o que o método ainda não diz

O custo

Menos de seis horas. É o tempo que o conjunto levou: as 52 fichas, as 250 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 em uma ordem de grandeza — e esse erro de estimativa talvez seja a verdadeira razão pela qual ninguém tinha feito esse trabalho antes: você acha que está fora de alcance, então não começa.

Três reservas sobre esse número, para que ele siga honesto. É uma medição em um produto, uma vez, não uma média. As fontes já estavam reunidas e indexadas localmente; o tempo de preparação 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 é justamente 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 em um escopo serve imediatamente a todas as áreas que trabalham nesse escopo. Um modelo de referência pela metade em cinco escopos não serve a ninguém.

A manutenção

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

A versão de referência serve de cursor: com um único comando, ela dá a lista exata do que se moveu no produto desde a última atualização — portanto a lista do que ainda falta registrar.

Cada ficha tem um diário onde a gente acrescenta 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 conta essa história: a fusão de dois objetos que a gente achava 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 de cabo a rabo, a gente não modifica a ficha dele: cria uma nova, e a antiga fica. Ela descreve o que o produto foi, e continua necessária para interpretar os dados e as trocas anteriores à mudança.

O que eu decidi não fazer

• Nenhuma reconstituição da história passada do produto.
• Escopo fechado nas exportações de dados, que são visões derivadas do produto e não o produto em si.
• Nenhum ferramental erudito enquanto nenhum uso exigir.

O que o método ainda não diz

• Até onde levar o rigor do formato. Isso 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 no meio do caminho.
• Quem revisa uma ficha, e segundo quais critérios, antes de ela entrar no modelo de referência.
• Em que ritmo atualizar o ponto de partida, e portanto recuperar o que se moveu desde então.

Um documento de método que se diz completo está mentindo. Este tem uma seção "o que ele ainda não diz", e ela encolhe conforme as questões vão sendo decididas.

Conclusão: o critério de parada é a verdadeira entrega

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.

Isso não vale só para ontologias. Vale para uma auditoria, uma migração, uma revisão de segurança, uma limpeza de dívida técnica. Cada vez que um trabalho termina com "olhei tudo", a pergunta a fazer é: tudo, ou seja? Você tem a lista?

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

Resta a parte mais interessante, e ela não está feita: os desvios. Todos esperam ser investigados — os bugs candidatos primeiro, depois aqueles que uma demanda de cliente já sustenta, depois as faltas, depois a dívida de design. Isso já não é descrição, é decisão de produto.

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

Apêndice A — Como é uma ficha

Este apêndice é a parte mais técnica do artigo; você pode 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 moram 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 do 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 item
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 "[[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, na versão de referência
---

# Sales Order

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

## Vínculos

- *placed-by* → [[Customer]] (um só)
- *contains* → [[Order Line]] (pelo menos um)
- 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 apareçam na visão em rede. Todo o resto existe em um único lugar.

Três critérios de qualidade, aplicá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á ligado a"; o vocabulário é multilíngue e carrega as palavras usadas pelos clientes.

Apêndice B — A grade dos desvios

O que se anota para cada desvio:

As cinco naturezas:

O que acontece quando o desvio desaparece. A gente marca como resolvido, e ele fica 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 limite de segurança. Um desvio descreve uma divergência estrutural, não um incidente. Uma linha, um link para o ticket. As capturas de tela, os passos de reprodução e o detalhe ficam na ferramenta de acompanhamento. Uma ficha não é um gerenciador de bugs.

Apêndice C — Os ângulos de enumeração

Passar por todos, e confrontar 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 de negócio, ou parte técnica. Nunca por omissão.
3. Dois corpora 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, em ordem decrescente de rendimento:

1. Os nomes das mensagens de erro técnicas. Nas partes menos organizadas do código, é muitas vezes a única fonte — e ela é lida sem saber programar.
2. As verificações feitas no início de uma operação, antes de qualquer coisa ser 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 diferença é um defeito.
4. As validações de preenchimento nas telas — a parte mais 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.