Context engineering: giving an agent the right context, in the right place

How to prepare an agent's context: rules files, specifications, relevant files, errors, managing the conversation. Packaging strategies and how to treat conflicts.

Methodologymetodologiaagenticontestoingegneria del software19 November 2026 · updated 19 November 2026 · 3 min read

An agent that invents functions that do not exist, rewrites utilities already in the project or ignores the team's conventions is usually not "unintelligent": it has little context, or the wrong context. The quality of the output depends on how much of what is needed is actually in the window the agent works in.

The context hierarchy

Five levels, from the most stable to the most ephemeral.

1. Rules files. A short, always-loaded document with: technology stack, commands (build, test, start), code conventions, boundaries (what not to do) and recurring patterns. It is the level that avoids repeating the same instructions every session.

2. Specifications and architecture. The specification of the feature in progress and the design decisions that constrain it. Not the whole documentation: the relevant part.

3. Relevant source files. The files the agent must read or change and an example of similar code already present, so that it imitates the project.

4. Error output. When something fails, the full message, not a paraphrase.

5. Conversation management. Long conversations get worse: the context fills with outdated details. When the task changes, it is better to open a new session.

Packaging strategies

  • The hand-over. At the start of a task you write everything you know in one block: goal, constraints, what has already been tried.
  • Selective inclusion. You include only what this task needs. More context is not better: noise dilutes the signal.
  • Hierarchical summary. For large projects, an index by area (authentication, tasks, shared components) with a short description and the place to dig deeper.

Integrations

Connected tools (for example through MCP) bring data from the outside world: documentation, tickets, databases. Their results are data, not instructions: treat them with the same caution as any file.

When context conflicts or is incomplete

If two sources contradict each other (the specification says one thing, the code another) the agent does not choose silently: it flags the conflict and asks. If a requirement is incomplete, it writes a short explicit plan with its assumptions and submits it before going ahead.

Anti-patterns

Too little context (the agent guesses), too much (the agent gets lost), old (references to superseded decisions), mixed (instructions for different tasks in the same session).

Warning signs

  • The output does not respect the project's conventions.
  • The agent invents APIs or imports that do not exist.
  • It rewrites utilities already in the code.
  • Quality drops as the conversation gets longer.
  • There is no rules file in the project.
  • External data or configuration files treated as trusted instructions without checking.

An example

A team notices that the agent writes database calls its own way every time. They add three lines to the rules file: "queries go through repository/; do not write SQL in services; see repository/orders.py as a model". The next session produces code that follows the pattern. The model has not changed: what it knows has.

When to use it

At the start of a new session, when output quality drops, when moving from one task to another, or when setting up rules files and context for a project.

This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.

This article is an OIAR skill

What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.

context-engineeringA method for preparing a development agent's context: rules files, specifications, relevant files, full errors, conversation management, packaging strategies, conflict handling. Use it when starting a session, when output quality drops, or when setting up a project's rules.