The Grounded Code series final article, published on dev.to by jucelinux, proposes 10 principles across 3 clusters to reduce AI coding agent re-derivation cost. The clusters—locality, contracts, quarantine—map directly to the three axes where agents pay the highest cognitive overhead.
Key facts
- 10 principles across 3 clusters: locality, contracts, quarantine
- Files under ~300 lines for agent-modifiable code (soft limit)
- One codebase had a 3,110-line orchestrator file
- Glob src/feature/feature.* returns all three files per feature
- Types carry contracts; prose docs do not
The unique take: codebases designed for agentic reading
The Grounded Code series, building on five prior articles covering cost, mechanism, patterns to drop, artifact, and workflow, culminates in a set of 10 principles that treat the AI coding agent as the primary reader. The central insight: when an agent re-derives context, it's usually because (1) the thing it needs isn't where it expected, (2) the contract it needs to honor isn't visible from the file it's reading, or (3) an exception to a pattern is invisible until it bites. These principles remove cost on each axis.
Locality (1 to 4)
1. Co-locate by feature, not by layer. Every file related to one feature lives in one directory. The agent finds everything about a feature with a single glob. The opposite—layered layout (src/controllers/payment.ts, src/services/payment.ts, src/repositories/payment.ts)—forces the agent to grep three directories and reconstruct the feature mentally from fragments. Only top-level layers that survive are bootstrap/, lib/, config/, possibly vendor/.
2. The triplet per feature: implementation, test, spec. Every feature carries three files with parallel names: <feature>.<ext> (implementation), <feature>.test.<ext> (tests as specifications), and <feature>.spec.md (markdown contract with frontmatter). The glob src/<feature>/<feature>.* returns all three. The three files reference each other: the spec's verification block names test commands, test names match invariants in the spec, and exported names match the spec's public_api field.
3. Imports use full paths with explicit extensions. Path aliases like @utils/foo cost the agent a resolution hop via tsconfig.json. Full relative paths like ../utils/foo.ts let the agent navigate immediately. One allowed exception: workspace package boundaries in a monorepo (@org/shared-types).
4. Files under roughly 300 lines for what the agent will modify. A soft limit—above 300 lines, the agent reads in slices and loses context. The audit corrected the author: a 3,110-line orchestrator file with an explicit defense in AGENTS.md showed that splitting would cost more in cross-file inference than the length costs in slicing. Orchestrators, generated code, large data tables, exhaustive switches can be longer, but the choice must be deliberate and named.
Contracts (5 to 7)
5. Spec before code (the five-step loop). For every non-trivial change, the spec gets written or updated first. Without a spec, the agent's implicit understanding lives only in prompt history, which doesn't survive compaction or session boundaries. With a spec, the agent re-grounds in seconds.
6. Types carry contracts; prose docs do not. Push invariants into the type system: brand types, discriminated unions, exhaustive switches with never checks. A file that violates a type-encoded invariant fails to compile; a file that violates a prose-encoded invariant passes silently. The agent reads the type and knows the contract without having to remember to read a docstring.
7. Tests encode and enforce invariants. Test names should read as specifications of behavior, not descriptions of which function is being tested. Tests serve as executable documentation that agents can trust without re-derivation.
Quarantine (8 to 10)
8. Exceptions to patterns live in dedicated files. When a rule has an exception (e.g., a file that must be longer than 300 lines), document it explicitly in AGENTS.md or CLAUDE.md. This prevents the agent from silently assuming the exception applies everywhere.
9. Side effects are isolated. Bootstrap code, configuration loading, and other unavoidable side effects live in dedicated directories (bootstrap/, config/). The agent can safely ignore these unless it's specifically working on initialization.
10. Generated code is separated. Files that are auto-generated (e.g., from OpenAPI specs, database schemas) live in a generated/ directory. The agent knows not to modify them and can regenerate when the source changes.
The audit correction
The author initially framed the 300-line rule as hard. Triangulation across three coding-agent codebases showed one codebase violating it deliberately: a 3,110-line orchestrator file with an explicit defense in its AGENTS.md. The defense: this is an orchestrator meant to be read top to bottom, and splitting would cost more in cross-file inference than the length costs in slicing. The rule survives as a soft preference for feature files, with the requirement that exceptions be named in a configuration file the agent reads.
What to watch
Watch for the Grounded Code series to be referenced in AI coding agent tooling documentation (Cursor, Copilot, Codex) as a recommended pattern for agent-optimized codebases. If major AI coding assistants adopt these principles as default project templates, the pattern could become an industry standard within 12 months.
