Third article in the Grounded Code series. The first two established the axis. This one names the patterns that score badly on it, and the ones I was wrong about.
I. The setup
The manifesto showed the cost. The second article showed the mechanism: how agents read, why re-derivation cost has a measurable unit (the token), and why bigger context windows don't fix it. We have the new reader, the new axis, and the receipts.
This article goes prescriptive. Which specific patterns earned their place when humans were doing the reading, and now cost more than they pay back?
I want to mark the framing carefully before I start, because the answer is more interesting than "delete these from your codebase." Some patterns survive untouched. Some survive in a modified form. Some need to go. And in three places, my initial intuition was wrong, and the audit corrected me. The last section names those.
II. The deeper finding: heterogeneity, not abstraction
Before going through the patterns one by one, I want to flag the conceptual move that came out of the audit and reshaped my read of every one of them.
I started by assuming abstraction itself was the cost. Each interface, each layer, each indirection meant another grep, another file read, another re-derivation. The natural conclusion was "less abstraction, fewer hops."
That conclusion turned out to be wrong, or at least incomplete.
The cost compounds when abstractions are heterogeneous. A codebase with five different DI patterns sprinkled around (one feature uses constructor injection, another uses a service locator, a third uses a context object, a fourth uses ambient module state) charges the agent re-derivation cost on every feature. The agent has to learn each pattern fresh, every time.
A codebase with one abstraction, applied uniformly everywhere, charges the cost once. The agent reads the Layer module (or the DI container, or the service registry) once, and every subsequent feature is a constant-cost extension of that knowledge.
This is what I saw in opencode's Effect Layer pattern. Every dependency is wired the same way, in the same place, with the same shape. The pattern is abstract, even heavy. But it's also uniform. The cost is paid once and amortized.
So the rewrite of the prescription is:
The disease is heterogeneity. Uniformity dissolves abstraction cost. Reduce the number of distinct patterns in your codebase, and apply them everywhere.
Holding this in mind, the anti-patterns below are mostly cases where the pattern is hard to apply uniformly across a real codebase, which means it will be heterogeneous in practice, which means it will compound cost. Not "abstract is bad," but "this particular abstraction tends not to stay uniform, and that's what costs."
III. Premature abstraction
Looks like: three call sites that look similar get extracted into a generic helper before there's a real reason to share.
Why it worked for humans: DRY was drilled into us as a virtue. Three concrete duplications felt like an open invitation to refactor. The shared helper communicated "these things are the same."
Why it costs agents: the generic helper has to be grepped twice (definition plus each caller). Three concrete sites are self-documenting and let the agent read each in isolation. The abstraction often turns out to be wrong as soon as the fourth case shows up, and refactoring a generalized helper is harder than refactoring three concrete copies.
There's also a uniformity problem. Premature abstractions tend to leak. The shared helper accumulates flags, options, and "just this one case" branches over time. Two years later, no one wants to read it. The agent reads it in a fog and pattern-matches the wrong thing.
Rule of thumb: wait for the fourth use case before generalizing. The Claude Code source has this rule encoded into its own prompt to the model. Three duplications is not the trigger. Four is.
What to do instead: for the first three sites, copy. Each site stays small and readable. When the fourth case appears, the actual shape of the generalization is usually obvious, and the helper that emerges fits.
IV. Ad-hoc dependency injection
Looks like: functions and classes that take five to twelve interfaces in their constructor or signature, each interface defined in a separate file, wiring done at call sites or by hand.
Why it worked for humans: it made the unit testable in isolation. It communicated "this thing depends on these capabilities." It also let teams parallelize work, each owning an interface contract.
Why it costs agents: every interface is another grep before the agent knows the actual call shape. A function that takes { db, logger, metrics, clock } looks self-documenting until you realize the agent has to load four interface definitions and their primary implementations to understand what happens at runtime.
The deeper problem is heterogeneity, which I flagged in section II. Ad-hoc DI rarely stays uniform. Feature A wires deps one way, feature B another. The agent learns each wiring fresh.
The exception that matters. Uniform DI works. opencode uses Effect's Layer pattern across the entire codebase: every dependency wired the same way, in the same place. Once the agent has read the Layer module, every feature is a constant-cost extension. The cost was paid once.
So the prescription isn't "drop DI." It's "if you have DI, make it uniform, or drop it." The version to drop is ad-hoc, heterogeneous DI that wraps first-party code without a multi-implementation justification.
What to do instead: concrete dependencies plus integration tests. The function imports what it uses. The test runs the real thing where possible. Reserve interfaces for genuine multi-implementation cases (a StorageAdapter with S3, Local, and InMemory implementations is fine; the abstraction is paying its way).
V. Codegen from schema
Looks like: an OpenAPI, GraphQL, or Protobuf schema, plus a build step that generates TypeScript types and client functions into src/generated/.
Why it worked for humans: single source of truth. "Free" types from the schema. Less hand-written boilerplate.
Why it costs agents: when the agent needs to add a field, it now has to identify (1) the schema source, (2) the codegen rule, (3) the build step, (4) the regen command, and (5) avoid editing the generated file directly. Five hops instead of one. The generated file is also typically gitignored or huge, both of which break the agent's mental model of the repo.
The "saves engineering time" argument is largely empty when the engineer is an agent that types at the speed of light. The original cost was human keystrokes. That cost is now near-zero. The cost that replaced it is the agent's re-derivation work across the codegen toolchain.
The exception that matters. Wire formats that humans should not author by hand (Protobuf descriptors, ABI bindings, large enum tables from external authorities). For these, keep the generated code committed and obvious. Don't bury it under .gitignore.
What to do instead: hand-write the boilerplate. Agents handle boilerplate well, in seconds. Reserve codegen for cases where the generated output is genuinely not human-authorable.
VI. Macros and decorators with implicit behavior
Looks like: @Injectable(), @Controller('/users'), @AutoMap, or any decorator that mutates the class it sits on without naming what it does at the call site.
Why it worked for humans: declarative. Reduced boilerplate. "Just works" if you knew the framework.
Why it costs agents: the behavior comes from somewhere not co-located. The agent reads @Controller('/users') and has to know what @Controller does, where it's defined, and what it injects into the class at runtime. Pattern-matching on identifiers fails when the meaning is elsewhere.
The deeper issue is that decorators are often conditional on framework state the agent can't see. Whether a method gets wrapped, whether a property gets serialized, whether a route gets registered: all of this can depend on runtime ordering, module load order, or other decorators on the same class. The agent reads the source. The behavior is at runtime. The two don't match.
The exception that matters. Decorators that are purely declarative and have no behavioral side effects (a @deprecated marker, for example, or a pure type-level brand) are fine. They're metadata, not behavior.
What to do instead: an explicit registration call at module level. The agent sees the registration in the same file as the class and infers the wiring directly.
// Instead of:
@Controller('/users')
class UserController { ... }
// Do this:
class UserController { ... }
router.register('/users', UserController)
The registration line is right there. The agent reads one file and knows what's going on.
VII. Patterns I'll mention briefly
I covered three of these in detail in the second article. Reposting the headline cases here for completeness; refer back for the full mechanics:
Path aliases (
@utils/foo). Every import becomes a two-step resolution. Use relative paths with explicit extensions. The one exception is workspace package boundaries in a monorepo, where the alias is the package name itself.Inheritance trees. Method resolution order is invisible at the call site. The agent has to walk the chain. Use composition: small functions, small types, explicit calls.
Living style guides disconnected from code. A
STYLE.mdwith prescriptions that the actual code doesn't follow competes for the agent's attention. Encode style in lint config that fails the build, or in.claude/rules/style.mdthat walks-discovers. The agent reads the code, not the guide.
VIII. What I was wrong about
This is the part of the article I owe the reader, because the audit didn't only confirm my hypotheses. It also corrected three of them.
1. Strict 300-line file limit. I expected to find a hard rule across all three codebases. I didn't. pi has a 3,110-line file with an explicit defense in its AGENTS.md: this is an orchestrator, it benefits from being read top to bottom, it's not feature code. The rule survives as a soft preference for feature files, not as a hard cap. Orchestrators, generated code, and large data tables can be larger.
2. Strict no-DI. I framed DI as an anti-pattern early on. The audit showed opencode using Effect's Layer pattern uniformly across the codebase, and it works. The cost is paid once. The rule survives as "drop ad-hoc, heterogeneous DI," not as "drop DI." Uniform DI is fine. The disease was heterogeneity, not abstraction.
3. Build-time feature flags. I expected convergence on one pattern (probably Bun's feature() constant, since that's what Claude Code uses). The three codebases diverged. Claude Code uses build-time constants. opencode uses runtime config. pi uses environment-gated branches. There's no agent-friendly consensus here, and probably the pattern is dominated by deployment constraints, not agent ergonomics.
If you spotted other things I have wrong, that's exactly the kind of feedback the series is asking for. The thesis improves when it gets falsified in public.
IX. What's next
We now have the patterns. The next article goes to the central artifact that makes the whole system work: the <feature>.spec.md document that sits next to the code, gives the agent a ground truth one read away, and carries the field tests-first never had: out_of_scope.
If you want to start applying any of this before the next article ships, the cheapest move is the one from article 1: pick a feature, co-locate everything about it in one directory with parallel names, and watch what happens to your agent's token consumption. The receipts are the argument.
Next in the series: "The central artifact: spec.md and the field that tests-first never had."
Top comments (0)