# The Agent-Shaped Codebase

> Codebases are about to be read more often by agents than by people. That changes what "clean code" means.

- Type: essay
- Published: 2026-03-31
- Topics: agentic-development, solution-architecture, conventions, code-review
- Canonical: https://cmlonder.com/essays/the-agent-shaped-codebase

---
For twenty years we optimised source code for a human reader. That reader had
limited working memory, read top to bottom, and could walk over and ask a
colleague. None of those constraints describe the reader we now write for most
of the time.

## What stops being cosmetic

Three things move from style preference to load-bearing infrastructure.

**File layout becomes an index.** An agent finds code by name and path before
it finds it by reading. A directory that reflects the domain is worth more than
one that reflects the framework.

**Comments become contracts.** Not *what* the code does — the code says that —
but which invariants must hold and what happens if they do not.

**Conventions become executable.** A convention that only lives in a reviewer's
head is invisible. One that lives in a schema, a lint rule, or an `AGENTS.md`
is enforced on every run.