Engenharia de contexto: o trabalho antes do prompt

spinny:~/writing $ vim context-engineering-agents.md

1~
2A palavra do momento, no pequeno mundo dos agentes de IA, é engenharia de contexto.
3~
4Parece mais um selo inventado para vender algo que já fazíamos. Em parte é. Porém, como costuma acontecer, o rótulo pega porque dá nome a uma dor real.
5~
6A dor é esta: os modelos não falham só porque “não pensam”. Muitas vezes eles falham porque os enviamos para trabalhar na sala errada.
7~
8Damos-lhes instruções antigas. Escondemos dele arquivos importantes. Passamos a eles documentos muito longos e que não dizem o que importa. Mostramos-lhes registros sem prioridade. Damos-lhes dez ferramentas sem explicar quando usá-las. Então ficamos surpresos se o agente se move como uma pessoa acordada em um apartamento desconhecido.
9~
10O prompt é a frase que você diz a ele. O contexto é o mundo que você prepara em torno dele.
11~
12## Da engenharia imediata à engenharia de contexto
13~
14A engenharia imediata era muitas vezes considerada como escrita. Escolha as palavras certas, pergunte da maneira certa, acrescente exemplos, especifique o formato.
15~
16A engenharia de contexto está mais próxima da arquitetura.
17~
18Você não pergunta apenas “como faço para formular o pedido?”. Ele pergunta:
19~
20- que informações são realmente necessárias?
21- o que são ruídos?
22- o que precisa ser recuperado na hora?
23- o que deve ser lembrado?
24- quais ferramentas devem ser expostas?
25- quais instruções são estáveis e quais dependem da tarefa?
26- como faço para o agente entender o que é autoritativo?
27~
28É uma mudança sutil, mas enorme. Porque quando você trabalha com agentes, o contexto não é um bloco estático. Ele muda a cada passo.
29~
30O agente abre um arquivo, aprende algo, executa um teste, recebe um erro, atualiza o plano, chama uma ferramenta, descobre uma dependência. A cada volta ele tem que decidir o que levar e o que deixar de fora.
31~
32Isso é engenharia.
33~
34## O contexto não é um aterro sanitário
35~
36Modelos com grandes janelas de contexto nos deram a tentação: vamos incluir tudo.
37~
38É compreensível. Se eu tenho um milhão de tokens, por que deveria escolher?
39~
40Porque mesmo quando você consegue colocar tudo, não significa que tudo ajuda. Na verdade, o ruído tem um custo. Custa tokens, custa atenção, custa latência, custa qualidade. Um modelo pode se perder em detalhes irrelevantes assim como nós quando abrimos vinte abas e não lembramos mais por quê.
41~
42Um bom contexto tem uma hierarquia:
43~
441. instruções e políticas do sistema;
452. objetivo específico;
463. situação atual;
474. dados relevantes;
485. restrições;
496. ferramentas disponíveis;
507. acompanhar as decisões já tomadas.
51~
52Não há necessidade de tratar tudo no mesmo nível. Um comando do usuário vale mais que uma nota antiga. Um teste reprovado agora vale mais do que uma preferência estética de três meses atrás. Uma política de segurança vale mais do que um atalho de produção.
53~
54Engenharia de contexto também significa dar pesos, não apenas dados.
55~
56## Memória: lembre-se menos, lembre-se melhor
57~
58A memória nos agentes é um dos tópicos mais escorregadios.
59~
60Como usuário, você deseja que o agente conheça você. Você quer que ele se lembre do tom, do plano, das convenções, das coisas já decididas. Como engenheiro, você sabe que toda memória persistente também é um risco: pode estar errada, antiga, muito pessoal, muito genérica, não verificável.
61~
62Uma memória útil deve ter pelo menos três qualidades:
63~
64- proveniência: de onde vem esta informação?
65- data: quando foi verdade?
66- finalidade: para que tipo de tarefa deve ser utilizada?
67~
68Sem essas três coisas, a memória se torna superstição.
69~
70Gosto de pensar na memória agente como um livro de exercícios, não como uma mente mágica. Existem notas temporárias, decisões confirmadas, preferências de estilo, restrições técnicas, links para fontes. Algumas coisas expiram. Alguns precisam ser reescritos. Alguns devem ser eliminados porque o agente os deduziu erroneamente.
71~
72Um bom sistema deve tornar esta manutenção normal. Não é heróico.
73~
74## Recuperação e ferramentas não são a mesma coisa
75~
76Quando falamos sobre contexto, muitas vezes acabamos imediatamente no RAG. Incorporação, banco de dados vetorial, fragmentação, reclassificação.
77~
78Tudo útil. Mas a recuperação é apenas uma forma de trazer informações para o modelo. Ele não é o único.
79~
80Um agente pode obter contexto lendo arquivos, consultando uma API, chamando um servidor MCP, abrindo um navegador, executando testes, pesquisando no Slack, olhando um painel, perguntando ao humano.
81~
82A parte interessante é decidir qual rota usar e quando.
83~
84Se o agente precisar responder a uma questão histórica, talvez apenas a recuperação seja suficiente. Se ele precisar consertar um bug, ele terá que ler o código real. Se ele precisar entender por que uma implantação falha, ele precisará examinar os logs recentes. Se precisar escrever para um cliente, você precisará recuperar o tom, o histórico e o status do ticket. Se ele precisar agir na produção, deverá pedir permissão.
85~
86Contexto não é um banco de dados. É um fluxo de trabalho.
87~
88## O bom agente também sabe ignorar
89~
90Um sinal de maturidade dos agentes será a capacidade de dizer: não preciso desta informação.
91~
92Parece trivial, mas é muito difícil. Muitos sistemas agentes se acumulam. Cada chamada de ferramenta adiciona texto. Cada erro permanece no buffer. Cada leitura de arquivo é adicionada à pilha. No final das contas, o modelo tem uma história muito longa e nenhum mapa.
93~
94A compressão é necessária. É necessária uma síntese intermediária. Precisa ser estruturado.
95~
96Não "foi tudo o que aconteceu", mas:
97~
98- objetivo ainda válido;
99- hipótese atual;
100- arquivos já verificados;
101- decisões tomadas;
102- riscos abertos;
103- próxima ação.
104~
105Isso torna o agente menos teatral e mais prestativo. Não porque pareça mais inteligente, mas porque trabalha com uma mesa arrumada.
106~
107## Engenharia de contexto para equipes, não para artistas imediatos
108~
109A razão pela qual este tópico me interessa é que ele transfere a responsabilidade do indivíduo para o sistema.
110~
111Na engenharia imediata, aquele que consegue falar melhor com o modelo geralmente vence. Na engenharia de contexto, ganha a equipe que melhor organizar seu trabalho: documentação, convenções, problemas, logs, testes, propriedade, nomenclatura, fontes.
112~
113Um repositório limpo torna-se um contexto melhor. Uma edição bem escrita torna-se melhor combustível. Um runbook atualizado economiza tokens e ansiedade. Um changelog claro reduz as alucinações.
114~
115Esta é uma notícia boa e um tanto desconfortável. Bonito porque premia boas práticas. Inconveniente porque você não pode resolver tudo com um prompt inteligente.
116~
117Os agentes amplificam a higiene do sistema que encontram.
118~
119## Como eu aplicaria amanhã
120~
121Se eu introduzisse a engenharia de contexto em um projeto real, começaria com pequenas coisas:
122~
123- um arquivo de instruções de projeto curto e mantido;
124- bons exemplos de resultados esperados;
125- uma lista de ferramentas disponíveis e casos em que utilizá-las;
126- decisões arquitetônicas escritas de forma citável;
127- emissão com contexto mínimo obrigatório;
128- fácil recuperação de logs e testes;
129- memória persistente modificável por humanos.
130~
131Aí eu mediria uma coisa simples: quantas vezes o agente tem que pedir esclarecimentos ou sai na direção errada?
132~
133Se isso acontecer com frequência, eu não adicionaria um modelo maior imediatamente. Eu olharia para o contexto.
134~
135## Minha leitura
136~
137Engenharia de contexto é uma palavra um pouco inchada, sim. Mas o conceito é sólido.
138~
139Isso nos lembra que a inteligência de um agente não está apenas no modelo. Está no ambiente que preparamos para ele: o que ele vê, o que ele lembra, o que ele pode fazer, o que está proibido de fazer, quais fontes ele reconhece como verdadeiras.
140~
141A parte humana é esta: preparar bem o contexto é uma forma de cuidado. É dizer ao agente, mas também à equipe: “Não quero que você adivinhe, quero que você tenha o que precisa”.
142~
143Menos magia. Sala mais limpa. Os agentes precisam disso tanto quanto nós.
144~
145## Fontes
146~
147- [Blog LangChain: A ascensão da engenharia de contexto](https://blog.langchain.com/the-rise-of-context-engineering/)
148- [Simon Willison: Engenharia de contexto](https://simonwillison.net/2025/Jun/27/context-engineering/)
149- [Protocolo de Contexto do Modelo: Introdução](https://modelcontextprotocol.io/introduction)
150- [Anthropic: Construindo agentes eficazes](https://www.anthropic.com/engineering/building-efficient-agents)
151- [OpenAI: Novas ferramentas para agentes de construção](https://openai.com/index/new-tools-for-building-agents/)
152~

NORMAL · context-engineering-agents.md [readonly]152 lines · :q to close

2A palavra do momento, no pequeno mundo dos agentes de IA, é engenharia de contexto.

4Parece mais um selo inventado para vender algo que já fazíamos. Em parte é. Porém, como costuma acontecer, o rótulo pega porque dá nome a uma dor real.

6A dor é esta: os modelos não falham só porque “não pensam”. Muitas vezes eles falham porque os enviamos para trabalhar na sala errada.

8Damos-lhes instruções antigas. Escondemos dele arquivos importantes. Passamos a eles documentos muito longos e que não dizem o que importa. Mostramos-lhes registros sem prioridade. Damos-lhes dez ferramentas sem explicar quando usá-las. Então ficamos surpresos se o agente se move como uma pessoa acordada em um apartamento desconhecido.

10O prompt é a frase que você diz a ele. O contexto é o mundo que você prepara em torno dele.

11~

12## Da engenharia imediata à engenharia de contexto

13~

14A engenharia imediata era muitas vezes considerada como escrita. Escolha as palavras certas, pergunte da maneira certa, acrescente exemplos, especifique o formato.

15~

16A engenharia de contexto está mais próxima da arquitetura.

17~

18Você não pergunta apenas “como faço para formular o pedido?”. Ele pergunta:

19~

20- que informações são realmente necessárias?

21- o que são ruídos?

22- o que precisa ser recuperado na hora?

23- o que deve ser lembrado?

24- quais ferramentas devem ser expostas?

25- quais instruções são estáveis e quais dependem da tarefa?

26- como faço para o agente entender o que é autoritativo?

27~

28É uma mudança sutil, mas enorme. Porque quando você trabalha com agentes, o contexto não é um bloco estático. Ele muda a cada passo.

29~

30O agente abre um arquivo, aprende algo, executa um teste, recebe um erro, atualiza o plano, chama uma ferramenta, descobre uma dependência. A cada volta ele tem que decidir o que levar e o que deixar de fora.

31~

32Isso é engenharia.

33~

34## O contexto não é um aterro sanitário

35~

36Modelos com grandes janelas de contexto nos deram a tentação: vamos incluir tudo.

37~

38É compreensível. Se eu tenho um milhão de tokens, por que deveria escolher?

39~

40Porque mesmo quando você consegue colocar tudo, não significa que tudo ajuda. Na verdade, o ruído tem um custo. Custa tokens, custa atenção, custa latência, custa qualidade. Um modelo pode se perder em detalhes irrelevantes assim como nós quando abrimos vinte abas e não lembramos mais por quê.

41~

42Um bom contexto tem uma hierarquia:

43~

441. instruções e políticas do sistema;

452. objetivo específico;

463. situação atual;

474. dados relevantes;

485. restrições;

496. ferramentas disponíveis;

507. acompanhar as decisões já tomadas.

51~

52Não há necessidade de tratar tudo no mesmo nível. Um comando do usuário vale mais que uma nota antiga. Um teste reprovado agora vale mais do que uma preferência estética de três meses atrás. Uma política de segurança vale mais do que um atalho de produção.

53~

54Engenharia de contexto também significa dar pesos, não apenas dados.

55~

56## Memória: lembre-se menos, lembre-se melhor

57~

58A memória nos agentes é um dos tópicos mais escorregadios.

59~

60Como usuário, você deseja que o agente conheça você. Você quer que ele se lembre do tom, do plano, das convenções, das coisas já decididas. Como engenheiro, você sabe que toda memória persistente também é um risco: pode estar errada, antiga, muito pessoal, muito genérica, não verificável.

61~

62Uma memória útil deve ter pelo menos três qualidades:

63~

64- proveniência: de onde vem esta informação?

65- data: quando foi verdade?

66- finalidade: para que tipo de tarefa deve ser utilizada?

67~

68Sem essas três coisas, a memória se torna superstição.

69~

70Gosto de pensar na memória agente como um livro de exercícios, não como uma mente mágica. Existem notas temporárias, decisões confirmadas, preferências de estilo, restrições técnicas, links para fontes. Algumas coisas expiram. Alguns precisam ser reescritos. Alguns devem ser eliminados porque o agente os deduziu erroneamente.

71~

72Um bom sistema deve tornar esta manutenção normal. Não é heróico.

73~

74## Recuperação e ferramentas não são a mesma coisa

75~

76Quando falamos sobre contexto, muitas vezes acabamos imediatamente no RAG. Incorporação, banco de dados vetorial, fragmentação, reclassificação.

77~

78Tudo útil. Mas a recuperação é apenas uma forma de trazer informações para o modelo. Ele não é o único.

79~

80Um agente pode obter contexto lendo arquivos, consultando uma API, chamando um servidor MCP, abrindo um navegador, executando testes, pesquisando no Slack, olhando um painel, perguntando ao humano.

81~

82A parte interessante é decidir qual rota usar e quando.

83~

84Se o agente precisar responder a uma questão histórica, talvez apenas a recuperação seja suficiente. Se ele precisar consertar um bug, ele terá que ler o código real. Se ele precisar entender por que uma implantação falha, ele precisará examinar os logs recentes. Se precisar escrever para um cliente, você precisará recuperar o tom, o histórico e o status do ticket. Se ele precisar agir na produção, deverá pedir permissão.

85~

86Contexto não é um banco de dados. É um fluxo de trabalho.

87~

88## O bom agente também sabe ignorar

89~

90Um sinal de maturidade dos agentes será a capacidade de dizer: não preciso desta informação.

91~

92Parece trivial, mas é muito difícil. Muitos sistemas agentes se acumulam. Cada chamada de ferramenta adiciona texto. Cada erro permanece no buffer. Cada leitura de arquivo é adicionada à pilha. No final das contas, o modelo tem uma história muito longa e nenhum mapa.

93~

94A compressão é necessária. É necessária uma síntese intermediária. Precisa ser estruturado.

95~

96Não "foi tudo o que aconteceu", mas:

97~

98- objetivo ainda válido;

99- hipótese atual;

100- arquivos já verificados;

101- decisões tomadas;

102- riscos abertos;

103- próxima ação.

104~

105Isso torna o agente menos teatral e mais prestativo. Não porque pareça mais inteligente, mas porque trabalha com uma mesa arrumada.

106~

107## Engenharia de contexto para equipes, não para artistas imediatos

108~

109A razão pela qual este tópico me interessa é que ele transfere a responsabilidade do indivíduo para o sistema.

110~

111Na engenharia imediata, aquele que consegue falar melhor com o modelo geralmente vence. Na engenharia de contexto, ganha a equipe que melhor organizar seu trabalho: documentação, convenções, problemas, logs, testes, propriedade, nomenclatura, fontes.

112~

113Um repositório limpo torna-se um contexto melhor. Uma edição bem escrita torna-se melhor combustível. Um runbook atualizado economiza tokens e ansiedade. Um changelog claro reduz as alucinações.

114~

115Esta é uma notícia boa e um tanto desconfortável. Bonito porque premia boas práticas. Inconveniente porque você não pode resolver tudo com um prompt inteligente.

116~

117Os agentes amplificam a higiene do sistema que encontram.

118~

119## Como eu aplicaria amanhã

120~

121Se eu introduzisse a engenharia de contexto em um projeto real, começaria com pequenas coisas:

122~

123- um arquivo de instruções de projeto curto e mantido;

124- bons exemplos de resultados esperados;

125- uma lista de ferramentas disponíveis e casos em que utilizá-las;

126- decisões arquitetônicas escritas de forma citável;

127- emissão com contexto mínimo obrigatório;

128- fácil recuperação de logs e testes;

129- memória persistente modificável por humanos.

130~

131Aí eu mediria uma coisa simples: quantas vezes o agente tem que pedir esclarecimentos ou sai na direção errada?

132~

133Se isso acontecer com frequência, eu não adicionaria um modelo maior imediatamente. Eu olharia para o contexto.

134~

135## Minha leitura

136~

137Engenharia de contexto é uma palavra um pouco inchada, sim. Mas o conceito é sólido.

138~

139Isso nos lembra que a inteligência de um agente não está apenas no modelo. Está no ambiente que preparamos para ele: o que ele vê, o que ele lembra, o que ele pode fazer, o que está proibido de fazer, quais fontes ele reconhece como verdadeiras.

140~

141A parte humana é esta: preparar bem o contexto é uma forma de cuidado. É dizer ao agente, mas também à equipe: “Não quero que você adivinhe, quero que você tenha o que precisa”.

142~

143Menos magia. Sala mais limpa. Os agentes precisam disso tanto quanto nós.

144~

145## Fontes

146~

147- [Blog LangChain: A ascensão da engenharia de contexto](https://blog.langchain.com/the-rise-of-context-engineering/)

148- [Simon Willison: Engenharia de contexto](https://simonwillison.net/2025/Jun/27/context-engineering/)

149- [Protocolo de Contexto do Modelo: Introdução](https://modelcontextprotocol.io/introduction)

150- [Anthropic: Construindo agentes eficazes](https://www.anthropic.com/engineering/building-efficient-agents)

151- [OpenAI: Novas ferramentas para agentes de construção](https://openai.com/index/new-tools-for-building-agents/)

152~