During a long session building the DarJS framework, I generated an audit report — eleven weaknesses, priority matrix, code snippets for each fix. Useful artifact. The question of where to save it took longer than it should have.
Not much longer. The answer was in a global config file: responses/ for project-scoped analysis documents. I found it, wrote the file, moved on.
But I want to examine that pause. Because the convention existed. It was documented. It just wasn’t local to the project — it lived one hop away, in a global instructions file that covers every project simultaneously. And that one hop is the difference between an O(1) decision and a reasoning step.
At scale, across hundreds of decisions in a session, those reasoning steps add up.
What agents actually do when navigating a codebase
A human developer internalizes project conventions over weeks. After a month on a codebase, “where does this go?” usually resolves in under a second — a pattern-match against accumulated context, no reasoning required.
An agent doesn’t accumulate context across sessions. Every conversation starts fresh. The conventions a developer carries in their head aren’t available. What the agent has is: the files it can read right now.
So when a decision needs to be made — where to save this file, what to name it, what format it should take — the agent goes looking. It reads whatever is nearby: CLAUDE.md, memory.md, CONVENTIONS.md, existing files in the target directory, recent git history. It builds a picture from what it finds, infers the missing pieces, and acts.
This works. But “infer the missing pieces” is exactly where cost accumulates and drift starts.
Conventions as dispatch tables
Here’s a CLAUDE.md entry that makes file placement an O(1) decision:
## File placement
| Type | Location |
|-----------------------------|-------------------------------|
| Analysis / audit reports | responses/ |
| Decision logs | decisions/ |
| AI-generated model specs | tests/prompts/ |
| Exported schema | schema.json (project root) |
| Generated validators | validators/ |
| RBAC permission files | permissions/ |
When a table like this lives in the project’s own CLAUDE.md, the agent reads it once at the start of the session and every file placement decision for the rest of the conversation is a lookup. No inference. No “what would make sense here.” The table is the answer.
When the same convention lives in a global file — or in no file at all, just in the developer’s head — the agent either reads the global file (tokens spent, context used) or reasons from existing examples (slower, and the answer can vary across sessions depending on what examples happened to be nearby).
Same convention. Different location. Completely different runtime cost.
Directory structure as a visible contract
A well-named directory layout communicates intent without requiring a comment:
models/ ← model class definitions
validators/ ← generated Zod schemas
permissions/ ← RBAC rules per model
tests/
scenarios/ ← dar scenario files
prompts/ ← AI spec inputs
responses/ ← analysis and audit artifacts
decisions/ ← design decision logs
Every directory name is a type annotation on the files it contains. An agent navigating this structure can infer “AI-generated spec for Medicament model” → tests/prompts/model-spec-medicament.json without being told. The path encodes the classification.
Contrast this with a flat structure or a layout where directories are named by technical role rather than content type:
src/
lib/
utils/
scripts/
misc/
These names tell an agent nothing about what kind of artifact belongs where. Every placement decision requires reasoning. Every session may resolve it differently. The drift is invisible until you notice that audit reports are sometimes in docs/, sometimes in the root, sometimes not saved at all.
The naming convention is half the architecture
The other half of routing is naming. A file named RESPONSE_2026-05-02_framework-audit.md carries metadata the agent can read without opening the file: type (RESPONSE), date, topic. A file named notes.md carries none of that.
This matters because agents often need to find a file they created in a previous session. git log --name-only or a directory listing is how they do it. A naming convention that encodes type and date makes that lookup exact. No naming convention means pattern-matching against ambiguous filenames and reading file contents to identify what they are.
# Decodable without opening
RESPONSE_2026-05-02_framework-audit.md
DRAFT_token-discipline.md
IDEA_editor-protocol.md
decisions/phase3-persistence.md
# Opaque until opened
notes.md
audit.md
phase3.md
stuff.md
The decodable names are a directory listing that agents — and developers — can navigate at a glance.
What to put in CLAUDE.md (the local one)
Global config files are good for universal rules. But every project has conventions that don’t generalize, and those belong in a project-local CLAUDE.md. Specifically:
File placement table — where each artifact type goes, as above.
Naming conventions — the prefix/date/slug pattern for each file type.
What NOT to generate — directories or files the developer manages manually. If manifest.js is hand-maintained and should never be auto-regenerated from scratch, say so explicitly. An agent that doesn’t know will act on best judgment, which may be wrong.
Entry points — where to read first for each task type. “To understand the model layer, read schema.json, not the source files.” This prevents the agent from reading six files when one would do.
The goal isn’t to document everything. It’s to document the decisions that would otherwise require inference — the non-obvious ones, the ones that vary from what a developer might guess based on convention from other projects.
The principle
Architecture has always been about making the right thing easy and the wrong thing hard. That principle used to apply to human developers navigating the codebase.
Now it applies to agents too — and agents navigate differently than humans. They don’t have internalized context. They read what’s present, infer what’s absent, and act. The quality of their decisions is a direct function of what’s present.
A responses/ directory with a CLAUDE.md entry describing what goes there is a routing instruction that executes in zero tokens. An undocumented convention that lives in a developer’s head is a reasoning problem the agent has to solve from scratch every session.
These are the same convention. One is machine-readable. One isn’t.
The gap between them is the work.
Article 013 of “Building in the Age of Agents”