// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

// o que a IA entrega
export function createSession(user: User) {
  const token = sign(user.id, SECRET)
  cache.set(user.id, hydrate(user, token))
  return redirect(user.role === "admin" ? "/ops" : "/app")
}

// o que o desenvolvedor precisa ver
// createSession → sign → cache → hydrate → redirect
// padrão: auth facade + role dispatch
// risco: SECRET no escopo, cache sem TTL, redirect sem guard

readit · estudo de fim de semana →

O código existe.
A leitura, não.

Na era da IA, padrões de arquitetura, de função e de método passam sem ninguém olhar. Este estudo embasa duas frentes: um agente que mapeia o código — e um software que ensina a lê-lo.

Ler o estudo As duas frentes ↓

readit Desktop

session.ts

O que createSession está fazendo — e qual padrão isso é?

Leu session.ts · 6s

Padrão: auth facade + role dispatch. O arquivo esconde o fluxo. O mapa não.

1export function createSession(user: User) {
2  const token = sign(user.id, SECRET)
3  cache.set(user.id, hydrate(user, token))
4  return redirect(
5    user.role === "admin" ? "/ops" : "/app"
6  )
7}

Qual o próximo beacon?

Agent

Mapa do padrão

readit CLI

$ readit explain createSession
padrão   auth facade + role dispatch
arestas  4 EXTRACTED · 1 INFERRED
risco    SECRET no escopo

01 Problema

Escrever ficou barato. Entender, não.

Xia, Bao, Lo e Hassan mediram 3.148 horas de trabalho real: desenvolvedores passam cerca de 58% do tempo tentando compreender o que o código faz. A IA não removeu essa conta — ela inverteu o gargalo. O código agora cresce mais rápido do que o modelo mental do time.

Tempo em compreensão

58%

Xia et al., 2017 · 78 devs, 3.148 horas

Padrões de dívida

Ahmad, 2026 · aceitação, contexto, atrofia, bypass

Fluxo do especialista

↓

CodeMap, 2025 · global → estrutura → lógica → local

A IA gera. O time não lê.

Vaithilingam et al. (2022) já mostravam o trade-off: Copilot acelera a entrega e reduz a compreensão do que foi gerado. O estudo com Copilot em código brownfield (2025) confirma: sobe o desempenho da tarefa, cai a capacidade de engenharia reversa no nível de átomo e de função.

O fluxo certo é global → local.

Auditores profissionais não começam no arquivo. CodeMap (2025) descreve a sequência: panorama do projeto, estrutura do codebase, lógica de negócio, só então funções e variáveis. LLMs falham em preservar relações entre esses níveis — e o desenvolvedor que aceita o snippet herda o buraco.

Perguntar ao chat não é ler o fluxo.

Trailblazer (UIST 2025) mostra que respostas de IA sem traço de programa deixam o desenvolvedor desorientado. Traces anotados — o caminho real entre símbolos — melhoram tempo e familiaridade. O mapa importa mais do que o parágrafo.

readit Field study

Xia et al. · 3.148 horas

Onde o tempo dos profissionais realmente vai.

Compreensão
ler, navegar, perguntar
58%
Edição
escrever e ajustar
24%
Outros
review, build, espera
18%

o gargalo inverteu

A IA barateou a escrita. A conta de leitura — 58% — ficou intacta, e agora cresce mais rápido que o mapa do time.

$ readit audit --hours
58%  comprehension
78   profissionais

02 Padrões

Um padrão é um chunk. Não um template.

Leitura fluente de código não é decodificar sintaxe linha a linha. É reconhecer formas. A psicologia da expertise (Chase & Simon; chunking) e a pesquisa clássica de program comprehension (Brooks, Pennington, Soloway) convergem: o especialista vê beacons — sinais que ativam um esquema mental já nomeado.

Camada	Exemplo	Como ler
Arquitetura	Clean / hexagonal / CQRS	Quem pode falar com quem. A seta importa mais que o arquivo.
Função	Facade, mapper, guard, policy	Qual o contrato: entrada, efeito, saída. O nome deveria mentir pouco.
Método	early-return, reduce, hydrate	O idioma local. Se o idioma é estranho, o chunk não dispara.
Fluxo	auth → session → redirect	A história entre arquivos. É aqui que a IA mais esconde o caminho.

readit Catalog

Beacon ativo

role dispatch

O chunk dispara quando o olho vê o branch por papel — não quando lê o `if`. Nomeie, ou a dívida já começou.

05 user.role === "admin" ? "/ops" : "/app"

03 Leitura

Especialistas leem de cima para baixo.

Seniors gastam menos tempo em compreensão não porque leem mais rápido — leem com um mapa. O júnior navega o arquivo. O sênior navega o grafo. A IA, hoje, entrega o arquivo.

1
Panorama
O que este sistema é, e o que ele não é.
2
Estrutura
Módulos, fronteiras, direções de dependência.
3
Lógica
Regras de negócio e invariantes que o código protege.
4
Local
Função, variável, branch — só depois do contexto.

readit Trace

Caminho anotado

Auth
EXTRACTED
sign
EXTRACTED
cache
INFERRED
hydrate
EXTRACTED
redirect
AMBIGUOUS

04 Dívida

A dívida não está no código. Está na cabeça.

Ahmad (EASE 2026) formaliza comprehension debt: o gap entre o que o time precisa entender para mudar o sistema e o que de fato entende. Diferente de technical debt, não mora no artefato. Mora no modelo mental coletivo. Testes verdes não a detectam.

Acumula dívida

Aceleração

A IA é provedora de solução. O output entra com pouca interrogação. A carga germane — a que constrói schema — some. Sweller (1994): se a ferramenta faz o trabalho pesado da schema, o aprendiz não a forma.

Paga a dívida

Exploração

A IA é andaime. Pedem-se explicações, reescreve-se o gerado, verifica-se contra o codebase. A carga germane sobe. O código continua rápido — e o mapa também cresce.

P1 · Black-box acceptance

Commit sem modelo mental. Integra. Quebra no sprint seguinte, na hora de mudar.

P2 · Context-mismatch

A IA não viu o sistema. O snippet é localmente certo e globalmente estranho.

P3 · Atrofia por dependência

Menos leitura, menos schema. A muleta vira o único músculo.

P4 · Verification bypass

Quem mais precisa verificar é quem menos consegue. O erro só aparece em runtime.

05 Frente A

Um Graphify para o Cursor. E para o Claude.

A primeira frente é um skill de agente: instalar, apontar o repo, obter um grafo. Não um chat que resume. Um mapa que preserva arestas — EXTRACTED, INFERRED, AMBIGUOUS — e comunidades que o olho não pediria.

AST + semântica

Imports e calls saem da árvore. Padrões, fluxos e similaridade saem do modelo. Os dois se fundem.

Comunidades e god nodes

O que está no centro. O que atravessa módulos. O caminho mais curto entre Auth e Database.

Onde o desenvolvedor trabalha

Cursor, Claude Code, Codex. O grafo entra no contexto do agente — não numa aba à parte.

Cursor

# skill readit
npx readit init --cursor

Claude

# plugin readit
/plugin install readit

06 Frente B

Fluência de leitura é um treino. Não um plugin.

A segunda frente é software de ensino. O objetivo não é gerar mais código. É fazer o desenvolvedor reconhecer o padrão no código que a IA já gerou — até a leitura ficar automática, como um idioma.

Catálogo vivo

Arquitetura, função, método e fluxo — nomeados, com beacons e contraexemplos do próprio repo.

Exemplos trabalhados

O mesmo trecho em três velocidades: o que a IA escreveu, o padrão que ela usou, o risco que ela escondeu.

Modo compreensão

A literatura pede isso explicitamente: não só gerar, decompor em segmentos semânticos e obrigar a pausa. Rewrite-before-commit como prática, não como conselho.

07 Escada

Pare no primeiro degrau que segura.

Ler código gerado por IA é uma escada. O erro é começar no arquivo. O acerto é subir só até o degrau que já responde a pergunta.

01
Que pergunta eu estou fazendo?
sem pergunta: não abrir o arquivo
02
Qual o panorama deste módulo?
sem mapa: não descer
03
Que padrão de arquitetura está em jogo?
nomear. se não nomeia, o chunk não disparou
04
Qual o fluxo entre símbolos?
aresta antes de linha
05
Onde está o beacon?
o sinal que um sênior veria em 4 segundos
06
Consigo reescrever em uma frase?
se não, a dívida já começou
07
Só então: o local.
função, branch, nome. mais um teste se há lógica

08 Fontes

O que lemos para não inventar.

Xia, Bao, Lo, Xing, Hassan, Li (2017)
Measuring Program Comprehension: A Large-Scale Field Study with Professionals
≈58% do tempo em compreensão · 78 profissionais · 3.148 horas
Vaithilingam, Zhang, Glassman (CHI 2022)
Expectation vs. Experience: Evaluating the Usability of Code Generation Tools
Mais rápido. Menos compreensão do código gerado.
Ahmad (EASE 2026)
Comprehension Debt in GenAI-Assisted Software Engineering Projects
CD ≠ TD. Quatro padrões de acúmulo. Uma orientação que mitiga.
Huang et al. (2025)
Understanding Codebase like a Professional! Human–AI Collaboration for Code Comprehension
Fluxo do auditor: global → estrutura → lógica → local. CodeMap.
Trailblazer (UIST 2025)
Answering Developer Questions with Annotated Agent-Discovered Program Traces
Trace anotado vence resposta de chat. O fluxo é o mapa.
Sweller (1994) · Brooks · Pennington · Soloway
Carga cognitiva, beacons e modelos mentais de programa
Schema se constrói com esforço germane. Padrão é chunk nomeado.
Gorman (2025)
Comprehension Debt
Quando o time produz código mais rápido do que consegue entender.
Graphify
Grafo de conhecimento sobre código, docs e papers
AST + semântica, comunidades, god nodes, arestas honestas.

O código existe.A leitura, não.

Escrever ficou barato. Entender, não.

A IA gera. O time não lê.

O fluxo certo é global → local.

Perguntar ao chat não é ler o fluxo.

Um padrão é um chunk. Não um template.

Especialistas leem de cima para baixo.

Panorama

Estrutura

Lógica

Local

A dívida não está no código. Está na cabeça.

Aceleração

Exploração

Um Graphify para o Cursor. E para o Claude.

AST + semântica

Comunidades e god nodes

Onde o desenvolvedor trabalha

Fluência de leitura é um treino. Não um plugin.

Catálogo vivo

Exemplos trabalhados

Modo compreensão

Pare no primeiro degrau que segura.

O que lemos para não inventar.

Measuring Program Comprehension: A Large-Scale Field Study with Professionals

Expectation vs. Experience: Evaluating the Usability of Code Generation Tools

Comprehension Debt in GenAI-Assisted Software Engineering Projects

Understanding Codebase like a Professional! Human–AI Collaboration for Code Comprehension

Answering Developer Questions with Annotated Agent-Discovered Program Traces

Carga cognitiva, beacons e modelos mentais de programa

Comprehension Debt

Grafo de conhecimento sobre código, docs e papers

O código existe.
A leitura, não.