Dívida cognitiva: quando o sistema está de pé e ninguém sabe explicar por quê

A dívida técnica mais cara é a regra que só uma pessoa sabe explicar. O teste de 40 minutos para achar essa concentração e o que fazer depois que ela aparece.

A regra mais cara da empresa costuma existir em dois lugares: nesse quadro e na cabeça de quem desenhou

A dívida técnica que trava o seu roadmap raramente está no arquivo feio. Ela está em quem consegue explicar aquele arquivo. E dá para medir isso hoje, em uns quarenta minutos: liste as dez regras de negócio que mexem em dinheiro na sua empresa (como o desconto é calculado, quando um pedido pode ser cancelado, o que libera o repasse ao parceiro) e escreva ao lado de cada uma o nome da pessoa que explica aquilo sem abrir o código. Se um nome aparecer em quatro ou mais linhas, ele custa mais caro que qualquer trecho mal escrito do seu repositório.

O preço aparece na agenda antes de aparecer no código. Toda tarefa que encosta naquela regra entra na fila de uma pessoa só. A estimativa do time passa a depender do calendário dela, a revisão que vale acontece quando ela tem tempo, e em janeiro, quando ela emenda as férias que foi juntando, o roadmap anda com o que sobra. Isso é dívida técnica na única definição que interessa a quem paga a folha, a mesma que eu uso quando trato tech debt como planilha de risco e não como queixa de dev: custo, prazo e receita.

Quantificar dívida técnica é a pergunta que a internet nunca respondeu direito

Com o agente, a alteração sai em quarenta minutos e ninguém novo aprendeu a regra

No Software Engineering Stack Exchange, a pergunta "How can I quantify the amount of technical debt that exists in a project?" já foi vista 20.433 vezes e recebeu 12 respostas. A vizinha dela, sobre como convencer a gestão a tratar dívida técnica, tem score 176 e perto de 19 mil visualizações. São duas perguntas com mais de uma década de idade, gente entrando nelas todo mês, e quase toda resposta oferecendo métrica de código: complexidade ciclomática, cobertura de teste, contagem de code smell.

Nenhuma dessas métricas explica por que o time não consegue mexer no cálculo de comissão sem chamar o Fulano.

A lista de nomes explica. Ela é grosseira, cabe num papel de reunião e qualquer pessoa não técnica entende o resultado sem tradução. Foi mais ou menos por isso que o shiftmag juntou 75 pontos e 72 comentários no Hacker News com um texto dizendo que dívida cognitiva é a nova dívida técnica. O fenômeno não é novo. O que faltava era nome para a parte que o analisador estático não enxerga.

O board limpo costuma ser o sintoma

Time só de sênior quase não documenta. Não é preguiça. É que ninguém nunca precisa explicar nada para ninguém: todo mundo já estava lá quando a regra foi escrita, a decisão saiu de uma conversa de dez minutos e o commit registrou o "como" sem uma linha do "porquê". A entrega sai na data, o board fica limpo, e o conhecimento mais caro da empresa vai se concentrando em três ou quatro cabeças que se entendem bem demais.

Nos sistemas que chegam aqui depois que o fornecedor anterior virou as costas, o que mais atrasa o começo nem é a query lenta encadeada ou o teste sem expect. É descobrir por que existe aquele if estranho no meio do serviço de pedidos. Aquele if é um contrato comercial de 2019 que alguém fechou por telefone. O código feio era a única documentação viva das regras da empresa, e ninguém lê documentação viva no ritmo em que o cliente cobra. É a mesma razão pela qual eu quase nunca aprovo reescrever um sistema do zero: a reescrita joga fora o registro sem ter feito cópia.

"Mas a gente tem documentação"

Meia página de porquê vale mais que o Confluence inteiro escrito no kickoff

Essa é a frase que aparece assim que eu levanto o assunto numa reunião. E quase sempre existe alguma coisa mesmo: um Confluence, um README, um diagrama bonito que alguém desenhou no kickoff. O documento descreve o que o sistema deveria fazer. O código descreve o que ele faz. Falta o terceiro, que é o motivo de os dois terem divergido.

Em obra isso tem nome. Existe o projeto, que é o que foi desenhado antes, e existe o as-built, o desenho de como a obra ficou depois de todas as decisões tomadas no canteiro, com a viga que mudou de posição porque o solo não colaborou. Quem não registra o as-built descobre o desvio quebrando parede, com o prédio já em uso. Software tem o mesmo problema, com um agravante: a parede é invisível, e a pessoa que sabe onde ela está foi para outra empresa.

Tem um teste honesto para isso. Pegue alguém que nunca mexeu naquela regra e peça uma alteração pequena, lendo apenas o documento. Se a pessoa terminar sem perguntar nada a ninguém, sua documentação é boa. Se ela abrir o Slack em vinte minutos, você tem um arquivo, não um documento. Já apliquei esse teste em projeto que herdei sem nada escrito, e ele rende mais do que qualquer auditoria, pelo mesmo motivo que fez as duas primeiras semanas num legado sem documentação serem de medição e não de código novo.

A IA aumentou a fila de código sem aumentar a fila de quem entende

O LeadDev publicou nesta mesma janela um texto sobre código de IA estar correto e ainda assim sair mais caro. Concordo, e o motivo tem tudo a ver com a sua lista de nomes.

Escrever código sempre foi a forma cara de aprender o sistema. Quem implementava a regra de comissão passava uns três dias dentro dela, xingava o histórico, e saía de lá sabendo explicar. Com um agente, a mesma alteração sai em quarenta minutos, funciona, passa no review e entra em produção. O repositório engorda, a superfície que precisa de manutenção cresce, e o número de cabeças capazes de explicar aquilo continua exatamente o mesmo. Seis meses assim e você tem bem mais sistema para sustentar com a mesma quantidade de gente que entende.

A ferramenta acelera quem já sabe o que quer, e acelera na mesma proporção quem não sabe. A diferença entre os dois casos aparece na primeira madrugada em que aquele trecho quebra.

Rodízio sai mais barato que wiki

Força-tarefa de documentação resolve pouco e envelhece rápido. O que muda a lista de nomes é rodízio, e ele cabe em três movimentos:

• Toda tarefa que encosta numa regra concentrada sai em dupla, com quem não sabe segurando o teclado e quem sabe apenas respondendo.
• O plantão roda entre todo mundo, com a pessoa que conhece o sistema na retaguarda e não na linha de frente, porque plantão é o único momento em que ninguém consegue adiar a pergunta.
• O dono da regra escreve meia página de porquê, com as decisões tomadas e o que foi descartado, e essa página só vale depois que outra pessoa conseguiu alterar a regra lendo apenas ela.

Isso custa. Uma dupla entrega mais devagar que um sênior sozinho, alguma coisa como 20% a 30% a mais nas primeiras semanas, e o time reclama. É o preço de tirar um nome de quatro linhas da sua lista. Quando a gente entra como squad sênior embarcado, isso faz parte da entrega desde o primeiro mês, porque o modelo de contratação que não prevê continuidade incentiva o contrário: concentrar o conhecimento, entregar rápido e ir embora com a chave no bolso.

Onde esse conselho é ruim

Se você tem três pessoas e ainda está procurando cliente, concentração é vantagem. Rodízio come a semana, dupla dobra o custo da tarefa, e o seu problema de verdade é descobrir se alguém paga pelo produto. Nesse estágio a dívida cognitiva é dívida barata, do mesmo jeito que a dívida técnica de MVP é barata enquanto o MVP ainda pode morrer. Sistema é vivo, e perseguir o sistema perfeito cedo demais custa mais que a dívida.

A conta vira de lado quando o faturamento passa a depender daquele sistema, ou quando o time cresce e a pessoa que sabe tudo vira gargalo de todo mundo. Isso acontece sem aviso. O primeiro sinal é uma reunião de planejamento em que o mesmo nome é citado em quase todos os cards, e ninguém acha isso estranho porque ela sempre resolve.

Marque as férias e veja o que acontece

Faça a lista das dez regras esta semana e guarde num lugar que você encontre depois. Olhe o calendário de férias do time. Se a pessoa que aparece em quatro linhas some por três semanas em janeiro, você vai receber de graça a medição mais honesta que existe da sua dívida cognitiva, que é o que o time entrega sem ela.

Quem aprova orçamento de engenharia quase nunca recebe um número desses. Você recebe uma vez por ano, e costuma jogar fora.