§2.1 From Context to Engineering Models
A foundation model knows programming languages, frameworks, databases, distributed systems, cloud infrastructure, testing practices, security concepts, and common architectural patterns. It does not arrive knowing the particular system in front of it: its boundaries, history, conventions, ownership, or current engineering state. That knowledge is distributed across source, configuration, documentation, registries, history, and the people who maintain the system. An agent can reconstruct what a task needs from those artifacts, but reconstruction consumes reasoning and is easily repeated across tasks and reasoning states.
AGENT HARNESSInset — Skills and Project Instructions
MAGE's emphasis on externalizing engineering knowledge appears in today's agent harnesses as project instructions and skills. Project instructions keep small amounts of cross-cutting, repository-specific guidance persistently available; skills package larger procedures and resources for a recurring class of work and load them when that work arises. Both reduce what a person must supply or an agent must reconstruct in each new reasoning episode.
The progression continues past prose. Retrieval can select knowledge from a larger external store, and models can represent it in structures that support queries, transformations, validation, or deterministic execution. As the representation becomes more structured, the environment can do more with the knowledge than simply show it to the agent.
Skills and instruction files are contemporary carriers. The engineering requirement survives changes in harness design: consequential knowledge that would otherwise be tacit or repeatedly reconstructed should be externalized in a form suited to how it will be used.
The first Modeling move is therefore to make reusable engineering knowledge explicit. Preserve the entities and relationships that recurring engineering questions depend on so that a task can retrieve the connected slice it needs rather than reconstructing that structure from raw artifacts.
The problem is not only context-window size. Natural language is itself a representation, and often an appropriate one: it is cheap, expressive, and for many engineering questions entirely sufficient. But consequential engineering knowledge expressed only in prose has two difficulties. The engineer must articulate the relevant distinctions correctly, and each later reasoner — human or agent — must recover those distinctions correctly, in this task and again in the next. A structured model can preserve distinctions that would otherwise have to be restated or reconstructed. The representation can therefore change what both the engineer and the agent are capable of getting wrong. Some knowledge should stay in prose, and some judgment should stay human; Chapter 6 returns to articulation and interpretation as separate sources of error with separate costs.
Models are not only for the agent. They are also for the engineer. A useful representation can make distinctions visible, force consequential decisions to be made explicitly, and expose omissions that ordinary prose leaves easy to overlook. Its value therefore does not depend entirely on whether an agent interprets it more accurately than natural language. Modeling improves the representation of engineering judgment before any agent attempts to act on it.
The Modeling Principle: externalize engineering knowledge and intent into explicit, structured models that both engineers and agents can reason through. In other words: once a system exceeds what a reasoner can usefully hold in view, give recurring engineering questions purposeful representations.
Software engineering has long treated the externalization of intent as an engineering problem. Requirements engineering, for example, distinguishes stakeholder goals and environmental assumptions from specifications used to constrain a realization, and develops representations through which those claims can be analyzed, refined, and traced.11. Pamela Zave and Michael Jackson, “Four Dark Corners of Requirements Engineering,” ACM Transactions on Software Engineering and Methodology 6, no. 1 (1997): 1–30, https://doi.org/10.1145/237432.237434.22. Bashar Nuseibeh and Steve Easterbrook, “Requirements Engineering: A Roadmap,” in “Proceedings of the Conference on the Future of Software Engineering,” special issue, Proceedings of the Conference on the Future of Software Engineering (New York), 2000, 35–46, https://doi.org/10.1145/336512.336523.33. Axel van Lamsweerde, Requirements Engineering: From System Goals to UML Models to Software Specifications (Wiley, 2009). Important requirements may remain qualitative, incomplete, or dependent on assumptions about the environment. The inheritance MAGE takes from this tradition is the more basic move: make consequential engineering knowledge into an explicit object through which engineering can reason. Chapter 3 takes up the separate question of which obligations the engineered environment should enforce.
2.1.1 Modeling Is a Classical Engineering Move
Modeling is not new. Engineering disciplines have long used representations that suppress irrelevant detail so that particular properties of a system can be reasoned about directly, and software engineering inherited and developed the same practice — architectural descriptions, schemas, state machines, interface contracts, formal models. Model-based systems engineering makes this commitment particularly explicit: engineering knowledge is organized around models that support analysis, communication, design, and assurance across the system lifecycle.44. International Council on Systems Engineering, Systems Engineering Handbook: A Guide for System Life Cycle Processes and Activities, 5th ed. (Wiley, 2023).55. ISO/IEC/IEEE, ISO/IEC/IEEE 42010:2022, Software, Systems and Enterprise — Architecture Description, technical report (Geneva, 2022).
These representations differ in purpose and rigor, but they share the same engineering move: choose a form in which the property of interest becomes easier to express, inspect, or analyze than it is in the realized artifact. UML standardized notations for many structural and behavioral views,66. Grady Booch et al., The Unified Modeling Language User Guide, 2nd ed. (Addison-Wesley, 2005). while requirements engineering developed representations for goals, assumptions, and specifications.3 MAGE does not propose a new modeling language. It does, however, use these established representations, and this chapter illustrates the technique through selected models.
What changes is the economics. Commodity intelligence makes structured representations cheaper to construct, maintain, and consume; generative implementation simultaneously increases their leverage, because engineering knowledge must remain available across an increasing volume of autonomous work. Models can become part of the engineered environment through which agents work, preserving that knowledge across reasoning episodes and making selected properties available for Alignment.
Models also participate in architectural reasoning. They expose relationships and make selected consequences available for analysis; engineers decide the decomposition, boundaries, interactions, allocations, and tradeoffs the system should embody. A model may record an architectural decision already made or reveal that the architecture should change.
SOFTWARE ARCHITECTUREInset — Models, views, and software architecture
MAGE follows Fairbanks's definition of software architecture as the set of structures needed to reason about a system, comprising software elements, relations among them, and properties of both.77. George Fairbanks, Just Enough Software Architecture: A Risk-Driven Approach (Marshall & Brainerd, 2010). Engineers therefore reason about one system through multiple views: a component view may expose decomposition, a behavioral view legal transitions, a deployment view allocation, and a quantitative view a resource bound. No one view need contain everything another does.
Architectural reasoning may therefore cross several model classes. An architectural decision may depend on structural, behavioral, ownership, decision, measurement, or provenance relationships together. The useful views follow from the engineering questions that must be answered.
Software makes the relationship between model and realization unusually fluid because both are made of information. A schema can generate code; a state machine can drive behavior; a policy model can generate configuration; a dependency graph can become an execution plan. Such a representation can participate directly in the system while remaining selective about what it represents.
When structured views are cheap to derive, maintain, connect, query, analyze, and sometimes execute, more of the knowledge required for architectural reasoning can remain explicit rather than being repeatedly reconstructed from implementation.
A useful model need not be elaborate. Sometimes it is three states and two legal transitions; sometimes a list of permitted service edges; sometimes a schema joined on stable identifiers. The relevant question is what representation makes a recurring engineering question easier to answer.
2.1.2 A Model Is a Purposeful Reduction
A model is a purposeful reduction of a system. It preserves the information one engineering question needs and suppresses the detail that question does not. Its value is not completeness but selective omission. A reduction an engineer or agent can reason through is more useful than a faithful copy too large to hold in view.
Purposeful reduction is therefore not only compression. It can change the difficulty and character of reasoning. A property that requires semantic reconstruction over thousands of implementation details may become a relation over a small graph, a transition over a finite state space, or a bound over a measured quantity. The representation does not make the answer true. It can make the question tractable. Nor does it make the design decision: it makes selected consequences of that decision easier to reason about.
Reduction is useful only if it preserves the distinctions the engineering question requires. A representation can contain accurate information and still be inadequate because its output has no way to express a consequential case. Later in this chapter, a DocAble entitlement failure shows exactly this: code observed that a group carried unlimited entitlement, then reduced entitlement to a finite-credit scalar that could not represent unlimited — the sum deliberately excluded the unlimited groups the code had just identified. An unlimited user became zero credits. The missing distinction produced a production failure and, in response, an explicit decision model.
This is the connection Modeling shares with representation learning: what a reasoner can infer efficiently depends partly on the form in which the problem is presented. MAGE begins from representations engineering has already developed for consequential system questions rather than asking a learned reasoner to rediscover those abstractions on every task.
Tolerance and degrees of freedom
The suppressed detail has a realization-side consequence. Engineering obligations rarely determine a single acceptable realization. They constrain some variation and leave other choices open. This book uses two engineering terms for that distinction. A tolerance bounds the variation that an obligation permits; a degree of freedom is a realization choice left open because the governing obligations do not distinguish among its acceptable alternatives. Purposeful reduction therefore does two things at once: it represents the distinctions the engineering question requires while declining to settle choices that do not matter to that question. MAGE does not seek to close those degrees of freedom merely because they could be specified.
Preserving a degree of freedom can defer a decision to a reasoner better positioned to make it. There are two distinct reasons. First, information may arrive later. The target environment, surrounding implementation, workload, available components, or consequences of earlier choices may not be known when the model is constructed. A decision made during realization can use information that an earlier decision could not. Second, the realizing agent can actively acquire evidence before deciding. It can construct alternatives, run pilots, benchmark them, measure their consequences, and tune the realization to its environment. Human engineers can of course do the same, as can evolutionary algorithms, autotuners, search procedures, and other optimization mechanisms. What changes with commodity intelligence is how broadly and cheaply this kind of exploration can be applied during ordinary realization. Closing a degree of freedom early can therefore replace a later, evidence-informed decision with an earlier guess. Engineering should constrain the choices whose consequences matter now while preserving choices that can be made better during realization.
Parsimony provides the complementary test. Degrees of freedom reasons from the engineering obligation outward: what must the model preserve, and what may remain unspecified? Parsimony reasons from the proposed model inward: which of the distinctions it contains are actually required by the engineering question? A distinction that contributes neither to the question nor to a consequential obligation should earn its place or be removed. The aim is therefore not the smallest model, but the smallest model adequate to its purpose.
Adequacy fails in either direction.
- Too little reduction — unnecessary distinctions reproduce the complexity the model exists to escape: they consume attention, create obligations to keep model and realization in correspondence, and may needlessly constrain realization.
- Too much reduction — a consequential distinction disappears.
- A parsimonious reduction — enough structure to preserve the obligation, plus whatever scaffolding this reasoner actually requires.
MAGE therefore does not prefer more detailed models. It prefers adequate purposeful reductions, and sometimes the engineering improvement is deleting modeled structure. Nor, as a later section of this chapter shows, does MAGE prefer stronger semantic commitments merely because they are available. Both detail and semantic precision must earn their carrying cost. The examples ahead supply the boundary cases of this criterion: an ownership model whose omission proved genuinely free, and the entitlement reduction whose omission proved consequential.
Degrees of freedom asks what our present engineering obligations permit us to leave open. Parsimony asks whether the distinctions we currently represent earn their place. Neither judgment is final: experience may reveal that an omitted distinction was consequential, or that a represented distinction was unnecessary. A model records a provisional engineering judgment.
In software engineering, a tolerance can be numeric but is often qualitative. A latency budget may set a numerical bound: a response must complete within 200 ms. Coupling admits an intermediate form: an architecture may tolerate dependencies up to a measured threshold while also distinguishing kinds of coupling that are acceptable or prohibited. Other architectural tolerances are primarily qualitative: one component may depend on another through a declared interface but not reach directly into its implementation. The difference partly follows from the medium. Physical engineering often concerns continuous quantities such as length, voltage, pressure, or temperature, so tolerances naturally take numerical form. Software structures and behaviors are largely discrete—types, sets, relations, graphs, states, and transitions—so tolerances often define sets of acceptable realizations instead.
Even a numeric bound is rarely a single line. A budget usually carries a margin; a capacity envelope leaves headroom. A quantitative model can represent not just a target but the band of acceptable variation around it, so that "within tolerance" and "over the line" are both statable.
Software's medium compounds this: because programs are constrained less by physical material than by the information they must accept, produce, and preserve, different implementations can satisfy the same obligations, so the space of acceptable realizations is often large.88. Frederick P. Brooks, “No Silver Bullet: Essence and Accidents of Software Engineering,” Computer 20, no. 4 (1987): 10–19. There are often many right answers. Engineering need not choose one point in that space merely because it could. It can instead specify the properties that distinguish acceptable from unacceptable realizations and leave the remaining choices open. Good engineering constrains the choices that matter and deliberately leaves the rest free. Commodity intelligence changes the economics of exercising that freedom: once realization becomes cheap, an autonomous reasoner can construct and revise implementations inside a space that would previously have been expensive for human engineers to explore. Modeling identifies the consequential distinctions; Alignment can enforce selected boundaries. The rest remains available to realization.
Figure 2.1-1 draws the relationship: obligations bound a region without selecting a point inside it.
How much must be written down depends partly on who realizes it. The engineering obligation determines what must remain true; a particular engineer or agent may also need representational scaffolding — examples, decomposition, intermediate constraints — to interpret and realize that obligation reliably. Obligation plus scaffolding form the specified region, and its two boundaries behave differently (Figure 2.1-2). The obligation boundary is set by the engineering problem, and agent capability does not move it: a more capable agent does not make a required ordering optional or a consequential distinction irrelevant. The specification boundary can move, because a more capable agent needs less scaffolding. Capability can reduce how much we must specify. It cannot reduce what must be true. The limit is semantic: capability can bridge omitted scaffolding, but it cannot recover omitted semantics — a distinction reduced away is not reconstructible downstream.
Not every unmodeled choice is free
This also distinguishes tacit obligations from genuinely free choices. An unmodeled choice can look open even when engineers would reject some realizations of it. Then the choice was never wholly free. Human judgment was already imposing a boundary. What was missing was an explicit representation of the obligation or its tolerance. A genuinely free choice is different. Once the governing obligations are accounted for, engineering has no reason to distinguish among the remaining alternatives. A useful diagnostic follows: if a realization would provoke not that, some consequential boundary remains, whether or not anyone has written it down.
Whether a choice is tacitly bounded or genuinely free can change as engineers learn from the system. A region initially treated as free may expose a consequential distinction; investigation may also show that a suspected distinction does not matter.
ENGINEERINGInset — Uncertainty and unknown unknowns
Engineering distinguishes a choice deliberately left open from one whose consequences are not yet understood. The first is a degree of freedom. The second is uncertainty. In the harder case—sometimes called an unknown unknown—engineering has not yet recognized the consequential property, interaction, or failure well enough to ask the right question about it. An unmodeled region therefore should not be assumed to be free merely because no obligation has been stated.
A model cannot directly represent what engineering has not yet recognized. It can, however, make uncertainty more inspectable. By reducing a complicated system to selected entities, relations, states, quantities, or alternatives, a model can make variation and interaction easier to compare and trace. Unexpected behavior can then expose distinctions that were difficult to see in the realized system directly. A degree of freedom is known freedom; uncertainty is not.
This is one reason modeling can precede specification. Sometimes engineers construct a model because they know which property must hold. Sometimes they construct one to discover which properties matter.
Modeling does not require complete specification. Engineers can model what is known while leaving uncertainty visible and genuine freedom unconstrained. As understanding improves, the model can change with it.
The question is the design input. Ask whether two workers can process the same job at once, and the color of the web interface falls away; you need who can own work, how ownership is acquired, when it expires, and what happens after a crash. Ask instead whether one service may bypass another, and the ownership details fall away; now you need components, communication edges, and the seams a call must pass through. The system did not change. The question did. The useful reduction is not always obvious at first. Sometimes you have to look at the problem differently to see which relationships matter.
Hold the system constant. Change the engineering question. Watch the model change.
A model earns its place by the question it settles, not by how much of the system it represents.
This idea also has a long history in artificial intelligence. Knowledge-representation research treats a representation as more than stored information: its form embodies commitments about what distinctions matter and affects what kinds of inference are convenient or possible.99. Randall Davis et al., “What Is a Knowledge Representation?,” AI Magazine 14, no. 1 (1993): 17–33, https://doi.org/10.1609/aimag.v14i1.1029. MAGE applies the same principle to engineering representations.
A representation remains a purposeful reduction even when it is executable. Some models in this chapter participate directly in execution or analysis: machines query them, derive artifacts from them, generate from them, or check properties over them. Software can therefore make the distance between architectural representation and realization unusually small. Executability changes what a model can do; it does not make the model a complete representation of the system. That is why the examples ahead are drawn as reductions before their implementations are discussed: the abstraction should remain visible apart from its encoding.
2.1.3 Constructing and Revising a Model
Purposeful reduction is a judgment process, not an algorithm. No procedure takes an engineering question and returns the right model. The engineer reasons toward the boundary — what the model must preserve, what it may leave free — from more than one direction, and revises it as evidence arrives.
One direction is top-down, from the question. What must remain true? Which distinctions are required to express or evaluate that obligation? The model preserves those; the remaining realization choices stay free.
The complementary direction is bottom-up, from the proposed model. For each distinction represented, ask what engineering question or obligation requires it. If no consequential purpose justifies carrying it, remove it. This is the discipline of parsimony, applied as a working test.
Neither direction guarantees the boundary is right. Analysis, implementation, measurement, or failure may reveal that an omitted distinction mattered or that an included one did not. When the evidence changes the engineering judgment, revise the model. This is the theoretical role the chapter's two boundary cases play. The ownership model ahead is evidence that an omitted distinction really was a degree of freedom: the omission survived contact with the system. The entitlement reduction is evidence that an omitted distinction was consequential, so it is not merely a bad reduction. It demonstrates model revision under evidence: the engineer judged a distinction collapsible, and production proved otherwise.
The most important instance of revising from evidence is learning from realization itself.
Implementation can induce a model
The chapter has so far run in one direction: from question to model to realization. The direction also reverses. A cheap exploratory realization can expose a constraint, a tradeoff, a state distinction, a dependency, a bound that was invisible on paper — distinctions no one knew to ask about.
A prototype preserves a realization, but not necessarily the engineering knowledge learned from it. After probing, extract the durable relationship into an explicit representation; otherwise deleting the prototype deletes the knowledge. The probe answers a question without preserving the answer. The model is the artifact that preserves it.
Judging what an agent discovers
An agent can bring engineering patterns learned from other systems into an exploratory realization. That can be valuable: the realization may embody a decomposition, boundary, state distinction, or constraint that the engineer had not specified in advance. But design is contextual. A pattern appropriate elsewhere may violate an obligation or erase a distinction that matters here. The engineer must therefore judge which choices discovered through implementation are appropriate to the present system. Choices worth preserving should be extracted into explicit models rather than left to persist accidentally in one realization.
Model extraction turns candidate knowledge transfer into local engineering law. The agent can propose a judgment through implementation; the engineer decides that the judgment is appropriate here and should persist across later realizations. Once made explicit, that judgment can be inspected, communicated, revised, and eventually enforced. Until then, it remains merely a choice one realization happened to make.
Not every extraction becomes law. Some of what implementation reveals is descriptive — a measured bound, an interaction the system turns out to have — and is worth preserving as knowledge without any intent that later realizations conform to it. Law is the narrower case: the engineer accepts the discovered choice as one that should persist.
training supplies candidate patterns → implementation instantiates one → engineering judgment evaluates it in context → Modeling makes an accepted judgment durable → Alignment can later give selected judgments force
This division of labor is why the account belongs to MAGE rather than to good practice in general. Human authority is not human invention. The agent may supply the insight; the engineer decides what becomes durable.
The same distinction explains why MAGE does not simply say: give a sufficiently capable agent the code and let it infer the architecture. An agent may well infer a plausible architecture every time it is asked. But inference is not institutional memory, and it is not engineering authority. Different agents, contexts, prompts, or future priors may infer differently, and nothing in the system records which inference the engineers accepted. Once an engineer has decided that a discovered structure matters here, repeatedly asking intelligence to rediscover it is needless epistemic decay. Chapter 4 develops these dynamics — realize, observe, model, align — across the system lifecycle.
2.1.4 Structure and Semantics Make Representations Machine-Operable
A model can preserve the right distinctions without completely defining what those distinctions mean. Consider a box-and-arrow diagram drawn during a design meeting. The engineers may agree that the boxes denote services and the arrows denote calls. The diagram can be useful precisely because the people in the room supply much of its meaning. They know what counts as a service, what an arrow means, which details have been omitted, and which interpretations would be nonsensical.
That is often enough. But representations can make progressively stronger semantic commitments: they can move meaning from the interpreter into the representation itself. Boxes can become typed entities with stable identities. Arrows can become declared relations with defined source and target types. Properties can acquire units, multiplicities, constraints, or invariants. A modeling language can define rules for composition and analysis. At the stronger end, tools can determine mechanically what a representation means well enough to query, transform, check, simulate, or generate from it. Call this axis semantic commitment: how much of the representation's meaning is carried explicitly by the representation itself, rather than supplied by the humans or agents interpreting it.
This axis is distinct from purposeful reduction. Two models may preserve exactly the same engineering distinctions while making different semantic commitments. An informal component sketch and a typed system model might contain the same four components and three dependencies. They differ not necessarily in what they choose to represent, but in how much of the meaning of those components and dependencies the representation itself carries. Purposeful reduction governs what the model says. Semantic commitment governs how much the model itself says about what it means.
Greater semantic commitment buys capabilities, but it also creates obligations. More precise representations can be harder for people to author and read. Their concepts must be defined, their types and relationships maintained, and their correspondence with the realized system preserved. Stronger semantics are therefore not inherently better. The appropriate question is what the representation must support.
Table 2.1-1 illustrates the range with concrete modeling artifacts, from an informal sketch through UML 2.5.11010. Object Management Group, OMG Unified Modeling Language (OMG UML), Version 2.5.1, OMG Document formal/17-12-05, technical report (2017), https://www.omg.org/spec/UML/2.5.1. and OpenAPI/JSON Schema to SysML v2 and its semantic foundation, KerML.1111. Object Management Group, OMG Systems Modeling Language (SysML), Version 2.0, OMG Document formal/26-03-02, technical report (2025), https://www.omg.org/spec/SysML/2.0.1212. Object Management Group, Kernel Modeling Language (KerML), Version 1.0, OMG Document formal/26-03-01, technical report (2025), https://www.omg.org/spec/KerML/1.0. The rows are not maturity levels: stronger semantic commitment is useful only when the resulting precision and machine operability justify its cost. Nor does stronger semantics necessarily close more degrees of freedom. A SysML model may say less about a realization than an elaborate natural-language specification while saying what it does say much more precisely. Amount specified and precision of meaning are separate axes.
| Semantic commitment | Concrete example | Semantics supplied by the representation | Interpretation burden | Remaining realization freedom | Agentic implication |
|---|---|---|---|---|---|
| Mostly implicit | Informal box-and-arrow architecture sketch | Almost none beyond marks and labels; the team supplies what boxes and arrows mean | Low for readers who share the context; high for anyone who does not | Very large | Agent must infer both the intended semantics and the realization |
| Notation with standardized semantics | UML 2.5.1 state-machine diagrams | Standardized model elements and relationships give diagrams meanings beyond their visual appearance | Requires notation knowledge and project context | Large; UML generally describes selected aspects rather than determining a program | Agent has substantially more structure to interpret, but considerable design and implementation remain |
| Machine-readable structured model | OpenAPI 3.1 / JSON Schema; a typed repository model such as DocAble's registries and schemas | Named entities, types, fields, constraints, references, and relationships are directly machine-readable | Structure is explicit, but domain intent remains contextual | Often still large: a schema can constrain externally relevant properties while leaving implementation open | Agent can query and transform explicit structure rather than reconstructing it from prose or code |
| Semantically defined engineering language | SysML v2 + KerML 1.0 | Abstract syntax, types, relationships, expressions, constraints, and semantic foundations are defined as part of the language; machine-readable interchange is standardized | Substantial language and tool knowledge, but less semantics to reconstruct | Potentially very large: precise semantics do not imply complete specification | Tools can reliably interpret and compose more of the model; agents can reason over model elements and tool-produced results rather than rediscovering their meaning |
The columns do not form a single progression from weak to strong engineering. Greater semantic commitment usually makes more mechanical interpretation possible, but it does not simply lower the interpretation burden — it relocates it. An informal sketch asks almost nothing of a reader who already shares its context and a great deal of one who does not; a semantically defined language asks for language and tool knowledge up front, and in exchange leaves less meaning to be reconstructed each time the model is read. What changes across the rows is where the interpretive work is done, and by whom.
This distinction matters particularly for generative implementation. Semantic precision and generative completeness are different properties. A model can have precisely defined meaning while remaining radically incomplete as a program. Conversely, a detailed prompt can say a great deal about an intended implementation while leaving much of its meaning informal. The question is not whether a model can generate the code. The question is which decisions the engineer has made explicit and which decisions the implementor remains authorized to make.
AGENT HARNESSInset — Tools
MAGE seeks to move suitable work out of probabilistic reasoning and into engineered mechanisms. Today's agent harnesses do this partly through tools. A tool gives the agent an engineered capability it can invoke: querying repository state, parsing a file format, running a compiler, inspecting a dependency graph, applying a transformation, or executing some other operation whose mechanics need not be reconstructed through model reasoning each time.
Tools change the division of labor inside the engineered system. Suppose an agent needs to determine which component owns a file. It might infer ownership from directory names, nearby code, and documentation. Or the environment might maintain an ownership model and expose a query over it. In the second case, the agent still has to decide why ownership matters and what to do with the answer, but it no longer has to infer the answer from indirect evidence. The same move applies to parsing, dependency analysis, schema validation, code transformation, and many other operations: suitable work can move from probabilistic reconstruction into mechanisms whose behavior is engineered directly. Merely exposing a tool does not guarantee that the agent will invoke it when appropriate, so consequential uses may need to be built into the surrounding workflow or checked at an enforcement boundary.
This is why MAGE's concern is broader than tool use. A tool is one contemporary interface through which an engineered environment can expose knowledge or capability. The deeper design question is what the probabilistic implementor should actually have to realize. As more knowledge and suitable operations move into models, queries, transformations, validators, and other engineered mechanisms, reasoning can be concentrated on the decisions that still require it.
Externalizing knowledge saves reconstruction only when later reasoners can recover what was externalized. Machines can do this more reliably when important entities and relations are structured — given a declared shape — rather than being recoverable only from prose. Schemas, registries, graphs, and typed records expose entities and relations that tools can traverse, validate, and join reliably.
A common useful form is a graph of engineering entities and relations. Its nodes are engineering entities: services, modules, endpoints, queues, databases, requirements, tests, owners. Its edges name the relations: calls, depends on, deployed to, owned by, verified by. The graph need not live in a graph database. YAML, registries, and schemas joined on stable identifiers can represent the same structure. The word graph names the structure, not the storage. Relevance then follows relationships: start at the entity a task names, and its neighbors come with it, so the agent reasons over a connected slice instead of a document dump.
Many of these representations can be interpreted as graphs of entities and relations. Their shape is not what distinguishes them; their semantics are. A dependency edge, a transition, an ownership claim, and a permission can all be drawn as arrows while answering different engineering questions. Semantic commitment determines how much of that distinction is merely understood by the reader and how much is declared in a form the engineered environment can interpret. The representation becomes useful through what those entities and relations mean, not through the fact that they happen to be drawn as nodes and edges.
Externalizing knowledge this way is the lightest form of Modeling, and much of current practice already stands on it. Spotify's public account describes a retrievable service catalog. Cloudflare's describes standards externalized under stable identifiers. Shopify's describes a different form, in which agent sessions are mined into reusable skills. DocAble assembles its graph from registries, schemas, and YAML joined on stable identifiers. Each makes selected engineering knowledge durable outside a single reasoning episode, allowing later agents to retrieve rather than reconstruct it.
Agentic systems make this tradeoff newly consequential. A human team can sustain surprisingly informal semantics through shared context: the same engineers repeatedly look at the same diagram and remember what its arrows mean. Agents do not provide the same continuity. Across tasks, contexts, models, and time, unstated semantics must be inferred again — the needless epistemic decay the previous section described, now at the level of meaning rather than structure. Stronger semantic commitment can therefore convert recurring interpretation into durable engineering knowledge. It does not eliminate agent reasoning; it lets engineers decide which meanings agents should no longer have to reconstruct.
2.1.5 Representations Support Accumulating Capabilities
Increasing semantic commitment can make additional capabilities possible: typed relationships, machine-checkable properties, derivation, generation, traceability, composition, querying, and checking. These capabilities do not arrive in a required sequence, nor do they define a maturity model. Different representations make different commitments because they serve different engineering purposes.
The practical rule remains selective modeling. Model facts that are repeatedly reconstructed and properties that are repeatedly adjudicated. A service catalogue may end repeated ownership discovery; an invariant may retire a recurring class of judgment. Add semantic commitment when the resulting reduction in recurring engineering work justifies carrying it.
Enforcement remains separate. A rich model may remain advisory, while permissions, sandboxes, compilers, or tests may enforce obligations with little explicit system-level modeling. Modeling expands the set of properties that can be stated and evaluated; Chapter 3 asks which the engineered environment should enforce (Figure 2.1-3).
2.1.6 The Engineering Modeling Repertoire
Software engineers do not need to invent a representation from first principles each time they encounter a consequential question. Engineering fields have accumulated a large repertoire of models for recurring questions: component and dependency diagrams, state machines, data-flow models, schemas, decision tables, quantitative models, provenance records, and many others. Each preserves different information and supports different analyses.
Figure 2.1-4 shows a small portion of that repertoire. A dependency graph makes reachability and layering available for analysis. A finite-state model makes legal transitions available for state exploration or model checking. A quantitative model can expose a budget, margin, capacity, or rate to calculation. Similar graphical forms can carry very different semantics: an arrow may represent a dependency, transition, flow, permission, ownership relation, or derivation. What matters is not the shape of the representation but the engineering question its entities and relations preserve.
The practical skill is recognizing the engineering question and selecting a representation that preserves the properties needed to answer it. MAGE prescribes no new notation. The inset gives the broader rule: reuse the modeling knowledge engineering fields have already accumulated.
ENGINEERINGInset — Reuse the engineering repertoire
This chapter does not attempt to enumerate every useful model nor every consequential engineering question. Its purpose is to draw attention to the fact that your system has consequential questions, and that models provide a means of articulating those questions in representations that let engineers reason about those properties and give agents a succinct form in which to reason about them. The examples ahead illustrate that practice rather than exhaust it.
But you are an engineer. Take this not as an invitation to invent a new modeling technique for every problem, but as a reminder to study the models, patterns, and analyses your field has already developed. Once the engineering question is known, start with the established repertoire. State machines capture legal transitions; dependency and data-flow graphs support reachability questions; schemas capture entities and relations; queueing and resource models expose capacity and contention; decision tables and constraint systems expose permitted combinations. Each comes with known semantics, applicable analyses, strengths, and tradeoffs.
An engineer who needs to sort data does not ordinarily invent a sorting algorithm from first principles. The engineer recognizes the problem and selects among established algorithms according to the properties and tradeoffs that matter. Modeling works the same way: recognize the engineering question, then choose a representation that preserves what is needed to answer it. Occasionally the established repertoire is inadequate and invention is required. Recognizing when that is true, and devising the new abstraction, is precisely the kind of judgment for which engineers are valuable.
There are books full of this accumulated knowledge. Software architecture, model-based systems engineering, formal methods, databases, distributed systems, operations research, performance engineering, and other fields document modeling techniques and the conditions under which they work. MAGE does not reproduce those catalogs. It provides a framework for deciding when such knowledge should become an explicit part of the engineered environment. A governed engineering environment can then make the relevant repertoire—or an approved subset of it—available directly to agents. Appendix E shows one realization: DocAble's self-governance skill packages the MAGE engineering method for agents, including a modeling repertoire and modeling moves. The agent can recognize a situation, choose an appropriate Modeling or Alignment move, act through the environment, and learn from the resulting evidence rather than inventing its engineering method afresh on each task. The repertoire is reusable engineering knowledge; choosing from it remains engineering judgment.
The sections ahead therefore do not survey the repertoire. They develop three kinds of modeling question through production examples from DocAble. Structural models ask what exists and how parts relate. Behavioral models ask what may happen and in what order. Decision models ask what is allowed or which alternative should be selected. Other questions require other representations; ownership, measurement, and provenance will appear where the examples need them. The final section asks what becomes possible when several such representations describe the same system and can be connected through shared identity.
A model does not govern the system merely by existing. Modeling makes an engineering property explicit; Alignment makes selected properties enforceable.
Works Cited
- Zave, Pamela, and Michael Jackson. “Four Dark Corners of Requirements Engineering.” ACM Transactions on Software Engineering and Methodology 6, no. 1 (1997): 1–30. https://doi.org/10.1145/237432.237434.
- Nuseibeh, Bashar, and Steve Easterbrook. “Requirements Engineering: A Roadmap.” In “Proceedings of the Conference on the Future of Software Engineering.” Special issue, Proceedings of the Conference on the Future of Software Engineering (New York), 2000, 35–46. https://doi.org/10.1145/336512.336523.
- Lamsweerde, Axel van. Requirements Engineering: From System Goals to UML Models to Software Specifications. Wiley, 2009.
- International Council on Systems Engineering. Systems Engineering Handbook: A Guide for System Life Cycle Processes and Activities. 5th ed. Wiley, 2023.
- ISO/IEC/IEEE. ISO/IEC/IEEE 42010:2022, Software, Systems and Enterprise — Architecture Description. Technical report. Geneva, 2022.
- Booch, Grady, James Rumbaugh, and Ivar Jacobson. The Unified Modeling Language User Guide. 2nd ed. Addison-Wesley, 2005.
- Fairbanks, George. Just Enough Software Architecture: A Risk-Driven Approach. Marshall & Brainerd, 2010.
- Brooks, Frederick P. “No Silver Bullet: Essence and Accidents of Software Engineering.” Computer 20, no. 4 (1987): 10–19.
- Davis, Randall, Howard Shrobe, and Peter Szolovits. “What Is a Knowledge Representation?.” AI Magazine 14, no. 1 (1993): 17–33. https://doi.org/10.1609/aimag.v14i1.1029.
- Object Management Group. OMG Unified Modeling Language (OMG UML), Version 2.5.1, OMG Document formal/17-12-05. Technical report. 2017. https://www.omg.org/spec/UML/2.5.1.
- Object Management Group. OMG Systems Modeling Language (SysML), Version 2.0, OMG Document formal/26-03-02. Technical report. 2025. https://www.omg.org/spec/SysML/2.0.
- Object Management Group. Kernel Modeling Language (KerML), Version 1.0, OMG Document formal/26-03-01. Technical report. 2025. https://www.omg.org/spec/KerML/1.0.