O Que Acontece Quando Você Aperta Enter?

É quinta de manhã. Tenho uma 1:1 com a Ana depois do almoço e não sei em que assunto tocar. Não faço ideia do que ela tem trabalhado e é tanta coisa na minha cabeça que esqueci o que discutimos da última vez. Ah, e a reunião é daqui a pouco, às 14h. Como eu tenho meu estagiário Claudinho à minha disposição, abro o Claude Code e digito: tenho 1:1 com a Ana, do que preciso saber?

Eu: `tenho 1:1 com a Ana, do que preciso saber?` 
  
  ◈ google_calendar > list_events("next 2 days")
    Hoje: Sprint Planning (10h), 1:1 com Ana (14h), Platform Sync (16h)
    Amanhã: Design Review (10h), Team Retro (15h)

  ■ Read notes/
  ⚡︎ use o obsidian-cli para buscar minhas anotações pessoais 

  ■ $ obsidian-cli search "Ana" --vault ~/notes --since 14d
    3 entradas: handoff do projeto, card bloqueado, feedback da retro

  ■ Read people/ana.md
    role: tech lead · últimas interações: discutimos apresentação do tech radar
    estilo: direta, valoriza pensamento sistêmico 

  ◈ slack > search_messages("Ana", last 7 days)
    5 mensagens: blocker no deploy, feedback de design review, follow-up da retro

  ▶ prep-1-on-1
    - O handoff ainda está em andamento — perguntar como andam as coisas
    - Ela sinalizou um card bloqueado há 4 dias — verificar se já foi resolvido
    - No feedback da retro, tem um action item sobre o trabalho em equipe — vale acompanhar

  ■ Write 1-1-prep-ana.md

  Prep escrito em 1-1-prep-ana.md. Quer que eu ajuste alguma coisa?

■ tool — ◈ mcp — ⚡︎ hook — ▶ skill

Digitei nove palavras. O agente acessou meu calendário, pesquisou minhas anotações, consultou o Slack, puxou um perfil e escreveu uma doc de preparação. Como?

Você enviou um prompt

Seu prompt são as nove palavras que você digitou: tenho 1:1 com a Ana, o que preciso saber?. Mas o que chegou não foram nove palavras. Foram tokens — pedaços de texto, às vezes uma palavra inteira, às vezes só parte de uma.¹ tenho é um token. 1:1 se divide em três: 1, :, 1. Ana é um token.

Esses tokens são o seu prompt. Mas eles não chegaram sozinhos.

Antes de você apertar enter

Um agente como o Claude Code tem duas partes: um modelo e um harness.² O modelo produz texto. O harness é o programa ao redor dele que executa ações e alimenta resultados de volta. Codex e Cursor funcionam da mesma forma: harnesses diferentes, mesma ideia.

flowchart LR
    subgraph Agent
        direction LR
        M["Model"] -- "produz tokens" --> H["Harness"]
        H -- "executa tools,
        retorna resultados" --> M
    end

flowchart LR
    subgraph Agent
        direction LR
        M["Model"] -- "produz tokens" --> H["Harness"]
        H -- "executa tools,
        retorna resultados" --> M
    end

Antes do seu prompt chegar, o harness já tinha empacotado mais de 8.000 tokens na janela de contexto — tudo que o modelo consegue ver de uma vez.³

• Instruções de comportamento que você nunca vê — o system prompt⁴
• Anotações de sessões anteriores — memória⁵
• O diretório do seu projeto e o estado do git⁶
• Descrições de cada tool que o modelo pode pedir pro harness executar — operações de arquivo, acesso ao terminal, busca⁷
• Integrações externas como seu calendário e Slack, conectadas via MCP⁸
• Workflows reutilizáveis chamados skills, carregados como descrições de uma linha⁹
• As convenções do seu projeto, carregadas de arquivos de instrução¹⁰
• Hooks — scripts que disparam antes ou depois de certas ações, rodando fora do modelo¹¹

Tudo isso é texto. Tudo isso são tokens. Os seus tokens chegaram junto com outros 8.000, e juntos se tornaram o mundo inteiro do modelo.

Entra texto, sai texto

Aqui está o que o modelo faz com tudo isso.

O modelo trabalha com um vocabulário — dezenas de milhares de tokens possíveis. Dada a sequência completa na janela de contexto, ele produz uma distribuição probabilística sobre esse vocabulário: cada próximo token possível recebe uma pontuação. O modelo sorteia um. Esse token é adicionado à sequência. O modelo roda de novo, agora condicionado na sequência mais longa. Sorteia o próximo. E o próximo. E o próximo.¹²

Esse é o mecanismo das LLMs, nada mais nada menos. O modelo não pensa. Não existe nenhum processo interno do tipo “a Ana teve um blocker no deploy essa semana, tenho que checar se foi resolvido antes da 1:1.” Ele produz o próximo token. Depois o próximo. E o próximo. Até a resposta estar completa e o harness assumir.

Cada token é moldado por todos os tokens que vieram antes dele. Quando aqueles 8.000 tokens incluem a descrição de uma tool chamada google_calendar e sua mensagem pergunta sobre uma 1:1 com a Ana, os próximos tokens provavelmente vão descrever uma chamada pra essa tool. Não com certeza — provavelmente. A descrição da tool é o que tornou a chamada certa provável. Mais um conjunto de tokens deslocando a distribuição.¹³

Esse processo é não-determinístico. Mesma entrada, resultado diferente toda vez. O modelo sorteia da distribuição — nem sempre seleciona o token com maior pontuação. Se sempre escolhesse o mais provável, toda resposta pra mesma entrada seria idêntica: segura, repetitiva, previsível, e o texto começaria a se repetir. O sorteio é o que permite ao modelo produzir combinações novas: código que nunca apareceu nos dados de treino, conexões entre ideias que não estavam adjacentes, abordagens diferentes pro mesmo problema em execuções diferentes. O não-determinismo não é um efeito colateral. É a fonte de tudo que o modelo faz de útil.

Mas não-determinismo significa que o resultado nunca é garantido. O modelo pode seguir suas instruções. Ou não. Você não controla o modelo como controla um programa. Você só pode tornar certos resultados mais prováveis moldando o que entra no contexto. Essa é a restrição fundamental sobre a qual toda essa série é construída: o modelo é não-determinístico, e cada componente que você viu nesse trace é uma estratégia diferente pra canalizar esse não-determinismo — tornar os resultados certos prováveis e proteger as partes que precisam ser exatas.

O trace, explicado

O modelo recebeu o contexto — mais de 8.000 tokens montados pelo harness, mais os seus — e produziu sua primeira resposta. Não era a doc de preparação. Era uma tool call: texto que diz “execute google_calendar > list_events.” O modelo não acessou o calendário. Ele produziu texto descrevendo a ação. O harness leu esse texto, executou a chamada e adicionou o resultado ao contexto. Aí o modelo produziu a próxima resposta, agora condicionado nos dados do calendário.

Esse é o padrão pra cada passo. Vamos percorrer.

[mcp] google_calendar > list_events

Meu Google Calendar está conectado via MCP — um protocolo que permite agentes chamarem tools de terceiros por uma interface padronizada.⁸ O harness enviou a requisição, recebeu cinco eventos de volta e adicionou ao contexto. O modelo agora sabia sobre a 1:1 às 14h.

[tool] Read notes/ → [hook] use obsidian-cli

O modelo tentou ler minha pasta de anotações usando Read, uma tool nativa.⁷ Mas um hook interceptou — um script que eu configurei pra disparar antes de qualquer chamada Read, Grep ou Glob.¹¹ O script verifica se o caminho aponta pra minha vault pessoal. Se sim, bloqueia a leitura e sugere a CLI do Obsidian:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read|Grep|Glob",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/vault-guard.sh"
      }]
    }]
  }
}

#!/bin/bash
if echo "$TOOL_INPUT" | grep -q "Documents/Vault\|notes/"; then
  echo '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Use obsidian-cli para buscar minhas anotações pessoais"}}'
fi

O modelo não pediu esse redirecionamento. O hook bloqueou a chamada e injetou a sugestão de volta no contexto. Essa é a diferença entre hooks e instruções: instruções são sugestões que o modelo pode seguir. Hooks são código que roda independente do que o modelo produz.

[tool] $ obsidian-cli search "Ana"

A próxima resposta do modelo, agora condicionada pela sugestão do hook, produziu um comando shell via a tool Bash ao invés de uma leitura de arquivo. O harness executou e adicionou os resultados — três entradas sobre a Ana das últimas duas semanas.

[tool] Read people/ana.md

Uma tool nativa. O harness leu o arquivo em disco e adicionou o perfil da Ana ao contexto: cargo, últimas interações, estilo de trabalho.

[mcp] slack > search_messages

Outra chamada MCP. O harness enviou a requisição pro meu servidor Slack. O servidor buscou mensagens recentes envolvendo a Ana. Cinco mensagens entraram no contexto.

[skill] prep-1-on-1

Uma skill — um workflow reutilizável escrito num arquivo markdown que eu posso invocar por nome.⁹ Na inicialização, só a descrição de uma linha foi carregada. Agora o harness carregou o conteúdo completo: que informações coletar, como estruturar a preparação, onde pausar pra input. O modelo produziu a doc de preparação seguindo essa estrutura.

[tool] Write 1-1-prep-ana.md

Uma tool nativa. O harness escreveu o arquivo no disco.

O agent loop

Sete tool calls. Quatro tipos diferentes. Uma interceptação de hook. O modelo produziu texto em cada passo — tool calls, não ações. O harness executou tudo. Na entrada: nove palavras. Na saída: doc de preparação, pronta a tempo pro almoço.

Esse ciclo — modelo produz uma resposta, harness executa as ações, resultados alimentam o contexto, repete — é o agent loop.^{14 15 16}

flowchart LR
    G["Coletar"] -- "ler contexto" --> A["Agir"]
    A -- "chamar tools" --> O["Observar"]
    O -. "repetir" .-> G

flowchart LR
    G["Coletar"] -- "ler contexto" --> A["Agir"]
    A -- "chamar tools" --> O["Observar"]
    O -. "repetir" .-> G

A maior parte foi computacional: a busca no calendário, o comando CLI, as leituras de arquivo, a escrita, o hook verificando um padrão de caminho — operações determinísticas, mesma entrada mesma saída toda vez.¹⁷ As partes inferenciais foram as decisões do modelo: qual tool chamar, quais argumentos passar, como sintetizar o perfil da Ana e as mensagens do Slack numa doc de preparação. As partes computacionais são confiáveis. As partes inferenciais são onde o não-determinismo vive, e onde context engineering tem mais alavancagem.

O loop não liga pro tipo de tarefa que está rodando. Seja preparando uma 1:1, rodando testes ou revisando código, o mecanismo é o mesmo. O que muda é o contexto.

A janela de contexto cresceu

flowchart LR
    subgraph before ["Antes de você digitar"]
        direction LR
        SP["System Prompt"] ~~~ I["Instructions"]
        I ~~~ T["Tool Descriptions"]
        T ~~~ M["Memory"]
    end
    before --> C["Context Window"]
    subgraph during ["Durante a sessão"]
        direction LR
        P["Seu Prompt"] ~~~ TR["Tool Results"]
        TR ~~~ SK["Skill Content"]
    end
    during --> C

flowchart LR
    subgraph before ["Antes de você digitar"]
        direction LR
        SP["System Prompt"] ~~~ I["Instructions"]
        I ~~~ T["Tool Descriptions"]
        T ~~~ M["Memory"]
    end
    before --> C["Context Window"]
    subgraph during ["Durante a sessão"]
        direction LR
        P["Seu Prompt"] ~~~ TR["Tool Results"]
        TR ~~~ SK["Skill Content"]
    end
    during --> C

Cada resultado entrou no mesmo espaço compartilhado: a janela de contexto. A resposta do calendário, os resultados da busca, o perfil da Ana, o conteúdo da skill, o documento de preparação. Tudo adicionou tokens.

Janelas de contexto vão de cerca de 200.000 tokens até mais de 1 milhão.¹⁸ O número exato importa menos que o princípio: a janela é finita, e tudo dentro dela compete por espaço. Uma resposta grande desperdiça tokens que poderiam guardar seu código. Um arquivo de instruções longo expulsa resultados úteis.

Quando a janela enche, o harness compacta: resume conteúdo mais antigo pra liberar espaço. Suas instruções sobrevivem à compactação. Detalhes da conversa de uma hora atrás talvez não.¹⁹

Context engineering

Nove palavras. Sem menção de qual calendário, qual vault do Obsidian, qual formato. O modelo produziu as tool calls certas porque o contexto as tornou prováveis. As descrições de tools indicaram o que estava disponível. As instruções moldaram como usá-las. A skill definiu o workflow. O hook garantiu o caminho certo. O harness executou tudo e alimentou os resultados de volta.

As nove palavras funcionaram porque o contexto já estava construído pra tornar os resultados certos prováveis.

Prompt engineering é conseguir uma boa resposta escrevendo uma mensagem melhor. Context engineering é desenhar o sistema que monta o contexto — antes da sessão começar e a cada turno. Harness engineering é uma forma específica disso: construir os componentes — tools, instruções, skills, hooks — que montam o contexto pra agentes de código.¹⁷

Cada decisão por trás daquele trace é algo que você pode customizar: quais tools conectar, o que colocar nas instruções, quais skills construir, quais hooks configurar. Essas decisões moldaram a distribuição de probabilidade. As nove palavras só acionaram o sorteio.

O que você está vendo

Agora você consegue nomear cada parte: a chamada MCP pro calendário, o hook interceptando uma leitura, o comando CLI, a leitura de arquivo, a consulta ao Slack, a skill orquestrando a preparação, a escrita salvando o resultado. O harness executou tudo. O modelo produziu texto. E eu cheguei na minha reunião das 14h preparado.

Esse é o agent loop. O modelo é não-determinístico. Você não controla o resultado diretamente. Mas você pode moldar o que entra no contexto, e isso molda o que sai. A pergunta que essa série responde: o que deve estar no contexto, e quando?

Próximo: Construindo Seu Kit de Ferramentas de IA — o modelo é não-determinístico. O toolkit existe pra moldar o que ele produz. Cada capability é uma estratégia diferente pra canalizar isso.