Why Intent Engineering Is Replacing Prompt Engineering

An AI coding agent spent three hours "improving checkout speed." It refactored the payment module, added Redis caching, restructured the database queries, and broke two downstream integrations. The prompt was clear. The intent wasn't.

This essay makes the case for the shift from better prompts to better product intent. If you need the concise meaning of the term, start with the intent engineering definition. If you are ready to apply it, use the intent engineering framework and INTENT.md template.

Intent Engineering is the practice of translating user problems into structured specifications that let AI agents act without inventing the product decision. It sits between research and code — the discipline of defining what gets built and why, precisely enough that a human can review it and an agent can make implementation choices from it.

It is not prompt engineering with more words. It is not a new name for requirements gathering. It is a fundamentally different activity: structuring the problem, not the instruction.

Why a New Discipline?

Something shifted in software development in 2025. AI coding agents — Claude Code, Cursor, Windsurf, GitHub Copilot — crossed a threshold. They went from autocompleting lines to implementing entire features autonomously. An engineer can describe what they need, point the agent at a codebase, and return to a working pull request with green tests.

This is extraordinary. It also exposed a problem that was always there but never mattered this much: most teams are terrible at specifying what they want.

When a human developer receives a vague ticket, they compensate. They walk to the PM's desk, check Slack history, look at the design file, make reasonable assumptions. An AI agent sees only the context available in its loop. If the decision and its boundaries are absent, it must stop to ask or guess, and a fluent guess can look finished long before anyone notices it solved the wrong problem.

The bottleneck in software development has moved. It's no longer writing code. It's deciding what code to write — and specifying it clearly enough that an autonomous system can proceed without relying on a hallway conversation.

That specification discipline is intent engineering.

The cost of skipping it is the vibe coding hangover at scale: AI agents generating code at unprecedented speed with no shared understanding of what that code should do. Features ship in hours but solve the wrong problem. Codebases grow fast but can't explain themselves. Every new developer — human or AI — starts from zero because the intent was never recorded. It's technical debt at warp speed.

The industry is converging on this. Developer tools are being rebuilt around structured intent — agent orchestration platforms that execute against specs, coding assistants that consume structured context instead of freeform prompts. The word "intent" keeps showing up because everyone has hit the same wall: an agent cannot recover product judgment it was never given.

Intent vs. Requirements vs. User Stories

The distinction becomes concrete when you see the same problem expressed in three different formats.

A requirement tells the agent what to build:

"Build a REST endpoint that validates claim submissions against a JSON schema."

The solution is already decided. The agent becomes a typist. If the chosen design is suboptimal, the agent faithfully implements the suboptimal version. It can't push back because it doesn't know why this endpoint exists.

A user story tells the agent who wants something:

"As a claims adjuster, I want to see missing fields so I can request them from the customer."

Better — there's a user and a goal. But user stories are deliberately thin. They assume a conversation will fill in the gaps. An agent can ask a follow-up question, but only if it can see that a domain rule is missing and reach someone who knows the answer. Hidden context still becomes a guess or a stalled run.

An intent spec tells the agent why it matters and gives it enough context to figure out the rest:

Incomplete claims cause a 2.4-day delay per follow-up cycle, 1.3 rounds of back-and-forth, and 18 minutes of adjuster time per round. A complete claim in auto insurance requires police report number and vehicle registration; in property insurance it requires damage photos and building year. Incoming claims must be checked for completeness before coverage review can begin.

The agent now understands the business pain, the scale of the problem, the domain rules, and the success condition. It has enough context to make intelligent implementation decisions — choosing the right data model, designing the validation logic, even suggesting optimizations the human hadn't considered.

The difference shows up in agent behavior. Hand the requirement to an AI agent, and it has little basis for questioning the endpoint already chosen. Hand it the user story, and it still has to discover or guess the domain rules. Hand it the intent, and it can plan around per-insurance-line completeness, surface the unresolved questions, and check its implementation against the actual workflow because the decision and its boundaries are explicit.

The core insight: AI agents don't need more precise instructions. They need more context and more freedom. Requirements over-constrain the solution. User stories under-specify the problem. Intent hits the sweet spot — precise about the what and why, deliberately open about the how.

The Four Schools of Intent Engineering

The term "intent engineering" is emerging simultaneously from different directions. Understanding the different perspectives helps clarify what it actually is — and isn't.

Intent Engineering as a Role

Some organizations are creating dedicated roles around intent. The idea: if code generation is automated, someone needs to own the upstream work of extracting intent from stakeholders, enriching it with domain context, and validating that outcomes match the original business need.

This isn't a rebranded Requirements Engineer or a Product Owner with a new title. The difference shows up the moment you hand traditional artifacts to an AI agent. Requirements over-specify the solution. User stories under-specify the problem. The intent role sits precisely at the interface between business need and technical execution — the exact spot where AI agents need the most help.

Discovery methods in this model include structured interviews, process shadowing, domain mapping, and data-driven analysis of error rates, throughput times, and support patterns. The output is a structured intent document that feeds directly into agentic workflows.

Intent Engineering as a Practice

Others frame intent engineering as a personal discipline — how individual developers and builders can be more intentional when working with AI tools.

The practice: alternate between rapid AI-powered iteration and structured reflection. Instead of diving into vibe coding without guardrails, you clarify your intent first, burst with AI to explore solutions, pause to evaluate, and iterate. It's vibe coding with a feedback loop.

This is valuable but incomplete. A personal practice helps a solo developer ship better code. It doesn't solve the team problem: how does the second developer understand why something was built? How does the PM trace a feature back to the user friction that justified it? How does the next sprint inherit the context from the last one?

Intent Engineering as Agent Configuration

A third angle is emerging from the AI product management community: intent engineering as a way to configure autonomous AI agents — customer support bots, workflow agents, research assistants. In this framing, intent defines the agent's ongoing behavior: objectives, outcomes, health metrics, constraints, escalation rules, and stop conditions.

This is adjacent but distinct from specifying what to build. Configuring a support agent's behavior ("resolve Tier-1 issues without frustration, keep CSAT above 4.2") is a runtime problem. Specifying a feature ("38% of claims arrive incomplete, causing 2.4-day delays — build completeness validation") is a build-time problem. Both need structured intent. Both suffer when intent is vague. But the artifacts and workflows are different.

Intent Engineering as a System

The fourth perspective — and the one we believe matters most — is intent engineering as a system: a structured layer in the product development workflow that connects user evidence to shipped software.

In this model, intent engineering isn't something one person does. It's something the team practices, around an artifact with an address. Friction signals flow in from support tickets, analytics, research. They get structured into a versioned spec with explicit objectives, outcomes, constraints, and verification criteria, and that spec lives in the repository as intent.md, where the agent already reads. The implementation is checked against it. What the build reveals gets written back as findings. Shipped outcome measurements stay measurements until a person decides what, if anything, they justify next.

This is what we call the Intent Layer: the missing middle between user signal and agentic execution, made of a file in the repo rather than another destination to keep in sync.

The Anatomy of an Intent Spec

An intent spec is a structured artifact: something a human can review and an agent can use to plan and check work. The open format requires identity, status, an objective, and at least one outcome. A build-ready working spec usually covers eight dimensions:

1. Objective — What user problem are you solving and why does it matter? Not "we think users want X" but "we observed users struggling with Y." Grounded in evidence: a support ticket, a metric, a user quote.

2. Outcomes — Observable, measurable state changes. Not "improve performance" but "p95 response time under 200ms." Each outcome should have a corresponding automated check, manual check, or observable shipped signal.

3. Evidence — Linked real user signals: friction points, quotes, observations, metrics. Evidence informs the decision; it does not make it. When the evidence is thin, label the claim as a hypothesis instead of laundering an assumption into fact.

4. Constraints — Hard limits the implementation must respect. Existing APIs it can't break, performance budgets, regulatory requirements, technology boundaries.

5. Scope — What the implementation may touch, and what it must leave alone. The "out of scope" fence stops an agent from refactoring code you never asked it to change.

6. Edge Cases — Boundary conditions and failure modes. What happens when the network is down? What about empty states? What if the user has 10,000 items instead of 10?

7. Health Metrics — What must NOT degrade once this ships. Outcomes say what should change; health metrics name what should stay true, so the agent doesn't quietly break one thing while improving another.

8. Verification — How do you check the implementation and observe the result? Name the fastest automated check, a manual fallback, and the shipped signal. A green implementation check establishes fidelity to the spec; the later production measurement answers whether the intended outcome actually happened.

Here's a real example:

---
id: onboarding-address-entry
status: approved
scope:
  inScope:
    - Step 3 address entry and its fallback path
  outOfScope:
    - Steps 1–2, payment, and saved addresses
evidence:
  - id: support-4821
    type: friction
    source: "Support ticket #4821 and linked duplicates"
    excerpt: "Customers abandon the six-field address form and ask for a faster path."
    anchors:
      - objective
  - id: onboarding-funnel
    type: metric
    source: "Onboarding funnel dashboard"
    excerpt: "35% of users abandon at step 3, costing about 200 signups each week."
    anchors:
      - objective
      - outcome:0
---
# Reduce address-entry abandonment

## Objective
New customers abandon onboarding at step 3 because address entry requires six
manual fields. The current drop-off costs about 200 completed signups each week.

## Outcomes
- Step-3 abandonment falls by at least 40%
- Customers who select a suggested address proceed in under 10 seconds
- Customers can complete the address step when suggestions are unavailable

## Constraints
- Existing downstream address validation must continue to pass
- Geocoding spend must remain below $200 per month at current volume
- Address suggestions must not be stored before the customer confirms one

## Edge Cases
- **Geocoding API unavailable**: Show the existing manual address form
- **Address outside supported regions**: Offer manual entry and explain the limitation
- **PO Box address**: Allow manual entry without forcing a suggested street address

## Health Metrics
- Completion rates for steps 1 and 2 do not decrease
- Downstream address-validation accuracy does not decrease

## Verification
- Automated check: suggestion, confirmation, and fallback integration tests pass
- Manual check: five supported, unsupported, and PO Box addresses follow the expected path
- Shipped signal: step-3 abandonment is at least 40% lower after two full weeks

Notice what this spec does not contain: implementation instructions. It doesn't say which geocoding API to use, which framework to build with, or how to structure the code. It defines the problem, the success criteria, and the constraints. The agent — or the developer — figures out the rest.

Here's a blank template you can copy and start using today:

---
id: replace-with-stable-id
status: draft
scope:
  inScope:
    - What the implementation may touch
  outOfScope:
    - What it must leave alone
evidence:
  - type: friction
    source: Ticket, dashboard, interview, or other retrievable source
    excerpt: A repo-safe summary or reference, not sensitive raw material
    anchors:
      - objective
---
# Name the intended change

## Objective
Who is affected, what goes wrong for them today, and why it matters.

## Outcomes
- An observable state change after success
- A second state change a person outside the codebase could see or measure

## Constraints
- A hard boundary the implementation must not violate

## Edge Cases
- **Failure or boundary condition**: The expected behavior

## Health Metrics
- A signal that must not degrade

## Verification
- Automated check: the fastest executable feedback with an expected result
- Manual check: the fallback when automation cannot establish it
- Shipped signal: the production observation that would confirm the outcome

For a deeper walkthrough, see Your First Intent Spec in 10 Minutes.

How to Practice Intent Engineering

Intent engineering is not a one-time documentation exercise. It's a workflow:

1. Start from friction, not features. The input isn't "what should we build?" It's "where does the user's experience break?" Support tickets, drop-off metrics, research transcripts, NPS comments — these are raw material. Features are conclusions. When evidence is absent, treat the conclusion as an explicit bet rather than a fact the data supposedly chose.

2. Structure the problem before the solution. Establish the objective, outcomes, and edge cases before implementation starts. A person can write them, or an agent can draft them for a person to judge. If you can't articulate what success looks like, you're not ready to authorize the build.

3. Make decision context explicit. Put in the spec what an agent — or a new team member — needs to understand the decision: why this problem, why now, what was tried before, and what cannot change. Keep sensitive raw evidence outside the repository and carry a repo-safe reference instead.

4. Build from authorized intent. The coding agent reads intent.md in the repository, orients itself in the codebase, and plans from the stated outcomes and boundaries. A good spec narrows the important ambiguity and makes the remaining questions visible; it does not promise a correct implementation in one pass.

5. Check the implementation, then measure the outcome. Before shipping, compare the diff and tests with the outcomes and constraints to establish implementation fidelity. After shipping, observe the production signal: did drop-off decrease, or response time improve? Those are different claims and should not share one green checkmark.

6. Carry learning forward deliberately. Implementation contradictions return as findings. Outcome observations remain measurements. Either may inform the next decision, but neither silently becomes evidence without human judgment. Intent engineering is a cycle, not a phase.

What Intent Engineering Is Not

It's not prompt engineering. Prompt engineering optimizes a single AI interaction — the art of crafting the right words to get a better response. Intent engineering structures the entire problem upstream of any prompt. A prompt says "write me a login form." An intent spec says "40% of users who forget their password abandon signup — add a reset flow that recovers 60% of them, verified by automated test."

It's not requirements gathering. Requirements describe solutions. Intent describes problems. A requirement says "build a REST endpoint." An intent says "claims arrive incomplete 38% of the time, causing 2.4-day delays." The solution space stays open.

It's not just for AI. Intent specs make human developers faster too. A clear spec with explicit edge cases and verification criteria is useful whether the person reading it is a junior engineer or a language model. The discipline of structured intent improves every workflow it touches.

It's not replacing product thinking. Intent engineering doesn't remove humans from the loop — it externalizes their judgment into a format that survives handoffs. The PM still decides what matters. The designer still champions the user. Intent engineering makes that thinking inspectable, so an agent's misunderstanding can be found against the record instead of debated from memory after the feature ships.

It's not bureaucracy. Writing an intent spec takes less time than the third round of PR review on code that missed the point. The overhead of precision is lower than the overhead of rework.

Who Needs Intent Engineering?

Intent engineering is most valuable for teams that work with AI coding agents — but it benefits anyone who specifies what software should do:

• Product managers who hand specs to AI agents or engineering teams. The spec becomes the product — not the code.
• Engineering leads who want consistent, reviewable specifications across their team. Intent specs are auditable in a way that verbal handoffs and Slack threads are not.
• Founders and solo builders who use AI to move fast. Intent prevents the vibe coding hangover — the moment your codebase outgrows the context in your head.
• Design teams who need to translate user research into development specs. Intent engineering connects research directly to what gets built.

If you're handing work to an AI agent and the output is unpredictable, inspect the specification first. A good spec will not fix a broken codebase or toolchain, but it will reveal whether the agent was ever given a stable product decision to build from.

Where the Spec Lives

A spec that lives in a tool nobody opens is documentation. A spec that lives where the agent works is infrastructure.

In practice that means the repository. The example above is intent.md: plain markdown, committed next to the code it governs, read by the agent at the start of a session and checked against the diff at the end. It merges, it branches, and it is still there when the vendor is not. The format is open.

Two things do not belong in that file, and they are the reason a hosted layer exists at all. The evidence under the claims: interviews, named quotes, support conversations, the metrics you would not commit to a tree that contractors and forks can read. And the people who know whether a claim is true, who often never open a repository. The file carries references; the evidence and the review live outside it. The repo gets the decision. Pathmode keeps the evidence and judgment behind it.

One more thing has changed since this post was first written: the author. In our own workspaces, agents already write specs through the API, and the human turn has moved from writing to judging. An agent-authored spec is a proposal until a person authorizes it. Practicing intent engineering increasingly means being good at that judging turn: challenging the draft, confirming what is actually known, and refusing what is not.

Getting Started

You don't need a platform, a methodology overhaul, or a new role. You need one spec.

Pick a real piece of user friction — a support ticket, a drop-off metric, a user complaint. Draft, or ask your agent to draft, a build-ready intent spec covering objective, outcomes, evidence, constraints, scope, edge cases, health metrics, and verification. Judge and authorize the proposal, keep it as intent.md, and compare the resulting build with what you usually get from a Jira ticket or a prompt.

The difference is the argument.

The fastest way to run that comparison is the free preflight: install the Claude Code plugin and run /preflight in the repository you are about to change. Six deterministic gates name what the spec is missing. No account, no API key, nothing leaves your machine.

For the concise meaning of the term, see the intent engineering definition. To apply it, use the intent engineering framework and INTENT.md template.

Run a preflight on your first spec →