Software’s hardest problem used to be the ‘how’ — the syntax, the tests, and the shipping. AI just collapsed the cost of solving it. But in doing so, it created a more dangerous one: our typing rate has finally decoupled from our reasoning rate.
When a team can produce code faster than they can think through its consequences, they don’t just work faster — they move faster in the wrong direction.
Intent-First Development (IFD) is the corrective. It is a methodology built on the claim that in an AI-driven world, documentation is no longer an optional audit trail; it is the design itself, with code as its executable expression. This piece walks through the four claims the methodology rests on, the structure they produce, and why this shift is what keeps an accelerated codebase from becoming one no one can reason about.
Table of contents
What design has always been
Before there was a methodology to write down, there was a practice. Senior engineers and architects have been doing some version of this for forty years.
The practice goes roughly: before you build the system, you reason about what it should be. You name the problem, the people who feel it, the constraints on the answer. You consider alternatives and rule some of them out. You make commitments to the choices that survive that reasoning. Then — only then — you start typing.
The reasoning was the design. The code was its expression. Documentation, when it existed at all, captured a fraction of the reasoning for posterity.
This worked, imperfectly, because the bottleneck on a software system was the typing. Typing was slow enough that the reasoning had time to catch up. The reasoning happened in heads, in whiteboard sessions, in code review, in the hour between deciding to refactor and starting to refactor. It rarely got written down because it didn’t have to — the people doing the typing were the same people doing the reasoning, and the rate of typing was slow enough that the reasoning kept pace.
Two things changed.
The first is that AI assistants now type as fast as the reasoning can be articulated, and often faster. The second is that the AI assistants doing the typing have no access to the reasoning unless it is written down. Where reasoning used to live in heads and stay in sync with the code by ambient effort, it now has to live somewhere durable, structured, and machine-readable, or it falls out of sync with the code on the first day of AI-assisted work.
Intent-First Development is a methodology designed around this fact.
The central claim
The methodology rests on one inversion, which produces everything else:
The documentation corpus is the design. Code is its executable expression.
In conventional practice, the design exists in heads and conversations; documentation, when written, captures fragments of it after the fact; code is the design’s primary durable form. Diagrams and comments orbit the code, secondary to it.
In Intent-First Development, the relationship reverses. The durable form of the design is the documentation corpus — the explanation documents, the design decision records, the reference artifacts, the captured assumptions and risks and open questions. The code is the executable expression of that corpus. When the corpus and the code disagree, the corpus is what was decided; the code is just what was last typed.
This is not a claim that documentation is important. Documentation has been “important” for forty years and most teams ship without it, because the practice did not need it. This is a claim that documentation is now load-bearing — that the reasoning of the design has to live somewhere durable because the typing rate has decoupled from the reasoning rate, and the AI assistants doing the typing read documentation but not minds.
Everything else in the methodology follows from this inversion.
The four pillars
If the central claim is “the documentation corpus is the design,” then four pillars follow as direct consequences. These are the structure of the methodology — what holds it together, and what distinguishes it from “write more docs.”
Pillar 1: Documentation precedes code
Significant new work begins with reasoning, captured as documentation, before any implementation. The explanation document that describes a feature is written before the feature is implemented. The design decision document that records a choice is written before the choice is committed to code. This is not a sequencing preference; it is the methodology’s primary discipline. Code written before its design is captured produces a system whose shape is decided by accident — by whichever piece of code happened to land first — and the methodology exists to prevent that.
The discipline is not “write a long design document and then start coding.” It is “write the design at the altitude where it is genuinely understood, before descending to lower altitudes that depend on it.” What’s known at the start of a project is rarely an architecture; it’s a vision. The methodology says: capture the vision, defend it, then descend. Premature commitment to lower altitudes is the most expensive mistake in AI-collaborative design, and the methodology has explicit machinery for preventing it.
Pillar 2: Intent is embedded throughout, not stored separately
There is no “intent document.” Intent — the chain of reasoning that explains why the system is this shape and not another shape — lives wherever it’s relevant. It lives in the explanation document for a feature. It lives in the design decision document that records a choice. It lives in the captured assumption that explains why a constraint is treated as fixed. It lives in the open question that names what is being deferred until more is known.
This is a discipline, not a layout decision. The discipline says: if there is reasoning behind something, capture it where the reasoning is relevant. A pattern with no captured why becomes a pattern that the next person — AI or human — has to reverse-engineer or guess at. A decision recorded as code without recorded reasoning is recorded as fait accompli; it cannot be debated, revised, or learned from. The methodology’s commitment to embedded intent is what makes the corpus a design rather than a description of one.
Pillar 3: Decisions are first-class artifacts
When a choice is made among real alternatives, it is recorded — not as an afterthought, but as a structured artifact with a specific shape: the scenario that surfaced the choice, the options considered, the recommendation that emerged from analysis, the decision that was actually made (which is sometimes different from the recommendation), and the reason for any divergence. These are called Design Decision Documents, and they are the spine of the corpus.
The discipline that distinguishes IFD from looser practices is the separation of recommendation from decision. A recommendation is what the analysis supports; a decision is what the team chose, possibly under constraints the analysis did not capture. Conflating the two produces a design record that cannot be revisited honestly — when conditions change, you can’t tell whether the original analysis was wrong or whether the original constraints just no longer apply. Keeping them distinct preserves the audit trail. It is what makes the corpus durable across time and across teams.
Pillar 4: Code is the executable expression of the design
The corpus is the design. Code follows. When the two disagree, the corpus is what was decided.
This pillar sounds redundant with the central claim, but it carries a separate operational discipline: when implementation reveals that the design needs to change, the documentation is updated as the first step of the work, not as an afterthought. This is the discipline that prevents the corpus from rotting. A corpus that is not maintained alongside the code becomes a museum exhibit within a quarter, and a museum exhibit is worse than no documentation at all because it gives false confidence.
The pillar does not require that every line of code have a corresponding paragraph in the corpus. It requires that the corpus and the code remain in conversation — that when the system’s shape changes, the design that was the system’s shape is updated to match. The methodology’s review processes (documentation review before code review, capture skills that auto-trigger during conversation, regular re-reading of the corpus during onboarding) all exist to keep this discipline real.
What the methodology gives up
A methodology is honest only when it names what it costs.
Time before the first commit. The first design session on a new project does not produce code. It produces a vision document. Teams that measure progress by commits will find this initially uncomfortable. The methodology does not pretend otherwise; it claims the trade is worth making because the alternative is committing to a design that emerged from typing rather than from thinking.
Resistance to “ship now, document later.” The methodology is incompatible with the school of thought that says documentation is what you do when you have time. It treats documentation as the work, not the wrap-up. Teams that have institutionalized “we’ll document it after launch” cannot adopt IFD without changing that habit. This is the most common failure mode of half-adoption.
A corpus to maintain. Once the corpus exists, it has to be kept in step with the code. This is not free. It is, however, more durable than the alternative: most undocumented systems lose their reasoning to attrition within eighteen months, regardless of methodology, because the original architects move on and the reasoning moves with them. The methodology’s cost is paid in steady maintenance; the alternative’s cost is paid in catastrophic loss.
Discipline that has to come from somewhere. No methodology executes itself. The capture discipline — recording decisions, assumptions, risks, and open questions as they surface — has to be installed in the team’s working habits. The most reliable installation pattern is automated capture during conversation (the work is offloaded onto the working surface itself), but the discipline still requires the team to value what it’s capturing. Teams that don’t believe the corpus is worth the maintenance will not maintain it well, regardless of how the capture is implemented.
These are the costs. The methodology is not free. It is worth paying for, for the reason the next section names.
Why this matters now and didn’t before
The four pillars are not new ideas. Documentation-driven development is older than most current engineers. Architecture Decision Records have existed since 2011. Domain-Driven Design predates that. Treating documentation as a primary artifact is a practice with a long pedigree.
What changed is the typing rate.
When a senior engineer typed, the rate at which code reached the codebase was slow enough that the reasoning had time to keep up. The engineer might write a function on Tuesday and not write the next one until Wednesday. In the intervening day, the design held still. The reasoning in the engineer’s head and the code in the repository drifted at compatible speeds.
When an AI assistant types alongside that same engineer, the rate at which code reaches the codebase is no longer constrained by typing. It is constrained by how fast the engineer can articulate intent. If the intent is articulated in a chat message, the chat message produces the code, and the chat message is gone the next morning. If the intent is articulated in a documented design, the document produces the code, and the document persists.
The methodology’s claim is sharper than “documentation is good.” It is: the rate at which code can be produced has decoupled from the rate at which reasoning is produced, and the only way to keep the two in step is to make the reasoning durable. The corpus is what keeps them in step.
A team that does not capture its reasoning durably can still ship — for a while. The cost shows up over months as the system’s shape becomes harder to defend, the team’s mental model drifts from what’s actually in production, the AI assistant starts contradicting decisions that were once load-bearing, and the next person who joins the team has no path into the reasoning that produced what they’re looking at. None of these are catastrophic in isolation. In aggregate, across the velocity AI assistance produces, they are how a working system quietly becomes a system nobody can defend.
The methodology is the discipline that catches this drift before it accumulates. It works because it captures reasoning where it lives — embedded in the corpus, structured by Diataxis quadrants, sequenced by altitude, formalized by decision records. None of these are new ideas. What is new is that they have to be applied as a coherent practice, because the typing rate no longer leaves room for ambient reasoning to keep up.
Diataxis
A documentation framework that organizes content into four quadrants based on what the reader is trying to do: Explanation (why things work the way they do), How-To Guides (how to accomplish specific tasks), Reference (facts and specifications), and Tutorials (guided learning paths). IFD uses Diataxis as its structural framework because each quadrant serves a distinct cognitive mode — keeping the corpus navigable by both humans and AI assistants without requiring every reader to understand the whole.
What this is not
Three things the methodology is sometimes confused with, briefly:
- It is not a process framework. It does not replace sprint planning, code review, or release management. It produces artifacts those processes can act on; it does not prescribe how to plan or ship.
- It is not “write more docs.” A team can write thousands of pages of documentation without practicing IFD, and a team practicing IFD may write less documentation than a team without it — but the documentation that exists is structured, reasoned, and load-bearing. Volume is not the measure.
- It is not tied to any specific AI tool or vendor. The methodology is tool-agnostic. The reasoning durability it produces benefits any AI assistant that reads documentation. It also benefits human readers — a corpus that reads well to an AI tends to read well to a new team member.
Where to start
The methodology is large enough that it is rarely adopted all at once. The natural entry points differ by situation:
- A team starting a new project commits to capturing the vision before descending to architecture. The first design session is the first explanation document. Lower altitudes earn their place as higher altitudes stabilize.
- A team adopting on existing code starts with whatever the code itself reveals about its purpose and structure. The reasoning that can be reconstructed from the code is the starting corpus. New decisions are captured as they surface; historical decisions are captured when they become relevant, not all at once.
- An individual practitioner adopting alone begins with the next decision they make. That decision becomes the first design decision document. The first one is a contagion event, not a mandate. The methodology spreads from individual practice more reliably than from team-wide rollout.
There is more, and more nuance, and the body of work behind the methodology continues to grow. But the entry point is small. The methodology is a discipline, and disciplines are practiced one act at a time.
A short list of what is true
If the methodology had to be reduced to a list of operational claims that hold up under examination, this is the list:
- The bottleneck in software has moved from typing to intent. The rate of typing has decoupled from the rate of reasoning, and the gap has to be closed somewhere durable.
- The documentation corpus is the design. Code is its executable expression. When they disagree, the corpus is what was decided.
- Intent is embedded throughout the corpus, not stored in a single document. There is no “intent doc” because intent is what gives every document its weight.
- Decisions are first-class artifacts. The recommendation, the decision, and the reason for any divergence are kept distinct.
- Documentation precedes code at the altitude where the design is genuinely understood. Lower altitudes earn their place as higher altitudes stabilize.
- The corpus is maintained alongside the code. When implementation reveals that the design needs to change, the documentation is updated as the first step.
- The methodology is tool-agnostic. Any AI assistant that reads documentation benefits from a corpus shaped this way.
That is what makes Intent-First Development tick.
Frequently Asked Questions
Isn’t this just ADRs with a new name?
ADRs record one decision at a time. IFD treats the entire documentation corpus as the design — explanation docs, recorded decisions, captured assumptions, all of it together. ADRs sit inside an IFD project; they’re one artifact type in a broader practice. The real difference isn’t vocabulary: it’s that IFD asks you to make documentation the directive for implementation, not its audit trail. A codebase with a healthy ADR repo but no documentation that AI sessions read as context still has the problem IFD addresses. The test is simple: if your AI assistant produces code that contradicts a decision you made last quarter, your documentation isn’t directing implementation. It’s record-keeping.
The post acknowledges the pillars aren’t new ideas. What is IFD actually contributing?
Prior art is real: ADRs since 2011, DDD since the early 2000s, documentation-driven development older still. IFD’s contribution is not any individual artifact type — it’s the claim that these artifacts are now load-bearing in a way they weren’t before, and the practice structure that follows from that claim. When typing was constrained by human speed, reasoning in heads kept pace with code. When an AI assistant types as fast as intent can be articulated, reasoning has to live somewhere more durable than heads. IFD is what you get when you design a practice around that specific pressure: not “write better docs,” but “make documentation the executable form of design, maintained alongside the code, at the altitude where the design is genuinely understood.”
“Documentation precedes code” — but when can I actually start writing code?
Nothing in IFD prevents you from writing code at any point. The constraint isn’t a rule; it’s a consequence of what you’re trying to accomplish.
IFD’s value is that your AI assistant has a documented corpus to work from — intent captured at each altitude, design decisions recorded, architecture settled before components are designed. When you write code before that corpus exists at the relevant altitude, the AI fills the gaps by inference. It generates an architecture by accident, optimized for the first feature rather than the system. You get code. You don’t get what IFD promises: implementation directed by documented intent, whose shape can be explained and defended six months later.
Premature implementation isn’t against the rules. It’s just not the fastest path to the outcome. The fastest path to a system whose shape you can defend is letting each altitude stabilize before descending to the next. That isn’t a waterfall: different components can be at different altitudes simultaneously, and well-understood components can enter implementation while others are still in design. What it prevents is code generated from nothing — which is the failure mode the methodology exists to catch.
On a brownfield project, the narrower version applies: write the DDD before the PR that depends on it.
Does this require AI to be useful?
No, but without AI-assisted development, most teams can ship without it — and historically, they did. The corpus benefits human readers too: new team members orient faster, technical decisions survive team turnover, architecture reviews have artifacts to evaluate. The methodology became necessary with AI-assisted development because the typing rate decoupled from the reasoning rate. A team practicing IFD without heavily using AI assistants will still produce more durable, defensible systems than one that doesn’t. The AI is what makes the practice urgent; the corpus is what makes the design survivable.
How do I know when the corpus is good enough to act on?
Run the test: hand the relevant explanation doc and any DDDs to your AI assistant, ask it to implement a feature you’ve already thought through, and read what comes back. If the output aligns with your intent without requiring you to intervene — if the design decisions the AI makes are the ones you would have made — the corpus is doing its job. If the AI produces code that contradicts a recorded decision or misses a documented constraint, the corpus has a gap. Fix the corpus, not the code. “Good enough” is the threshold where AI sessions are directed by the corpus rather than inventing design as they go.