An agent can see an open file and still miss the goal, architectural constraint, or reason an earlier attempt failed. Context engineering closes that gap by designing, selecting, structuring, and maintaining the information supplied to an AI system. Unlike prompt engineering, which concentrates on phrasing instructions, it addresses the surrounding information environment: sources, ordering, detail, and relevance. section 1.4.1 section 3.0
Watch for four context failures before adding more material:
- Vacuum: too little context leaves the agent to guess. section 3.0
- Context rot: too much information can obscure what matters. section 3.0
- Poisoning: stale or incorrect information steers the agent toward flawed answers. section 3.0 section 3.5.4
- Lost in the middle: relevant information is present but placed where the model stops paying attention. section 3.0
Label code by its role
A prompt containing an authentication service, a user class, and a custom error can leave the agent guessing about their responsibilities. Label the user class as a persistence entity and identify the service and repository layers. That framing helps prevent the service from querying the database directly or treating the entity as a plain dictionary. Generated code still needs review. section 3.2.1 section 3.2.2 section 1.4.1
Agents can retrieve files, reorder results, and compress conversation history, but automation does not make the sources trustworthy. Ranking may miss what matters, and lossy compaction can drop an instruction given only once. Pin important files when necessary, and keep the project's documentation and examples current. section 3.5.4
Cut context ballast
One rules-file audit reduced an 8,200-token file to 2,800 tokens. Architectural guidance and testing examples moved into separate documents for use when relevant; contradictions and redundant formatter instructions were removed. A second agent instructions file shrank from 4,000 to 1,200 tokens by removing information discoverable in the repository and README. section 9.2.3
Listing 9.1 Rules file audit
General coding style # Section added by Alex (month 1) You are a senior TypeScript developer #400 tokens of personality instructions React patterns # Section added by Sarah (month 2): When writing React components, always use functional components… #600 tokens, 50% overlaps with Alex's section Error handling # Section added by Marcus (month 3) For all error handling, use our custom ErrorBoundary… # 800 tokens, includes three full code examples Testing # Section added by Dave (month 3 When writing tests, use Jest with React Testing Library # 1,200 tokens, includes five example test patterns API patterns # Section added by Sarah (month 4) For API calls, use our useApiQuery hook… # 500 tokens, contradicts Alex's section on fetch patterns (...)
The audit listing shows how overlapping guidance, long examples, and contradictions accumulate in a shared rules file. section 9.2.3
Make upkeep a practice, not a one-time cleanup: record useful discoveries at the end of a session, then periodically check rules for unused, duplicated, or contradictory guidance. Context gives an agent a better basis for work; tests and verification remain separate safeguards. section 9.1.3 section 10.8






