Every extra file an agent must open before it can edit one rule costs tokens, review time, and first-pass mistakes. Prompts cannot fix that. Shape the architecture so the change is small, local, and explicit. (This guide calls each extra file a hop.)
How much context an agent must load and emit to ship one product rule. Types that exist only to satisfy layers (DTO, command, query, contract, exception) are wasted context. Extra detail in the file you actually edit — like a closed list of outcomes — is not.
Navigation before the first edit, files a human must review, and forgotten registration points. Agents still need a person when finding the right file is a search problem.
First-pass completeness, compile-time outcome coverage, and tests that actually hit persistence. Mocked layers can be green while the query is wrong.
Controller, service façade, mediator, handler, repository, unit of work, factory. Business errors as exceptions. Every new field fans out across projects.
Feature handlers that call a few modules in one process. Shared status vocabulary. No separate Domain / Application / Infrastructure solutions.
One file owns request, rules, persistence, closed outcomes, and HTTP mapping. A map names the file. Copy a template instead of inventing a layer.
Each topic is drawn from a measured change on three C# apps that implement the same functionality in three different architectures. The advice is the architecture, not the domain of those apps. The question is always the same: how many files, concepts, and dependencies does an agent need before it can safely change this code? That question is the overarching metric.
Three in-process postures for identical behaviour, and why hop count dominates cost.
02 · CostPercentage matrix for tokens, navigation, review surface, latency, and correctness proxies.
03 · CodeBoring beats clever. Explicit beats implicit. Local reasoning beats global knowledge.
04 · CodeClosed unions, strong types, copy-not-share, shallow graphs, and explicit construction.
05 · CodeBehaviour names and a real host. Mocks do not document the query the database actually runs.
06 · SystemsAlign the process boundary with the change boundary. Chatty RPC multiplies every hop.
07 · SystemsOne ritual to add an operation, a feature map, agent notes, and a closed status set.
08 · SystemsA staged path: spec, collapse hops, map operations, then stop splitting co-changing work.
Layered C# is indexed at 100%. Modular and Operation-local are shown as percentages for tokens, developer involvement, and correct-output proxies.