Intent-First Development for Engineering Managers and Directors

Your AI investment is paying off by every metric your dashboard tracks. Pull requests are up. Cycle time is down. The team is shipping at a rate that would have looked unusual two years ago.

Something is also getting more expensive, and you cannot quite name what it is.

It might be the onboarding time that has not improved the way it should have — new engineers still spending months before they can touch anything without supervision. It might be the rework that appears in sprints without an obvious explanation: a feature that shipped correctly, then had to be partially undone because it violated something somewhere that nobody remembered was there. It might be the senior engineers who spend an increasing fraction of their time answering questions that feel like they should have documented answers. It might be the creeping sense, in retrospectives and design reviews, that the system is accumulating shape the team can describe but not quite defend.

None of this shows up in velocity. It shows up in conversations, in scheduling friction, in the questions nobody can answer quickly, and in the way your most experienced engineers talk about modifying the oldest parts of the system.

What you are observing is the other side of AI-assisted development. This piece is about that other side, and about the methodology that addresses it.

What the velocity gain deferred

When AI tools enter a development workflow, the thing that accelerates is code generation. A senior engineer who previously spent two days on a complex feature now spends a morning. The productivity is real. The metric moves.

What does not change at the same rate is design capture — the work of deciding why the system is shaped this way, which alternatives were ruled out, what constraints apply, and what the code is actually trying to accomplish. That work has a different ceiling. It is bounded by how quickly humans can reason through trade-offs and make intent legible to everyone who will work on the system.

When code generation gets faster but design capture stays at the same pace, something has to give. In most teams, what gives is this: design decisions start happening implicitly, inside AI sessions, without being recorded anywhere. The AI suggests an approach. The engineer accepts it and ships it. The decision was made. Nobody wrote it down. The next person to touch that code — human or AI — has to reverse-engineer why it is shaped the way it is.

At one feature per week, that gap was manageable. At five features per week, it compounds. The system acquires shape that is nobody's fault and nobody's deliberate choice.

This is what the onboarding problem and the rework problem have in common. They are both symptoms of design decisions that were made implicitly and never captured.

What your AI tools do not know

Here is the fact about AI assistants that matters most for engineering managers to understand: every session starts from scratch. The AI generating code this afternoon does not know what approach was recommended last Tuesday. It does not know which architectural decision was made in January. It does not know that a particular approach was ruled out because of a compliance requirement discovered in November.

If that reasoning was documented — if it existed in a structured form the AI could read at the start of the session — it would apply it. It would flag when an approach contradicts a recorded constraint and produce code that fits the system as designed.

If the reasoning was never written down, the AI does not have it. It generates the most plausible answer it can from the code it can see. That answer might align with your architecture. It might not. Without the documented reasoning, neither the AI nor the engineer reviewing the PR can reliably tell the difference.

This is not a criticism of AI tools. It is a description of how they work and what they need to work well. What you give them determines the quality of what they produce.

Where the cost shows up

The costs that flow from undirected AI sessions are real and measurable. They are deferred, which is why they do not appear as sprint line items. But they are paid.

Onboarding friction. A new engineer joining the team needs to understand why the system is the shape it is. If that understanding exists in documented design decisions, they can read their way to it. If it lives in the heads of senior engineers, they need to schedule interviews, interpret code archaeology, and make guesses that will occasionally be wrong. Teams that have doubled their code output with AI tools have often not reduced their onboarding timelines at all. The gap is here.

Rework from undocumented constraints. A feature ships. Two sprints later, it needs to be partially undone because it violated a constraint the implementing engineer did not know about. The constraint was real — it just was not written down anywhere the engineer, or the AI that generated their initial implementation, could have found it. This work rarely shows up as rework in tracking systems. It is categorized as new work, which makes the team look busy while the underlying cause goes unaddressed.

Knowledge attrition. When a senior engineer leaves, the explicit knowledge goes to their LinkedIn profile. The implicit knowledge — the decisions they made, the constraints they applied informally, the "why" of the systems they shaped — leaves with them. How long before the team can confidently modify those systems? On teams with documented intent: weeks. On teams without it: the uncertainty compounds with every team change.

AI session drift. The longer a team uses AI tools without a documented intent corpus, the further each new session drifts from actual design intent. Early in a project, the system is small and the drift is minor. A year in, the system has accumulated decisions from hundreds of sessions, none of them visible to any future session. The AI generating code today is increasingly out of alignment with the decisions that shaped the system last quarter. This surfaces as code that technically works but architecturally does not fit — and it accumulates faster than review processes can catch.

What Intent-First Development changes

Intent-First Development is a methodology built around a single inversion: design intent is captured before implementation begins, and that captured intent directs every AI session that follows.

The artifacts it produces — explanation documents, Design Decision Documents, structured convention files called Skills — are not documentation written after the fact. They are the directive that AI sessions read before generating anything. When this corpus exists and sessions read from it, the sessions produce aligned code. When the corpus is absent, they guess.

For managers, the practical changes look like this:

Design decisions leave a permanent record. When a meaningful choice is made — between approaches, patterns, or technical trade-offs — it is recorded in a Design Decision Document that names what was considered, what was recommended, and what was actually chosen and why. The next engineer or AI session that encounters the relevant code can read that record and understand not just what was built but why.

Architecture constraints travel with the system. Security requirements, data governance rules, integration patterns, compliance constraints — currently these live in various places and require a senior engineer's presence to apply consistently. In an IFD corpus, they are encoded as Skills: short, AI-readable directives that every implementation session reads as context. The constraint is applied whether or not the architect is in the room.

Onboarding becomes reading, not interviewing. A new engineer joining an IFD-documented system reads the explanation documents, the architectural overview, and the key decision records before writing a single line of code. They understand the system's intent before they modify it. The senior engineers they would otherwise need to schedule time with are, in large part, documented.

The corpus survives turnover. When a senior engineer leaves an IFD-documented system, their design decisions stay. The constraints they applied consistently become Skills others can use. The intent they carried in their head is in a corpus the next AI session — and the next engineer — can read on day one.

The question about overhead

Every manager who hears this asks the same question: if the team is already moving fast, won't this slow them down?

The work that IFD makes explicit is already happening. It is just happening implicitly — in hallway conversations, in chat threads, in the forty-five-minute call the senior engineer takes when someone asks why a particular decision was made. That time is real. It is already being paid. IFD moves it forward in the project timeline, where it directs implementation, rather than backward, where it explains implementation after the fact.

The overhead question is better asked differently: what is the cost of not capturing intent? Onboarding time, rework from undocumented constraints, and the productivity cliff that follows experienced engineers leaving are all real costs. They are paid incrementally, in untracked hours and quiet frustration. When they are summed, they exceed the cost of the design work that would have prevented them.

The teams that adopt IFD report a brief period of increased deliberate design work and a sustained reduction in implicit rework. The crossover point — where the time saved exceeds the time invested — typically arrives within a few months of consistent adoption.

The honest limit

IFD does not make design decisions for your team. It provides structure for capturing the decisions your team makes and making them durable. A team making poor architectural choices will produce a well-documented corpus of poor decisions. The methodology surfaces reasoning; it does not fix it.

IFD also does not solve team dynamics, prioritization pressure, or the organizational incentives that lead to technical shortcuts. It can make shortcuts visible — a Design Decision Document that says "we chose the expedient option under timeline pressure" is at least honest about what happened — but it cannot prevent the shortcut from being taken.

What it does, in the specific context where it matters most, is make design intent survivable. Intent that lives only in chat windows and individual heads does not survive the team changes, AI session resets, and accelerating pace that characterize the current development environment. Intent in a structured, AI-readable corpus survives all three.

A note on XTIVIA

XTIVIA helps engineering organizations adopt IFD without rebuilding how they work. For most teams, that means running facilitated design sessions to establish the corpus for a critical system, putting in place the review workflow that keeps the corpus current, and enabling the team to run the practice independently from that point forward. The methodology is open — the full documentation and templates are publicly available for teams that want to adopt it without assistance. What XTIVIA provides is compression: the practice established in weeks rather than quarters, with support for the edge cases where the methodology gives principles but not specific answers for your context. If your organization is experiencing what this piece describes, the conversation starts at the Get Started page.

Frequently Asked Questions

We have tried documentation initiatives before. They always go stale. Why would this be different?

Documentation that is not read is not maintained. IFD documentation stays current because it is read — not by humans browsing a wiki, but by AI sessions before they generate code. When a corpus document is wrong, the AI generates misaligned code. That misalignment surfaces in code review and traces back to the document. The feedback loop is tight: the corpus stays current because its staleness has immediate, observable consequences. A Confluence page that nobody reads can be wrong for two years. A Skills file that directs every implementation session cannot.

My team uses AI tools, but I do not control which ones. Does IFD require specific tooling?

No. IFD is AI-tool agnostic. The corpus — explanation documents, Design Decision Documents, and Skills — consists of structured text that any AI assistant can read as context. Claude Code loads these files into the conversation automatically. Other tools require the context to be injected manually or through a retrieval layer. The practice is the same either way: the corpus is written before sessions begin, and sessions read from it. The specific AI tool your team uses does not change what the corpus contains or how it is organized.

How do I know if this is working? What should I track?

Two metrics are most revealing. The first is time to first independent contribution for new engineers — how long before someone joining the team can modify a system without requiring close senior-engineer supervision on every decision. The second is the proportion of rework that traces to undocumented constraints — work that had to be revised because an existing decision or constraint the implementing engineer did not know about made the initial implementation wrong. Both require a baseline to compare against, but both are trackable with data most engineering organizations already collect. Teams with a functioning corpus typically see onboarding time fall meaningfully and rework from undocumented constraints approach zero.

My architects say they already document architecture decisions. How is this different from what they are doing?

IFD documentation is directive, not descriptive. The difference is in who reads it and when. Architecture documentation that lives in a wiki is written for human review and read occasionally, in retrospect. IFD documentation — specifically the Skills layer — is consumed by AI sessions at the start of every implementation conversation. It is written so that an AI assistant reading it will apply the architecture, not so that a human auditor can verify it was followed. If your architects' current documentation changes what AI sessions produce, it is already doing the IFD job. If AI sessions occasionally generate code that contradicts it, the documentation exists but is not directive.

What is the realistic investment? How much does this add to the team's workload?

Establishing a corpus for an existing system is a concentrated upfront investment — typically a set of facilitated design sessions that produce the vision, architectural overview, and the key decision records for the most critical parts of the system. Teams that do this without outside support typically dedicate a week or two of senior-engineer time. Ongoing maintenance is distributed: the person making a significant decision writes the record for it; the engineer implementing a component updates the component's explanation when the implementation diverges from it. XTIVIA's facilitated adoption compresses the initial investment. Neither path is free, and both are cheaper than the alternative once a team has experienced a serious knowledge-attrition event and measured what it actually cost.