Apresentando a cobertura de compreensão

Toda base de código carrega dois mapas. O primeiro mostra o que a suíte de testes verifica — medido até a segunda casa decimal, acompanhado no CI, discutido em toda organização de engenharia do planeta. O segundo mostra o que os humanos ainda entendem — e ninguém mede isso.

Por vinte anos, ninguém precisou medir. O segundo mapa vinha de graça com o controle de versão: quem escreveu o código entendia o código, então o git blame funcionava também como um mapa de compreensão. Esse pressuposto sustentou silenciosamente todas as métricas de conhecimento que a área já construiu. E, na era dos agentes, ele é simplesmente falso. A pessoa que "escreveu" três mil linhas no mês passado pode entender todas elas, algumas delas ou nenhuma.

Então aqui está o conceito que este post apresenta, aquele para o qual os últimos seis posts desta série vinham caminhando: cobertura de compreensão — uma medida por módulo, por pessoa, baseada em evidências, de quais humanos ainda entendem quais partes de um sistema, decaindo ao longo do tempo a menos que novas evidências apareçam. Cobertura de testes para o único componente que não pode ser regenerado: a compreensão que existe na cabeça do seu time.

Uma teoria, não um texto

Isso começou como leitura de fundo para uma ferramenta que estou construindo, e a leitura foi puxando o fio mais para trás do que eu esperava — até 1985. O ensaio de Peter Naur, Programming as Theory Building, argumenta que um programa não é primariamente seu texto; é a teoria mantida pelas pessoas que o construíram — a capacidade de explicar por que ele tem essa forma, de mapear o mundo sobre o código, de enxergar quais mudanças se encaixam e quais brigam com o design. O texto é um subproduto. E Naur é brutal sobre o que acontece quando as pessoas vão embora: um programa morre, escreve ele, "quando o time de programadores que possui sua teoria é dissolvido." Reconstruir a teoria apenas a partir da documentação, argumenta ele, é estritamente impossível — seu conselho para um programa revivido sem nenhum detentor da teoria sobrevivente é descartar o texto e resolver o problema do zero.

Ler Naur me fez procurar o lado empírico: com que velocidade a teoria de fato apodrece? O melhor estudo que encontrei é o "Do You Remember This Source Code?", de Krüger et al. (ICSE 2018), que mediu a rapidez com que desenvolvedores de código aberto esquecem o próprio trabalho: metade dos seus próprios arquivos em 30 dias, na mediana. E o detalhe que me fez parar: o que previa retenção era fazer — o número de commits próprios teve correlação forte com lembrar (ρ≈0,67) — enquanto meramente acompanhar as mudanças de outras pessoas em um arquivo não previa praticamente nada (ρ≈0,04, não significativo). Ver o código mudar não constrói a teoria. Se esse achado soa familiar, é a armadilha do espectador, medida em laboratório sete anos antes de os agentes a transformarem em estilo de vida.

Por que a teoria importa economicamente? Porque compreensão é a maior parte do trabalho. Xia et al. (IEEE TSE, 2018) instrumentaram desenvolvedores profissionais em atividade e descobriram que cerca de 58% do tempo de desenvolvimento vai para compreensão de programa. Ler é o trabalho. A teoria é o que torna a leitura rápida.

O proxy que acabou de quebrar

Como a teoria em si é invisível, a área passou duas décadas medindo sua sombra: autoria. Os modelos de degree-of-knowledge de Fritz e Murphy pontuavam a familiaridade desenvolvedor–arquivo a partir de quem criou e alterou o quê. Os algoritmos de truck factor foram construídos sobre isso — Avelino et al. encontraram 65% dos sistemas do GitHub estudados apoiados em dois ou menos desenvolvedores-chave. Os mapas de conhecimento do CodeScene industrializaram o mesmo sinal. Até o CODEOWNERS do GitHub, que muitos times tratam como registro de conhecimento, na verdade é outra coisa: um estudo recente dos repositórios mais estrelados do GitHub descobriu que 79% dos owners individuais listados não estavam entre os cem maiores committers do próprio repositório — é uma camada de roteamento de review, uma declaração de responsabilidade, não evidência de compreensão.

Tudo isso — cada métrica dessa família — repousa sobre um axioma: escrever código é evidência de entendê-lo. Esse axioma é o que os agentes apagaram. Um preprint de junho de 2026 do pesquisador independente Brett Wheeler, The Substrate Collapse, faz o argumento com uma precisão que não vi em outro lugar: uma vez que o código chega por meio de um agente, a pegada de autoria passa a ser compatível com compreensão total, parcial ou nenhuma — de modo que nenhuma reponderação dos dados de autoria recupera a inferência, porque a falha é estrutural, não um problema de calibração. E isso não é deriva hipotética: um estudo de 2025 que simulou 50% de envolvimento de IA generativa encontrou 73% dos valores de truck factor alterados nos projetos analisados. A era da medição por sombra acabou; as ferramentas é que ainda não perceberam.

Quero ser cuidadoso sobre o que o artigo de Wheeler é e o que não é: é um preprint de autor único, sem citações até onde consigo verificar, e que deliberadamente não propõe nada — ele diagnostica, crava uma previsão falseável e para. Mas sua declaração final sobre a lacuna é a frase que transformou minha leitura em projeto. O que falta, escreve ele, é o instrumento de compreensão "na escala de um sistema inteiro e de um time inteiro, contínuo e não intrusivo". Isso é uma especificação. Alguém deveria construir para ela.

O conceito: cobertura de compreensão

Cobertura de compreensão é minha tentativa de atender a essa especificação, e ela se apoia em cinco compromissos de design.

Evidência, não autoria. Uma linha do mapa só é conquistada por atos que plausivelmente constroem ou demonstram teoria: escrever à mão, revisar em profundidade (não carimbar — a distinção de que tratava o post sobre desagregar o code review), diagnosticar um incidente naquele módulo, escrever o ADR, percorrer o código de novo de forma explícita. Fazer merge do diff de um agente sem ler não conquista nada. Assistir tokens em streaming não conquista nada — o ρ≈0,04 de Krüger diz isso empiricamente.

Decaimento por churn, não por calendário. Krüger mediu o esquecimento contra o tempo, e o tempo importa — metade da familiaridade se vai em semanas, não em anos. Mas o relógio mais preciso para uma base de código é a mudança: a compreensão de um módulo reescrito duas vezes desde seu último contato real está velha independentemente do calendário, e a compreensão de um módulo congelado sobrevive a longos períodos de silêncio. Então a pontuação decai em função do churn desde a evidência, com o decaimento por tempo de relógio servindo de piso. Essa é a decisão de design que eu mais quero ver contestada, porque vai além do que a literatura sobre esquecimento mediu diretamente.

Por módulo, mapeado à arquitetura. A unidade é a mesma fronteira de módulo que seus testes de arquitetura já conhecem — as fatias da constituição de fitness functions. A saída é um mapa: para cada módulo, quais humanos detêm compreensão atual e evidenciada — e quais módulos estão no escuro: rodando em produção, mudando toda semana, entendidos por ninguém que esteja hoje no time. Módulos no escuro são os programas mortos de Naur cuja morte ninguém percebeu.

Contínuo, não pontual. Compreensão já foi medida antes — pesquisadores fazem isso com questionários (a Anthropic reporta um ensaio randomizado em que autores assistidos por IA acertaram 50% em quizzes de compreensão sobre o próprio código, contra 67% dos autores manuais). Mas um quiz é um instantâneo. Cobertura é um fluxo: cada merge, cada review e cada incidente atualiza o mapa, do mesmo jeito que cada commit atualiza a cobertura de testes.

Agregados por módulo são públicos; pontuações individuais não são. Este é um instrumento para localizar risco em um sistema, não para ranquear pessoas. No momento em que pontuações individuais de compreensão alimentarem uma avaliação de desempenho, Goodhart chega e a evidência seca — as pessoas vão farmar atestados do mesmo jeito que agentes farmam suítes de teste. A saída que circula é "o módulo X não tem ninguém que o compreenda atualmente", nunca "o desenvolvedor Y pontua 0,3".

O que já existe — e o que não existe

Apresentar um conceito obriga a procurar trabalho anterior, e a busca mudou este ensaio. Dívida de compreensão — o lado passivo deste balanço — foi nomeada em 2025 e popularizada este ano por Addy Osmani. Medição pontual de compreensão é um método de pesquisa estabelecido. E um praticante chegou mais perto do que qualquer outro: o Feature Comprehension Score de Leonid Sokolovskiy, publicado meses antes do artigo de Wheeler, gera perguntas de avaliação a partir dos próprios artefatos de uma feature no momento em que ela é entregue e pontua as respostas agregadas do time — um instrumento real, construído, de evidência de compreensão, com uma ferramenta por trás e uma postura que compartilho: "Isto não é um teste de desempenho individual de desenvolvedores."

Mas o FCS, na minha leitura, para deliberadamente onde a cobertura começa: ele dispara uma vez por feature em vez de continuamente sobre a base de código, agrega em um único número de time, não acompanha decaimento e não mapeia nada sobre o código em si. Então a afirmação que vou defender é a estrita, com a ressalva exata do alcance da minha busca: até setembro de 2026, não consigo encontrar nenhum mapa contínuo, por módulo e por pessoa, de evidências de compreensão — nada que faça pela compreensão o que o git blame fez pela autoria, agora que as duas se separaram. Se alguém já construiu isso, quero saber mais do que quero ser o primeiro.

O que o mapa torna possível

No momento em que o mapa existe, ele se compõe com tudo o que esta série construiu. Um módulo no escuro vira uma regra de roteamento para o control plane: mudanças de agente nele exigem um compreendedor designado no review, ou são recusadas por completo. Um limite de cobertura vira uma fitness function — o lado humano do sistema conectado aos mesmos gates da constituição arquitetural, para que o build possa dizer o que nenhum dashboard hoje diz: esta mudança está ok, mas ninguém que entenda a coisa que ela toca olhou para ela. Onboarding deixa de ser feeling — designe o novo engenheiro para reevidenciar dois módulos no escuro e o mapa mostra as luzes se acendendo.

E o conceito herda um protocolo de validação que não precisou inventar. O preprint de Wheeler crava sua previsão falseável exatamente na existência desse instrumento: sistemas com truck factors saudáveis baseados em autoria, mas com compreensão medida baixa, deveriam sofrer desproporcionalmente quando um incidente inédito exigir teoria real do sistema — e, se não sofrerem, tanto o argumento dele quanto este conceito perdem. Esse é um teste que qualquer time com dados de incidentes vai poder rodar um dia, e prefiro publicar o conceito com suas condições de refutação anexadas a fingir que ele chega provado.

Dois limites honestos, antes de fechar. Evidência de compreensão não é compreensão — um review profundo ainda pode passar longe do ponto, e qualquer tipo de evidência que eu pondere vira algo que pode ser encenado; o instrumento precisa do mesmo ceticismo sobre seus próprios gates que o post anterior exigiu das fitness functions. E a ética é estrutural, não decorativa: este mapa só se mantém honesto em uma cultura que trata um módulo no escuro como um risco de sistema a ser corrigido, nunca como acusação contra quem deixou que ele ficasse no escuro.

O próximo post desta série será o instrumento em si — uma pequena biblioteca open source que constrói esse mapa a partir do próprio histórico de um repositório: extração de evidências, decaimento indexado por churn, detecção de módulos no escuro e um modo de gate para CI. Está em andamento agora — a spec v0.1 e um protótipo de referência em Python já estão públicos — e escrever este ensaio primeiro foi deliberado: o conceito deve se sustentar ou cair pelo próprio argumento, antes que uma única linha da ferramenta enviese o julgamento. O Substrate Collapse terminou com uma especificação e um desafio. Esta é minha resposta à especificação. A ferramenta é minha resposta ao desafio — e o mapa do seu próprio sistema, quando você o renderizar pela primeira vez, vai responder a uma pergunta que talvez você prefira não fazer: quanto do que você está rodando alguém ainda entende?