Context engineering: the work before the prompt

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

1~
2The word of the moment, in the small world of AI agents, is context engineering.
3~
4It seems like yet another label invented to sell something we already did. In part it is. However, as often happens, the label catches on because it gives a name to a real pain.
5~
6The pain is this: models don't fail just because they "don't think". They often fail because we send them to work with the wrong room.
7~
8We give them old instructions. We hide important files from him. We pass them documents that are too long and don't say what matters. We show them logs without priority. We give them ten tools without explaining when to use them. Then we are surprised if the agent moves like a person woken up in an unknown apartment.
9~
10The prompt is the phrase you say to it. The context is the world you prepare around it.
11~
12## From prompt engineering to context engineering
13~
14Prompt engineering was often thought of as writing. Choose the right words, ask in the right way, add examples, specify the format.
15~
16Context engineering is closer to architecture.
17~
18You don't just ask "how do I formulate the request?". It asks:
19~
20- what information is really needed?
21- what are noise?
22- what needs to be recovered on the fly?
23- what should be remembered?
24- which tools should be exposed?
25- which instructions are stable and which depend on the task?
26- how do I make the agent understand what is authoritative?
27~
28It's a subtle but huge change. Because when you work with agents, context is not a static block. It changes at every step.
29~
30The agent opens a file, learns something, runs a test, receives an error, updates the plan, calls a tool, discovers a dependency. With each lap he has to decide what to take with him and what to leave out.
31~
32This is engineering.
33~
34## The context is not a landfill
35~
36Templates with large context windows gave us a temptation: let's throw everything in.
37~
38It's understandable. If I have a million tokens, why should I choose?
39~
40Because even when you can put everything in, it doesn't mean everything helps. Indeed, noise has a cost. It costs tokens, it costs attention, it costs latency, it costs quality. A model can get lost in irrelevant details just like us when we open twenty tabs and no longer remember why.
41~
42Good context has a hierarchy:
43~
441. system instructions and policies;
452. specific objective;
463. current status;
474. relevant data;
485. constraints;
496. available tools;
507. track the decisions already made.
51~
52There is no need to treat everything at the same level. A user command is worth more than an old note. A failed test is now worth more than an aesthetic preference from three months ago. A security policy is worth more than a production shortcut.
53~
54Context engineering also means giving weights, not just data.
55~
56## Memory: remember less, remember better
57~
58Memory in agents is one of the most slippery topics.
59~
60As a user, you want the agent to know you. You want him to remember the tone, the plan, the conventions, the things already decided. As an engineer, you know that every persistent memory is also a risk: it can be wrong, old, too personal, too generic, unverifiable.
61~
62A useful memory should have at least three qualities:
63~
64- provenance: where does this information come from?
65- date: when was it true?
66- purpose: what type of task should it be used for?
67~
68Without these three things, memory becomes superstition.
69~
70I like to think of agentic memory as a workbook, not as a magical mind. There are temporary notes, confirmed decisions, style preferences, technical constraints, links to sources. Some things expire. Some need to be rewritten. Some must be eliminated because the agent misinferred them.
71~
72A good system must make this maintenance normal. Not heroic.
73~
74## Retrieval and tools are not the same thing
75~
76When we talk about context, we often end up immediately on RAG. Embedding, vector database, chunking, reranking.
77~
78All useful. But retrieval is only one way to bring information to the model. He's not the only one.
79~
80An agent can get context by reading files, querying an API, calling an MCP server, opening a browser, running tests, searching Slack, looking at a dashboard, asking the human.
81~
82The interesting part is deciding which route to use and when.
83~
84If the agent needs to answer a historical question, perhaps just retrieval is enough. If he has to fix a bug, he has to read real code. If he needs to understand why a deployment fails, he needs to look at fresh logs. If you need to write to a customer, you need to retrieve the tone, history and status of the ticket. If he must act on production, he must ask permission.
85~
86Context is not a database. It's a workflow.
87~
88## The good agent also knows how to ignore
89~
90A sign of maturity in agents will be the ability to say: I don't need this information.
91~
92It seems trivial, but it is very difficult. Many agentic systems accumulate. Each tool call adds text. Every error remains in the buffer. Each file read adds to the stack. In the end the model has a very long history and no map.
93~
94Compression is needed. Intermediate synthesis is needed. It needs to be structured.
95~
96Not "that's all that happened", but:
97~
98- objective still valid;
99- current hypothesis;
100- files already checked;
101- decisions made;
102- open risks;
103- next action.
104~
105This makes the agent less theatrical and more helpful. Not because he seems smarter, but because he works with a tidy desk.
106~
107## Context engineering for teams, not for prompt artists
108~
109The reason this topic interests me is that it shifts responsibility from the individual to the system.
110~
111In prompt engineering, the one who can speak to the model best often wins. In context engineering, the team that best organizes its work wins: documentation, conventions, issues, logs, tests, ownership, naming, sources.
112~
113A clean repository becomes a better context. A well-written issue becomes better fuel. An updated runbook saves tokens and anxiety. A clear changelog reduces hallucinations.
114~
115This is good and somewhat uncomfortable news. Beautiful because it rewards good practices. Inconvenient because you can't solve everything with a clever prompt.
116~
117The agents amplify the hygiene of the system they find.
118~
119## How I would apply it tomorrow
120~
121If I were to introduce context engineering into a real project, I would start from small things:
122~
123- a short and maintained project instruction file;
124- good examples of expected output;
125- a list of available tools and cases in which to use them;
126- architectural decisions written in a citable manner;
127- issue with minimum mandatory context;
128- easy to retrieve logs and tests;
129- persistent memory modifiable by humans.
130~
131Then I would measure a simple thing: how many times does the agent have to ask for clarification or goes off in the wrong direction?
132~
133If it happens often, I wouldn't add a larger model right away. I would look at the context.
134~
135## My reading
136~
137Context engineering is a bit of a bloated word, yes. But the concept is sound.
138~
139It reminds us that the intelligence of an agent is not just in the model. It lies in the environment that we prepare for him: what he sees, what he remembers, what he can do, what he is forbidden to do, which sources he recognizes as true.
140~
141The human part is this: preparing the context well is a form of care. It's telling the agent, but also the team, "I don't want you to guess, I want you to have what you need."
142~
143Less magic. Cleaner room. Agents need it as much as we do.
144~
145## Sources
146~
147- [LangChain Blog: The rise of context engineering](https://blog.langchain.com/the-rise-of-context-engineering/)
148- [Simon Willison: Context engineering](https://simonwillison.net/2025/Jun/27/context-engineering/)
149- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/introduction)
150- [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
151- [OpenAI: New tools for building agents](https://openai.com/index/new-tools-for-building-agents/)
152~

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

2The word of the moment, in the small world of AI agents, is context engineering.

4It seems like yet another label invented to sell something we already did. In part it is. However, as often happens, the label catches on because it gives a name to a real pain.

6The pain is this: models don't fail just because they "don't think". They often fail because we send them to work with the wrong room.

8We give them old instructions. We hide important files from him. We pass them documents that are too long and don't say what matters. We show them logs without priority. We give them ten tools without explaining when to use them. Then we are surprised if the agent moves like a person woken up in an unknown apartment.

10The prompt is the phrase you say to it. The context is the world you prepare around it.

11~

12## From prompt engineering to context engineering

13~

14Prompt engineering was often thought of as writing. Choose the right words, ask in the right way, add examples, specify the format.

15~

16Context engineering is closer to architecture.

17~

18You don't just ask "how do I formulate the request?". It asks:

19~

20- what information is really needed?

21- what are noise?

22- what needs to be recovered on the fly?

23- what should be remembered?

24- which tools should be exposed?

25- which instructions are stable and which depend on the task?

26- how do I make the agent understand what is authoritative?

27~

28It's a subtle but huge change. Because when you work with agents, context is not a static block. It changes at every step.

29~

30The agent opens a file, learns something, runs a test, receives an error, updates the plan, calls a tool, discovers a dependency. With each lap he has to decide what to take with him and what to leave out.

31~

32This is engineering.

33~

34## The context is not a landfill

35~

36Templates with large context windows gave us a temptation: let's throw everything in.

37~

38It's understandable. If I have a million tokens, why should I choose?

39~

40Because even when you can put everything in, it doesn't mean everything helps. Indeed, noise has a cost. It costs tokens, it costs attention, it costs latency, it costs quality. A model can get lost in irrelevant details just like us when we open twenty tabs and no longer remember why.

41~

42Good context has a hierarchy:

43~

441. system instructions and policies;

452. specific objective;

463. current status;

474. relevant data;

485. constraints;

496. available tools;

507. track the decisions already made.

51~

52There is no need to treat everything at the same level. A user command is worth more than an old note. A failed test is now worth more than an aesthetic preference from three months ago. A security policy is worth more than a production shortcut.

53~

54Context engineering also means giving weights, not just data.

55~

56## Memory: remember less, remember better

57~

58Memory in agents is one of the most slippery topics.

59~

60As a user, you want the agent to know you. You want him to remember the tone, the plan, the conventions, the things already decided. As an engineer, you know that every persistent memory is also a risk: it can be wrong, old, too personal, too generic, unverifiable.

61~

62A useful memory should have at least three qualities:

63~

64- provenance: where does this information come from?

65- date: when was it true?

66- purpose: what type of task should it be used for?

67~

68Without these three things, memory becomes superstition.

69~

70I like to think of agentic memory as a workbook, not as a magical mind. There are temporary notes, confirmed decisions, style preferences, technical constraints, links to sources. Some things expire. Some need to be rewritten. Some must be eliminated because the agent misinferred them.

71~

72A good system must make this maintenance normal. Not heroic.

73~

74## Retrieval and tools are not the same thing

75~

76When we talk about context, we often end up immediately on RAG. Embedding, vector database, chunking, reranking.

77~

78All useful. But retrieval is only one way to bring information to the model. He's not the only one.

79~

80An agent can get context by reading files, querying an API, calling an MCP server, opening a browser, running tests, searching Slack, looking at a dashboard, asking the human.

81~

82The interesting part is deciding which route to use and when.

83~

84If the agent needs to answer a historical question, perhaps just retrieval is enough. If he has to fix a bug, he has to read real code. If he needs to understand why a deployment fails, he needs to look at fresh logs. If you need to write to a customer, you need to retrieve the tone, history and status of the ticket. If he must act on production, he must ask permission.

85~

86Context is not a database. It's a workflow.

87~

88## The good agent also knows how to ignore

89~

90A sign of maturity in agents will be the ability to say: I don't need this information.

91~

92It seems trivial, but it is very difficult. Many agentic systems accumulate. Each tool call adds text. Every error remains in the buffer. Each file read adds to the stack. In the end the model has a very long history and no map.

93~

94Compression is needed. Intermediate synthesis is needed. It needs to be structured.

95~

96Not "that's all that happened", but:

97~

98- objective still valid;

99- current hypothesis;

100- files already checked;

101- decisions made;

102- open risks;

103- next action.

104~

105This makes the agent less theatrical and more helpful. Not because he seems smarter, but because he works with a tidy desk.

106~

107## Context engineering for teams, not for prompt artists

108~

109The reason this topic interests me is that it shifts responsibility from the individual to the system.

110~

111In prompt engineering, the one who can speak to the model best often wins. In context engineering, the team that best organizes its work wins: documentation, conventions, issues, logs, tests, ownership, naming, sources.

112~

113A clean repository becomes a better context. A well-written issue becomes better fuel. An updated runbook saves tokens and anxiety. A clear changelog reduces hallucinations.

114~

115This is good and somewhat uncomfortable news. Beautiful because it rewards good practices. Inconvenient because you can't solve everything with a clever prompt.

116~

117The agents amplify the hygiene of the system they find.

118~

119## How I would apply it tomorrow

120~

121If I were to introduce context engineering into a real project, I would start from small things:

122~

123- a short and maintained project instruction file;

124- good examples of expected output;

125- a list of available tools and cases in which to use them;

126- architectural decisions written in a citable manner;

127- issue with minimum mandatory context;

128- easy to retrieve logs and tests;

129- persistent memory modifiable by humans.

130~

131Then I would measure a simple thing: how many times does the agent have to ask for clarification or goes off in the wrong direction?

132~

133If it happens often, I wouldn't add a larger model right away. I would look at the context.

134~

135## My reading

136~

137Context engineering is a bit of a bloated word, yes. But the concept is sound.

138~

139It reminds us that the intelligence of an agent is not just in the model. It lies in the environment that we prepare for him: what he sees, what he remembers, what he can do, what he is forbidden to do, which sources he recognizes as true.

140~

141The human part is this: preparing the context well is a form of care. It's telling the agent, but also the team, "I don't want you to guess, I want you to have what you need."

142~

143Less magic. Cleaner room. Agents need it as much as we do.

144~

145## Sources

146~

147- [LangChain Blog: The rise of context engineering](https://blog.langchain.com/the-rise-of-context-engineering/)

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

149- [Model Context Protocol: Introduction](https://modelcontextprotocol.io/introduction)

150- [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)

151- [OpenAI: New tools for building agents](https://openai.com/index/new-tools-for-building-agents/)

152~