---
title: "Apresentando a cobertura de compreensão"
url: https://tiarebalbi.com/pt-br/blog/introducing-comprehension-coverage
markdown: https://tiarebalbi.com/pt-br/blog/introducing-comprehension-coverage.md
description: "Autoria deixou de implicar compreensão. Cobertura de compreensão: um mapa por módulo, com decaimento, do que seus humanos ainda entendem — e por quê."
author: "Tiarê Balbi Bonamini"
locale: pt-br
published: 2026-09-21
updated: 2026-09-21
category: "AI"
tags: ["ai-development", "comprehension-coverage", "engineering-practices", "architecture", "agents", "concept"]
translation: https://tiarebalbi.com/en/blog/introducing-comprehension-coverage
---
# 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_](https://gwern.net/doc/cs/algorithm/1985-naur.pdf), 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](https://www.tiarebalbi.com/pt-br/blog/spectator-trap-staying-in-control-ai-development), 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)](https://ieeexplore.ieee.org/document/7997917) 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.](https://homepages.dcc.ufmg.br/~mtov/pub/2016-icpc.pdf) 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](https://arxiv.org/abs/2512.05551) 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_](https://arxiv.org/abs/2606.20882), 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](https://arxiv.org/abs/2507.08160) 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](https://www.tiarebalbi.com/pt-br/blog/review-bottleneck-unbundling-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](https://www.tiarebalbi.com/pt-br/blog/fitness-functions-control-plane-agentic-coding). 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_](https://mironyx.dev/blog/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](https://github.com/tiarebalbi/comprehension-coverage) — 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?