Context Engineering: Feeding the Right Knowledge to AI Agents

A clear prompt can still produce the wrong change if the agent reads an old API contract or never discovers the service that owns the behavior. Context engineering is the work of selecting, retrieving, and maintaining the information available to the model during a task.

That includes instructions, source files, data schemas (rules for the shape of data), tool results, and conversation history. A file in a repository helps only when the agent finds and reads it. Anthropic describes this broader, iterative view in Effective context engineering for AI agents.

After AI Gateways and Model Routing, this builds on Prompt Engineering: instructions define the request; context supplies the evidence needed to act on it.

Retrieve the right facts

In a system split across services, an agent working in order-service may also need the inventory API contract (the agreed request and response format), the rules for payment events, and the database change history. Reading only the local application code can hide important dependencies.

Start with a small task-specific set:

1. The code that owns the behavior and an existing implementation to follow.
2. The authoritative contract for each affected integration.
3. Applicable repository instructions and test commands.
4. The failing test, runtime observation, or acceptance criterion motivating the change.

Expand that set when the evidence points to another dependency. Keep source paths and versions so a reviewer can retrace the reasoning.

Example: the right service, the wrong contract

Suppose the agent discovers commerce-pricing but retrieves an old guide that says the browser should submit a discount percentage. The candidate pricing API instead accepts a code and returns an authoritative quote. The agent found the service successfully, but the evidence it used to implement the change was still wrong.

For this illustrative checkout task, inspect the evidence before editing:

Retrieved source	Check	Action
Old integration guide	Which API version and release does it describe?	Retain it as historical context; flag the conflict
Pricing schema at the candidate commit	Does it define code input, quote output, and error cases?	Read the relevant operations and examples
Orders consumer and contract tests	Which contract version does the candidate actually consume?	Verify compatibility before assuming migration is complete

Record the repository, commit, and source path for each decision. A newer document alone does not establish which contract governs a deployed consumer. If the schema and implementation disagree, identify the owner and resolve whether this is a defect, planned migration, or stale documentation.

Evaluate retrieval separately from implementation. Build a small task set with reviewer-identified required sources. Measure how many required sources were retrieved and how much retrieved material was relevant, then check whether the generated change actually followed those sources. Missing an authoritative contract and ignoring a contract already loaded require different fixes. The labeled source set is a bounded benchmark, not a claim to know every relevant file in the company.

Include meaning and freshness with the data

Pramod Sadalage and Prem Chandrasekaran’s Making Your Data Ready for Agentic AI distinguishes data quality, business meaning, and controlled access.

For checkout, establish these details from the contract and tool response:

Data	Meaning to establish	Check before use
Quote amount	Currency, units, and whether tax and shipping are included	Match the quote schema and agreed amount representation
Discount	Percentage or fixed amount; eligible items and exclusions	Use the current pricing policy version
Expiry	Time zone and whether the boundary is inclusive	Evaluate against the authoritative clock and validity rule
Retrieved policy	Source revision and indexed revision	Detect an index that has not incorporated a policy change

Record source timestamps separately from successful index-refresh timestamps. When required meaning or freshness is unknown, return a specific missing-data result. Schema validation can detect malformed data; business owners must still confirm its meaning.

A larger context window is useful, but not sufficient

A larger window can help with broad analysis, but available capacity and effective use are different questions. The Lost in the Middle study found that retrieval performance depended on where relevant information appeared in the tested models’ contexts. This is evidence to test long-context behavior, not a universal law about every newer model. See the original study.

Unrelated files can also introduce conflicting conventions and increase processing cost. Prefer an index of where to look, then retrieve the relevant source, rather than copying every repository into each request. Chip Huyen’s Chapter 6, “RAG and Agents” in AI Engineering discusses retrieval and agent context in more depth.

Architecture also affects what must be discovered. A change to an interface may require following implementations, registrations, and consumers that use different vocabulary from the task. Supplement text search with symbol references, import relationships, and contract ownership where available. The spec-driven development post examines architecture’s maintenance cost and the limits of current evidence.

For frontend changes, add the design system’s tokens, component guidance, and examples to the working set. Teams exploring AI-assisted design can try OpenDesign to create or refine a DESIGN.md system from brand references and use it for web prototypes. Check the generated guidance against the current frontend before relying on it.

Language coverage, training data, and token budgets

No single percentage describes English and Brazilian Portuguese across all models’ training data. Public web-crawl statistics describe collected pages; each model uses its own selected training material. For example, the Common Crawl language statistics report these shares for HTML pages in crawl CC-MAIN-2026-39:

Public figure	What it measures	What it does not tell us
English: 41.86%; Portuguese: 2.49%	Pages in one Common Crawl collection, classified by main language	Share of all internet text or any model’s training data; or a split between Brazilian and European Portuguese
Llama 3: more than 5% non-English	Meta’s disclosed share of one model’s pretraining data, across more than 30 languages	The Portuguese share or the training mix of other models

Common Crawl’s detector analyzes HTML pages and reports a primary language, so its Portuguese figure combines varieties. It is useful evidence that Portuguese is less common than English in this crawl, not a census of internet material or a measure of what every model has seen. Meta’s Llama 3 overview is one example of a model-specific disclosure; its aggregate non-English share cannot be treated as an industry-wide ratio.

The amount of text is only part of the story. The quality and range of sources, repeated material, and later training also affect results. In a 2025 study of Portuguese text collections, researchers continued training an experimental model with selected Portuguese material and improved its results on Portuguese tasks. This shows that training choices matter; it does not predict how another model will perform.

Tokens add a separate constraint. A tokenizer splits text into pieces called tokens, and different models can split the same text differently. These two short requests give the same basic instruction:

Language	Example	Tokens with OpenAI o200k_base
English	“Please explain how the number of input tokens affects the context window and API cost.”	16
Brazilian Portuguese	“Explique como a quantidade de tokens de entrada afeta a janela de contexto e o custo da API.”	21

The Brazilian Portuguese version uses 31% more tokens in this particular pair. That is an illustration, not a general Portuguese-to-English conversion rate: vocabulary, wording, and the model’s tokenizer can change the result. These counts can affect how much context fits and, for token-priced API calls, the billed input usage. Total cost also depends on the model, cached input, and generated output.

Count the full request with the target model in mind: system and developer instructions, tool definitions, retrieved files, and conversation history all use context. Use the OpenAI Tokenizer or tiktoken for OpenAI encodings, and Anthropic’s model-specific token-counting API for Claude requests. Anthropic’s count is an estimate; check actual usage after a call when available. Remove irrelevant context before translating useful facts just to reduce a count; compare quality and cost on representative tasks. The prompt-language guidance explains how to compare English and Brazilian Portuguese instructions.

Use documentation as an entry point

README.md can explain purpose, setup, and architecture. AGENTS.md can record operational instructions for compatible agents, such as build commands and local conventions. Support and discovery rules vary by tool; check whether your agent loads the file and how nested instructions apply. The AGENTS.md site describes the format and participating tools.

These files should point to authoritative artifacts rather than duplicate every detail:

# Order service

Owns order creation and order state transitions.

## Contracts
- HTTP API: contracts/orders.openapi.yaml
- Inventory API: ../inventory/contracts/inventory.openapi.yaml
- Payment event: contracts/payment.processed.schema.json
- Database schema history: migrations/

## Integration summary
- Reads stock: GET /api/v1/stock/{sku}
- Reserves stock: POST /api/v1/reservations
- Consumes payment.processed from the payment-events RabbitMQ exchange
  through the order-payments queue.

The distinction between an exchange, routing key, and queue matters. A catalog should use the same broker and terminology as the contract. If a system bridges brokers, document that bridge explicitly.

Show the important paths, including failures

Mermaid keeps diagram source reviewable alongside code, and a text-capable agent can read it without image processing. Multimodal agents can also inspect images; neither representation guarantees a correct interpretation.

The following illustrative order flow includes an out-of-stock path that a success-only diagram would omit:

sequenceDiagram
    accTitle: Order and inventory interaction
    accDescr: The web client requests an order. The order service requests a reservation. Available stock returns reservation and order IDs with status 201; insufficient stock returns status 409.
    participant Web as Web client
    participant Order as Order service
    participant Inventory as Inventory service
    Web->>Order: POST /api/v1/orders
    Order->>Inventory: POST /api/v1/reservations
    alt Stock available
        Inventory-->>Order: 201 Created, reservation ID
        Order-->>Web: 201 Created, order ID
    else Insufficient stock
        Inventory-->>Order: 409 Conflict
        Order-->>Web: 409 Conflict, unavailable items
    end

Timeouts, reservation expiry, and compensation still need their own contract decisions. A diagram is a navigational aid, not the entire specification.

Make service ownership discoverable

A small SERVICES.md file can be enough to route an investigation. Identify services independently of local folder names, and record contract paths relative to the owning repository:

Contract or capability	Service ID	Repository ID	Authoritative artifact
POST /api/v1/orders	commerce-orders	acme/orders	contracts/orders.openapi.yaml
POST /api/v1/reservations	commerce-inventory	acme/inventory	contracts/inventory.openapi.yaml
payment.processed routing key	commerce-payments	acme/payments	contracts/payment.processed.schema.json

These identifiers are illustrative. Include canonical repository URLs and responsible teams in a real catalog. A repository can contain several services, so record the source subdirectory when needed. Discovery does not grant access: the agent still needs the appropriate workspace or connector permissions.

Follow checkout across service boundaries

For checkout discounts, trace web input to the orders API and the pricing quote. Retrieve the current contracts first, then prepare editable checkouts only for components that need changes. Record candidate revisions, downstream consumers, and the acceptance cases that cross repository boundaries.

Use stable repository IDs and a supplied local checkout mapping so teammates can use different folder layouts. A catalog pointer must be discoverable through loaded instructions or configured tools. Record access failures and unknown dependencies explicitly.

The cross-repository reference guide below covers catalog bootstrap, checkout mapping, impact analysis, and coordinated delivery in detail.

Keep context current and traceable

Automate checks where the source is structured. Generate API tables from OpenAPI, validate event examples against schemas, and fail CI when committed generated documentation differs from a fresh generation.

Architecture rationale and business meaning still require review. A rule that merely checks whether a Markdown file changed cannot establish that the change is accurate.

flowchart LR
    accTitle: Documentation update workflow
    accDescr: Regenerate documentation after code or contract changes, check schemas and links, review behavior and architecture notes, then merge code and documentation.
    A["Code or contract changes"] --> B["Regenerate derived documentation"]
    B --> C["Check schemas, links, and generated diffs"]
    C --> D["Review behavior and architecture notes"]
    D --> E["Merge code and documentation together"]

For retrieved material, preserve the source, version, or retrieval time, and any known conflicts. If documentation and code disagree, surface the discrepancy and identify which contract governs the change.

Treat external documents, issue text, and tool output as task data, not as authority to override instructions or expand permissions. Retrieve only the information the task needs, and keep credentials out of context bundles.

Useful context makes a decision easier to check. The next post covers the environment that lets an agent act on it: Harness Engineering.

Reference: catalog setup and coordinated delivery

Use this guide when a task spans repositories; the core retrieval checks above also apply to a single repository.

When one feature spans several repositories

An agent cannot reliably infer system membership from a single microservice’s AGENTS.md. Imports, API clients, deployment manifests, and traces provide clues, but they may omit consumers, shared services, or dependencies reached through gateways. Use those clues to verify a documented system map rather than treating a guess as the architecture.

Separate three questions: which repositories belong to the system, which ones this task affects, and which ones the agent can access and edit. The answers need not be identical. A shared identity service might support several systems without needing a change for this feature.

Separate repository identity from local location

Team members do not need identical folder layouts. Shared documentation should identify repositories by stable IDs and canonical URLs. Each development environment can map those IDs to its own checkouts.

For example, a shared catalog might contain this entry. This is an illustrative team-defined format, not a configuration file that agents automatically understand:

repositories:
  acme/orders:
    url: https://github.com/acme/orders.git
    services: [commerce-orders]
    instructions: AGENTS.md
    contracts:
      - contracts/orders.openapi.yaml

A developer’s local workspace mapping can then look like this:

checkouts:
  acme/web: /home/alex/projects/storefront
  acme/orders: /home/alex/work/order-service
  acme/pricing: /mnt/workspaces/pricing

Another developer can use entirely different paths for the same IDs. The local mapping should stay outside shared repository metadata. A team-provided setup tool can create or discover selected checkouts, validate their Git remotes and revisions, and expose the mapping to the agent. Without such tooling, provide the mapping explicitly in the task. Do not assume an invented manifest filename will be discovered automatically.

A standardized task workspace is an alternative: a bootstrap script can prepare a temporary directory with a predictable layout for just the selected repositories. Reproducibility comes from that setup process and recorded revisions, not from expecting everyone to organize their personal folders identically.

Give each service a stable discovery entry point

Keep shared system context in a documentation repository or catalog service. Each application’s AGENTS.md can identify where to find it without using fragile paths such as ../../system-context:

## System context
- Service ID: commerce-orders
- Repository ID: acme/orders
- System: Commerce
- Shared documentation repository: https://github.com/acme/system-context
- Read SYSTEM.md, SERVICES.md, and WORKFLOW.md there for cross-repo tasks.
- Resolve local checkouts through the supplied workspace mapping.
- If shared context is inaccessible, report what is missing.
- Before editing another repository, read its applicable instructions.

The URLs above are placeholders for your organization’s locations. A link is a discovery aid, not guaranteed automatic loading or authentication. Configure a repository connector, catalog query tool, or local documentation checkout, and tell the agent how to use it. For a task, record the revision of the shared documentation that was consulted.

An AGENTS.md inside orders does not govern frontend or pricing files. Likewise, the documentation repository’s AGENTS.md governs its own files; it is not automatically a global policy. Load shared procedures deliberately and apply each target repository’s local rules. The AGENTS.md guidance describes directory-scoped instructions; exact discovery behavior still depends on the agent.

How does the agent find the catalog in the first place?

Discovery needs a starting point that the agent actually receives. A catalog existing somewhere inside the company is not enough. Configure at least one of these entry points:

Entry point	How the agent learns the location	What the team must provide
Repository instructions	The loaded AGENTS.md names the catalog or documentation repository	A maintained pointer in each participating repository
Organization or workspace instructions	The agent’s configured startup instructions identify the catalog	Tool-specific setup that actually loads those instructions
Configured catalog tool	The runtime exposes a tool with a description explaining what it searches	An installed integration, endpoint configuration, and authentication
Explicit task context	The user supplies the catalog location and access method	Enough information to retrieve the relevant entries

For an agent starting in orders, the discovery chain can be this simple:

Task: Add discount-code support to checkout
  → Load orders/AGENTS.md
  → Read its catalog pointer and service ID: commerce-orders
  → Retrieve that service's catalog entry using configured access
  → Follow system, API, and consumer relationships relevant to checkout
  → Resolve candidate repository IDs to remote sources or local checkouts
  → Read each target repository's instructions before editing

The first arrow depends on the tool: verify that it loads AGENTS.md, or explicitly ask it to read the file. Naming a catalog in that file does not install a connector, configure a server, or grant access.

If the team exposes a catalog tool, its description should explain when to use it and which identifiers it accepts. For example, a team-defined lookup_service(service_id) tool could return repository URLs, contracts, owners, and relationships; a search_services(query) tool could locate candidates when the service ID is unknown. These names are illustrative, not built-in agent capabilities. The same access can be implemented through a documented CLI or API; MCP is an optional transport.

Configure authentication in the execution environment or connector, not in AGENTS.md. A developer being signed into a catalog in their browser does not establish that an agent’s API tool can access it. Distinguish a missing entry from an authorization failure or unavailable catalog.

Keep the discovery pointer small and stable. Repository templates can include it, and a CI check can verify that it is present and references the expected location. This reduces configuration drift without copying catalog contents into every repository. Test the complete discovery path during onboarding: can the configured agent retrieve the current service’s entry and locate a known dependency?

If none of these entry points are available, the agent should report that it cannot establish the system boundary and request the catalog location or responsible team. It can still inspect local evidence, but it should not present guessed repository relationships as verified facts.

Discover broadly, retrieve selectively

Thousands of microservices do not require thousands of local clones. At that scale, use a searchable catalog of systems, service owners, repository locations, provided APIs, consumed APIs, and event relationships. For example, Backstage’s system model represents systems, components, and APIs. A catalog is an index to verify against authoritative artifacts, not proof that every dependency has been captured.

Use progressively more detailed retrieval:

1. Find candidates: Query the relevant business capability or user journey, such as checkout, instead of loading the entire catalog into the prompt.
2. Inspect boundaries: Retrieve the API schemas, event contracts, and relevant source excerpts for candidate services through available remote tools. Check both dependencies and consumers of a contract that may change.
3. Prepare the working set: Reuse or clone only repositories needed for edits, deeper investigation, or local builds. Record the chosen revisions and load their applicable instructions.
4. Expand when evidence requires it: Add another repository when a discovered dependency affects the task. Report inaccessible or unknown dependencies instead of assuming the scope is complete.

For a discount-code feature, the agent might read metadata for several services but need editable checkouts only for the frontend, orders, and pricing repositories. An unchanged inventory service may require only its contract for analysis and a test double or deployed test instance for verification.

Source retrieval and runtime setup are separate decisions. Even with three checkouts, the application may depend on additional services. Use published packages or images, contract-compatible test doubles, or an integration environment as appropriate. State which boundaries were simulated and which were exercised against real services; local mocks cannot establish full-system compatibility.

Turn the feature request into an impact map

Suppose the feature is “let customers apply a discount code at checkout.” System membership narrows the search, but the agent must still trace the behavior to determine the change set:

Repository	Responsibility in this example	Candidate change	Verification
acme/web	Collect the code and display the quote	Add input, validation messages, and totals	UI tests and checkout flow
acme/orders	Coordinate checkout and persist the accepted quote	Accept the optional code and request a server-side quote	API and persistence tests
acme/pricing	Own eligibility rules and price calculation	Evaluate the code and return the authoritative quote	Rule tests and contract tests

This is an initial hypothesis to check against source and contracts. If pricing already supports discount codes, its implementation may need no change. If another consumer relies on the order response, include compatibility checks for that consumer. The frontend should display the server’s quote rather than invent a second set of pricing rules.

Record the agreed scope in changes/checkout-discounts.md: affected repositories and revisions, contract changes, acceptance cases, unresolved decisions, and dependencies between changes. Keep the feature-specific plan there; update AGENTS.md only when ongoing working instructions change.

A starting task could be:

Implement discount-code support across the Commerce checkout flow.

Read SYSTEM.md, SERVICES.md, and WORKFLOW.md from acme/system-context
using the configured repository access. Resolve acme/web, acme/orders,
and acme/pricing through the supplied local workspace mapping; prepare
missing checkouts only when needed. Read their applicable AGENTS.md
files and trace the quote flow before deciding which repositories to edit.

Record the impact map and compatibility plan in
changes/checkout-discounts.md in acme/system-context. Implement the necessary
changes in these three application repositories, run local checks and
the cross-service checkout scenario, and report results per repository.
If another repository needs a change, identify it and explain why.

Coordinate verification and delivery

Separate repositories have separate histories and releases. Passing each repository’s unit tests does not show that their proposed versions work together. Run contract checks and an integration scenario using the actual candidate revisions, then record that version combination in the change plan.

For this example, a compatible rollout might add pricing support first, then order-service support for an optional code, and finally enable the frontend feature. Verify that old clients remain supported and define what happens during rollback. Do not assume that merging several pull requests creates an atomic deployment.

Use a branch and linked pull request for each changed repository when following a PR workflow, with one shared change record connecting them. A single agent with suitable access can work across these checkouts; separate agents are optional. The essential pieces are a shared map, explicit scope, local instructions, and evidence that the components work together.