Model-Based Agentic Software Engineering

Generative AI is shifting software engineering from a practice built around scarce implementation toward one built around abundant, low-cost code. The hard part stops being writing code and becomes governing the conditions under which fast code can be trusted. This site describes a method for doing that. The method is called Model-Based Agentic Software Engineering (MAGE). MAGE has six big ideas described below. To learn more, the book provides the full treatment.

QuickStart: Bootstrap MAGE in your own project by installing the Skills for Claude.

The MAGE method: the two theses that hold off churn and earn trustworthy software A cheap agent fleet is one input with two fates. Left ungoverned, it drifts into churn as its work outgrows the context window: drift, confidently-wrong. Run through the governed environment — which holds the Modeling Thesis (a typed model the fleet reasons through) and the Alignment Thesis (a mechanism that keeps output aligned with intent) — it converges on software that is high quality (correct), auditable (every change traces back to the models, so a result can be explained and reversed), and delivered at velocity. Model-Based Agentic Software Engineering is the governed path. Churn work outgrows the window; drift, confidently-wrong left ungoverned The agent fleet fast · cheap one input, two fates The governed environment Modeling Thesis a typed model the fleet reasons through Alignment Thesis keeps output aligned with intent Trustworthy software high quality · auditable at velocity traces to the models MAGE is the governed path: the two theses hold off churn.

Big idea 1 · the problem

Churn is the scaling limit

An agent fleet scales until the work outgrows its context window. Then it churns: it re-derives what it already built and confidently undoes yesterday's fix.

A team of people slows under Brooks's Law; an agent fleet collapses when the work exceeds its window. Churn is the symptom; its causes are three not-knowings — what to build, how to realize it, how to change safely — and the theses below divide them: models treat the first two, governance the third.
Read in the book →Concept card →
Three process models for agentic software engineering Three panels arranged as a triangle. The two poles sit on top: velocity-centric at top-left — a human sets a goal, then a ring of role-labeled agents — planner, developer, tester, reviewer, security, deploy — passes work around a cycle, with insufficient quality control; and oversight-centric at top-right — a human and a single agent exchange a prompt and an output in a round trip, so human attention gates every step of progress. Governance-centric sits centered beneath them as the synthesis: a human hands policies into a governed engineering environment that contains the agent, so known obligations become controls before the agent works. The book takes the third stance. (a) Velocity-centric Human goal ↓ Planner Developer Tester Reviewer Security Deploy Insufficient quality control (b) Oversight-centric Human Agent: bounded work prompt output Human attention gates progress (c) Governance-centric Human Governed engineering environment Agent policies Known policies become controls

Big idea 2 · the stance

Governance-centric — the enabling substrate

Build the environment first: encode each obligation as a mechanism the environment enforces, so quality is a property of the ground the agents stand on.

Velocity-centric hands work around a ring of job titles and leaves quality implicit; oversight-centric parks a human beside each change, and attention does not scale with the fleet. Governance pays attention per class of failure instead: once, when you build the mechanism that retires it.
Read in the book →Concept card →
The apex of the documentation hierarchy is a typed model that binds docs, code, and tests A two-panel contrast. Left panel, typical agentic methods: three boxes — docs, code, and tests — stand as separate islands with no glue between them. Nothing binds them, so they drift apart and there are no guardrails; a red marker notes the missing binding. Right panel, the MAGE move: a single typed model sits at the apex and binds the same three — docs, code, and tests — with checked edges. The model is the one description the machine can check the others against, so a drift check fails the build when any of the three disagrees with it. The lesson: lift documentation to its apex, a typed model, and the three that used to drift become one checkable whole. Typical agentic methods three islands, no glue docs code tests nothing binds them → they drift no guardrails The MAGE move a typed model at the apex typed model binds intent to implementation docs code tests checked: the map must match the territory

Big idea 3 · Thesis 1

Documentation, taken to its limit, is a structured model

A context-bounded agent cannot hold the whole system. Give it a structured, drift-checked model to reason through, and the work fits in the window.

Models used to die because keeping them current was somebody's unpaid job; agents now do that job for cents, re-checking the map against the code on every change. A drifted prose doc lies quietly — a drifted model fails the build.
Read in the book →Concept card →
Two forms a quality goal splits into: a constraint or a sensor A quality goal you want to hold splits into two moves — prevent the mistake, or catch it — however you arrived at the goal, up front from the domain or in response to a failure. On the left, a constraint: it makes the whole class of mistake impossible by scoping the action space, like choosing a typed enumeration over free-form strings so an unlisted value cannot be represented, like a firewall. On the right, a sensor: it lets the mistake happen but detects it and surfaces it in time to stop the damage, like a test suite in CI or a smoke detector. The wall forbids the bug; the sensor watches for it. The wall is cheaper to live behind than the sensor is to keep reading. Quality goal prevent the mistake, or catch it Constraint — prevents Makes the whole class of mistake impossible. typed enum over strings · firewall Sensor — detects Lets the mistake happen, detects it before it ships. test suite in CI · smoke detector

Big idea 4 · Thesis 2

Hold intent with a mechanism: prevent first, sense the rest

Enforced mechanisms hold work to intent across later changes. Constrain first so the wrong move is unavailable; where prevention falls short, a sensor catches the drift.

A type the compiler checks, a lint that blocks the commit, a gate that refuses the deploy: each holds a policy decided once against every later change. Costly goals earn both a constraint and a sensor; what neither reaches stays a human job.
Read in the book →Concept card →
Governance runs soft to hard: a compact spectrum of mechanism classes. A horizontal spectrum runs from soft governance on the left to hard governance on the right. Soft, probabilistic mechanisms that aim an agent sit on the left: conventions, briefs, templates, prose conventions, and a reviewing agent. Judgment-laden doc-derived tests sit in the middle. Deterministic mechanisms that hold the line sit on the right: lints, types, schemas, and quality, drift, or deploy gates, together with a marker file the tool reads. Soft aims the agent; hard holds the line; a mature environment uses both. Governance runs soft to hard Soft aims the agent; hard holds the line. A mature environment uses both. probabilistic · aims an agent deterministic · holds the line SOFT HARD convention · brief template · prose reviewing agent doc-derived test lint · type · schema quality / drift / deploy gate · marker file the tool reads The second time a soft rule fails, convert it: a documented rule becomes a lint the agent cannot talk past. Stronger guardrails let the fleet run faster, safely.

Big idea 5 · the practice

Convert recurring failures into controls

Velocity surfaces the failures you could not foresee. Convert each recurring one into a mechanism, pushed as far toward hard enforcement as it will go.

Mechanisms sit on a spectrum from soft to hard: a convention or a brief aims the agent but cannot block it; a lint or a gate holds the line whether the agent cooperates or not. The second time a soft rule fails, move it right — the documented rule becomes a lint the agent cannot talk past.
Read in the book →Concept card →
SDLC to SELC: one seat reassigned Two lanes of the same six lifecycle activities — requirements, specification, design, implementation, validation, maintenance. Top lane, the conventional SDLC, has every seat held by one engineering role, with implementation marked as the seat that consumes the calendar. Bottom lane, the SELC, reassigns the implementation seat to the agent fleet, drawn in the accent colour; the engineer flanks the fleet, authoring intent on the left and judging and governing the output on the right, and a governance band beneath holds every seat’s output. A dashed arc returns from the last activity to the first, the cycle in “life cycle.” SDLC — CONVENTIONAL Requirements Specification Design Implementation eats the calendar Validation Maintenance the engineering role — every seat, and above all the developer’s one seat reassigned: the D is delegated to the fleet SELC — MAGE Requirements Specification authored as models Design authored as models Implementation the agents Validation gates, not reading Maintenance run as governance the engineer — authors the intent the fleet — develops the engineer — judges and governs governance — the environment holds every seat’s output to the standard the engineer set (Part Two) the keystrokes are delegated; the accountability is not

Big idea 6 · the seat

The lifecycle stays, but now agents sit in the developer's seat

SDLC becomes SELC: one seat reassigned, the lifecycle otherwise intact. The fleet writes the code; the engineer keeps the seats that were always the engineering.

The engineer flanks the fleet: models carry intent in on one side, judgment meets the output on the other. The seats the human keeps — requirements, specification, design, validation — were always the consequential ones; now they are the job.
Read in the book →Concept card →

The code got cheap; the judgment got expensive. Govern the conditions under which fast code can be trusted — the machine can search faster than any of us, but it cannot tell us what is worth searching for. So start with one recurring failure your agents keep handing you, and convert it: one type, one lint, one gate. The method grows from there; below are four ways in.

The construction kitthe architecture: 9 capabilities · 25 canonical mechanisms · 8 compositions Full catalogueevery mechanism, by role · model · enforcement Bookthe full treatment of the method Claude quickstartinstall the skills in your repo