The blueprint is the source
I set out to compile docs from a codebase, and ended up questioning whether code should be the source at all.
Where it started
I have worked on codebases that span frontend and backend, held together by glue such as the T3 Stack, tRPC, Hono with drizzle-zod, and more recently Effect v4. Much of the reason these exist is to carry the backend's source of truth to the frontend that consumes it, with type safety and runtime validation that catch drift early.
Public documentation follows the same principle: derive every downstream view from one source of truth, so nothing has to be maintained twice. Docs generated from code can be tailored to serve both public and internal readers, yet I think they could do far more to help engineers and agents understand a codebase and move through it efficiently. So I began to wonder: what if there were a tool that feels alive and dynamic, yet is derived entirely from the codebase it runs on?
My first answer was a better doc generator: one that scans the whole codebase, parses it, compiles functions and documentation recursively, and works out how everything is wired together.
I tried this on several of my projects: TypeScript, React Native, monorepos with modules, native code, web and backend. It proved extremely difficult, if not impossible, for static analysisInspecting source code without running it, usually by parsing files into syntax trees and following imports and types. to understand all of that at once.
A config file seemed like a way out. But the point of the tool is to compile directly from the source, and a config file is one more layer that can drift or be forgotten as new things are added to the repository.
Drift, even with agents
These repositories are already agent-run. Agents write the code, update the docs in the same commit, and run gates on every change. Stale references still slip through: 1 of about 45 code references in this site's AGENTS.md, and 3 of 176 path references in UT Companion
, one of which stayed wrong for 77 days.
21 Jun · file moved6 Sep · doc fixed
The drift that costs most is semantic driftWhen two parts of a system still compile and run, but quietly disagree about what a name, field, or rule actually means.: a server and a client that disagree on what totalSpaces means, or a README that recommends npm where AGENTS.md forbids it.
It gets worse with size. If a repository grows ten or twenty times, keeping every doc and function aligned costs that many more tokens.
That cost led me to an intermediate idea, while I was still treating code as the source: for functions and classes, what if their human-readable descriptions were not stored at all? A description that is not stored cannot go stale. An agent would write one on demand, only when someone wants to know more. Everything else, the comments and the code itself, could then be written for agents first. That solved stale prose on individual functions, but it did not explain the whole shape of a repository.
One codebase, many views
Tools that derive docs from code already exist. I ran TypeDoc, react-docgen-typescript and scip-typescript on two of my repositories, and on a repository set up the way they expect, they work well. But none of them reads a stylesheet, a design token, a Figma file, the meaning of a route file or a glossary: the part that is particular to one repository.
So the first half of my vision is a layer that covers that part too: documentation, visualizations and isolated previews of the frontend, derived from the source and the designs, and kept current by agents.
What it makes possible is that every team reads the same codebase in the language it understands, laid out the way it works. Take a payment flow. A designer cares where the cart, checkout, confirmation, failure and order detail screens go. Marketing and sales care about pricing and offers, the funnel and what is tracked. Developers care about the logic they own. Each reads the same plain-language blueprint of the flow from its own side, and each can suggest a change that an agent understands and carries out against the code.
Primitives, not platforms
The other half of the vision is how that layer itself is built. Code is now cheap. Theo Browne argues that generating lines of code is virtually free, and that the engineering value lies in verification, infrastructure and keeping software correct. So I don't think the old shape, one software core with adapters and plugins around it, is the right way to build this. I picture an ecosystem instead, like shadcn/ui but for lower-level code: small chunks that are owned locally and tailored to what one codebase needs, which makes the tool both faster and simpler.
There is an older name for what I want from those chunks. Rico Mariani called it the pit of success: a platform built so that people fall into the right practice, with no willpower needed. For human developers that is good design. For agents it matters more, because an agent that hits a blocker does not stop. It reverse-engineers the code around it and still produces work that looks valid. A primitive removes the reason to do that: the right way through is also the shortest one.
Two releases point the same way. Vercel launched Board as an experimental primitive for agents: a message store they use through a CLI, an SDK and a skill. Guillermo Rauch calls it a "headless Slack" for agents, with "no heavyweight or opinionated UI". UI SDK ships UI behaviors as primitives that an agent assembles into components, and it lets an agent read a running component's state and call its actions. I read both as products turning into primitives: small, refined parts that share one language, so an agent can build the final product from them, then understand and control it through the same API, without the menus, forms, or glue added for a person.
What I would keep shared is smaller than a core: a Glossary. I take the term from Matt Pocock's skills, where GLOSSARY.md is the one file that holds a project's vocabulary, so that every person and agent on it uses the same words in the same sense. Here the Glossary is the language the blocks share, and everything built from it is owned locally.
The blocks can start from a registry, in the manner of shadcn/ui, but once an agent has fitted them to the repository, they belong to it. That means an agent can reshape the pit itself as well. A Glossary is still a document, so it cannot eliminate drift on its own. What it does is shrink the shared surface area to one small vocabulary file and a suite of contract testsAutomated tests that verify the shared inputs, outputs, and invariants a component must honor, regardless of how it is implemented internally. that every locally tailored block must still pass.
What I expect
The programming language will become a matter of mechanics, not preference. When I read a liquid thermometer, I note the line at the fluid's level and rarely care what the fluid is made of, as long as it holds within the range I am measuring. For most product behavior, I care as little about the language underneath a program, and for much of what I build, that is already true.
Once every role can read and edit a blueprint like the payment flow's, the direction of compilation starts to invert. I expect programs to be read and judged in the structure of natural language, open to finer and finer technical detail. The blueprint becomes the source, the thing people keep and change, and the code is what an agent builds from it. Picture it as recursive text: a passage that opens into deeper passages as you zoom in. Engineers would inspect behavior instead of code.
Depth 0 of 3The blueprint
That promise is not new. MDAAn approach that generates executable code from high-level visual or structural models, rather than writing the code by hand., UMLUnified Modeling Language: a standard set of diagrams for modeling a software system's structure and behavior. and BDDBehavior-Driven Development: writing plain-language scenarios (such as Given/When/Then) that serve as both specification and automated tests. all tried to make high-level specifications the source, and all ran into the same walls: ambiguity in plain language, broken round-trippingKeeping a high-level model and its generated code in sync when edits happen on either side. once someone edited the generated code, and production bugs that the spec never described. A single line like charges once, safe to retry still hides idempotencyEnsuring that repeating the same request (after a timeout or double-click) produces the same result instead of charging a customer twice. keys, race conditions, and partial failures. What agents change is the translation cost: they can turn a concise rule into those mechanisms and fold a production fix back into the blueprint without a brittle formal grammar. What they do not erase is drift itself. It moves, from docs falling behind code to generated code falling behind intent, and when production disagrees with the blueprint, an engineer still has to drop down to the traces and the code.
One tool has kept the round trip whole. In XState, a machine's structure is declarative enough that Stately can render it and write visual edits back to code: the diagram is not generated from the code, they are two views of the same definition. Drift moves here too. The structure cannot fall out of sync, so drift collects behind the named guards and actions that still live in code. What it shows is the trade-off: the round trip holds only because the grammar is formal, and a statechartA visual model of a system's states, the events it responds to, and the transitions between them. only describes states and transitions, not the pricing, layout or copy other teams care about. A blueprint does not have to be all prose: where a flow really is states and transitions, that formal skeleton is worth keeping, with agents handling the rest.
Tools may invert the same way. Board and UI SDK are already products turning into primitives, and a tool is only a packaged set of actions, kept so they can be reused and shared. If an agent can assemble those actions whenever it needs them, nobody has to keep the package. The tool becomes something living, assembled just in timeCompiled or generated at the moment it is needed, rather than built and packaged ahead of time. and changed every time it is used.
Another way to see it is as streaming, where what flows is not a film or a song but code, generated and run as it arrives. Versions and packages exist to freeze code so people can agree on what they are running, and just as importantly, to amortize the cost of verification across security fixes, edge cases, and audits. An agent that owns its part, and can change it, test it and run it again, can only do without them where automated verification is cheap and complete enough to trust every run. Where that holds, it can keep improving that part with no person in the loop.
For now, the blueprint holds: a person keeps the source, and an agent builds from it. I don't yet know how far that is from a river of code that assembles and runs itself, or what we would have to understand before we could cross it.