Overview
A coding agent is only as effective as the context it carries into the conversation. Feed it the wrong files and it hallucinates APIs that do not exist. Feed it too many files and critical details drown in noise. Feed it too few and it reinvents logic that already lives three directories away. This chapter treats context engineering as a first-class engineering discipline: the systematic construction, compression, and retrieval of the information a language model needs to act correctly on a large codebase.
We begin by quantifying why context is the bottleneck for coding agents (Section 11.1), then build the chunking and summarization machinery that compresses code into context-friendly units (Section 11.2). Section 11.3 introduces retrieval-augmented code generation, combining embedding search, BM25, and hybrid ranking to surface the right code at the right time. Finally, Section 11.4 assembles these pieces into a working repository intelligence layer that scales to codebases of 50,000 lines and beyond.
The ideas here connect backward to the prompt construction techniques of Chapter 10 and forward to the MCP server architecture of Chapter 12, where the intelligence layer becomes a tool that agents call through the Model Context Protocol. The Discovery Workbench, introduced in Chapter 6, gains a repository intelligence module in Section 11.4 that every subsequent chapter builds upon.
Prerequisites
This chapter assumes you have read Chapter 8: Foundations of AI-Assisted Software Engineering (for the mental model of how LLMs process code) and Chapter 10: Prompting to Programming (for prompt construction patterns). Familiarity with Python, basic linear algebra (dot products, cosine similarity), and introductory information retrieval concepts (TF-IDF, inverted indexes) will be helpful. If you need a refresher on embeddings and vector spaces, see Chapter 26.
Learning Outcomes
- Quantify the context bottleneck: why token limits, attention decay, and information density make naive "dump everything" strategies fail.
- Parse source code into meaningful chunks using tree-sitter, and summarize those chunks with docstring extraction and LLM-generated summaries.
- Build a hybrid retrieval system combining dense embeddings (sentence-transformers), sparse retrieval (BM25), and structural signals (import graphs).
- Formulate context selection as a knapsack optimization problem and solve it with greedy and dynamic-programming approaches.
- Construct a complete repository intelligence layer using tree-sitter, ripgrep, sentence-transformers, and pgvector.
- Integrate the intelligence layer into the Discovery Workbench as a reusable service for downstream coding agents.
Sections
11.1 Why Context Is the Bottleneck
Token limits versus codebase size. Attention decay and the lost-in-the-middle problem. Information density of code versus prose. Repo structure signals: file trees, import graphs, symbol tables. The context budget as a scarce resource.
11.2 Chunking and Summarization
Syntactic chunking with tree-sitter. Semantic chunking by logical units. Hierarchical chunking for nested structures. Summarization via docstring extraction, signature condensation, and LLM-generated overviews. Building a chunk store.
11.3 Retrieval-Augmented Code Generation
Dense retrieval with code embeddings. Sparse retrieval with BM25. Hybrid search and reciprocal rank fusion. Structural re-ranking with import graphs. Context budget as a knapsack problem. Evaluation metrics for code retrieval.
11.4 Building a Repository Intelligence Layer
Recipe: assembling tree-sitter, ripgrep, sentence-transformers, and pgvector into a repository intelligence service. Indexing pipeline, query interface, and integration with the Discovery Workbench. Performance benchmarks on a 50k-LOC codebase.
Bibliography
Foundational Papers
The landmark study showing that LLMs attend most strongly to the beginning and end of their context window, with significant degradation for information placed in the middle.
The benchmark that revealed how critically context retrieval quality affects coding agent success rates on real repository issues.
Introduced data-flow-aware pre-training for code representations, showing that structural information dramatically improves code understanding.
Books
The classic information retrieval textbook covering TF-IDF, BM25, and inverted indexes; essential background for code search systems.
Tools & Libraries
An incremental parsing library that builds concrete syntax trees for source code in dozens of languages, used throughout this chapter for syntactic chunking.
A blazing-fast line-oriented search tool that respects .gitignore rules, used as the text search backbone in the repository intelligence layer.
The Python library for computing dense vector embeddings with pre-trained transformer models, used for semantic code search in Section 11.3.
A PostgreSQL extension for vector similarity search, providing the persistent embedding store in the repository intelligence layer.
A Python implementation of the BM25 ranking algorithm, used for sparse keyword-based code retrieval.
Tutorials & Surveys
Demonstrates iterative retrieval-and-generation for repository-level code completion, a key pattern for context engineering.
Proposes Repo-Level Prompt Generator (RLPG), which learns to compose prompts from repository context for code completion.
A benchmark specifically designed to evaluate cross-file code understanding, directly testing the retrieval quality that context engineering aims to optimize.