02Capítulo 2: Contexto: o que o modelo enxerga

O capítulo anterior terminou numa regra: o modelo só sabe o que está no texto que recebe. Esse texto inteiro é o contexto, e quem monta é o aplicativo, a cada chamada. Entender o que vai nele é o que separa resposta genérica de resposta útil.

O que vai dentro de uma chamada

Quando você manda uma mensagem num assistente de código, o app empilha várias coisas antes de enviar ao modelo. A ordem e os nomes variam de ferramenta para ferramenta, mas a pilha é parecida com esta:

1. Instruções do sistemao appQuem o assistente é, como usar as ferramentas, regras de segurança.
2. Instruções do projetovocêCLAUDE.md, AGENTS.md e similares. Entram em toda conversa.
3. Definições de ferramentaso app e os servidores MCPNome, descrição e parâmetros de cada ferramenta disponível.
4. Históricoa conversaMensagens anteriores, respostas e resultados de ferramentas.
5. Arquivos e trechosvocê ou o appCódigo anexado, arquivos que o assistente leu, saída de comandos.
6. Seu pedidovocêA mensagem que você acabou de escrever.

Repare no tamanho relativo. Em ferramentas de código, instruções do sistema e definições de ferramentas podem ocupar milhares de tokens antes de você digitar qualquer coisa. Cada servidor MCP que você instala (capítulos 4 e 5) acrescenta as descrições das ferramentas dele a essa pilha. Instalar vinte servidores “só por garantia” tem custo.

Instruções de projeto

Toda conversa nova começa do zero: o modelo não sabe que o projeto usa pnpm, que os testes rodam com um comando específico nem que a pasta migrations/ não pode ser editada. Em vez de repetir isso toda vez, você escreve num arquivo que o app inclui sozinho no contexto.

Cada ferramenta procura um nome de arquivo:

Para não manter arquivos repetidos, escreva tudo no AGENTS.md e faça o CLAUDE.md apontar para ele. No Linux e no macOS dá para usar um link simbólico. No Windows é mais simples deixar o CLAUDE.md com uma linha só, que importa o outro arquivo:

@AGENTS.md

O que escrever

Um exemplo enxuto para uma API em Node:

# api-pedidos

## Como rodar
- Node 24 e pnpm. Instale com `pnpm install`.
- Testes: `pnpm test`. Lint: `pnpm lint`. Rode os dois antes de dizer que terminou.

## Convenções
- TypeScript estrito, sem `any`.
- Rotas novas em `src/rotas/`, uma por arquivo, com o teste ao lado (`*.test.ts`).
- Mensagens de commit em português, no imperativo.

## Não faça
- Não edite migrations que já rodaram. Crie uma nova.
- Não adicione dependência sem perguntar.

Três regras para esse arquivo funcionar:

• Curto e específico. Comando exato vale mais que princípio. “Escreva código limpo” não muda nada; “rode pnpm lint” muda.
• Só o que não dá para descobrir lendo o código. Por que algo é do jeito que é, o que é proibido, onde fica o quê.
• Atualize quando o modelo errar. Se ele errou a mesma coisa duas vezes, isso vira uma linha no arquivo.

Quando a janela enche

Conversas longas acumulam: cada mensagem, cada arquivo lido, cada saída de comando fica na pilha. Perto do limite, o app precisa cortar ou resumir o começo da conversa. O Claude Code, por exemplo, compacta o histórico sozinho quando chega perto do teto, e você pode pedir isso antes com /compact.

Mesmo longe do limite, contexto demais piora a resposta. A informação que importa fica diluída no meio de log, de arquivo que não tinha nada a ver e de tentativa que não deu certo. Na prática:

• Uma conversa por tarefa. Terminou, comece outra (/clear no Claude Code).
• Traga só o que importa. O trecho relevante do log, não o arquivo de 30 mil linhas.
• Se a conversa desandou, recomece. Abra uma nova com um resumo do que você já descobriu, em vez de insistir na que ficou confusa.

Contexto é a entrada. O próximo capítulo trata da saída que não é texto: quando o modelo pede para fazer alguma coisa.