How agents actually read code, why re-derivation cost has a unit, and why this doesn't go away when context windows grow.

series: Grounded Code

Second of five articles in the **Grounded Code* series. The first one showed the cost. This one shows the mechanism underneath.*

I. The receipt, and what's underneath it

In the manifesto I showed a number: 7.5x more tokens for the same feature, with the same final verification on both sides. That's the receipt. This article is about what produced it.

The short version is that code has a new primary reader, and the new reader works with a completely different set of tools, a completely different memory model, and a completely different way of recognizing patterns. The patterns we adopted over twenty years answered the old reader's needs. The cost in the new reader's mode of reading wasn't on anyone's chart, because there was no reader to charge it to.

There is now.

II. How a human reads code

For a moment, ignore the agent. Look at what your IDE has been doing for you.

When you open a feature in a clean codebase, you carry roughly five to ten files in working memory at any time. Your tooling lets you jump between them in a fraction of a second. Cmd+P, fuzzy match, you're in the file. Cmd+click on a symbol, you're at its definition. The IDE follows path aliases, computes type inference, resolves imports, highlights related symbols, all silently.

You recognize patterns by similarity. Two functions that "look like they do the same thing" register as related even if they share no literal substring. A PaymentService and a UserService register as parallel because of conceptual symmetry, not because of any string they share.

You carry the project's mental model across days. The feature you worked on Tuesday is still in your head Thursday morning. You don't need to re-derive what the system does every time you open the editor.

Domain language helps you bridge files. When you read Aggregate in one file and EntityRoot in another, you know they belong to the same DDD vocabulary even if neither imports the other. The vocabulary is in your head, not in the code.

Clean Code, DDD, Clean Architecture, hexagonal: every pattern in that family was tuned to this reader. The trade-offs they made (some indirection, some boilerplate, some abstraction) were paid in exchange for a real benefit: this reader's mental load went down.

The reader is still you. The reader is still real. But on the codebases that ship features regularly with an agent in the loop, this reader is not doing most of the work anymore.

III. How an agent reads code

An agent reading code does not scroll. It does not Cmd+P. It does not Cmd+click. It has none of the silent IDE machinery you take for granted.

What it has is three primitives:

• grep, to find files containing a literal pattern.
• glob, to find files matching a path pattern.
• read with offset and limit, to load a slice of a file into context.

That's the whole toolset for navigating a codebase. Every operation that an IDE does for you in milliseconds becomes a tool call. Every tool call costs tokens (for the call, for the result, for the model to parse the result). Every file the agent reads stays in context until something pushes it out. There is no persistent project memory. The session is the memory.

This changes pattern recognition completely. The agent doesn't see similarity the way you do. It recognizes patterns by co-located names and exact shapes. If two files have parallel filenames (user.ts and user.test.ts) and parallel structure inside, the agent will pattern-match them. If one is models/user.ts and the other is __tests__/user-tests.ts, the relationship is invisible until something explicit ties them together.

Domain language doesn't bridge files for an agent the way it does for you. If Aggregate is mentioned in domain/order/aggregate.ts and EntityRoot is mentioned in infra/repository.ts, the agent has no automatic understanding that these terms are part of the same vocabulary. It might learn the connection by reading a glossary if one exists and is in context. But the vocabulary doesn't live in the agent's head between sessions, because there is no head.

Each turn, the agent rebuilds enough of the project model to do the next action. The model is rebuilt from what's currently in context, plus what it fetches with its three primitives. Everything not in context has to be re-fetched, which means re-paid in tokens.

This is the new primary reader. None of this is a deficiency of the model. It is the structural reality of how a stateless reasoning system, equipped with grep, navigates a codebase.

IV. Three places the cost shows up

Let me make this concrete with three patterns from the original article and show what they actually cost.

A. Path aliases

// services/user.ts
import { User } from '@models/user'

export async function getUser(id: string): Promise<User> {
  // ...
}

Human path. You Cmd+click on @models/user. Your IDE knows the alias config from tsconfig.json and lands you in src/models/user.ts in one keystroke.

Agent path. The agent reads services/user.ts and sees @models/user. It does not know what that resolves to. It reads tsconfig.json. The tsconfig.json may extend a base config, so it reads that too. It identifies the paths entry that maps @models/* to src/models/*. Now it can glob for src/models/user.ts. Then it reads it.

Three file reads where the IDE did one keystroke. Multiply by every import in every file the agent has to navigate during a task.

The fix is one line of change per import:

// services/user.ts
import { User } from '../models/user.ts'

Now the path is the path. No tsconfig hop. The agent reads services/user.ts, sees ../models/user.ts, globs it, reads it. Two operations instead of three or four.

B. Deep dependency injection

function process(deps: ProcessDeps) {
  const user = deps.db.users.findById(deps.context.userId)
  deps.logger.info('processed', { user })
  deps.metrics.increment('process.success')
  return user
}

Human path. You read process(deps: ProcessDeps). You know how the app wires deps together because you wrote it. You move on.

Agent path. The agent reads process(deps: ProcessDeps). It does not know what ProcessDeps contains. It greps for ProcessDeps. It finds the interface, with eight fields, each typed as another interface. For each field used in the function body (db, logger, metrics, context), it greps for the interface definition. For each interface, it greps for the implementation. For each implementation, it may have to load multiple files to understand the actual call shape at runtime.

What started as "what does process do?" has become five to ten file reads, just to understand the four lines of code.

The fix is concrete dependencies for first-party code:

import { findUserById } from '../db/users.ts'
import { logger } from '../logging/logger.ts'
import { metrics } from '../metrics/metrics.ts'

function process(userId: string) {
  const user = findUserById(userId)
  logger.info('processed', { user })
  metrics.increment('process.success')
  return user
}

Now the function is self-evident. The imports name the actual call shape. The agent reads one file and understands.

I want to mark this case carefully, because it's the most contested in the set. Genuine multi-implementation abstractions (a StorageAdapter with S3, Local, and InMemory implementations) still earn their place. The cost they incur on the agent is real, but the benefit (the ability to swap implementations) is also real. The pattern to drop is ad-hoc DI that wraps first-party code without a multi-implementation justification. That's the version that adds five greps and gives back nothing the runtime structure didn't already say.

C. Inheritance

class PaymentProcessor extends BaseProcessor {
  // override of handle() not visible here, lives in BaseProcessor or grandparent
}

Human path. Cmd+click on paymentProcessor.handle() at the call site. The IDE jumps to the actual override location, or if there isn't one, follows the chain up.

Agent path. The agent greps for class PaymentProcessor. It reads the class definition. There is no handle() method visible. It identifies the extends BaseProcessor. It greps for class BaseProcessor. It reads that file in full. Maybe handle() is there; maybe BaseProcessor also extends something. The chain continues. Each class file gets opened in full because the agent doesn't know up front which one has the method.

To understand a single method call, the agent may read three to five class files. The MRO that your IDE renders in one click is invisible to the agent until it walks the chain itself.

The fix is composition. A function that takes the data it needs. A small file. One read instead of five.

V. Re-derivation cost has a unit

What these three examples have in common: every architectural decision now has a token receipt attached.

That's the move that matters. For thirty years, architectural cost was a soft variable. You could talk about "complexity," "cognitive load," "maintainability." These were real, but they were estimated, not measured. Two engineers could disagree about whether a layer was worth it, and there was no way to settle the argument except by accumulated experience.

Now there is. The unit is the token. Every architectural choice has a measurable receipt: how many tokens does the agent need to extend the average feature on this architecture? You can run the experiment in your own repo. You can compare the receipt across two organizations of the same code.

I want to name what we are measuring:

Re-derivation cost. The total tokens spent re-establishing a fact that the architecture didn't make immediately available. Cross-file inferences, alias hops, interface chases, MRO walks. Everything the agent has to do to know something the codebase didn't put where it could be read.

The 7.5x in the manifesto is re-derivation cost being measured. The 8.5x in cache reads is re-derivation cost compounding (the agent reloads what it already had, because something pushed it out of context). The 4.4x in output tokens is re-derivation cost spreading into the agent's own reasoning (more turns, more thinking, more rationalization).

When architectural cost has a unit, architectural decisions become testable. That changes the conversation.

VI. "But context windows are growing"

The most common objection I hear when I lay this out: "Sure, but context windows are getting bigger. 200K today, a million next year, ten million after that. Won't this whole problem just go away?"

It's a fair objection and the answer is "no, and here's why."

Context window size and attention quality are two different things. A model with a million-token context can technically read your entire repo into one prompt. The question is what the model actually does with that mass of tokens.

Attention quality on compact, self-contained contexts is what models are good at. A 4K-token window with everything the model needs and nothing it doesn't: that's where you get clean reasoning and reliable outputs. The reasoning works because the relevant facts are not buried under irrelevant ones.

Attention quality on diffuse, sprawling contexts is where things degrade. A million-token context full of cross-references, mostly-irrelevant background, and only a thin thread of what's actually needed: the model has to filter, and filtering is where mistakes leak in. The needle in the haystack problem is real even when the haystack fits.

The architectures that score well on re-derivation cost happen to be the same architectures that produce compact, self-contained contexts. Co-located feature directories. Files under three hundred lines. Imports without indirection. These principles aren't about saving raw bytes. They are about giving the model a context that's tight, relevant, and self-contained, regardless of how big the window technically is.

So no, I don't think context-window growth deprecates this. If anything, it makes the principles more durable. Because as windows grow, the temptation is to throw more of the codebase at the model. The temptation is wrong. The same principles that minimized re-derivation cost on a small window minimize attention spread on a large one.

VII. What comes next

Now we have the mechanism. The next article gets prescriptive: which specific patterns score badly on the new axis, and what to do about them.

I want to flag the framing upfront. The next article is not "delete these patterns from your codebase." It is "these patterns paid for themselves on the old axis, and the trade-off changed on the new one." Surgical, not demolition. You will keep some of them. You will drop others. The point of the article is to let you make that choice with the cost made visible.

If you want to try the experiment from the manifesto before the next article ships, do. The principle is the same: pick a feature, ask the agent to extend it, count the tokens. The receipt is the argument.

Next in the series: "What to unlearn: the most expensive patterns from the human era."