Context Engineering: A Skill Mais Importante Para Agentes

Durante muito tempo, a conversa sobre IA para devs girou em torno de prompt engineering. Como escrever melhor a pergunta. Como dar papel ao modelo. Como pedir formato. Como evitar resposta genérica. Isso ainda importa, mas deixou de ser o centro do jogo.

Com agentes, o problema não é só o texto do prompt. O problema é o ambiente informacional em que o agente opera. Quais arquivos ele vê? Quais regras carrega? Quais docs consulta? Quais exemplos usa? Quais ferramentas estão disponíveis? O que entra no contexto agora e o que só deve entrar se for necessário?

É por isso que o Radar da Thoughtworks colocou context engineering em Adopt. Não como buzzword, mas como preocupação arquitetural. Contexto virou superfície de design. Um agente bom não precisa saber tudo o tempo inteiro. Ele precisa conseguir descobrir a coisa certa na hora certa, com pouco ruído e alta confiança.

Se desenvolvimento agêntico é o tema da semana, context engineering é a base silenciosa por trás de quase todos os outros temas. Sem contexto bem projetado, BMAD vira documento jogado no prompt, skills viram ruído, feedback sensors chegam tarde e PRs de agentes falham por premissa errada.

---

Prompt Engineering Era Só o Começo

Prompt engineering olha para formulação. Context engineering olha para sistema. A diferença é parecida com escrever uma boa mensagem para um dev versus montar um onboarding de projeto que permite a qualquer dev trabalhar bem.

Um prompt pode dizer: "siga boas práticas, escreva testes e respeite arquitetura". Context engineering pergunta: onde estão essas boas práticas? Como o agente sabe qual arquitetura vale para este repo? Quais testes são relevantes? Quais decisões antigas precisam ser respeitadas? Como evitar instruções obsoletas?

Essa mudança fica clara em tarefas grandes. Para pedir uma função pequena, um prompt bem escrito pode bastar. Para pedir uma mudança em codebase real, o agente precisa navegar domínio, dependências, padrões locais, contratos, histórico e restrições. Isso não cabe de forma saudável em um único prompt gigante.

O erro comum é tentar resolver falta de contexto com mais contexto bruto. Joga README, docs, arquivos, logs, issues, padrões, exemplos e conversas no modelo. Parece completo, mas cria context rot: excesso de informação reduz sinal, aumenta contradição e degrada raciocínio.

---

Progressive Context Disclosure

Progressive context disclosure é uma das práticas mais importantes aqui. A ideia é simples: comece com um índice leve do que existe e carregue detalhes sob demanda. Em vez de despejar todo manual do projeto, mostre ao agente onde estão as fontes e deixe ele buscar o que precisa.

Isso é parecido com como devs humanos trabalham. Um senior não lê o repositório inteiro antes de corrigir bug. Ele usa mapas mentais, nomes de arquivos, testes, logs e grep para chegar ao ponto certo. O agente precisa de algo parecido: caminhos, descrições curtas, ferramentas de busca e regras para não carregar tudo de uma vez.

Na prática, isso pode ser implementado com arquivos como AGENTS.md, índices de docs, skills específicas, embeddings, search semântico, MCPs sob demanda ou ferramentas internas. O formato importa menos que o princípio: reduzir ruído e aumentar recuperabilidade.

Um bom índice para agente responde: quais áreas existem no sistema? Quem é fonte de verdade para cada contrato? Onde ficam exemplos canônicos? Quais arquivos nunca devem ser tocados sem aprovação? Quais comandos validam cada tipo de mudança?

---

Contexto Também É Governança

Context engineering não é só produtividade. É governança. O que você coloca no contexto define o comportamento provável do agente. Se as instruções estão espalhadas, duplicadas ou contraditórias, você está treinando o agente para improvisar.

Isso aparece muito em repositórios com múltiplas superfícies: CLAUDE.md, AGENTS.md, .cursorrules, prompts locais, docs antigas, scripts de CI, comentários em issues. Se cada uma diz algo diferente, o agente pode escolher a instrução errada com total confiança.

Por isso a prática de "curated shared instructions for software teams", também em Adopt no Radar, combina tanto com context engineering. Instruções compartilhadas precisam ser tratadas como ativo de engenharia: versionadas, revisadas, atualizadas junto com templates e alinhadas à arquitetura real.

O ganho para tech leads é enorme. Em vez de cada dev criar seu próprio prompt secreto, o time define regras comuns no repositório. O agente que entrar naquele projeto herda o jeito do time trabalhar. Isso reduz variação e torna review mais previsível.

---

O Contexto Que Mais Importa Para Coding Agents

Nem todo contexto tem o mesmo valor. Para agentes de código, alguns tipos são especialmente importantes.

Primeiro, comandos de validação. O agente precisa saber como rodar lint, testes, build, typecheck, e2e e validações específicas. Sem isso, ele tende a parar quando o código "parece" certo.

Segundo, fronteiras arquiteturais. Quais módulos podem depender de quais? Onde fica regra de negócio? O que é componente burro? O que é serviço? O que é infra? Agente sem fronteira mexe onde for mais fácil.

Terceiro, contratos externos. OpenAPI, schema, eventos, filas, migrations, feature flags, permissões. Mudança que ignora contrato pode compilar localmente e quebrar produção.

Quarto, exemplos canônicos. Um bom exemplo local vale mais que dez instruções genéricas. Se o agente encontra um padrão certo já aplicado no repo, tende a copiá-lo. Por isso codebase desorganizado vira professor ruim para agentes.

---

Memória Não É Contexto Mágico

Muita ferramenta promete memória persistente. Isso é útil, mas memória não substitui context engineering. Memória pode carregar preferências, decisões e histórico. Também pode carregar erro velho, regra obsoleta e conclusão mal interpretada.

Contexto bom precisa ter origem, validade e escopo. Quem disse isso? Quando? Vale para este repo ou para outro? É regra global ou exceção? Foi aprovado pelo time ou inferido pelo agente?

Sem essas perguntas, memória vira superstição automatizada. O agente "lembra" algo e age com confiança, mas ninguém sabe se aquilo ainda é verdade. Em times, isso é especialmente perigoso porque memória pessoal do agente pode entrar em conflito com regra versionada do repositório.

Minha regra prática: memória pode sugerir, repositório decide. Preferências e histórico ajudam, mas contrato, comando e regra de projeto precisam estar versionados em lugar revisável.

---

Como Começar Com Context Engineering

O primeiro passo é inventariar contexto existente. Onde o time documenta padrões? Onde estão comandos? Onde ficam decisões arquiteturais? Quais docs estão obsoletas? Quais instruções se repetem?

Depois, criar um ponto de entrada curto. Um AGENTS.md bom não deve virar enciclopédia. Ele deve orientar o agente: leia estes arquivos para este tipo de tarefa, rode estes comandos antes de finalizar, respeite estas fronteiras, peça aprovação nestas áreas.

Terceiro, separar contexto estático de contexto dinâmico. Regras de estilo e comandos mudam pouco. Estado de issue, logs e dados de produção mudam muito. Misturar tudo no mesmo arquivo cria desatualização rápida.

Quarto, medir falhas. Quando um agente erra por falta de contexto, não basta corrigir o prompt daquela sessão. Pergunte qual contexto deveria existir para evitar repetição. A resposta pode virar doc, skill, teste, script ou sensor.

Um bom exercício de primeira semana é pegar três falhas recentes de agentes e rastrear a causa. O agente não sabia o comando certo? Não encontrou contrato? Ignorou padrão local? Repetiu solução antiga? Cada causa vira uma melhoria pequena no sistema de contexto.

Também vale criar uma regra de higiene: contexto que não é usado deve sair. Arquivo de instrução não é depósito. Se uma regra não ajuda o agente a tomar decisão ou evitar erro, ela provavelmente está competindo por atenção com coisa mais importante.

O Papel do Tech Lead

Context engineering não deve ficar só na mão de quem "gosta de IA". O tech lead precisa tratar isso como parte da arquitetura do time, porque contexto ruim cria comportamento ruim em todos os agentes que passam pelo repo.

Na prática, isso significa revisar instruções como revisaria código. Uma mudança em AGENTS.md, skill ou prompt de workflow pode alterar centenas de execuções futuras. Precisa de PR, justificativa e teste no fluxo real.

Também significa nomear donos. Quem mantém guia de arquitetura? Quem atualiza comandos de validação? Quem remove instrução obsoleta? Sem dono, contexto vira lixo acumulado. E agente é excelente em reciclar lixo com confiança.

---

Principais Aprendizados

• Prompt engineering foca mensagem; context engineering foca sistema.
• Contexto demais pode piorar raciocínio por ruído e contradição.
• Progressive context disclosure carrega informação sob demanda.
• Instruções compartilhadas precisam ser versionadas e revisadas.
• Memória ajuda, mas não substitui fonte de verdade no repositório.

---

Conclusão

Context engineering virou uma das skills mais importantes para quem usa agentes porque determina a qualidade do ambiente em que o agente pensa. Modelo bom em contexto ruim parece burro. Modelo mediano em contexto bem projetado pode ser surpreendentemente útil.

Para devs e tech leads, a mudança prática é clara: pare de tratar instrução de agente como prompt pessoal. Trate como arquitetura. Onde o contexto vive, como é carregado, quem revisa, como envelhece e como é validado são decisões de engenharia.

O time que fizer isso bem vai extrair mais dos agentes sem depender apenas de modelos melhores. E esse é um tipo de vantagem mais difícil de copiar.

---

Fontes e Referências

• Thoughtworks Technology Radar Vol. 34
• Harness engineering for coding agent users - Martin Fowler
• GitHub Spec Kit
• OpenSpec
• Superpowers - agentic skills framework
• Pi Engram package

---

Sugestão de Imagens

Capa (context_engineering_agentes_cover.png): pipeline visual de contexto: índice leve, docs, skills, memória, ferramentas e validações entrando no agente sob demanda.

Inline 1: comparação prompt engineering vs context engineering.

Inline 2: diagrama progressive disclosure: index -> retrieve -> act -> summarize.