Mostly Done.
Contents

2 Architecture localizes change

A good boundary lets the neighbors keep their tea.

The best agent workflow cannot rescue an architecture that makes every change global. Agents edit code fast, but they are not exempt from coupling. Architecture is the mechanism that makes delegation safe.

2.1 One truth, many projections

Consider an editor whose defining decision is that the Markdown source and its syntax tree are the only truth. The screen is a projection. The rich view is not an independent data model that later attempts to round-trip back into the source.

That boundary removes an entire family of ambiguity. When the view and the source disagree, there is no negotiation over which one wins. The view is wrong. When a projection changes, the source should remain byte-faithful. When the caret moves, its relationship to the source should remain stable. The architectural choice turns philosophical questions about document state into concrete invariants.

This matters disproportionately for coding agents. An agent entering a WYSIWYG codebase with two semi-authoritative models must reconstruct a large web of synchronization behavior before it can predict a local edit. An agent entering the one-truth editor can reason from a single direction of authority:

source + AST -> projection -> view

The architecture narrows the proof burden.

The rule holds because ordinary code cannot bypass it. Every keystroke passes through a single interception point, where it becomes a relative source edit routed into the document session; the text view never commits the mutation itself. An architectural principle deserves trust in proportion to how hard the code makes it to cheat. If any handler can quietly write to the view model, the principle is a preference. If every edit must cross one narrow, observable boundary, the principle is a mechanism.

2.2 Frontend, intermediate representation, backend

Take a diagram renderer built on a related split:

source language -> parser/frontend -> platform-free IR -> renderer/backend

The intermediate representation is the leverage point. Adding a new export format to that renderer took one implementation file plus tests, because the scene representation already carried everything the format required. Adding a new input language for entity-relationship diagrams crossed four surfaces: the parser, a key field in the semantic model, one layout line for badge width, and a badge-rendering block. It could not stay in one layer because it added meaning, key badges, that the existing representations lacked.

That contrast is the claim at its true size. A boundary is cheap to extend only when the representations crossing it already carry the needed meaning. The architecture changes the economics of ideas, but the discount applies to changes the model anticipated. Measure leverage by counting the layers a change must touch, and remember that the count is a property of the change as much as of the architecture.

The same caution applies to platform free. A typesetting engine can keep its layout layer free of platform imports, which buys headless testing on Linux, yet the same input can still produce different geometry on different platforms, forcing a separate set of golden files for each. A portable core buys headless verification. It does not buy platform-identical output.

2.3 Locality is a verification feature

Software architecture is often discussed in terms of comprehensibility or reuse. With agents, another property becomes central: how much of the system must be trusted for a small change to be believed?

A local change has a local proof:

A cross-cutting change has a global proof burden. It requires more context and creates more chances for two agents to edit the same shared boundary differently.

So if you have six agent branches in flight and a whole-codebase language-mode migration waiting, do the migration alone. The mode flip is not necessarily a bad change. It is a bad concurrent unit. It destroys locality and turns otherwise independent branches into a merge and semantics experiment.

2.4 Design boundaries for agents, not around them

It is tempting to create agent-friendly code by adding more comments or smaller files. Those can help, but the more important move is to create boundaries where correctness can be observed.

A useful boundary has three properties:

  1. A narrow input and output. The agent can state what crosses the boundary.
  2. A stable contract. The expected behavior is less volatile than the implementation.
  3. An independent probe. Tests or tools can inspect the result without exercising the entire application.

A platform-free layout layer satisfies all three. So does a projection boundary in an editor whose source is the only truth. Either way, a fresh agent can take a bounded problem and return a bounded artifact.

2.5 Dogfood through real package boundaries

The strongest modularity claim is one enforced socially and mechanically at once: make your host application consume its own engines as versioned packages from a public registry, the way an external consumer would. This is more rigorous than keeping the engines as internal folders and calling the arrangement modular.

A real package boundary forces several truths:

The dogfood path is a contract test for the architecture. It catches the difference between separable in principle and actually separable in use.

2.6 The architectural question to ask

Before assigning a feature to an agent, ask:

Can this change be expressed as one new thing crossing one existing boundary?

When the answer is yes, implementation can often be broad and autonomous. When the answer is no, the work needs a design step first: create the boundary, then delegate. That is how architecture converts a large creative request into a small proof obligation.

use ← and → to turn pages