<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.
o prompt do operador
como se trabalha aqui
arc42 · C4 · BDD · ADR
PRD · design · specs · tasks
o código que já está lá
lint e formatação
tipos e contratos
os *.test.js do tester
o pre-commit
a mensagem do commit
os workflows do GitHub
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
11 ofícios, cada um na sua janela
52 procedimentos
47 defeitos proibidos
khaby-lame.sh, antes do Write
/craft /ship /audit /sync /extend
ferramentas externas
o código — onde a saída vira arquivo, com o teste ao lado
Fontes
o que ela lê antes de escrever
Claude Code
o modelo — prevê o próximo token a partir da janela
Recursos · .claude/
configuram o modelo
src/[contexto]/[container]/[componente]/
onde a saída vira arquivo, com o teste ao lado
Validadores
o veredito volta para o modelo
// 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.
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.
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.
1º documento
10º documento
20º documento
// 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
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.
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.
a tarefa com escopo fechado
decide o próximo passo
lê um arquivo, roda um teste
lê o resultado
o resultado, não a leitura
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.
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%.
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
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.
| Passo do cálculo | O que isso causa | A resposta do ecossistema |
|---|---|---|
| 1 · A janela é finita e degrada | Contexto cheio perde o que importa | .claude/: ofícios com escopo fechado, cada um na sua janela |
| 2 · Tokeniza o texto | O que não tem nome fica invisível | src/ com nomes de negócio, uma capacidade por pasta |
| 3 · Vetoriza o sentido | Sinônimos espalham o significado | specs/ com um vocabulário só, do BDD ao código |
| 4 · Atenção sobre tudo | Texto irrelevante dilui o relevante | changes/: tasks.md atômico, só o que a tarefa pede |
| 5 · Probabilidade | Sem contexto, o provável não é o certo | specs/ e changes/ tornam o certo o mais provável |
| 6 · Escolhe e repete | Erro plausível se acumula e passa | verify 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.
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
o trabalho de ontem
specs/ e changes/
o engenheiro agêntico
Agora o harness faz sentido
Veja como .claude/ organiza ofícios, regras e contexto em volta dessas limitações.