Here is a small thing that nearly everyone building AI agents has noticed, and that almost nobody has properly explained. The smaller the artifact you hand an agent, the better it does with it. Break the thousand-line file into modules and the coding agent stops mangling it. Split the ebook into a file per chapter and the writer stops losing the plot halfway down. Turn the sprawling knowledge base into a page-per-idea wiki and a cheap little model suddenly reasons as if it knows your business cold.

Ask why, and the answer comes back automatically: “it fits the context window better.” That is true. It is also about a quarter of the reason. The other three-quarters are more interesting, they do not go away when the windows get bigger, and — this is the part worth the whole book — they turn out to be the same pattern showing up on four completely different kinds of work.

To see it clearly, we need to start somewhere unexpected: with a watchmaker in a sixty-year-old paper, and with the peculiar, short, repeatedly-interrupted life of the agent doing your work right now.

The two watchmakers

In 1962, Herbert Simon — Nobel laureate, one of the founding figures of artificial intelligence — published a paper called The Architecture of Complexity.¹ Buried inside it is a parable about two watchmakers that reads, today, like an operating manual for agentic AI.

Both watchmakers, Tempus and Hora, make fine watches of about a thousand parts each. Both are excellent, so both are in demand, and their workshop phones ring constantly with new orders. That constant ringing is the whole story.

Simon’s point was not really about horology. It was about evolution, organisations, and why complex things exist at all. His conclusion is one sentence, and it is the hinge of everything that follows:

Complex systems that survive in an interrupting world are built from stable intermediate forms.

Read the parable a second time with a single substitution, and it stops being a charming analogy and becomes a specification.

Your agent is Tempus

Ask a plain question: what is an LLM agent’s working life actually like? The honest answer is constant interruption. Context windows fill and end. Sessions die. Compaction quietly eats the history in the middle of a task. The next agent that picks the work up starts cold, with no memory of what the last one was holding in its hands. An agent’s normal condition is Hora’s ringing phone — except the phone never stops ringing.

This is not a rough edge that better models will sand away. It is structural. We have written before about the one-hour ceiling — the way an agent’s coherent working session runs out and has to be handed on — and the architecture required to build understanding across those deaths rather than within one of them. Call it what it is: agent mortality. Your builders are on a one-hour clock, and the clock resets to a stranger.

Now the parable bites. A monolith forces every agent to be Tempus. Hand an agent one giant, undecomposed artifact and every interruption threatens the whole of it: to make a safe change it must re-hold the entire thing in attention, and when the context ends, the work in flight falls apart on the bench. Hand it stable subassemblies instead — a function, a chapter file, a wiki page — and each one survives the death of the session that produced it. The interrupted agent loses only the small piece in its hand.

That is why breaking work into pieces, making the pieces navigable, and recomposing them is not merely tasteful engineering imported from a neighbouring discipline. It is an agentic pattern, forced by a property of the workers themselves. And it is the thing worth writing down: the pattern of decomposing, making navigable, and recomposing is an agentic pattern in its own right.

So isn’t this just good software engineering?

Partly — and that is a feature, not an embarrassment. But notice the difference in why.

Software engineers earned this discipline over decades because it made systems humane to change. We inherit it for free, and then discover a reason Simon would have recognised instantly: our builders are mortal, on a one-hour clock, and only the work already assembled into stable pieces is still standing when the next one arrives.

So the pattern is agentic. The rest of this book is what the pattern actually is. It pays four dividends, not one — and three of them never expire, no matter how big the context windows grow (Chapter 2). It has a full four-step mechanism, and the step everyone skips is the one that quietly rebuilds the monolith if you get it wrong (Chapter 3). And it is a single move that shows up, unchanged, on four different planes of work — code, artifacts, agents, and knowledge (Part III).

Start with the dividend everyone underrates. When you break a thousand-line file into modules and the agent stops choking, “it fits the window” is the reason you reach for — and it is the least important of the four.

Anyone who used agentic coding tools in the early days remembers the wall. Files under a few hundred lines: the model was a delight. Files past about a thousand lines: it started to lose its footing. It would edit the wrong region, patch a function two screens away from the one you meant, and — the memorable failure — occasionally delete a big chunk of working code while trying to make a small, careful change. The instinct at the time was to blame the model’s intelligence. That was the wrong diagnosis, and getting it right is the whole of this chapter.

Here are the four jobs a component quietly does, each with the concrete failure it prevents, and — the column that matters most — whether a bigger, smarter model makes it go away.

The unit of edit: the filename is the address

Start with the one the early models taught us the hard way, because it dismantles the “the model was just dumb” story completely. Those patch disasters were not failures of reasoning. They were failures of addressing. The model was asked to locate a precise span inside a thousand-line sea and to mutate exactly that span and nothing else — a needle-in-haystack targeting problem — and it missed the needle. When it deleted a working block, it was not because it misunderstood the code; it was because it aimed at the wrong coordinates.

Decompose the file and the addressing problem evaporates, because the filename becomes the address. You no longer ask the model to find the code; you hand it the file that is the code. The unit of matter and the unit of edit line up, and a whole category of careless, destructive mistakes simply cannot occur — there is nowhere for the patch to go wrong, because the target is the entire small thing in front of it.

This is the first hint that “fits the window” is a decoy. A model with a ten-million-token window can still fumble the edit if the edit target is a fuzzy region inside a giant blob. Fit is about reading. Addressing is about writing. They are different problems, and only one of them scales away with context size.

The unit of regeneration: decomposition sets the grain

The second dividend is the sleeper, and it is the one that welds this pattern to how the durable asset in AI work is actually the recipe, not the output. Our position elsewhere is blunt: stop nursing AI outputs; once patching costs more than rebuilding, nuke the thing and regenerate it from its kernel.

Here is the connection nobody states out loud: a component is the largest thing you can cheaply throw away and regenerate from its specification. Which means your decomposition is quietly drawing the borders of what you can afford to regenerate. Cut coarse, and “regenerate” means rewriting an enormous artifact to fix one paragraph — too expensive, so you patch instead and accumulate rot. Cut well, and regeneration becomes surgical: throw away the one chapter, the one function, the one page whose spec changed, and rebuild only that. Decomposition sets your regeneration granularity. The finer and cleaner the cut, the more often “delete and rebuild from the recipe” is the cheap, correct move rather than the nuclear option.

The unit of parallelism: monoliths serialise your fleet

The third dividend is why the whole pattern stays optimal even after models stop choking on big files. A monolith is a single shared resource: only one agent can safely be working inside it at a time, because two simultaneous edits to the same giant file collide. That serialises your agents. It turns a job that could be ten workers wide into a queue one worker deep.

Components break the serialisation. When each unit lives in its own file with its own cheap interface, a sprint can fan out — ten workers, ten files, no merge conflicts, because nobody is editing anybody else’s subassembly. This is the same reason Hora could, in principle, hire ten apprentices and have them build ten subassemblies at once, while Tempus’s single-blob method can only ever be one pair of hands deep. Parallelism is not a bonus you bolt on; it is a property you unlock the moment the matter is decomposed.

So what happens when the windows get huge?

This is the objection that sounds devastating and is not. The models have got better at big files. The attention constraint genuinely relaxed — a modern model can hold a thousand lines without losing the middle. If “fits the window” were the whole story, decomposition would now be a crutch we could throw away. So look again at the right-hand column of the table.

The constraint that eased was exactly the one people mistook for the whole reason. The other three — clean addressing, surgical regeneration, collision-free parallelism — are structural. They belong to how the work is arranged, not to how clever the reader of it is. No model release touches them. That is why the honest verdict on the “we can stop decomposing now” reflex is short and unhedged:

A thousand-line file in a glass vial is still bad design — and the agent was never the only reason.

Breaking work into pieces is the famous half of the pattern. But a pile of pieces is not a system. The half that gets skipped — and the half that decides whether you have actually escaped the monolith or merely relocated it — is how the pieces are allowed to reconnect. That is the next chapter, and it contains the one leg of the pattern that almost everybody leaves out.

A pile of well-cut components is not yet a working system. Something has to hold them together, and the nature of that something decides whether you have genuinely escaped the monolith or simply moved it somewhere harder to see. The complete pattern has four moves, and the fourth is the one that separates people who have felt the benefit from people who can reliably reproduce it.

The interface is Parnas, 1972

The second move is the oldest idea in the pattern, and naming its lineage is worth a paragraph because it tells you what a good interface is for. In 1972, David Parnas asked the question the whole discipline of modularity turns on: on what criteria should you split a system into modules?² His answer was information hiding: a module should be built around a design decision it keeps secret, exposing only a stable interface, so that when the hidden decision changes, nothing outside the module has to change with it.

Fifty years later, that is exactly why a coding agent can call a function it has never read, and a writing agent can reference a chapter it is not currently holding. The signature is the secret-keeper. The chapter card says what the chapter delivers without making you hold its prose. The one-line index entry lets a page be reached without being loaded. Each is the cheapest possible view of a component — enough to use it, not enough to drown in it. It is the resolution ladder applied one component at a time: the interface on top, the body available on demand below.

The map stays dumb, and so does the glue

The third move — the map — is deliberately unglamorous. It is a manifest, and a manifest should be mechanical: a call graph the compiler builds, an index.md you can read at a glance, an outline file, a table of contents. Its whole virtue is that it carries no cleverness. It just records which interface connects to which.

Which brings us to the fourth move, the load-bearing one, the one almost everybody skips: recomposition must be dumb. Assembly must require no intelligence at all.

Why does this leg matter so much? Because of what happens if you get it wrong.

If composition required intelligence, you’d re-import the monolith problem at assembly time — just moved somewhere later, and harder to see.

The moment your reassembly step needs a model to work out how the pieces fit together, you have quietly built a second monolith at the seam. Now there is a stage that has to hold all the components in attention at once to glue them — which is precisely the giant-blob problem you decomposed to escape, wearing a different hat and standing further down the pipeline where it is harder to notice. You did not remove the monolith. You relocated it to assembly time.

The rule that falls out is simple to state and easy to check: intelligence lives inside the components; the glue between them is mechanical. Any cleverness that migrates into the map or the recompositor is a warning sign, not a feature.

That is the whole mechanism. It sounds almost too tidy — four verbs and a warning — until you point it at something real and watch the correspondences turn out to be exact rather than poetic. The cleanest place to see that happen is somewhere no one expects a codebase: a wiki.

Everything so far has been the pattern in the abstract, illustrated with code. This chapter is the pattern done end to end on a single, unlikely example — unlikely because most people file “knowledge base” and “codebase” in different mental drawers. The claim of this chapter is that, once you build the knowledge base the right way, they are the same drawer.

The setup is a wiki of the page-per-idea kind: each concept gets its own small page, pages link to each other with typed edges, and an index lists them. It was built for a mundane reason — to make a large, sprawling worldview navigable, so an agent could focus on one idea at a time and then pull the relevant ones together for the job at hand. Exactly the composability move from code, pointed at knowledge. And that is when the strange thing happened: the correspondences to software were not loose analogies. They were exact.

The mapping is not poetic

Lay the two side by side and the terms line up one for one:

• Pages are functions. Each is a small unit with a single responsibility and a body you do not have to read to use it.
• Edges are the call graph. A link from one page to another is one unit invoking another; follow the edges and you are tracing execution.
• The index is the manifest. index.md is the map — the deterministic list of what exists and how to reach it.
• Claims are statements. The atomic assertions inside a page are its lines of code.

If that were the end of it, it would be a cute table. It is not the end of it, because the maintenance layer — the agent whose job is to keep the wiki from decaying into a junk drawer, the one we call the janitor — turns out to be doing something a software engineer would recognise on sight.

The janitor is a refactoring engine

Watch what the janitor actually does when it tidies the graph, and translate each move into its software name:

This is the moment the metaphor collapses into identity. You are not looking at a knowledge system that happens to resemble software maintenance. You are looking at software maintenance, performed on claims instead of statements.

You didn’t build a knowledge base that resembles a codebase. You built a codebase whose language is claims — and imported forty years of software maintenance discipline for free.

Why does the janitor work at all?

Because of that last phrase. The reason an automated maintainer of a knowledge graph is even buildable — the reason it does not immediately drown in judgement calls it cannot make — is that refactoring is a solved craft. Deduplication, extract-method, splitting an overgrown module, running the tests before you commit, recognising a bad refactor when you see one: these are not novel problems anyone has to invent for the knowledge domain. They arrive pre-invented, with decades of accumulated discipline behind them. Once your worldview is a codebase in disguise, maintaining it is not a research project. You are running refactor on your own thinking, with a toolset the industry spent forty years hardening.

What this rests on — and what it doesn’t re-litigate

This chapter is deliberately narrow: it is about the wiki as a codebase, not about why a wiki-graph beats other ways of storing knowledge. That larger argument — that the binding constraint in retrieval is relationships, not raw text, and that you should compile a self-cleaning wiki-graph before any question is asked — is one we have made in full elsewhere, and it is the substrate this whole chapter stands on. Take the wiki-graph as given; the point here is only that, given it, its maintenance is refactoring.

One property is worth a single paragraph because it shows the loop closing. When an agent queries the wiki and descends far enough to find a page contradicted by ground truth — the page says one thing, the source says another — the right move is not to quietly answer around the discrepancy. It is to file a work item for the janitor: page X contradicts its source; pages Y and Z overlap. Query-time failures become the maintenance queue. Which means the act of using the system improves it — the same write-back loop that turns a codebase’s bug reports into its next refactor, running on knowledge. (The mechanics of that loop are the substrate’s, not this chapter’s; we simply note that the refactoring frame explains why it belongs there.)

So knowledge is a plane where the pattern runs perfectly — arguably the most convincing demonstration, because it is the one place you would least expect a codebase to be hiding. But it is only one plane. The reason this chapter earns the word flagship rather than the point is that the very same move — decompose, interface, map, dumb-recompose — runs on three other kinds of matter too. Two of them you already work with every day. The other two are where almost nobody had thought to make the cut.

If the pattern is real, it should not feel exotic. It should turn out to be the thing you were already doing on the planes you know best, only now visible as a single named move rather than a set of unrelated habits. So before the two surprising planes, the two familiar ones — because seeing the move in territory you already trust is what makes the generalisation land.

Plane one: code

This is the home plane, the one every engineer already lives on. You do not write one giant monolithic block; you break it into functions and classes, and you refactor it different ways as your understanding sharpens. That instinct is decades old and needs no defending. What is worth noticing is a second habit that comes from the same instinct and is easy to miss: prying the prompts out of the agent code.

A prompt buried inside application code is a monolith in miniature: coupled to the logic around it, awkward to version, owned by nobody in particular, drifting quietly. Lift it into its own markdown file and it becomes a component — separately maintainable, diffable, ownable, with the code that uses it now depending on a small stable surface instead of a wall of inlined text. It is the exact code move (extract the thing, expose an interface, keep the caller dumb) applied to a new kind of matter.

What’s the cheap interface on code?

On the code plane the interface has a precise, tooling-backed form: the signature-level skeleton. Tools that give an agent a repository map extract the function and class signatures — structure without bodies — so the model can navigate a codebase far larger than it could ever hold, seeing how the parts connect without reading every line.³ That is the cheap interface made concrete: enough of each component to reason about, none of the body until the body is needed. The same idea as a chapter card or an index entry, expressed in tree-sitter.

Plane two: artifacts

The second familiar plane is the documents themselves — and this ebook is standing on it. When the writing got serious, the move was to stop treating a book as one long document. Build an outline as a markdown file. Outline each chapter as its own file. Then, when rendering the finished thing, make each chapter its own PHP file and let the index simply pull them in.

Look at what each move buys. The writer works one chapter’s context at a time — the unit of attention, honoured. Each chapter is its own file, so the edit target is the whole file — the filename is the address again. The outline is the map. And assembly is a mechanism the coding tools understand cold: include the parts, run php index.php, and the book falls out. No intelligence at the seam. The dumb recompositor from Chapter 3, wearing PHP.

Trace it against the four moves and there is nothing left over. Decompose: one file per chapter. Interface: the chapter card — a one-line promise of what the chapter delivers — is what the outline holds instead of the prose. Map: the outline file and the table of contents. Dumb recompose: include and render. The same skeleton as the wiki, the same skeleton as the code, on a third kind of matter.

Two planes down, and neither one surprising once you can see the shape. The interesting part is that the identical move runs on two more — the agents doing the work, and the worldview they work from — and those are the two planes where hardly anyone had thought to pick up the knife.

The first two planes were recognitions: oh, I was already doing that. The next two are extensions — the places where taking the knife to the monolith was genuinely a new move, and where the payoff was largest precisely because so few people had made the cut.

Plane three: agents

The obvious way to build a capable agent is to build one big capable agent — a single brain wired to every tool, holding every responsibility, prompted to do it all. It is also the Tempus move: one monolith, and every interruption threatens the whole of it. The decomposed alternative is to split the work across single-responsibility workers, each narrow, each behind a thin router that only classifies and dispatches. Small, composable agents beat one mega-brain for the same reason small files beat one giant one — and we have argued that plane in full on its own.

Two things from earlier chapters snap into place here. The unit of parallelism from Chapter 2 is the fleet: decomposed agents fan out because each owns its narrow scope, exactly as decomposed files let workers fan out without collision. And the handoff between a cheap agent that explores and a frontier agent that decides — swap the brain, keep the transcript — is the agent-plane version of interface-plus-dumb-recompose: the exploring worker hands over a stable artefact, and the decider composes from it without re-doing the walk. This chapter does not re-derive either argument; it only notes that both are this book’s one pattern, applied to workers.

Plane four: knowledge

The last plane is the worldview itself — and it is last for a reason worth ending on. For a long time the mental model of an AI “kernel” was a single document: the big markdown file that held your taste, your rules, your frameworks, the whole compiled understanding an agent should boot with. And it produced a puzzle that would not resolve: why are there different kernels? A taste kernel, a brand kernel, a frameworks file — if the kernel is the kernel, why does every task-shape seem to need its own version of it?

The puzzle dissolves the moment you see it as a decomposition problem. Multiple kernels were never a design; they were a workaround for a monolith that could not be queried. The wiki is the kernel after the refactor: the same worldview, cut into pages, linked by edges, and recomposed on the fly from whatever a given job actually touches. You do not load the whole thing and hope the relevant part is in there; you boot tiny and demand-page the pages the task reaches. The named kernels survive, demoted to something better — entry points into the graph rather than rival documents. (The full argument for kernel-as-wiki is its own piece; here it is simply the fourth plane arriving.)

There is a fleet consequence that closes the loop with plane three, and it deserves exactly one sentence because its economics belong to other articles: once the intelligence lives in the wiki, every agent you write is nearly the same agent — a toolbelt, a slightly different North Star, different inputs — because the way each one navigates and understands its problem is the shared, decomposed worldview rather than a bespoke, hand-tuned prompt. Decompose the knowledge, and the agents that read it commoditise.

Four planes, one move

Stand back and the whole thing is a single gesture repeated on four kinds of matter.

Same move each time: match the unit of matter to the unit of attention, hide the bodies behind cheap interfaces, keep the map deterministic. Four planes, one gesture. Which would be a satisfying place to stop — except that the gesture has a boundary, and the boundary is where all the real difficulty lives. Simon knew it, said it in the same 1962 paper, and it is the subject of the last chapter.

It would be easy to end a chapter short of here, on the tidy four-plane summary, and leave the pattern sounding like a rule you can apply without judgement. That would be dishonest, and Simon — who started us off — supplies the correction himself, in the very same paper as the watchmakers.

Simon’s real word was “nearly”

His term for the systems that survive was not “decomposable.” It was nearly decomposable.¹ The distinction is the whole of this chapter. Real systems are never perfectly separable. Some concerns genuinely cut across every component — and pretending they do not is how you get a decomposition that looks clean on paper and fights you in practice. Those cross-cutting concerns are precisely why edges exist. An edge carries a relationship that does not belong inside any single piece. The map is not a concession to messiness; it is where the near-ness of near-decomposability is honestly recorded.

Which hands you a diagnostic that works on all four planes at once.

The god-object smell, on every plane

The pattern of the failure is the same wherever you look, which is the last piece of evidence that these really are one problem in four costumes:

And here is the part that should keep you honest about what can and cannot be automated. The decomposing can be mechanised — splitting a file, extracting a prompt, spinning out a page. The recomposing is dumb by design. But choosing where to cut — drawing the lines so that what is strongly related stays together and what is weakly related is separated by an edge — is the one irreducibly hard judgement, and it is the same judgement on every plane. The janitor’s hardest calls are all of this species. So are a senior engineer’s. It is exactly the kind of scarce, high-stakes judgement worth spending your best cognition on, and worth keeping a human’s hand near.

The one thing to carry out of here

Everything in this book compresses to a single, old, unglamorous truth, now wearing new clothes.

In software, the hard part was never writing the modules. It was choosing where to cut. That was true in 1962, it’s true for your codebase, and it’s now true for your agents and your knowledge — because they are the same problem wearing four different clothes.

Recall why the cut matters so much here in particular. Three of the four dividends — clean addressing, surgical regeneration, collision-free parallelism — are structural, and no model release will hand them to you for free (Chapter 2). And the deepest reason of all is the one we opened with: decomposition is how work outlives the worker, and your workers die every hour. A well-cut component survives the death of the session that made it. A monolith does not. Every interruption is a small test of whether you built like Tempus or like Hora.