Every structural decision is a performance decision — for agents. Confusing names cost spin time, multiplied across every invocation. Thousands of invocations per month turn naming into a tax.

Principle

Architecture is Agent Performance

The asymmetry

Humans build a model. Agents arrive cold.

👤

Human developer

navigates a codebase

Builds a mental model over weeks. Remembers that helpers.py contains the rate limiter because they wrote it.

Confusing names are tolerable. Accumulated context makes bad naming survivable.

🤖

Agent

arrives cold — every time

No accumulated model. Navigates by reading names — files, modules, functions. If names don't convey purpose, must open, read, reason before any real work.

Confusing names are a tax. Paid on every invocation, with no compounding familiarity to offset it.

Why it matters at scale

One invocation is nothing. A thousand is a tax.

Same ~30s orientation overhead per cold agent. The cost compounds by invocation count.

1invocation

30s

~30s

10invocations

5 min

~5 min

100invocations

50 min

~50 min

1,000invocations

8.3 hours

~8.3 hrs

10,000invocations

83 hours

~83 hrs

A one-time rename buys down the tax for every future invocation.

Naming is the cheapest, highest-leverage optimization in the system.

The test

Can a cold agent tell what each file does — without opening it?

Orientation testls /src

adw_plan.py

planning phase script

✓

workflow_ops.py

workflow operation utilities

✓

r2_uploader.py

R2 upload logic

✓

utils.py

unknown without opening

✗

helpers.py

unknown without opening

✗

manager.py

unknown without opening

✗

Every file name is a claim about its contents. A name that fails to tell the agent what's inside has abdicated its job.

The design rubric

Three words. Every structural decision is measured against them.

Flat

Deep nesting forces agents to traverse levels just to learn the structure.

Depth for its own sakesrc/features/auth/services/providers/oauth/

Depth that earns its placesrc/auth/oauth.py

Named

Every name is a falsifiable claim. Specific enough to be right or wrong.

Not a claimprocess_data()

A claimnormalize_notion_task_tags()

Obvious

If you need a README to explain where things are, the structure failed.

Needs a guidesee ARCHITECTURE.md to find

the rate limiter

Self-describingsrc/rate_limiter.py

A real directory

Same module. Two ways to lay it out.

Opaquemust open to know

adw_modules/

├──utils.py

├──helpers.py

├──manager.py

├──common.py

└──core.py

Self-describing0 opens to orient

adw_modules/

├──git_ops.py

├──worktree_ops.py

├──workflow_ops.py

├──state.py

└──r2_uploader.py

Same number of files. Same underlying logic. The right half costs zero orientation tokens — every name is a standalone claim.

Scope

This Principle governs file, module, and directory structure — where things live and what they're called at the filesystem level. For code constructs inside files — function, class, type, variable names — see A Priori Friendly Naming. Same discipline, different altitude.

The discipline

Every file name is a claim. Make it falsifiable.

Flat, named, obvious. A cold agent should be able to read the directory and know what's where without opening anything. At one invocation, this is aesthetics. At a thousand, it's leverage — the cheapest performance optimization the system has.