The book models — a reading view

The ideas the whole argument turns on — the two theses, the conversion that grows the environment, the governing metaphor, and the vocabulary of models underneath them.

What a fleet of coding agents is, and the ways it comes apart.

The environment that holds the fleet to a standard, and the mechanisms it is built from.

Two mechanisms from the book's running example, DocAble.

Building DocAble was not only a way to ship a product.

Three books frame what this one attempts.

The first is **Software Engineering at Google** (Winters, Manshreck, and Wright, 2020) [cite: winters2020] — three Google engineers' account of how the company sustains software engineering across tens of thousands of people and one vast codebase over decades — whose premise this book shares: engineering discipline should be *mechanized, not remembered* — pushed into review, testing, tooling, and culture so that correctness does not depend on any one engineer keeping a rule in their head.

The second is the **Gang of Four's** *Design Patterns* (Gamma, Helm, Johnson, and Vlissides, 1994) [cite: gof1994], the catalogue that gave object-oriented design its shared vocabulary of reusable solutions, whose lasting contribution was less any single pattern than the *form* — name, recurring problem, solution shape, consequences, known uses — written so an engineer could reach for a vetted answer instead of re-deriving one.

The third is **Model-Driven Software Engineering in Practice** (Brambilla, Cabot, and Wimmer, 2017) [cite: brambilla2017], the standard concise statement of the modeling tradition: treat models as first-class engineering artifacts, structured representations with defined semantics a tool can check, not pictures pinned beside the code.

The hard problem of building software with agents is simple to state: the tools are fast and the tools are unreliable.

The through-line is a single idea; hold every chapter against it.

Read the book once, front to back, and you learn the method.

Five appendices, each with its own job.

The three reference appendices are strongest read in sequence, from the capability you want down to the detail you need to ship it.

The book and the online catalogue divide the work.

[ref:where-to-look] lays the surfaces side by side — each with the job it does and the question that sends you to it, from the main text through the five appendices to the online catalogue.

Of course, not every programming task needs the machinery this book describes.

Start at the decision on the left.

This book covers both modes.

Think of a 3D printer.

A 3D printer belongs to a rare class of technology — the *open-ended* kind — alongside the invention of writing and the printing press.

Everyone can sketch a piece of software.

Here is the shift in posture the whole book turns on.

The explicit problem is a mountain of inaccessible documents.

From the outside the system is almost boring, which is the point.

Inside, six parts carry that upload, drawn in [ref:docable-pipeline].

Now the part that makes this a book about engineering rather than accessibility: I did not write this system.

None of that machinery was designed in advance.

Early on, the codebase held two libraries that could touch a PDF: the sanctioned one, and a convenient second one an agent had adopted for quick page operations.

The second failure came from the process that built the product.

Neither fix stopped at the patch.

You now hold the object: a real system, built by a fleet, governed by machinery that grew scar by scar.

An agent runs in a loop, and the loop has a fixed shape.

(no topic sentence — opens on a non-paragraph block)

Now put the two ideas back together, because they are one machine.

[Loops and Models](1.3-loops-and-models.html) called the foundation model a probabilistic reasoning machine.

A raw model only recommends.

Cross the two lists and the method starts writing itself.

Now collect the derivation.

Engineering ran on the same handful of activities long before software, and software inherits them whole: **requirements** (find out what the system must do, and for whom — usually the hard part, since the people who need it cannot state it), **specification** (say what it will do, precisely enough to check later), **design** (decide the parts, the seams, and how the whole meets its constraints), **implementation** (build it — for software, write the code), **validation** (show the built thing meets the spec), and **maintenance** (change it over the long life without breaking what already works).

Two words for two jobs, and this book keeps them apart.

The field's own name for the lifecycle gives the old arrangement away: SDLC, the software *development* life cycle.

Same lifecycle, then; no new phases.

Before the walk, I owe you four definitions — *engineering*, *software engineering*, *agent*, and *model* — and, before we leave them, one adjective the last of them will come to lean on: *structured*.

**At the bottom sits the foundation model.** It comes from a commercial vendor or an open-weight release, and it is a general language reasoner, able to *induce* an understanding of your environment — though that induction is expensive, and it happens fresh every time.

Read the stack as a list of opportunities, because that is what it is.

Your first governance mechanism is the prompt, because the agent is a language model and words are how you talk to it.

The models are the map; the code is the territory.

Here a skeptic has a fair question.

Step back from drift for a moment and look at what you actually hand an agent to work from.

The argument so far is that a structured model earns its keep by binding intent to implementation and letting a checker prove things about it.

The claim I just made hides a trap, and the book's enthusiasm for drift gates can be misread into a dangerous half-truth.

There is an over-reach on the other side of the mirror, and it is worth naming before the enthusiasm for models runs away.

If the structured model is where you now start, an old idea says to finish there too: skip the code and *execute the model directly*.

Enforce a property at the wrong level and it slips through; [ref:semantic-gap] shows the fix — lift the check to where the meaning is legible.

A second instance of the semantic gap lives not in the product but in the operator's own loop.

So I moved the check up to where the property *is* legible: the operator's loop.

Why insist on both conditions?

I want to be straight about a compromise buried in this, because it is the kind of thing the semantic-gap idea should make you notice rather than paper over.

Some things you genuinely know from the beginning, and you should write every one of them down.

But you will not know everything, and pretending otherwise is the mistake.

Run the promotion rule for a season and the environment fills with controls.

A mechanism is one of two moves — prevent the mistake, or catch it — and [ref:constraint-vs-sensor] draws the split.

One boundary before moving on, because without it the word swells.

Step back and this is what you are really doing: describing policies for how the engineering work should proceed, and letting those policies produce a **governed engineering environment** — the rules of the road the agents operate within.

That closing line reads as if it settles everything.

Start with the lifecycles, because everything else hangs off them.

Once the healthy path and the failure map are written, the thing you hand the agent is a **runbook** (or playbook): the steps to take, whether recovering from a failure or working a fresh ticket.

**The judgment parts get the roughest algorithm that still fits.** For a well-constrained decision, write the algorithm down and let the agent do the glue.

John Ousterhout gives the rule in one line [cite: ousterhout2018]: **measure one level deeper than the number you think you want.** A metric earns its place only when it drives a decision, and the surface number usually cannot; the deeper the measurement, the nearer it sits to the decision it must drive.

Start at the deterministic end, where a metric is a millisecond number nobody argues about.

Now the middle of the spectrum, and the chapter's teaching example: the "measure one level deeper" rule applied to the number that most often gets it wrong.

The flagship walks from a model claim *to* the code and asks whether a test exercises it.

The link graph that drain walks has a second use, and it comes for free.

Slide to the far end of the spectrum, where the metric stops being a number a threshold can act on and becomes a judgment a human has to make.

The most useful honesty in measurement is the one that catches you before you publish a comfortable non-result.

The hard end and the flagship follow the same pattern.

[ref:metrics-table] collects every metric — the decision each drives, where it sits on the hard-soft axis, and who reads it.

The Governance Graph draws it.

The graph settled one question a flat list could not: which two controls collide.

The census has a counterpart, and the two are true opposites over one graph.

Every mechanism so far was one you wrote.

Two disciplines keep the model honest, and both are the book's.

Part 1 derived the Modeling Thesis from the machine.

Model-based systems engineering never failed on its ideas.

The fewer-tokens leg is the one we can measure directly.

The last chapter invoked Kruchten's **4+1 views** in a final sentence — "the reason one model is never enough." This Part promotes that sentence to its organizing structure.

Kruchten, of course, described the views; he did not have a drift gate.

Making the model executable is why this Part is not really *about* 4+1.

Before the views, one chapter of framing.

The last chapter warned against repetition: two models that say the same thing must now be kept in sync.

A model and the code it concerns stay equal by derivation, and derivation runs in one of two directions.

The purest model-from-code artifact is not one of the zoo's own views.

A model earns trust only if you can get from a model element back to the lines that realize it, and forward from a line to the model element that governs it.

DocAble did not design this up front.

The right sensor was read off real drift rather than guessed.

(no topic sentence — opens on a non-paragraph block)

Every model in this Part is rendered by filling the same five-field template.

Every model page in this Part draws the same shape.

*The typed source-of-truth for a service-oriented architecture — its services, their endpoints, their authentication, and the wiring between them — from which the access policy and environment wiring are generated and against which the real call graph is checked.*

The domain registries are the frozen tables the service-flow model rests on: the file types the system handles, its known conformance gaps, its scheduled jobs, its user-facing surfaces.

Formal invariant verification is the backbone the other three models hang their invariant tables on.

*A typed registry that models the system's synchronization behavior — every OS-level lock, which shared resource it guards, and the required acquisition ordering — so concurrency contracts are declared and checkable, not tribal.*

The synchronization model catalogs the raw locks.

The mediator registry is the *how-many* half.

The single-writer registry is the *exactly-one* half, and its failure mode is what makes it a separate model.

*A typed catalog of every component's code zone — its focus directories, its tags, its boundary kind, its external seams, its read surfaces — so "which component owns this file, and what may touch it" is a queried fact rather than a per-tool guess.*

The rule-metadata registry is the self-referential slice of the domain registries: the governance rules' own metadata, and so the model the governance machinery — and this book — are partly governed by.

The zoo names a performance and cost model as a general type, and the framework supports it.

*The typed statement of where things run — each service's name, its layer, and its tier — from which the deploy scripts and layering lints reason about a declared topology rather than scattered constants, and against which the real deploy table is reconciled.*

*A deploy graph whose edges carry a typed intent — correctness, cost-gate, or load — kept host-identical, plus a typed Scheduler that reads a per-host profile and rations load and cost so one host fans work out while a scarce one serializes it.*

The substrate-dependency model makes each governance mechanism declare, as typed metadata, the substrate assumption it bakes in — bound to one substrate, substrate-aware, or substrate-agnostic.

The user-journey model makes the product's journeys first-class typed entities — each an actor pursuing a goal through ordered steps, every boundary-crossing step joined to the endpoint it calls.

The agent-orchestration model is the developer-journey counterpart — the scenarios view pointed at the fleet rather than the user.

This model — the **Selector** in the join below — derives which environment tier a journey's tests run in from the journey's criticality: a `MAJOR` part runs the fast local tier and the full staging matrix, a `MINOR` part runs staging only.

Coverage-to-node mapping projects the test suite's coverage onto the model's *nodes* — states, seams, invariants, journey endpoints — instead of its lines.

The three models above ask whether a journey's test *exists*, *runs*, and runs *in which tier*.

*Four models composed on a shared key, so a product goal reaches all the way to how the deploy runs its tests.

Three questions the raw deploy scripts and test config cannot answer on their own.

The four models compose through shared keys.

The join has no single appendix diagram, so this composite is composed from the four real panels, adding only the join edges between them.

The join's invariants span all four models, collected in [ref:scenarios-invariants].

Two pieces of real policy code make the join concrete.

*Model-from-code, joined.* Every leg derives from the code: the journey's deps from its real call sites (M13), coverage from the real test run (M5), the host tier from the criticality field by a pure function (M6), the rationing plan from the per-host profile (M7).

There is a moment when a working sketch stops carrying its weight, and it is worth learning to see it coming.

Each view here is a working sketch.

If you read a few things past this book, read these.

One branch of modeling this book leaves untouched is the *digital twin*: a live model of a physical thing, kept in step with its real counterpart by a stream of sensor data, and used to predict and control it.

One thread ties every entry here to the book behind it.

A context-bounded fleet governs a context-exceeding codebase *through* structured models.

Sync holds through two layers stacked over the model↔code gap.

Sync is a living practice, not a one-time alignment.

The claim is a field-report result, so the numbers come with their provenance.

Documentation drift is excluded here by construction; this table is model↔code sync only.

Stale headers and stale prose numbers are **documentation drift, not model drift.** They are the soft layer's true positives, and they are cheap: a reader catches them, and the close tool heals them.

The net has two escape hatches.

Both failure modes lean, by default, on an engineer or an agent *noticing*.

The result is narrow, and stating its limits is part of stating it.

Do not dismiss a drifted wiki as failed documentation.

Four small additions turn the wiki from optional documentation into the start of an engineering environment.

The migration runs in four stages.

Name the starting point and both destinations before you move.

Start coarse and refine.

The second approach starts from the code and flies upward.

Both approaches assume you can make sense of the code — and often you cannot, because it is a mess.

[ref:squash-zero-promote] draws how a lint is worn into a legacy tree without breaking any in-flight agent — the order is what keeps it safe.

Induction gives you a first model, but it never tells you where it stops.

Coverage walks one direction: model to code.

A pilot makes the shape concrete.

Which raises the real question: how much governance is enough?

I know this because I lived it.

Self-operate is the starting point, because it holds the lifecycles of running a repo — everything an engineering team actually does.

The second skill, self-governance, triggers on a simple signal: a bad thing happened more than once — sometimes just once, if it was bad enough.

The first heuristic is to **avoid a teetering tower of governance.** Do too much of this and you end up in trouble: so much code governing and constraining the behavior that tending the tower becomes the work itself.

The third skill, self-communicate, governs how the agent explains itself — to you and to other people.

Self-communicate also owns a **lexicon**: the house vocabulary for your repo, so one concept gets one word, used consistently.

The three feel of a piece because they were all built the same way.

Give a model an input and either examples of a transformation or a precise description of it, and it will apply that transformation to something new — as long as the new thing is close enough to the examples, or the rule is precise enough.

Two transformations from this book show the lens at work — one sized right, one shaped wrong.

[ref:transformations-pipeline] shows the shared skeleton — each skill carrying an input to an output through a sequence of sized transformations.

Think of the training data as the whole internet and every book ever written, and think of the model as biased toward whatever it saw most.

[ref:novelty-axis] sets a part's novelty against the leap you can trust and the oversight you owe.

I hold this through an analogy.

So think of it this way: the agent will hand you a working prototype, but look under the hood of a novel system and you find Rube Goldberg machines in the engine room.

There are three ways to run a coding agent, and I suggest you choose among them by where you sit on the risk map; taste does not enter into it.

Coding agents accelerate *within the frame you give them* — even when the frame is wrong.

(no topic sentence — opens on a non-paragraph block)

For my whole career, refactoring was something you rationed.

Two consequences follow from cheap implementation, and both caught me off guard.

(no topic sentence — opens on a non-paragraph block)

AI reduces friction, of course; but what it chiefly manufactures is optionality — an endless stream of choices, some architecturally critical, some product-relevant, and some stupid things the agent should have sorted for itself.

A failure mode appeared again and again: Claude reported a task complete, and my review agents later found the half-done implementations, the missing integration points, and the tests that never actually exercised the behavior.

An agent fails differently than a person does.

When you vibe-code, you ask the agent to produce something that appears to satisfy the requested behavior, and the evidence you use is all external: does the demo run, does the output look right?

A normal codebase keeps most of its conceptual structure in human memory.

(no topic sentence — opens on a non-paragraph block)

The mechanisms I ended up with were not all the same kind of thing, and the axis that sorted them was soft versus hard.

The thing agents amplify is your autonomy — your capacity to turn intent into a working system without waiting on anyone.

Watching my own experience of software engineering get compressed, I expected to feel the role shrinking.

This is where I think companies may have trouble.

[ref:generative-family] lays the family out on one page.

Before the three members, the shared shape.

In property-based testing the author writes the law and the machine hunts the counterexample.

Property testing asks tame inputs a rich question.

This is the synthesis.

Once you have a generator, a new question appears that example tests never had to ask: *did the campaign explore the space that matters, or did it just spin?* The book already owns coverage — the [metrics chapter](2.5-metrics.html) develops it as a flagship, with the rule to measure one level deeper than the raw percentage — so this section adds only the one cut that is genuinely native to generation and hands the rest back.

The family gives a compact decision aid, and the axes of the opening table are the decision.

The Americans with Disabilities Act starts from a simple promise: people with disabilities should have equal access to public life, able to work, travel, study, vote, and use services without barriers society could reasonably remove.

Universities have been obligated to comply with Title II since 1990.

Compliance carries a cost, and the cost is easiest to feel on a single deck.

Underneath the institutional bind sits a technical problem deeper than it looks, and it is why this became a software project worth building rather than a policy memo worth writing.

The project began, fittingly, in a committee meeting about the very deadline described in the last chapter.

What followed moved through a recognizable sequence of stages.

[ref:velocity-curve] plots commits per week: a steep rise as the fleet gained capability, then the dip where velocity buys trustworthiness.

The apparatus outgrowing the product is not a one-time fact; it is a curve.

Under the ratio sits the raw motion of the code: lines added and lines deleted, week over week, on the two paths that carry the product — `web/`, the Python service and worker, and `backend/`, the C# tool and rule engine.

For a stretch of the build, nearly every unwelcome surprise came from deployment, and they shared a shape.

Read this timeline as a catalog of the *kinds of work* agentic development turned out to need — a more useful reading than any feature list.

A user uploads a file.

None of this would be worth building if a document were merely text in a box, and of course it is not.

A model is a **probabilistic component**.

A model shows a view.

The back end is a set of small services wired to react to events.

The front end is a small single-page application plus a set of supporting surfaces — an account view, a job history, an operator dashboard, and the editor.

Here the two halves of the system join, and the join is the function-call pattern from earlier in the chapter, seen once more.

The frontier models can already skip all of this.

Notice the shape of the argument, because the book made it again at a larger scale.

At the start there was one document format, a few hundred lines, and me.

The first offload was to hand the review itself to an agent.

The single reviewing agent worked, but it had a flaw I could not brief away.

A crew that coordinates is still a crew of agents each of whom has to understand the code it touches.

By this step I never looked at code at all.

Once that first model paid off, the others followed — but the right way to see the set is not "more models." Each model is a **view** of the system, and each view exists to answer for one **property or quality metric** I had to guarantee: a property like *deployability*, a quality metric like *security*.

So the models grew a nervous system.

The Architect rung is where the ladder ends, but the work on it does not.

This book opened on one diagram — [The MAGE Method at a Glance](0.1-the-mage-method-at-a-glance.html) — that named every part before the argument had earned it.

[ref:mage-dynamic-model] draws the whole theory on one diagram: a single set of constructs rather than four separate pictures, because the four dynamics act on the same system.

Each dynamic gets its own section below, and each opens with a simplified diagram of just its local causal path.

Not all governance is discovered through failure; the blue path, in [ref:mage-loop-1], seeds the environment before any agent runs.

The red loop, in [ref:mage-loop-2], is where work outruns a weak environment and the gap surfaces as pressure.

A structural diagnosis triggers governance adaptation, the green loop of [ref:mage-loop-3].

Successful governance does not end the process; the purple loop of [ref:mage-loop-4] reopens it.

The two conditions the book leaned on — capability-fit and authority — are not global switches over the whole model.

MAGE is a capability model, not a maturity ladder, and the distinction matters because the field has been here before.

The model earns its keep only if its outcomes can be watched.

A second discipline governs how the environment itself is read.

Here is where the model sticks its neck out.

Several claims read more precisely as consequences or domain-specific instances of the seven than as coequal predictions.

Two of the hypotheses have a form clean enough to write down.

Durable throughput is raw velocity net of what churn eats:

The second relation contrasts two ways to hold a failure class.

The theory did not arrive whole.

The induced kernel and its later extensions are epistemically different, and the chapter should not blur them.

The seven hypotheses suggest a focused program, not a scatter of disconnected tests.

The claim of MAGE is not that more governance produces better software.

The tidy version of governance says: figure out your obligations in advance, encode them as mechanisms, and let the agents run inside the fence.

The volume is only half of why supervision fails.

Here is a proposition I would put money on.

Fred Brooks warned the field off silver bullets forty years ago.

If implementation is abundant, the human's comparative advantage moves to the work that surrounds the code: framing the problem, discovering the abstraction, making the architectural call, and designing the governance under which fast code can be trusted.

A few consequences follow, and I will keep them short because each could be its own argument.

The theory gives the chapter's scattered observations a single shape.

Here is the claim the whole book has been climbing toward.

Every claim in this book rests on a single deep case: one repository, one method, roughly two years.

Throughout this book the test suite, the lint, and the conformance gate appear as *controls* — the deterministic machinery that converts a probabilistic generator's output into something an engineer can trust.

The most instructive negative result in this case study is one where the measurement *failed to find an effect* — and the failure is the finding.

A reasonable reader reaches this point with a methodological objection: *this is all one repository.* The objection is correct, and meeting it squarely is itself a contribution — because the AI-augmented engineering literature is currently split between two evidence forms that answer different questions, and conflating them is the field's most common mistake.

Set this case's unmeasured threads against the field they belong to, because the difficulty is not local to one repository.

I should be plain about the limits of this book.

We opened by calling the agent a 3D printer, not a stapler.

You do not have to adopt all of this at once, and you should not.

This book was set in Fraunces for display, Source Sans 3 for the body, and IBM Plex Mono for code, on a warm paper stock with a single burnt umber accent.

The argument no longer lived solely in prose.

Each model carried one facet of the manuscript's structure, and a check held that facet consistent as the prose moved.

Running the method on the manuscript followed the same loop the book teaches for code:

Large language models were part of making this book, and it would be coy not to say so.

The machinery had a firm boundary, and it is worth stating without hedging.