Context engineering para agents de código
Agents não se lembram do seu projeto; eles leem o que você coloca na frente deles. Bons resultados vêm do que o modelo vê: instruções claras, os arquivos certos, um plano e tarefas pequenas o bastante para verificar.
O que é
Context engineering é decidir o que entra na do modelo e em que formato. Mais texto não é melhor: um contexto longo e ruidoso faz o modelo perder instruções e custa mais. O objetivo é o menor contexto que contenha tudo o que é necessário para fazer a tarefa corretamente.
Um arquivo de instruções do projeto
A maioria dos harnesses lê um arquivo na raiz do repositório no início de cada sessão. virou uma convenção comum entre ferramentas; o Claude Code lê CLAUDE.md (que pode apontar para AGENTS.md). Coloque nele o que um colega novo e experiente precisaria no primeiro dia, e mantenha curto.
# Notas do projeto para agents de código
## Comandos
- Instalar: `npm ci`
- Testar (rodar antes de todo commit): `npm test`
- Lint e tipos: `npm run lint && npm run typecheck`
## Convenções
- TypeScript strict. Sem `any`. Prefira funções pequenas e puras.
- Acesso ao banco só por `src/db/*`; nunca monte SQL por concatenação de strings.
- Novos endpoints precisam de checagem de autorização e de um teste para "o usuário B não pode ler os dados do usuário A".
## Limites
- Não edite `infra/` nem `.github/workflows/` sem perguntar.
- Nunca leia nem imprima `.env` ou qualquer coisa em `secrets/`.
- Pergunte antes de adicionar uma dependência.Método de trabalho
- Planeje primeiro: peça um plano (muitas ferramentas têm um somente leitura), edite-o e então aprove. Corrigir um plano é mais barato que corrigir código.
- Tarefas pequenas: uma mudança por sessão ou branch, com um teste que decide o sucesso. Tarefas grandes e vagas produzem diffs grandes e vagos.
- Aponte exemplos: "siga o padrão de src/users/handler.ts" vale mais que um parágrafo de descrição.
- Declare a verificação: diga ao agent como verificar o próprio trabalho (rode este teste, este linter, este comando).
- Reinicie com frequência: comece uma sessão nova quando o contexto ficar longo ou o agent se confundir, levando adiante só as decisões.
- Dê ferramentas, não ensaios: conecte um servidor ou um script para uma necessidade repetida (consultar o banco de staging em somente leitura, abrir um ticket) em vez de colar dados no chat.
Skills, hooks e subagents
Além do arquivo de instruções, os harnesses oferecem pontos de extensão. Skills empacotam um procedimento que o agent carrega só quando é relevante. Hooks executam seu código em momentos fixos (antes de uma ferramenta rodar, depois de uma edição), que é o lugar confiável para impor regras que o modelo pode esquecer, como formatação ou bloquear um comando perigoso. Subagents executam uma tarefa focada em seu próprio contexto e devolvem um resumo, o que mantém limpa a conversa principal. Trate tudo que um agent pode executar como código com as suas permissões e revise como código.
Erros comuns
- Um arquivo de instruções gigante cheio de regras que o agent ignora. Curto e específico vence.
- Regras que são só prosa. Se nunca pode acontecer, imponha com permissões, hooks ou CI, não com uma frase.
- Segredos nas instruções ou em logs colados.
- Deixar o contexto se encher de tentativas fracassadas. Recomece com o que aprendeu.
- Confiar na afirmação do agent de que os testes passam sem executá-los você mesmo.
conexões no mapa
- Quando usar o quêé seguido porContext engineering para agents de código
- Context engineering para agents de códigoescala paraOrquestração e agents paralelos
- Context engineering para agents de códigodefine as verificações deO loop de verificação
atualizado em 14/10/2026 · fontes para aprofundar · reportar erro
em outros domínios
- Tool callingai-agentsferramentas e permissões decidem o que o agente consegue fazer
Estude antes
Desbloqueia
teste o que entendeu
Carregando perguntas…