Applying Intent-First Development on Existing Projects

The cornerstone piece on Intent-First Development argues that AI assistance has decoupled the rate of typing from the rate of reasoning, and the only way to keep the two in step is to make reasoning durable — captured, structured, and read back by future AI sessions as primary input. The argument lands cleanly on a greenfield project: you're about to start something, you write the design before the code, the documentation grows alongside the implementation. The harder case is the one most of us are actually working in: an existing codebase, with active feature work, no documented design corpus, and AI assistants already involved.

The cornerstone gives one paragraph to that case — start with whatever the code reveals, capture new decisions as they surface, capture historical decisions only when they become relevant. That's the philosophy. What follows is the operational version: what to do, in what order, with what prompts.

There exist Claude Code plugins that automate IFD's setup work, and this piece will return to where they earn their keep. But they're conveniences over a methodology the cornerstone is explicit about being tool-agnostic. If you use a different AI tool, want to understand the methodology before committing to a plugin ecosystem, or are evaluating IFD on behalf of a team and need to defend the practices on their own merits, you can adopt IFD without installing anything specific to it. The path below uses your AI tool's native capabilities and a willingness to drive the orchestration yourself.

Two terms used throughout, briefly. Diataxis is a documentation framework that organizes content into four modes — explanation, how-to, reference, tutorials. Design Decision Document (DDD) is an artifact capturing a single architectural choice and the reasoning behind it. The IFD methodology defines templates for these and other artifacts, provided as part of an engagement with XTIVIA; this piece doesn't require them to start.

The misconception

"Documentation precedes code" is a methodology principle. It is not a setup requirement. It does not mean "document everything you have before you start." That reading produces the response IFD is most often dismissed for: "I don't have time for a documentation sprint."

Neither do we. A documentation sprint is the wrong move on a brownfield codebase even when there's appetite for it. The artifacts produced by a sprint are stale before they're reviewed — written by whoever has time, not by whoever has the context, with no validation against actual behavior. Three months later, half of them describe a system that no longer exists.

What "documentation precedes code" actually means on brownfield is narrower and more useful: the next decision gets documented before it gets implemented. You're not retroactively documenting what already exists. You're starting now, at the next real decision, and letting the corpus grow forward from there.

What actually starts the work

Brownfield IFD adoption rests on two ideas that change the cost equation entirely.

First: your AI assistant can produce the first cut, you don't have to write it. A capable AI assistant can read the codebase, infer its purpose and structure, reconstruct hypothesized design intent, and organize the output into Diataxis-shaped documentation. You're not authoring from a blank page — you're curating a draft. That changes the math. Authoring is what takes a sprint. Curation is the work this article is actually describing.

A caveat worth saying directly: AI authoring is fast, but human review of AI-authored documentation is not. Reading every hypothesized design intent, checking it against tribal knowledge, fixing the wrong ones, filling the gaps where neither the code nor anyone on the team can recover the original reasoning — that's the real time sink. We'll come back to this in tradeoffs.

Second: the transition entry point is the next feature, not the existing codebase. You do not document what you are not changing. The obligation is to the work at hand — the next feature, the next significant decision, the next component you are about to modify. Code that nobody's changing remains undocumented. Active code earns documentation as a natural byproduct of being touched.

This second idea has nuance worth naming. The line between "untouched" and "active" is porous on real codebases. A new feature pulls legacy code into the change surface during integration. A refactor sweep crosses the line opportunistically. AI agents wander further than expected. The principle is sound — do not preemptively document inert code — but the operational version is closer to "documentation grows wherever the work lands, including the surprises."

These two ideas together are why brownfield IFD adoption isn't a months-long preamble. The AI produces the starting tree. The team curates. The next feature begins with a design session. Documentation grows where the work grows.

Why bother — what going in without it actually costs

The argument for IFD on brownfield code is not "documentation is good." Documentation has been "good" for forty years and most teams ship without it. The argument is sharper than that.

On a brownfield codebase being touched by AI assistants, every session starts with limited grounding in past decisions. AI tools can read the code, search git history, parse PR descriptions, pull from Slack via MCP — the situation is rarely "no ambient memory at all." But what an AI cannot reliably reconstruct from those sources is intent under constraint: what was tried and rejected, what subtle requirement shaped the current design, which apparent oddities are load-bearing. Code records state, not choice. Git records changes, not the alternatives that were considered.

What you get when intent isn't captured, predictably:

• AI-generated PRs that propose patterns the team explicitly rejected eighteen months ago, with no record of why
• Refactors that flatten subtle constraints because the constraints weren't visible to the AI
• "Improvements" that re-introduce bugs the original team already fixed
• Drift: the system shape after six months of AI-assisted edits doesn't match anyone's mental model anymore, including the team's

IFD's value is not that records exist — they often do, scattered. It's that intent is captured deliberately, in a structured form, at the moment the decision is made, and is then read by future AI sessions as primary input. Structure and intentionality are what catch drift before it accumulates.

What you actually do — the six setup passes

What follows is six passes, each a prompt or short sequence of prompts you give your AI assistant. Each is a deliberate act. The whole sequence takes an afternoon for a small to mid-sized codebase. For a genuinely large system — multi-service, hundreds of thousands of lines — the honest answer is one to two days of orchestration, split across multiple sessions, plus a comparable amount of curation time afterward.

A note on the prompts below: they're written as if you can run them once across the entire codebase. On anything beyond a small monolith, that will blow context windows and produce thin output for whichever modules the AI happened to compress. Run them area-by-area on a large codebase — by service, by bounded context, by package — and accumulate the outputs into the same target file.

Pass 1 — Orient your AI to the codebase

Most AI tools have a native command for this. In Claude Code: /init. In Cursor: populating .cursor/rules/. If your tool has no equivalent, the prompt is straightforward:

"Read this codebase. Produce a starter orientation file describing: what the project is (in one paragraph), the technology stack (with versions where relevant), the inferred conventions (naming, structure, patterns), and any non-obvious facts a new contributor would need to know on day one. Save this as CLAUDE.md (or your tool's equivalent) at the project root."

This step gives the AI a codebase-grounded picture of the project before any IFD content is layered on. It is far more effective than authoring an entry file by hand from a blank template, because the AI can read the actual code and infer details a human would have to research.

Pass 2 — Scaffold the IFD structure

Create the Diataxis folder tree and the register subfolders. You can do this manually with mkdir, or have your AI do it:

"Create the following folder structure under docs/: explanation/, how-to/, reference/, tutorials/. Under reference/, create subfolders for decisions/, assumptions/, open-questions/, risks/, features/, stakeholders/. Add a README.md to each register subfolder briefly describing what artifacts that register holds. Add a top-level INTENT-FIRST.md that names this project as following IFD methodology."

IFD defines standard templates for each artifact type — Design Decision Document, Assumption, Open Question, Risk, Feature, Stakeholder, Project Context Card, Roadmap. These are provided as part of an IFD engagement with XTIVIA; if you're working independently, a minimal stub is enough to start and your AI can scaffold one on first use. The methodology does not require templates to be present from day one, but consistent structure makes it faster to scaffold new artifacts.

Pass 3 — Inventory the codebase

This is the structural pass: what exists, what depends on what, what each piece appears to do.

"Walk this codebase and produce a structural inventory at docs/audit/codebase-inventory.md. For each significant module, package, or service, list: its name, its location, its apparent purpose (one sentence), its dependencies (other internal modules and external libraries), and the entry points it exposes (functions, classes, endpoints, message handlers, whatever applies). Group entries by layer or by bounded context where the structure suggests one. Where you are uncertain about a piece's purpose, say so explicitly — do not invent a purpose to fill the field."

The inventory is not the documentation. It is the input to the next pass. Read what the AI produced. Where it got things wrong, correct it. Where it expressed uncertainty, that uncertainty is itself a finding — it points at code that lacks self-documenting structure.

Pass 4 — Reconstruct latent design intent

This is the harder pass. The AI is reasoning backward from code to the intent that shaped it.

"Using the structural inventory at docs/audit/codebase-inventory.md plus the code itself, produce a latent-intent reconstruction at docs/audit/intent-reconstruction.md. For each major area of the system, infer: what problem this area appears to solve, who appears to be the primary user or consumer, what constraints appear to have shaped the design (technical, organizational, regulatory, performance), and what design choices were apparently made among alternatives. Treat the output as hypothesized intent flagged for human curation — phrase claims as "appears to," "likely," "suggests," not as asserted facts. Where the code is consistent with multiple intents, name them and say which seems most likely from the evidence."

This is the pass that turns code into the seeds of a design corpus. The quality of the output depends heavily on the quality of the prompt and on how rigorously the AI marks its uncertainty. Read this output carefully. The places where the AI's hypothesis is wrong are the places where the team's tribal memory most needs to be captured — those are the highest-value curation targets.

Pass 5 — Organize into a Diataxis seed corpus

Now translate the inventory and the intent reconstruction into the IFD documentation structure.

"Using docs/audit/codebase-inventory.md and docs/audit/intent-reconstruction.md, produce a Diataxis-shaped seed corpus under docs/. Specifically:

• In docs/explanation/, write one explanation document per major area of the system, capturing the inferred why — what problem this area solves, what constraints shaped it, what alternatives appear to have been considered.
• In docs/how-to/, write one how-to per recurring active pattern in the codebase — patterns that future work will follow.
• In docs/reference/, write reference documents for the system's interfaces, data shapes, and structural facts. Cite the inventory.
• In docs/tutorials/, write a single 'onboarding new developers' tutorial describing the reading order through the corpus you just produced.

Mark every claim that is hypothesized rather than asserted. Where the AI is filling a gap with reasonable inference, say so explicitly. Cite specific file paths and line numbers where supporting evidence exists."

The output is a working draft. Curation comes next: promote what holds up, fix what's wrong, prune what doesn't matter, fill in what only humans know. Plan for this honestly. On a codebase with three years of history and twenty active developers, careful curation of Pass 5's output is days of focused team time, not an afternoon. The AI's draft makes the work tractable; it doesn't make it brief.

Pass 6 — Inventory the integration boundaries

The seed corpus from Pass 5 covers internal structure. This pass covers what crosses the system's edge — and it deserves its own focused attention because tracing call sites and reading integration config requires different inferential work than reading internal structure.

"Walk this codebase and produce a boundary inventory at docs/reference/boundaries.md. List every integration boundary: REST/SOAP/GraphQL endpoints (incoming and outgoing), message-bus producers and consumers, database connection points, file I/O call sites, UI-to-service call paths, and any other point where the system communicates with something outside its process. For each boundary, document: location in the code, direction (inbound or outbound), protocol or mechanism, the adjacent system or actor, and any non-obvious behavior (retries, timeouts, idempotency, authentication)."

The boundary inventory is what makes the next design session concrete. When the next feature touches an existing integration, the boundary record tells the design session what is already there and what is changing.

The ongoing practice — The next feature gets a design session

The six passes are setup. They run once. What follows is the steady state, and it's the part that actually delivers IFD's value over time.

Every new piece of work — feature, integration, user-facing capability — starts with a design session before implementation. On a brownfield project, the design session opening accounts for current state:

"I'm designing [new feature]. Before I describe the feature itself, here's the relevant context from the existing system that shapes the design space: [current state summary]. Given that context, here is the intent for the new feature: [intent statement]."

The explanation doc produced by this session includes a "Current State" section that captures what exists today and what changes with this feature. This is how brownfield context enters the documentation corpus — not through a separate documentation effort, but as the natural first section of any feature explanation doc. Decisions made during the session become DDDs in the decisions register. Assumptions surfaced during the session become Assumption records. Risks become Risk records. The corpus grows forward as a natural byproduct of the work.

That's the whole IFD adoption sequence. The first run takes an afternoon to a couple of days. Everything after is the next feature, and the next.

When the Intent-First Development plugins start to earn their keep

The IFD plugins automate the setup passes. The code-archaeologist plugin orchestrates passes 1, 3, 4, and 5 with pipeline-managed state between them, and offers an audit-grading variant for prioritization. The boundary-mapper plugin orchestrates Pass 6 and offers diagram-producing variants. The intent-first plugin scaffolds Pass 2 in a single command and provides capture skills that auto-trigger during design sessions.

The decision rule is simple. Run the methodology-only path once, on a single codebase, and the plugins are overhead — installation and configuration take longer than running the prompts manually. The plugins start earning their keep at the second run, and they're load-bearing by the fifth: across multiple codebases, on a recurring engagement basis, or for client-facing audit reports where output consistency matters.

What plugins give you that the manual path doesn't: state preservation between passes (Pass 4 sees what Pass 3 produced via explicit handoffs, not a context window your AI may have compressed), prompts that have been tuned over many runs, and pipeline reuse across projects. The manual path makes you the orchestrator of those concerns.

The corpus is portable. If you start with the methodology-only path and adopt plugins later, the documentation you've already built carries forward unchanged. The plugins read what's there and pick up from where you stopped.

The methodology is what matters. The plugins are an automation of it. Either path produces the same shape of corpus.

What you don't have to do

This list is the part most teams need to hear explicitly.

• You don't have to document the whole codebase before you start. The seed corpus from passes 3–5 covers what the code itself reveals; you curate it, and that's the starting point. No sprint.
• You don't have to reconstruct historical decisions. The decisions register begins empty. Capture decisions as they become relevant — when you encounter an architectural choice with no recorded reasoning, write a Design Decision Document for it then. Not all at once.
• You don't have to touch untouched code. Legacy modules nobody is changing remain undocumented. They are not at risk because nothing is changing them. (Caveat from earlier: the line is porous; expect to document a few "inert" things that turn out to be in the change surface.)
• You don't have to commit to specific tooling. The methodology runs on top of any AI assistant capable of reading code and producing structured documentation.
• You don't have to convince the whole team before starting. A single team member can adopt the practice for their own work and demonstrate the value. The first design decision document is a contagion event, not a mandate. A caveat applies though: solo-adopted IFD captures one person's view of intent. When teammates' AI sessions consult those docs, they're grounding on a single perspective. That's still better than nothing — it gives the team something concrete to react to — but the methodology's full value comes from design sessions as a collaborative act. Plan to broaden adoption rather than treating solo as the destination.

The honest tradeoffs

The methodology-only path is more work than the plugin path. It is honest to name where.

You are the orchestrator. The plugins manage state between passes — pass 4 sees what pass 3 produced, pass 5 sees what pass 4 produced, with explicit handoffs. Without them, you hold that state by reading each output and feeding it forward. AI assistants forget; long sessions degrade in quality; context windows have limits. You will sometimes need to re-issue a prompt with the prior pass's output explicitly included, because the assistant has lost track of it.

Prompt quality matters more. The plugins ship with prompts that have been tuned over many runs. Your version of pass 4's prompt may not be as good as the plugin's. The first time through, the output may be thinner or less rigorous. This improves with iteration; the plugins amortize that iteration cost across all users.

The output is hypothesized intent, not recovered ground truth. This is true for both paths. The seed corpus tells you what the code currently does and what its structure suggests it was meant to do. It cannot tell you:

• What was tried and rejected — the alternatives that were considered and ruled out
• What constraints came from outside the code — regulatory requirements, client agreements, deals struck with adjacent teams
• What the system should do that it currently doesn't — gaps between intent and implementation
• The reasoning behind decisions that the code records as state but not as choice

Those gaps close as the team curates the seed corpus and as new design sessions add their own design decision documents. They do not close on day one.

Curation isn't free. The framing throughout this piece is that the AI does the authoring and the team does the curation. That trade is real and favorable, but curation costs are still substantial on any codebase with meaningful history. Reading the AI's draft, checking each "appears to" claim, fixing wrong ones, capturing the gaps where neither the code nor any human can recover the original reasoning — for a brownfield system with three years of history, this is days of focused team time. The AI makes it tractable. It doesn't make it small.

You will repeat work if you scale up. Running this sequence on one codebase is fine. Running it on five — across a portfolio, an engagement, or a multi-system migration — is when the plugins' pipeline-reuse value becomes load-bearing. Once you find yourself wishing you had a saved copy of pass 4's prompt and a way to feed pass 3's output into it automatically, you've discovered why the plugins exist.

The honest framing: the methodology-only path gives you the starting structure, the active-code coverage going forward, and the capture discipline for new decisions — the same outcomes as the plugin path. It costs you more attention and more orchestration. It rewards you with full understanding of what each pass is doing and why, and full portability across whatever AI tooling you use now or later.

Frequently Asked Questions

The intent reconstruction pass asks the AI to reason backward from code to intent. How do you know the reconstruction is accurate vs. confident-sounding fiction?

The AI is explicitly instructed to mark its uncertainty — "appears to," "likely," "suggests" — and to name multiple interpretations where the code is consistent with more than one intent. Even so, the output is hypothesized intent, not recovered ground truth. The curation pass is where accuracy is established: the team reads the reconstruction and promotes claims that are correct, fixes claims that are wrong, and leaves explicit gaps where neither the code nor anyone on the team can recover the original reasoning. The reconstruction's value is not that it's right — it's that it gives you a specific, concrete artifact to react to rather than staring at the codebase wondering where to start.

How do you prevent the corpus from drifting from the code once it's established?

The same way you prevent any artifact from drifting: treat it as part of the work, not as overhead alongside it. The practice for this is documentation-leads-implementation: when the next feature goes through a design session, the explanation doc is produced before the PR. When implementation reveals something the doc didn't capture, the doc is updated as the first step, not the last. The signal that the corpus is drifting: your AI assistant starts producing PRs that contradict documented decisions. When that happens, the corpus isn't being read. Fix the workflow, not the docs.

What's the minimum viable version? Can I skip the six passes and just start the next feature with a design session?

Yes, if you're willing to trade structural coverage for speed. Passes 1–2 (orientation and scaffolding) take an hour and are easy to skip. Passes 3–5 (inventory, intent reconstruction, seed corpus) are the upfront investment that gives AI sessions real context to work from; skipping them means every session starts without grounding in existing design. Pass 6 (boundary inventory) is valuable if the next feature touches an integration. The minimum that produces meaningful benefit: run a design session before the next feature, capture the decisions, add them to the register. The six passes are how you build the context that makes those sessions substantially better.

How long does this realistically take on a large codebase?

Passes 1–2 take an hour regardless of codebase size. Passes 3–6 scale with complexity — a 50K-line monolith might take a half day of orchestration plus a half day to a day of curation. A multi-service enterprise system might take two to three days of orchestration and a comparable amount of curation, split across multiple AI sessions. The orchestration time is what people usually mean by "an afternoon"; the curation time is the part that gets undersold in most discussions of AI-assisted documentation. Plan for both.

"Documentation precedes code" — but on a brownfield project, the code is already there. What does that principle even mean?

It means the next decision gets documented before it gets implemented. You're not retroactively documenting everything that exists — that's what the seed corpus is for. The principle applies at the feature boundary: when the next feature is about to be designed, the design session and its resulting explanation doc come first. The DDD for any significant choice in that feature is written before the PR that depends on it. The brownfield entry point doesn't require you to reconstruct the past. It requires that you start now, at the next real decision, and let the corpus grow forward from there.