The Concept

Why Intent Engineering exists, what it rejects, and what changes when intent becomes the scarce resource.

The bottleneck has moved

Software engineering spent decades optimizing for one constraint: human-written code was expensive. Patterns, code review, CI/CD, microservices, agile: all management systems for scarce code.

That constraint collapsed. AI agents can now generate, review, test, and deploy code at machine speed.

The new bottleneck is intent. When code is cheap, the scarce resource is deciding what to build, why it matters, and what must stay out. Without that, AI produces polished waste.

What Intent Engineering is not

It is not prompt engineering: prompt engineering tunes one conversation, while Intent Engineering defines the persistent document every conversation inherits.

It is not a design doc: design docs prescribe How, while Intent Documents refuse to, because stack, architecture, and timelines are implementation choices.

It is not a PRD: PRDs try to be comprehensive and static, while Intent Documents stay minimal, evolve through exploration, and can be dropped.

It is not a framework or tool: it is a markdown file and a discipline.

The three layers

An Intent Document has exactly three layers because humans only own three things here: Why, What, and Not. Everything else is implementation choice.

Why — the reason this exists

Why is the claim about value: whose pain matters, what outcome counts as success, and what evidence would change your mind. In seed and exploring, it is a wager; in clarified, it is a commitment.

What — the thing being built

What is the surface area of the promise: features, user flows, and edge cases. It must be concrete enough for AI to derive work from, but silent on How; "users can export reports as PDF" belongs here, "use puppeteer" does not.

Not — the boundaries that must not be crossed

Not is where seriousness shows: security constraints, scope limits, quality bars, forbidden patterns. Without Not, AI will optimize against assumptions you never wrote down.

Evolution — rewrite, don't append

Clarity usually comes late. An idea starts as seed: vague, fragile, and wrong in interesting ways. The way forward is exploration.

Intent evolves by rewriting Why, What, and Not, not by appending a log of what you learned. An interview that kills a feature deletes a line from What. A prototype that exposes a risk adds a line to Not. A result that shifts who suffers rewrites Why. If a learning changes none of the three, it does not belong in INTENT.md yet.

For AI: INTENT.md always states the current intent, with no stale hypotheses mixed in. An agent reading it never has to work out which lines still hold.

For humans: the path is not lost; it lives in version control. Each change to INTENT.md is a commit whose message says what was learned and why the intent moved. git log -p INTENT.md is the history of the intent; the file is its present.

The lifecycle

Intent moves through four states:

State	Description	What to do
seed	Idea only. Why is a guess; What and Not are empty or vague.	Write the hypothesis. Run the first test.
exploring	Hypothesis under pressure through prototypes, research, and interviews.	Run experiments. Rewrite Why/What/Not with each result. Say why in the commit.
clarified	Why, What, and Not are explicit. Uncertainty markers are gone.	Hand off to AI. Let it build.
dropped	Evidence says do not build, or an existing solution already wins.	Set status to dropped. Say why in the commit. This is a good outcome.

The hardest transition is any state → dropped. Starting projects is cheap; stopping bad ones is judgment.

Relationship to existing concepts

Concept	Scope	Relationship to Intent Engineering
Context Engineering	Per-task, ephemeral	The Intent Document is the persistent context above all tasks.
Harness Engineering	Tool and environment setup	The Not layer should compile into harness rules: CLAUDE.md, linters, CI.
Spec-driven Development	Feature specification	Specs are derived from What. Humans stop hand-authoring them.
Vibe Coding	Code generation	Vibe coding gets leverage only when intent is sharp.

The automation pipeline

In a mature pipeline, humans touch two points: intent at the top, judgment at the bottom.

  [Intent Document]     ← Human writes and maintains
         ↓
  [Spec Generation]     ← AI derives task list from Why/What/Not
         ↓
  [Implementation]      ← AI agents write code in parallel
         ↓
  [Verification]        ← AI cross-reviews, tests, lints
         ↓
  [Deployment]          ← CI/CD automates release
         ↓
  [Feedback]            ← User data flows back
         ↓
  [Learn & Decide]      ← Human evaluates, updates intent or drops

Everything between intent and feedback is automatable now. Tech stack, architecture, task breakdown, verification flow, deployment cadence: choices. The irreducible human job is Why, What, and Not, and rewriting them as feedback arrives.

The .gitignore thought experiment

Ask repeatedly: what is NOT in .gitignore? — what survives in the repo that cannot be regenerated?

Code is output, like node_modules — AI can regenerate it. Tests are derivable from What. Config and infra are choices AI can make. Docs are derivable from intent. Strip away everything regenerable and one file remains: INTENT.md.

This is not a metaphor. It is the logical endpoint: the only artifact that requires human insight is the intent itself. Everything else is abstraction waiting to happen.

Intent is convergence, not declaration

Good intent is not written once. It is converged on through hypothesis → build → validate loops. Each loop ends by rewriting Why, What, or Not. Convergence is visible when the rewrites get smaller and then stop. Failed experiments become assets through the commits that record them, so the same dead ends are never revisited.

Intent Engineering is not a document format. It is a discipline of finding the destination quickly, safely, and efficiently through iterative learning. The journey of convergence is the engineering.

Why it works

Constraints breed clarity. Why/What/Not removes the places people hide: roadmap theater, architecture cosplay, false precision. If you cannot state intent cleanly, you are not ready to build.

AI is better at How than you are. It has broader implementation recall than any individual engineer. Over-specifying How caps the solution at your local maximum.

Dropping is productive. A documented drop is not waste; it is paid-down uncertainty. The commit history of a dead intent often outlasts the code from a shipped one.

Intent precision scales. One sharp sentence in Why propagates through task generation, review, tests, and deployment. Vague intent multiplies ambiguity; sharp intent multiplies coherence.

Getting started

Create INTENT.md at the project root and write only Why, What, and Not. Mark uncertainty with (?) until evidence removes it.

The mechanics are in the Quick Start Guide; the discipline is refusing to smuggle How into the document.

→ Quick Start Guide