What is context engineering for AI coding agents?

Context engineering treats what an agent can discover about a codebase as platform infrastructure rather than as a prompting technique. On a repository of any size the binding question is not how a request is worded but how the agent locates the relevant files among tens of thousands, how current that knowledge is, and whether every agent gets the same answer. Those are infrastructure questions with the same shape as build caches.

What does a semantic code index give an agent that grep does not?

Grep matches strings. A semantic index such as SCIP, the Protobuf-based format Sourcegraph announced in 2022 as a replacement for LSIF, records definitions, references and implementations, so an agent knows that a method in one file is defined in a second, overridden in a third, and called from nine places, while forty other occurrences of the same word are unrelated. Once indexed, the result is a code graph that can answer what breaks if a signature changes.

Do larger context windows remove the need for retrieval?

No, for two independent reasons. Sending an entire repository on every request for every agent is an unbounded cost for a bounded benefit. And model performance degrades measurably as input grows: the peer-reviewed Lost in the Middle study found accuracy dropping when the answer sat mid-context, and NoLiMa found most models falling below half their short-context baseline at 32K. Relevance still pays, so retrieval still pays.

Context Engineering

Treating agent context as platform infrastructure - semantic indexing, code graphs, and shared index services that many agents can query at once

Context Is Infrastructure, Not a Prompting Trick

The question is not how to word a request. It is what the agent can find out before answering it.

Most writing about context engineering treats it as an extension of prompt engineering - a matter of phrasing, examples, and instructions. That framing misses where the difficulty actually lives. On a repository of any real size, the binding question is not what you put in the prompt. It is how the agent locates the twenty relevant files among forty thousand, how current that knowledge is, who paid to compute it, and whether the answer is the same for every agent on the team.

Those are infrastructure questions. They have the same shape as build caches and artifact registries: expensive to compute, cheap to reuse, wasteful to duplicate per developer, and stale the moment someone pushes. An organization running many agents against a shared codebase is running a retrieval workload, and retrieval workloads belong in the platform.

This is also where the economics bite. If every agent container rebuilds its own understanding of the repository on every run, you pay for that work once per agent per run, in wall-clock latency and in tokens. If the platform computes it once and serves it, you pay once and amortize across everyone. That is the entire argument for putting indexing where platform engineering already lives rather than on each developer's laptop.

Expensive to Compute

A full semantic index of a large repository is a compile-scale job. Doing it per agent, per container, per run is the same mistake as giving every developer a cold build cache.

Cheap to Share

One index can serve every agent, every IDE, and every code search query in the organization. The marginal cost of the second consumer is close to zero.

Stale Immediately

Every push invalidates part of it. Freshness policy is the central design decision, and the one most likely to be skipped until it causes a confusing failure.

What a Semantic Index Gives an Agent That Grep Does Not

The difference between matching text and knowing what a symbol is

Grep finds strings. A semantic index knows that process in one file is a method on a class defined in a second file, overridden in a third, and called from nine places - and that the forty other occurrences of the word are unrelated. For an agent deciding what to change, that distinction is the difference between a targeted edit and a plausible-looking mess.

SCIP: a portable index format

SCIP is a Protobuf-based code indexing format originally built at Sourcegraph and announced in June 2022 as a replacement for LSIF. It records definitions, references, implementations, and hover documentation in a schema an indexer emits once and any tool can consume.

Static types from a machine-readable Protobuf schema, which LSIF did not provide
Human-readable symbol names rather than opaque numeric IDs, which makes indexers far easier to debug
Substantially smaller output - Sourcegraph reports LSIF indexes averaging around 4x larger gzip-compressed
Sourcegraph reported a 10x CI speedup replacing lsif-node with scip-typescript

LSIF support in Sourcegraph has since been fully deprecated and removed. The project now lives under its own organization at github.com/scip-code/scip with a steering committee; Sourcegraph sponsors it and may appoint members. Known adopters include Sourcegraph, Mozilla's Searchfox, rust-analyzer, and Meta's Glean. Performance figures here are Sourcegraph's own, published while promoting a format it authored.

Tree-sitter and repository maps

Tree-sitter, created by Max Brunsfeld, describes itself as "a parser generator tool and an incremental parsing library" that builds a concrete syntax tree and updates it efficiently as a file is edited. Incremental is the operative word: it is cheap enough to re-run on every keystroke, let alone every push.

The best-documented application is the repository map. Aider builds one by parsing every file for its symbols and then, per its documentation, "analyzing the full repo map using a graph ranking algorithm, computed on a graph where each source file is a node and edges connect files which have dependencies".

The result is a compact, budgeted summary - Aider defaults to roughly a thousand tokens - that tells the model what exists and how it connects, without shipping the source. That is a very different artifact from a pile of retrieved chunks, and for orientation it is usually the better one.

From index to code graph

Once definitions and references are indexed, you have a graph: symbols as nodes, calls and imports and implementations as edges. That unlocks retrieval queries no chunk store can answer - what breaks if this signature changes, what is the transitive blast radius of this module, which tests actually exercise this path. An agent that can ask those questions produces smaller and better-targeted diffs, which is precisely the intervention the code review bottleneck needs.

Embeddings, Symbols, and Agentic Search

A genuinely contested question where both sides have published numbers

The common claim is that naive vector retrieval over source code underperforms symbol-aware or agentic retrieval. The evidence broadly supports that as a statement about naive retrieval, and it is worth being precise about what has actually been measured, because there is a serious counter-position with numbers of its own.

Source	What it found
Agentless arXiv preprint, 2024	Prompting-based retrieval located the ground-truth file in 78.7 percent of cases against 67.7 percent for embedding-based retrieval. Combining both reached 81.67 percent - the two are complementary, not rivals.
SWE-bench Jimenez et al., ICLR 2024. Peer reviewed.	Sparse BM25 retrieval recovered the oracle files in only 29.6, 44.4 and 51.1 percent of instances at 13k, 27k and 50k token limits. Claude 2 resolved 1.96 percent of issues with BM25 context against 4.80 percent with oracle context - retrieval quality dominated the result.
CodeRAG-Bench arXiv preprint, 2024	On SWE-bench, the best available retrieval gave a 21-point improvement over no retrieval, but left a 9-point gap against gold context. Retrieval helps a lot and is still the limiting factor.
Cursor: semantic search Cursor, November 2025. Vendor-published.	The counter-position. Cursor reports semantic search delivering on average 12.5 percent higher accuracy in answering questions, and a 2.6 percent improvement in code retention on codebases of 1,000 files or more. Cursor sells a product built on this index.

The case against standing indexes

In "Effective context engineering for AI agents" (Anthropic, September 2025), Claude Code is described as a hybrid: instruction files are loaded up front "while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time, effectively bypassing the issues of stale indexing and complex syntax trees". The same write-up concedes the cost plainly - "runtime exploration is slower than retrieving pre-computed data" - and endorses hybrid approaches rather than pure exploration.

Cline put it more pointedly in May 2025, arguing that chunked retrieval is like "trying to understand a symphony by listening to random 10-second clips", and that "an index, by definition, is a snapshot frozen in time". Cline sells an agent that does not index.

The most telling data point comes from a vendor with every incentive to argue the other way. In "How Cody understands your codebase" (Sourcegraph, February 2024), Sourcegraph explained why it built embeddings for Cody and then removed them: third-party data transmission, index-maintenance complexity, and that searching vector databases for codebases with more than 100,000 repositories is complex and resource-intensive.

Where that leaves a platform team

The defensible reading is that chunk-and-embed alone is weak on code, that symbol-level and graph-aware retrieval is stronger, that live exploration avoids staleness at the cost of latency and tokens, and that hybrids beat any single method - which is exactly what the Agentless numbers show.

Practically: give agents a fresh symbol index and a graph to query, let them explore at runtime for anything the index cannot answer, and treat embeddings as one retriever among several rather than the architecture. Then measure it on your own repositories - every number above comes from someone else's.

Bigger Context Windows Do Not Remove the Need for Retrieval

"Put the whole repository in the prompt" fails on relevance and on cost

Every context window expansion revives the idea that retrieval is a temporary workaround. It is not, for two independent reasons. The first is cost: paying to send an entire repository on every request, for every agent, is an unbounded bill for a bounded benefit. The second is that model performance degrades as inputs grow, and the degradation is measurable.

Position matters

Liu et al., "Lost in the Middle", TACL vol. 12, 2024. Peer reviewed.

With 20 documents in context, GPT-3.5-Turbo scored 75.8 percent when the answer was first, 63.2 percent when last, and 53.8 percent when in the middle. Closed-book, with no documents at all, it scored 56.1 percent - mid-context retrieval performed worse than no retrieval.

Length degrades reasoning

NoLiMa, ICML 2025. Peer reviewed.

At a 32K context, 11 of 13 evaluated models dropped below 50 percent of their strong short-context baselines. GPT-4o fell from an almost-perfect 99.3 percent baseline to 69.7 percent.

Claimed is not effective

RULER, NVIDIA, COLM 2024. Peer reviewed.

RULER reports claimed and effective context lengths separately. GPT-4-1106-preview claimed 128K and was assessed effective to 64K; Llama-3.1-70B likewise claimed 128K against an effective 64K.

Chroma's Context Rot report (July 2025, 18 models tested) makes the general version of the point: "even on tasks as simple as non-lexical retrieval or text replication, we see increasing non-uniformity in performance as input length grows". It is a company technical report rather than a peer-reviewed paper, and Chroma sells a vector database, so weigh it accordingly - but its direction agrees with the peer-reviewed work above. The useful mental model, as Anthropic puts it, is a performance gradient rather than a hard cliff. Relevance still pays, which means retrieval still pays.

Running Indexing as a Platform Service

Freshness, cost, and the monorepo problem

The operational shape is a familiar one: index on push, incrementally, into a store that agents query over an API. Full re-indexing is the fallback, not the routine. The design decisions worth making deliberately are freshness policy, blast radius of an incremental update, and whether the index is per-repository or spans the whole graph.

Example: an incremental indexing pipeline

# Triggered on push. Incremental by default, full rebuild on schedule.
index_pipeline:
  trigger:
    on_push: true
    full_rebuild: "weekly"        # guards against incremental drift

  stages:
    - name: changed-set
      # Only re-parse what moved, plus anything that referenced it
      compute: "git diff --name-only $BASE..$HEAD"
      expand: reverse-dependencies  # from the existing graph

    - name: parse
      tool: tree-sitter             # fast, incremental, many languages
      emit: symbols

    - name: semantic-index
      tool: scip                    # definitions, references, implementations
      emit: index.scip

    - name: publish
      store: index-service
      key: "${repo}@${commit}"
      # Agents pin to a commit so retrieval is reproducible
      retain_versions: 10

  serving:
    # One index, many consumers - agents, IDEs, code search
    api: grpc
    queries:
      - find-definition
      - find-references
      - callers-of
      - blast-radius
    staleness_budget_seconds: 300   # alert if the index falls behind

Illustrative sketch rather than a product configuration. The load-bearing ideas are the reverse-dependency expansion, pinning retrieval to a commit so an agent run is reproducible, and treating index lag as an alertable service level.

Freshness vs Cost

Indexing every push on a busy monorepo is expensive; indexing hourly means agents work against a repository that no longer exists. Set an explicit staleness budget, expose the index commit to the agent, and let it fall back to live exploration when it detects drift.

Monorepo vs Multi-repo

A monorepo gives you one coherent graph and one enormous indexing job, where incrementality is essential rather than optional. Many small repositories index trivially but leave cross-repository edges - the ones that matter for blast radius - unresolved unless you build a federation layer.

Access Control

An index is a queryable copy of the source. It must inherit repository permissions, or it becomes an elegant way to leak code an agent's invoking user could not otherwise read. Treat index access as a first-class concern alongside governance.

Curated Context and Generated Context

An index tells an agent what the code is. It cannot tell it what the team decided.

Generated indexes are complete, current, and mechanical. They capture structure perfectly and intent not at all. No amount of parsing reveals that a module is deprecated but not yet deleted, that a service must never call another directly, or that a naming convention exists for a reason. That knowledge is human-written, and it belongs in curated files that live beside the code.

AGENTS.md

AGENTS.md is a plain-Markdown convention for instructions an agent should read before working in a repository - build commands, conventions, testing expectations, things not to touch. The figure published on the project site is adoption by more than 60,000 open source projects, corroborated by a Linux Foundation announcement in December 2025. The project is now stewarded by the Agentic AI Foundation under the Linux Foundation.

One portability caveat worth knowing: Claude Code reads CLAUDE.md rather than AGENTS.md, and Anthropic's documentation recommends importing the latter from the former. Support is broad but not uniform, so verify against your own toolchain rather than assuming.

How far to take it

A 2026 preprint, "Codified Context: Infrastructure for AI Agents in a Complex Codebase" (Vasilopoulos), documents an unusually thorough version: a constitution file, nineteen domain-expert agent definitions, and a 34-document knowledge base retrieved over MCP, applied to a 108,000-line C# system across 283 development sessions.

Preprint, and read it for the architecture rather than the result. It is a single-author, single-project experience report with no control group, no baseline, and no reported efficacy figure. It shows what a maximal curated-context setup looks like; it does not establish that the approach outperforms a simpler one.

The failure mode of curated context

Hand-written context rots faster than generated context, and it rots silently. An index that falls behind can be detected automatically by comparing commits; an AGENTS.md that describes a build system replaced eight months ago looks exactly like one that is correct, and it will confidently mislead every agent that reads it. Review curated context on a schedule, keep it short enough that reviewing it is realistic, and prefer pointing at generated sources over restating them. Vendor writing on this subject is worth reading with the disclosure attached: Sourcegraph's agentic coding guide (Matt Tanner, 2026) argues that "agentic coding's productivity ceiling is set by context, not model quality", and describes an "80% problem" in which agents complete the visible majority of a task and silently miss what falls outside their context. It is a sharp framing, published by a company that sells retrieval.