A library rebuilt from 50 design docs matches its hand-checked models

Code is no longer the main artifact

Developers are used to treating code as a project's primary artifact. Documentation sits beside it, tests sit beside it, architecture notes live off somewhere to the side. The authors of Design Docs Are All You Need propose flipping that order: make design documents the primary thing and rebuild the library itself from scratch every time using AI coding agents.

It sounds like a provocation. But this is not one more chatbot bolted onto a repository. The authors are solving a specific problem: performance modeling for machine learning systems goes stale fast. Today you carefully describe one transformer type and one scheme for how accelerators work. Tomorrow mixtures of experts show up, a different attention scheme, new inference phases, a different hardware topology — and the old abstraction is already lying to you. In projects like this, the code often turns into a layer cake of patches.

The paper's idea is simple: if AI agents can already write code fast and cheaply enough, sometimes it is easier to rebuild the library from scratch than to fix the technical debt that has piled up.

This is a conversation about something larger: what should be long-lived in the age of AI — the code or the specification.

What the authors propose

The authors describe a library called smart for symbolic performance modeling of machine learning systems. But the real subject of the paper is how that library is maintained.

The repository's main branch contains almost no code. What it holds instead is a set of text design documents. They are linked into a directed acyclic graph: some documents depend on others, so code has to be generated in order. First, say, the description of hardware topology and numerical parameters, then the cost models for collective operations, then the model catalogs.

Then a pipeline of AI agents takes over:

🟠 the agents read the documents and automatically reconstruct the dependencies between them

🟣 an orchestrator walks the graph in the right order

🟠 a separate coding agent is launched for each document

🟣 the generated code is checked against reference models, parameter validation and tests

🟠 if something does not line up, a human edits only the document text, not the code

The point is that a human no longer edits the library by hand. They edit a specification in natural language. Code is a temporary build product.

The authors even introduce a near-formal term for this. When you change a system on top of an old implementation, you take on incremental generation debt — the debt of accumulated edits. The new version comes to depend not only on the new specification but on the old code with all of its compromises. A full rebuild simply zeroes that debt out.

Why ordinary code maintenance works badly here

The paper describes a problem plenty of teams will recognize. There are two sources of pain.

The first is a domain that keeps changing. Machine learning models and hardware move so fast that yesterday's convenient abstractions break. You cannot invent one elegant framework and then live off it quietly for ten years.

The second is the limits of the AI agents themselves. Even if you lean hard on code generation, the model rarely sees an entire mature codebase at once. It gets fragments. It solves a local problem. That lets it write a plausible-looking piece that fits the overall architecture badly. Repeat that enough times and the project's structure degrades.

The authors offer a radical answer: keep a clear textual description of the system, split it into self-contained documents, and run a full rebuild regularly.

In short, the idea looks like this:

🟣 debt from edits accumulates with any incremental update

🟠 an AI agent's context is limited, so local edits often damage the whole

🟣 full regeneration from the documents removes the dependency on old code

🟠 documentation becomes an executable specification

The numbers, briefly:

🟠 1.5–3 hours for a full rebuild of the library

🟣 about $100 for a build through the Claude Code API

For an academic prototype or an internal engineering tool, that already looks like a workable way to operate.

The documents have to be written differently

An interesting point in the paper: if you want to generate a system out of text, ordinary architecture notes will not do.

The authors do not stop at general rules, tests and interface descriptions. They insist on a different documentation style: it has to contain step-by-step worked examples. Not just a line saying "an all-gather costs this much", but a small scene with numbers and intermediate steps: on this topology, at this data size, each node carries this many links, so the cost works out like so.

Examples like that work as demos inside the text. For an AI agent they are not an abstract instruction but a sample of exactly how the semantics should be read. Where prose leaves room for ambiguity, an example narrows it.

The authors say outright that every document with calculations in it needs a verification anchor: a small, predefined case with an exact expected result. A test is then born out of that same text.

Here documentation is no longer an explanation attached to the code. It is the harness for generating, checking and repairing the system.

How the library itself is built

For this approach to work, writing good documents is not enough. You also need a minimal, stable internal model that can be generated from text again and again without an explosion of complexity.

So smart uses a very compact intermediate representation of operations. The base entity is an operation, which knows:

🟠 its inputs and outputs

🟣 its symbolic cost in compute, memory and communication

🟠 a table of resource occupancy per cycle

🟣 the parameters that let operations be assembled into graphs and loops

The key idea is that this representation is recursive. An operation can be a leaf, or it can be a subgraph or a loop with a body. That makes it possible to describe both a single matrix operation on a TPU and a large chunk of a model such as attention out of a small set of building blocks.

An important detail: all sizes and formulas are kept symbolically, through SymPy. The library does not substitute numbers right away; it builds expressions as formulas. Sequence length, block size, the number of nodes in the mesh — all of those are variables. You build the model once, then plug in different values quickly and sweep thousands of configurations.

That gives you two modes of operation:

🟣 a fast mode — a coarse analytical rollup for large sweeps across many points

🟠 a slow mode — a more detailed schedule that accounts for resources and dependencies

The first is what you want when exploring a space of options. The second is for when a fast sweep has turned up an interesting point and you now need to understand what is happening there at the level of the schedule.

Distribution is handled separately. The authors try not to place collective operations by hand wherever they can avoid it. Instead, tensors carry sharding annotations, and the all-gather or reduce-scatter that is needed is derived automatically from the data layout and the result of the operation. Only the collectives that genuinely change the layout across dimensions are specified explicitly.

Why minimality is what matters here

In many systems the problem is not that there is too little documentation. The problem is that the domain model itself is too heavy. If you have dozens of exceptions, special cases and historical sediment, an AI agent will get confused reliably, and a full rebuild will not save you.

The authors bet on a minimal set of orthogonal abstractions. The algorithmic half assembles a graph out of operations. The systems half assigns a price to leaf operations for specific hardware. If attention changes, you touch one layer of documents. If the interconnect or the TPU parameters change, another.

For domains where the specification changes faster than the code, that looks sensible. You want the long-lived object to be a clearly written-out model of the domain.

What they showed in practice

The authors do not stop at the general idea. They write that the current version of smart consists of roughly 50 design documents and about 9,000 lines of textual specification. That covers TPU topology, cost models for collective operations, numerical details, schedulers and catalogs of frontier model families: dense models, mixtures of experts, attention variants, plus models for robotics and vision-language tasks.

The main practical check is that the library rebuilt from scratch by the agents reproduces hand-verified reference models down to rounding. Among the examples is a model of serving DeepSeek-V3 on part of a TPU pod.

What matters here is something else: the text specification turned out to be enough to restore a working tool without hand-editing code as the main process.

The results, condensed:

🟠 about 50 documents in place of the main codebase

🟣 about 9,000 lines of specification in natural language

🟠 1.5–3 hours for a full rebuild

🟣 about $100 for a full build through the API

🟠 a match with the hand-built references down to rounding error

What this changes for engineering

The paper has a larger point. It suggests looking at a software system as a product regularly rebuilt from a specification, provided three conditions hold:

🟣 the domain changes fast

🟠 AI agents can already write modules like these reliably

🟣 the cost of a full rebuild is lower than the cost of living with the technical debt

This fits internal tools, research libraries and the parts of the stack where requirements and hardware move too fast especially well. In places like that, maintaining old code carefully may simply cost more.

But there is a hidden requirement too. The approach demands far more precise thinking in the documents. Write a vague specification and the agent will generate a vague system. If you cannot state invariants and examples, the rebuild will fail regularly.

So the paper is not about the magic of "the code writes itself". It is about the center of gravity of development shifting into the specification, the regeneration pipeline and the checks.

The takeaway

If you build tools for fast-moving AI systems, documentation can become the primary source and code a rebuildable artifact. On problems like these, that is sometimes a better deal than endlessly growing an old implementation.

The smart approach rests on three things:

🟠 self-contained design documents instead of scattered notes

🟣 step-by-step examples and verification anchors inside every document

🟠 a minimal symbolic representation that survives changes in models and hardware

Out of this grows a different mode of development. The human edits meaning. AI agents restore the implementation. Tests and reference calculations cut out the errors. If the specification changes every week, that loop may turn out to be more practical than the familiar hand-driven evolution of a codebase.