Say the concrete thing, then the shorthand
These words are the author’s coinages. They are defined here once so the rest of the guide can stay short.
- Hop
- An extra file, type, or process an agent must open or reconstruct before it can safely edit one rule. A hop chain is that sequence. Hop tax is the tokens, review time, and missed outcomes it produces.
- Fan-out
- A small product change that forces edits across many files because the same fact is copied at every layer. The opposite of a local change.
- Posture
- One of the three in-process shapes this guide compares: Layered, Modular, and Operation-local. They keep the same HTTP-in, database-out behaviour and disagree only on where the use case lives.
- Change boundary
- The set of files that actually have to move when one product rule changes. A healthy architecture keeps that set small and aligned with the process that owns the tables.
- Closed outcome
- A fixed, named set of results the operation can return. Missing a member is a compile error, not a silent 500. The guide’s set is on the Playbooks page.
- Cold start
- The first time an agent (or a person) meets the codebase. Completeness here means the map, the template, and the file itself are enough; the agent does not have to tour sibling folders “just in case.”
- Review surface
- The files a human has to read in the pull request. It is the same set as files touched, looked at from the reviewer’s chair.
- Search tax
- The files opened only to find the right place to edit. A current feature map collapses this.
- Ceremony
- Types, interfaces, and pipelines that exist to satisfy a layering style rather than a product need. One-implementation repositories, auto-mapped DTOs, and mediator commands with a single handler are typical.
- Folder folklore
- Knowledge that lives only in how the team names directories. If an agent has to infer the topology from folder names, write a map instead.