Intent-First Development for Architects

Anyone can build software now. That is not a complaint. It is the new operating condition, and your job has changed because of it.

Business users with capable AI assistants are expressing their vision in working prototypes. Finance analysts. Operations leads. Product managers who never waited for IT and now have less reason to. They have a problem, they have an idea, and they have an AI assistant willing to implement it overnight. The result is functional, creative, and often genuinely solving something real — and it lands on your desk as an artifact someone is already depending on.

Your job is to make it real. Not the prototype — the intent behind the prototype.

That is the translation problem architects have always faced. The shape of it just changed.

What changed specifically: an architecture that lives only in your head used to be sufficient because the rate at which code reached production was constrained by the engineers who consulted you. An architecture that lives only in your head is no longer sufficient, because the code reaching production is being generated at a rate that does not pause for your availability. Either your architectural decisions are written down where every implementation session can find them, or they disappear the first time someone builds without you.

What you're actually inheriting

The prototypes that surface from business-driven AI development have a recognizable shape. They are functional in the sense that they do the thing the builder wanted. They are also, almost uniformly:

Security unknowns. API keys in source. No credential rotation. Auth is whatever the AI reached for or skipped. Data handling has not been reviewed by anyone whose job is to think about data handling.

Wrong tech stack. The AI assistant used what it knows best or what the user's environment already had. Your org runs Java; the prototype is a Python script running on someone's laptop. Your org has a managed database tier; the prototype connects to a flat file or a personal cloud account the owner will not share credentials for.

Hardcoded everywhere. Configuration that should be externalized is embedded. Constants that will need to change are literals. The prototype works on the builder's machine with the builder's data, and will require surgery before it can be parameterized for anyone else.

Not shareable. It lives in a personal account. It runs on a machine in accounting. Knowledge of how it works lives in one head. When that person is on vacation, the thing stops working.

Below the threshold. Even as a prototype, the code quality would not pass review by any standard your development organization maintains. No tests. No error handling for the edge cases that will definitely occur in production. No logging. No graceful failure. The happy path works and nothing else does.

You are familiar with all of this. You have been cleaning it up, quietly, for years. What is different now is the volume and the speed. The prototypes are better than they used to be — better enough that stakeholders believe they are closer to production than they are — and there are more of them, arriving faster.

The ask that comes with them is always a version of the same thing: make this real.

The actual ask underneath the ask

Here is what the business stakeholder does not say but means: I have a vision. The AI helped me express it. I showed it to someone and they said it should go through IT. You are IT. Make the vision real.

The prototype is not the deliverable. It is evidence of intent.

This is the reframe that makes the architect's job tractable instead of Sisyphean: you are not being asked to clean up Bob's code. You are being asked to understand what Bob actually wants, determine whether it is worth building, and design the system that should deliver it. Bob's prototype is the best evidence you have of what Bob wants — it is imperfect evidence, but it is more concrete than a requirements document and more honest than a slide deck.

The architect's job has always been translation. The source material has changed.

What translation requires

To move from Bob's prototype to a production system your organization can own and operate, three things need to happen:

The intent has to be made explicit. What is the prototype actually trying to accomplish? Not what does it do — what is it for? Who benefits, in what way, and why could they not get that before? This is the question the business stakeholder answered implicitly by building the prototype. It needs to be answered explicitly before any design work begins.

The design decisions have to be made and recorded. The prototype made dozens of design decisions — most of them made by the AI, optimizing for "works on this machine today," none of them documented. The production system will make different decisions, for different reasons. Those decisions need to be recorded: not just what was chosen, but what was rejected and why. The difference between the prototype and the design is most of those decisions reversed.

The architecture constraints have to be carried forward. Security posture, data governance, the tech stack your organization actually operates, the integration points that determine how this system touches everything else — these constraints exist before any line of production code is written. They need to be encoded so that every implementation session — human and AI — applies them without requiring the architect to be present.

None of this is new. What is new is that the volume of incoming prototypes means architects can no longer do this work implicitly, on the fly, in their heads. The methodology needs to be externalized, or it does not survive at the pace the business is now generating intent.

Where IFD fits

Intent-First Development is a methodology for making design intent explicit, structured, and AI-readable before implementation begins. For architects facing the operationalization problem, three parts of the methodology apply directly.

The altitude protocol as ascent before descent

IFD organizes design work into five altitude bands, named by how far above the implementation they sit:

• Vision (50K) — what problem the system exists to solve
• Capabilities (30K) — what the system needs to be able to do
• Architecture (10K) — what the system looks like and how its pieces fit
• Component design (5K) — how each piece is structured internally
• Implementation (1K) — where design hands off to coding

Most architects are familiar with some version of this instinctively — you don't design schemas before you understand what the system is supposed to accomplish. What the altitude protocol adds is formal gate conditions: you do not descend to the next altitude until the current altitude is stable. For more details, refer to the Introduction to Altitude-Gated Design article in the "Learn More" section at the bottom of this article.

Applied to the Bob-from-accounting problem, this means starting by ascending from the prototype before descending to design. The prototype lives somewhere near 1K — it is a working implementation without stable architecture, capabilities, or vision behind it. The first thing to do is not to redesign it but to ask what it was trying to accomplish, and then ask what the system would need to be capable of to accomplish that at organizational scale.

This ascent is where the architect's value is concentrated. Business stakeholders are extremely good at expressing vision. They are not trained to distinguish between "what the prototype does" and "what the system should do" at production scale. The altitude protocol gives the architect a structured way to facilitate that separation — not as a bureaucratic exercise but as the thing that determines whether what you build solves the actual problem.

Design Decision Documents as the operationalization trail

Every gap between the prototype and the production design is a decision. In practice, these decisions happen informally, during implementation, and most of them are never recorded. The next developer who touches the system has to reverse-engineer why it is shaped the way it is. The AI assistant working on the next feature has no access to the reasoning that produced the current shape.

Design Decision Documents (DDDs) record these choices in a format that separates Recommendation, Decision, and Decision Driver — because those are three different things. The analysis may have recommended one approach; organizational constraints, timeline pressure, or a dependency the analysis did not know about may have driven a different choice. Recording the driver is what lets a future reader — or a future AI session — know what would need to change before the decision could be revisited.

For the architect operationalizing a business prototype, DDDs are the artifact that makes the operationalization defensible. When the business stakeholder later asks "why isn't it built the way I built it?", the DDD has the answer. When the engineer implementing the system wants to know whether a particular constraint is load-bearing, the DDD says what it is and why it was chosen.

Skills as the constraint layer that travels with the corpus

The architecture constraints that apply to a system — security requirements, data governance rules, mandated integration patterns, tech stack boundaries — currently live in several places: architecture review board documentation, informal knowledge in senior engineers' heads, post-hoc code review comments. They do not automatically travel with the system into every implementation session.

Skills, in IFD's vocabulary, are short markdown files that an AI assistant reads automatically before generating code — typically a single page capturing one constraint or pattern, with a pointer back to the DDD or architecture document that produced it. A Skill might say "all external API calls in this system go through the gateway service — see DDD-014 for the rationale" and live in a location the AI session reads as conversation context. When an architecture constraint is stable enough that every AI-assisted implementation session in this system should apply it automatically, the constraint becomes a Skill. The Skill points back to the design work that produced it; it does not duplicate the reasoning.

For architects who are not present at every implementation session — which is all architects, on any non-trivial system — Skills are what carry the architecture into the sessions you are not in. The AI assistant reads the Skills as conversation context. Implementation that would violate a constraint surfaces the constraint before it becomes a PR that needs to be rejected in review.

What this looks like in practice

Take a concrete version of the pattern. A business analyst in operations has built a prototype that pulls data from two source systems, applies a set of rules the analyst understands extremely well, and produces a weekly report the team currently generates by hand. It works. The analyst is sharing it informally with three other people. The VP of Operations has heard about it and wants to know why it is not production software.

The architect's conventional path: investigate the prototype, document what it does, write tickets, hand it to a team, watch a six-month project begin with unclear scope, unclear requirements, and a business stakeholder who thought "make it real" meant "make what I built, real." Six months in, the business analyst sees the production version and says, "this isn't what I built." That is the moment the project either gets rescued or rewritten, and the moment that IFD makes structurally less likely — because the corpus captured what the analyst actually wanted, not what they happened to implement.

The IFD path:

Ascend first. Run a short design session. What is the analyst actually trying to accomplish? What does the report enable that was not possible before? What are the downstream decisions that depend on it? Surface the vision and the capabilities at the right altitude — not what the prototype does, but what the system would need to be capable of to deliver the business value reliably.

Record the gaps. The prototype connects directly to production databases as the analyst's personal credentials. The production system cannot do this. That is a decision: what is the correct integration pattern, and what drove the choice? The prototype applies rules encoded in the analyst's head and visible only in the code. The production system needs the rules externalized in a form that can be maintained without the analyst present. Each of these is a DDD.

Encode the constraints. The data governance requirements that apply to this system — what data can be stored, how long, who can access it — are encoded as Skills. The integration pattern decided by the DDD becomes a Skill. Every implementation session that touches this system reads those constraints automatically.

Direct the implementation. The team implementing the production system reads the explanation document (what the system is and why), the architecture document (what the system looks like and how its pieces fit), the DDDs (what choices were made and why), and the How-To Guides (how to implement the specific patterns this system uses). The AI-assisted implementation is directed by the corpus, not by the prototype and not by the architect's ability to be present.

The output is a production system that the business recognizes as their vision — because you started from their intent, not from their implementation — and that your engineering organization can own, because the decisions that shaped it are documented and the constraints are encoded.

The honest limit

IFD does not prevent business users from building things. It does not give you a governance mechanism to intercept prototypes before they become dependencies. It does not solve the organizational dynamics that produce "Bob is already using this, can you make it real by Q3?"

Beyond those organizational limits, there are architectural ones worth naming. IFD does not produce threat models — security analysis remains its own discipline, and a DDD that records "we chose this auth pattern" is not a substitute for actually modeling the threats. It does not handle non-functional requirements that depend on measurement: performance budgets, capacity planning, latency targets. The corpus can capture the target; achieving it is still empirical work. It does not automatically catch architecture-vs-implementation drift — that remains a code review concern, with the corpus providing the reference rather than the enforcement. And it does not solve the political problem of an architect being routed around by a VP who has decided Bob's prototype is good enough; no methodology does.

What IFD does is give you a structured method for making the operationalization work productive rather than chaotic. The business's enthusiasm for building is evidence of genuine need — the prototype exists because someone wanted something badly enough to figure out how to get it. That is valuable. IFD gives architects a way to honor that intent while doing the translation work that turns it into something the organization can actually operate.

The constraint it places on you: the translation work has to be done before implementation begins, not during it. The corpus comes first. The engineers follow the corpus. The architecture review is what produces the corpus — not what reviews the implementation after it exists.

Architects who have run systems where design decisions lived only in their own heads, and then tried to onboard a new engineer or a new AI assistant to that system, understand immediately why this matters. The corpus is not overhead. It is the thing that makes the design survivable beyond the person who holds it.

A note on AI assistants changing the architect's leverage

There is a secondary effect worth naming. The architect who builds a corpus — explanation docs, DDDs, Skills, How-To Guides — for a system they have designed is not just making that system legible to the current team. They are making it legible to every AI-assisted implementation session that will touch it for as long as the corpus stays current.

The architect who carries design intent in their head has linear leverage. They can be in one conversation at a time, review one PR at a time, answer one "why does this work this way?" question at a time.

The architect whose design intent lives in a corpus has multiplicative leverage. Every AI assistant reading the corpus is applying the architecture to the problem at hand — not guessing at it, not inferring it from code structure, not forcing a junior developer to make a decision they are not qualified to make. The corpus is what carries the architect's decisions into rooms the architect isn't in — not a replacement for architectural judgment, but a way for that judgment to be present at the scale AI-assisted development now operates at.

This is the long-term case for IFD in architectural practice: not better documentation for its own sake, but architectural intent that is still present and operative in every implementation session, at every scale, without requiring the architect to be personally present for each one.

Frequently Asked Questions

My organization has tried documentation-first before. Docs went stale within a quarter. Why would this be different?

The failure mode you've seen is documentation that isn't read. Documentation that isn't read isn't maintained. The IFD practice that prevents this: the corpus is directive — it's what the AI assistant reads before generating implementation. When an AI session produces code that contradicts a documented decision, the corpus is wrong, not the code. That feedback loop makes maintenance visible: a stale corpus produces stale implementation, and stale implementation is caught in code review. The corpus stays current because its staleness has immediate, observable consequences. A documentation system that sits in Confluence and gets read by nobody has no such feedback. The architecture of the practice is what's different, not the documentation itself.

The DDD format separates Recommendation from Decision. The same person usually makes both. What's the actual value of that distinction?

When Recommendation and Decision are the same person, they're often still different things. The Recommendation is what the analysis supports. The Decision is what was chosen, which may have been constrained by a factor the analysis didn't capture: a vendor relationship, a team skill gap, a timeline that foreclosed the technically better option. Keeping them distinct means a future reader — or a future AI session — can distinguish "this is the technically preferred option" from "this is what was actually chosen and why." When conditions change, you can revisit the Decision without confusing the original analysis. Collapse them, and you get a record that says "we chose X" with no record of whether X was the best option or just the available one.

Who owns corpus maintenance? This sounds like it becomes one person's full-time job.

Corpus maintenance is distributed, not centralized. The person working on a component updates that component's explanation docs when implementation diverges from them. The architect updates the architecture overview when the architecture changes. Design decision documents are written by whoever makes the decision, at the moment it's made — not catalogued afterward. The corpus doesn't have a curator; it has contributors, each responsible for the artifacts in their domain. The failure mode you're imagining — one person trying to keep all of it current — is what happens when the practice is treated as overhead rather than as design work. When the documentation is the design, maintenance is part of designing.

What's XTIVIA's role in adoption? Can we do this ourselves from the open-source methodology?

Yes, the methodology is open. The full corpus, templates, and artifact formats are publicly available, and teams have adopted them without XTIVIA involvement. Where XTIVIA's engagement model is useful is in reducing the time it takes for the practice to stabilize — running facilitated design sessions, seeding the first corpus, establishing the review workflow, and working through the first edge cases where the methodology gives principles but not specific answers for your context. The rough heuristic: a team that can read the methodology and commit to practicing it independently can probably do it alone. A team that needs the methodology installed and running within a quarter, or that is adopting across multiple teams simultaneously, is where facilitation produces faster results than iteration.

What's the ROI case? How do I justify this to leadership?

The case is in the cost of the alternative. Track one metric: the time between "we need to modify this system" and "the team has enough context to safely modify it." On codebases without intent documentation, that gap runs to days or weeks — research time, tribal-memory interviews, careful reading of code that reveals what was done but not why. On a corpus-documented system, that gap collapses. The next engineer reads the explanation docs and DDDs and has what they need. The next AI session reads the corpus and produces aligned code. The ROI is not in documentation produced; it's in onboarding time reduced, rework from contradicted decisions avoided, and design coherence maintained across the team turnover that will happen regardless.

Working with XTIVIA on architectural adoption

The methodology is open and freely available. Teams adopt it without us, and that path is genuinely viable for architects who can dedicate the time to absorbing the practice and adapting it to their organization's specifics. Where XTIVIA helps is when the adoption needs to happen faster than that — when you have an incoming prototype and a quarter (or less) to operationalize it, or when you want the first corpus seeded against your actual systems rather than against generic examples. We facilitate the first design sessions, write the initial DDDs alongside your architects, and stay engaged through the first PI or release cycle so the practice is running before we step back. If that's useful to you, we're happy to talk.