# Designing the Project Knowledge Layer for Coding Agents: The Underestimated Piece of the User Harness

The agent answers the wrong question, edits the wrong files, burns a pile of tokens, and still spins in place. The first reflex is often “the model isn’t strong enough” or “this agent isn’t good enough.” The more common bottleneck sits elsewhere: the context it sees is both large and scattered.

Strong AI coding depends not only on the model and the agent runtime, but on the user harness you build around them. Inside that harness, one piece is easy to underestimate and yet directly drives accuracy and cost—the project knowledge layer: where knowledge comes from, how it is stored, and how it is retrieved.

User Harness and the Project Knowledge Layer

In one line: Agent = Model + Harness. Products ship part of the harness (system prompt, retrieval, orchestration). Users still build an outer harness—rules, permissions, skills, verification loops, and the knowledge-supply design this article focuses on.

In the Harness Engineering framing, the knowledge layer is mainly a guide (feedforward): it raises the odds of getting it right before the agent acts. The Context dimension asks what the agent knows; the project knowledge layer asks the upstream question—what is worth knowing, and in what form it should enter context.

This post does not cover the full five-dimension harness. It digs into one slice: how to turn “what lives in the repo” into a knowledge surface the agent can afford and can use accurately.

From Code Warehouse to Project Knowledge Surface

For a long time, an engineer’s mental model of a repository was roughly: code plus a thin README. Humans read the code, remember the conventions, and fill in context in their heads.

In the AI coding era, a repo is no longer only a code warehouse. Beyond source, you at least have:

• Specifications: under SDD, the spec is one source of truth (see Spec as the source of truth), but specs are one knowledge type—not the whole layer
• Decisions and domain knowledge: why the design looks this way, where the boundaries are, which pitfalls must not be repeated
• Indexes and pointers: where to find deeper material, instead of stuffing full text into always-on context

The real shift: the repository becomes a knowledge orchestration surface—keep controllable, lightweight, high-signal assets locally; load volatile or external knowledge on strategy when needed. The goal is not to move everything into the repo, but to make the repo the agent’s navigation map.

Principle 1: Minimize Load

The first principle is simple: put as little as possible into the agent’s attention budget.

Anthropic describes context engineering as finding the smallest high-signal set of tokens that maximizes the chance of the desired outcome. Dumping everything into CLAUDE.md / AGENTS.md / docs/ looks “complete,” but it mostly creates noise—cost goes up, hit rate goes down, and retrieval paths scatter.

Prefer shrinkable storage:

Store	Don’t store
Indexes, tables of contents, one-line summaries	Long documents that can be re-read on demand
Stable conventions and hard constraints	Interface details that change every week
Pointers to deeper material	Encyclopedias “just in case”

In practice, a lightweight Repo Wiki beats a documentation stew. Andrej Karpathy’s LLM Wiki pattern ingests sources into cross-linked markdown pages; the agent does the bookkeeping while the human curates sources and asks questions. Products such as Qoder’s Repo Wiki similarly extract structured knowledge from the codebase and keep revising it—distill, don’t dump.

The same logic as progressive disclosure: the always-on layer is identity and index (a lean CLAUDE.md); task-specific detail expands via skills or path-scoped rules. See Nine types of Claude Code Skills.

Principle 2: On-Demand Fetch = Lazy Loading

Every programmer knows Lazy Loading: don’t load by default; load when needed. The project knowledge layer should share that mindset.

Not all knowledge belongs in the repo, and even less belongs in the “read every session” layer. Volatile data, external system state, large document stores, tickets, and monitoring are better pulled through tools when required. What the repo should hold is the loading strategy: where to fetch, when to fetch, and at what granularity—not the full payload laid out in context ahead of time.

That matches Anthropic’s just-in-time retrieval: the agent keeps lightweight identifiers (paths, queries, links) and pulls data into context at runtime. For external platforms, MCP is the contract—but remember “don’t install everything”: a pile of MCP servers is Lazy Loading with a directory that never stops competing for attention.

A simple contrast:

	Eager (anti-pattern)	Lazy (preferred)
In-repo	Paste full external docs	Store MCP/command and query conventions
Session start	Preload everything that “might help”	Carry only the index and hard constraints
During the task	Context is already bloated	read / call tools on demand

Minimize load governs how heavy the always-on layer is; Lazy Loading governs when everything else appears. Together they make knowledge supply shrinkable.

Principle 3: Bounded Taxonomy

Shrinkage and lazy loading still need one more piece: how paths are cut. Without boundaries, retrieval feels like “everything is somehow related”—even small pages get lost in the wrong tree.

Give the agent an explicit classification language (in the wiki schema or AGENTS.md):

1. DDD bounded contexts — split directories by domain boundaries so “payments” and “notifications” don’t share one mushy concept space
2. Ontology awareness — separate entities, concepts, relations, and decisions; stable page types make cross-links structural
3. MECE — partitions that are as mutually exclusive and jointly complete as practical, reducing overlapping tags and orphan pages

Karpathy’s wiki constrains shape with page types such as summary / entity / concept; Qoder’s Repo Wiki uses structured docs for architecture and module relationships. You need not copy a product; you need an executable classification contract: agents that file and retrieve by contract beat free-form docs/ sprawl.

Taxonomy is not decoration. It is what makes retrieval paths converge—and what lets the knowledge layer work as a real guide.

Anti-Patterns and a Minimal Action List

Anti-pattern	Better move
Giant CLAUDE.md / AGENTS.md	Always-on layer as index + hard constraints; details live elsewhere
Index-less wiki / catch-all docs/	Fix taxonomy first, then ingest; lint broken links and orphans
MCP/tools installed because they “might help”	Few and precise; descriptions state when to call
Specs, meeting notes, and raw monitoring all in-repo	Specs in the source of truth; everything else as pointers + Lazy Loading

If you only do four steps:

1. Define the knowledge taxonomy (context boundaries + page types)
2. Write the minimal always-on layer (identity, constraints, index)
3. Turn the rest into pointers or MCP/tool strategies
4. Treat “knowledge-layer lint” as a harness sensor: broken links, duplicates, and stale summaries get swept regularly—by a human or an agent

Closing

The coding agent matters. What matters more is the user harness you build for it. Inside that harness, the project knowledge layer decides whether the agent “sees” a clear map or a junk drawer.

Upgrading the repository from a code warehouse to a project knowledge surface is not about piling on more documents. It is about three executable principles: minimize load, Lazy Loading for on-demand fetch, and a bounded taxonomy. Get those right, and knowledge becomes a guide—not noise.

References

• Birgitta Böckeler, Harness engineering for coding agent users, Martin Fowler, 2026
• Anthropic, Effective context engineering for AI agents
• Andrej Karpathy, LLM Wiki
• Qoder, Repo Wiki