<omh-como-a-ia-funciona />

Para entender o porquê de tudo isso, entenda como a IA funciona.

Um modelo de linguagem não pensa como uma pessoa nem lembra de você. Ele prevê a próxima palavra, uma de cada vez, a partir do que está na janela de contexto. Harness, specs e estrutura de pastas existem por causa disso.

// Onde você está no harness

Esta página explica o centro: o modelo

Tudo o que vem a seguir é sobre o cartão escuro — como ele calcula. As outras páginas tratam do que fica em volta.

Validadores
o que confere a saída
Fontes
o que ela lê antes de escrever
Claude Code
o modelo e o que o configura
pedido
o prompt do operador
CLAUDE.md
como se trabalha aqui
specs/
arc42 · C4 · BDD · ADR
changes/
PRD · design · specs · tasks
src/ existente
o código que já está lá
Biome
lint e formatação
check
tipos e contratos
bun test
os *.test.js do tester
husky + lint-staged
o pre-commit
commitlint
a mensagem do commit
CI
os workflows do GitHub
Claude Code
o modelo — prevê o próximo token a partir da janela
tudo em volta decide o que entra na janela e o que sai dela
Recursos do Claude Code · em .claude/
agents
11 ofícios, cada um na sua janela
skills
52 procedimentos
rules
47 defeitos proibidos
hooks
khaby-lame.sh, antes do Write
commands
/craft /ship /audit /sync /extend
MCPs
ferramentas externas
src/[contexto]/[container]/[componente]/
o código — onde a saída vira arquivo, com o teste ao lado
lê
veredito
escreve
configuram
confere

Fontes

o que ela lê antes de escrever

pedidoCLAUDE.mdspecs/changes/src/ existente
↓ lê

Claude Code

o modelo — prevê o próximo token a partir da janela

Recursos · .claude/

configuram o modelo

agents · 11skills · 52rules · 47hookscommands · 5MCPs
↓ escreve

src/[contexto]/[container]/[componente]/

onde a saída vira arquivo, com o teste ao lado

↓ confere

Validadores

o veredito volta para o modelo

Biomecheckbun testhusky + lint-stagedcommitlintCI

// 01 · Ela prevê

A IA escolhe a próxima palavra mais provável

O texto é quebrado em pedaços chamados tokens. A cada passo, o modelo calcula a probabilidade de cada token possível vir a seguir, escolhe um, e repete — milhares de vezes por resposta.

Não existe uma resposta guardada em algum lugar. Existe a continuação mais provável para aquele contexto. Mude o contexto e muda o que é provável.

Por que isso importa

Com 80% de acerto por token, uma resposta de 1.000 tokens tem chance praticamente nula de sair inteira correta: 0,8 elevado a 1.000 ≈ 0. Cada pedaço de contexto certo aumenta a chance do token certo.

Qual é o próximo token?

Depois de function calcularFrete(pedido) { — probabilidades ilustrativas.

const
41%
if
27%
return
18%
let
9%
outros
5%

Exemplo ilustrativo do mecanismo de previsão.

// 02 · Ela só sabe o que está na janela

A janela de contexto é tudo o que ela vê

A janela é o texto que o modelo recebe de uma vez: instruções, arquivos lidos, a conversa. Ela é grande, mas finita — e não é lida por igual. Quanto mais cheia, menos confiável fica a leitura.

O que ocupa a janela numa tarefa

Distribuição ilustrativa.

CLAUDE.mdspecs/ lidoarquivos de src/conversalivre

Exemplo ilustrativo.

O meio da janela é onde a informação se perde

Acerto conforme a posição da resposta entre 20 documentos (GPT-3.5-Turbo). No meio, pior do que sem documento nenhum.

sem nenhum documento: 56,1%
75,8%
53,8%
63,2%

1º documento

10º documento

20º documento

Fonte: Liu et al., Lost in the Middle, 2023

Fonte: Chroma, Context Rot, 18 modelos, 2025

// 03 · Ela não lembra

Cada tarefa começa do zero

Uma pessoa paga o custo de entender o sistema uma vez, no onboarding, e acumula por anos. O agente paga a cada tarefa: começa sem memória, lê o que estiver no caminho e esquece ao terminar.

É a diferença entre um investimento e uma assinatura. Uma base que espalha o conhecimento cobra essa assinatura de cada tarefa, para sempre.

Dez tarefas seguidas

A pessoa acumula contexto; o agente redescobre a cada vez.

Pessoa

Agente

custo de descobrir o contextocontexto já acumulado

Representação ilustrativa.

// 04 · Ela completa lacunas

Alucinação é uma resposta plausível

Quando falta informação, o modelo não para: ele completa com o que é mais provável em geral. O resultado soa certo, compila, e está errado para o seu caso.

Por isso 66% dos devs recebem respostas “quase certas”. O problema raramente é o modelo — é o que faltou na janela.

Fonte: Stack Overflow Developer Survey 2025

Sem contexto

“aplique o cupom no pedido”
→ desconta do total com impostos,
  aceita cupom vencido

Com specs/ e changes/

cupons.feature + tasks.md
→ desconta do subtotal, antes do frete,
  recusa vencido e explica o motivo

// 05 · Um agente é um loop

Pensar, agir, observar — e repetir

Um agente é o mesmo modelo dentro de um ciclo: ele decide um passo, usa uma ferramenta, lê o resultado e decide o próximo. É poderoso, e cada volta consome a mesma janela finita.

Objetivo
a tarefa com escopo fechado
Pensa
decide o próximo passo
Age
lê um arquivo, roda um teste
Observa
lê o resultado
Cumpriu?
Entrega
o resultado, não a leitura
sim
não
volta a pensar — cada volta ocupa mais da mesma janela finita

Contexto deve ser tratado como um recurso finito, com retorno marginal decrescente.

Anthropic Engineering, Effective context engineering for AI agents (tradução livre)

// 06 · Do cálculo à estrutura

Cada passo do cálculo explica uma pasta

Juntando tudo: o modelo repete seis passos a cada token. Cada passo tem um jeito de errar — e cada pasta do ecossistema existe para fechar um deles. Não é preferência de organização; é engenharia em volta do cálculo.

Workflow · do prompt à saída
Um pedido real atravessando os seis passos que o modelo repete a cada token — e, embaixo de cada um, o risco e a pasta que existe por causa dele.
A conversao que você vê
O cálculorepetido a cada token
O riscosem estrutura, o cálculo erra assim
A respostaa pasta que existe por causa dele
Prompt
“aplique o cupom FRETE10 no pedido”
Saída
return subtotal - desconto(cupom)
Você vê uma linha de código.
Por baixo, o cálculo rodou uma vez
para cada token — cerca de 8 só nela.
1 · Janela
tudo o que ela lê de uma vezprompt + specs/ + tasks.md
2 · Tokeniza
o texto vira pedaçosaplique·o·cupom·FRETE·10
3 · Vetoriza
cada token vira números com sentidocupom → [0,12 −0,80 0,33 …]
4 · Atenção
cada token pesa todos os outros“cupom” → “subtotal”
5 · Probabilidade
uma nota para cada token possívelsubtotal 62%
total 21%
preco 9%
6 · Escolhe um
o mais provável — não o certo→ subtotal
Janela cheia degrada: o que importa se perde no meio
Nome genérico (utils/, helpers/) não carrega sentido
Sinônimos espalham o sentido: “cupom”, “voucher”, “desconto”
Atenção se dilui: o custo cresce com o quadrado do texto
Sem a regra na janela, vence o padrão genérico: total
Erro composto: 80% de acerto por token, 0,8¹⁰⁰⁰ ≈ 0
.claude/
CLAUDE.md curto, skills sob demanda, um ofício por janela
src/
cupons/ e aplicar-cupom.ts: os mesmos tokens do pedido
specs/
um vocabulário só em BDD, C4 e código: palavras iguais, vetores próximos
changes/
tasks.md atômico: pouco texto, tudo relevante para a tarefa
specs/ + changes/
“desconto sobre o subtotal” escrito: a probabilidade vai para o certo
verify
reviewer, tester e 4 checks: o erro de um token não chega ao merge
o token escolhido entra na janela e o cálculo recomeça — até a resposta terminar
entra
sai
risco
evita
tokens + vetores

Nome é sinal, não estética

O pedido “aplique o cupom” e a pasta cupons/ viram os mesmos tokens e vetores próximos. Com nomes genéricos, a dependência certa cobre 76% do que importa; com estrutura navegável, 99%.

Fonte: Paipuru, CodeCompass, arXiv 2026

atenção

Menos texto, mais acerto

Cada token compara-se com todos os outros: o custo cresce com o quadrado da janela e a atenção se dilui. A informação no meio de uma janela cheia rende menos do que nenhuma informação.

Fonte: Vaswani et al., 2017

Fonte: Liu et al., Lost in the Middle, 2023

probabilidade + escolha

O certo precisa ser o provável

O modelo escolhe o provável. A regra escrita em specs/ e changes/ desloca a probabilidade para o certo — e o verify existe porque, em mil tokens, algum ainda vai errar.

Fonte: Chroma, Context Rot, 18 modelos, 2025

Passo do cálculoO que isso causaA resposta do ecossistema
1 · A janela é finita e degradaContexto cheio perde o que importa.claude/: ofícios com escopo fechado, cada um na sua janela
2 · Tokeniza o textoO que não tem nome fica invisívelsrc/ com nomes de negócio, uma capacidade por pasta
3 · Vetoriza o sentidoSinônimos espalham o significadospecs/ com um vocabulário só, do BDD ao código
4 · Atenção sobre tudoTexto irrelevante dilui o relevantechanges/: tasks.md atômico, só o que a tarefa pede
5 · ProbabilidadeSem contexto, o provável não é o certospecs/ e changes/ tornam o certo o mais provável
6 · Escolhe e repeteErro plausível se acumula e passaverify com reviewer, tester e os quatro checks

// A pergunta que ninguém faz em voz alta

A IA vai tomar o meu emprego?

Ela troca a tarefa, não o engenheiro. Tudo o que você leu acima aponta para o mesmo lugar: a IA precisa de alguém que decida o quê e por quê, especifique o suficiente para o provável virar o certo, e verifique o que ela entregou.

Quem entende como ela funciona deixa de competir com ela e passa a dirigi-la.

64%

dos desenvolvedores não veem a IA como ameaça ao emprego.

Fonte: Stack Overflow, 2025

75%

ainda procuram uma pessoa quando não confiam na resposta da IA.

Fonte: Stack Overflow, 2025

A IA faz bem

  • Escrever a partir de uma especificação
  • Ler muito código rápido
  • Repetir padrões conhecidos
  • Gerar testes e variações

Continua com você

  • Decidir o que construir e por quê
  • Escolher entre alternativas
  • Especificar o que é “certo”
  • Verificar e responder por produção
Quem digita
o trabalho de ontem
Quem especifica
specs/ e changes/
Quem decide e verifica
o engenheiro agêntico

Agora o harness faz sentido

Veja como .claude/ organiza ofícios, regras e contexto em volta dessas limitações.

Ver o harness