Repogenic1
Intent
What is the desired outcome?
← All case studies
Foundations · The discipline behind every case study
What is Intent-Driven Engineering? State what must be true. Accept what is proven.
State the outcome, the boundaries and the evidence of success before the work begins. Then let the work be performed by the best available executor — human, agent, tool or combination — and accept the result based on evidence.
customer-risk.intent.md
Intent Return a customer's current risk classification and the evidence used to determine it. Inputs and context A valid customer identifier. The existing API and its callers. Outputs Classification + supporting evidence. Success criteria ✓ Unauthorized callers get no data ✓ < 2s under normal load ✓ Every decision auditable ✓ Existing compatibility unbroken
No framework, no class names, no file layout. Everything the executor needs to decide how, and nothing that decides it for them.
4
Questions every useful intent answers: outcome, context, output, success
3
Forces, each with one job: humans declare, agents reason, systems verify
1
Contract for every executor, so the process survives as AI capability grows
0
Credit for activity. Work is done when the evidence says the desired state is reached
The shift
AI changes the economics of instruction.
The more capable the executor becomes, the less useful it is to prescribe every step in advance.
For years, teams have been trained to think in tasks. Write this API. Create this screen. Add this validation. Fix this bug. The unit of work became the ticket, the ticket became the instruction, and the instruction grew ever more detailed because teams were trying to eliminate uncertainty before implementation started.
That worked reasonably well when humans were the primary execution engine. But an intelligent system can often determine many implementation details for itself. So the engineering problem changes.
We used to ask
“How exactly should this be done?”
We increasingly ask
“What must be true when it is done?”
That is the heart of Intent-Driven Engineering.
What intent is
Intent is not a vague goal. It has structure.
“Improve the checkout.” “Make the API faster.” “Use AI to automate this process.” Those are aspirations. Useful intent answers four questions, and those four elements form a practical foundation.
2
Inputs and context
What does the executor need to know?
3
Outputs
What is expected to come back?
4
Success criteria
How will we know it succeeded?
The principle: use the minimum sufficient constraint.
Add constraints, assumptions, acceptance evidence, stop conditions, security requirements or operational boundaries when they matter. But do not describe every implementation choice merely because you can. Every unnecessary instruction removes a possible solution. Every premature technical decision narrows the search space. Every extra paragraph consumes context — and in an AI-driven system, unnecessary context is not free.
Specification vs. intent
A specification describes the solution. Intent describes the result.
Two instructions for the same piece of work. Both have constraints. Only one leaves room for a capable engineer or agent to inspect the system, find existing patterns, choose the right components, build, test and return evidence.
Instruction A
Create a Python FastAPI endpoint named /customer-risk. Use this library, call this function, create these three classes, put the validation in this file, return this JSON structure, and log the result using this exact pattern.
Largely procedural. The solution is already chosen.
Instruction B
Given a valid customer identifier, return the customer’s current risk classification and the evidence used to determine it. Unauthorized callers must receive no customer information. A response must complete within two seconds under normal load. All decisions must be auditable. Existing API compatibility must not be broken.
Intent. The result is fixed; the path is open.
If the agent found a better solution than the one described here, would it be allowed to use it?
If the answer is no, you may not have written intent. You may have written implementation — the overwritten intent, where so much procedure is supplied that an intelligent agent has been converted into a keyboard.
Executor independence
Intent-Driven Engineering does not care who performs the work.
A human developer may implement it. An AI coding agent may implement it. Several specialized agents may collaborate. A deterministic automation may perform part of it. A shared platform capability may already exist. From the perspective of intent, those are execution choices. The contract is the same:
- Here is what we need.
- Here are the boundaries.
- Here is what success means.
- Show me the evidence.
If a process is designed around assigning instructions specifically to humans, it has to be redesigned every time AI capability improves. If it is centered on intent and evidence, the executor can change without changing the engineering model. That is a much more durable architecture for work.
Evidence at the center
AI increases generation speed. Engineering must increase verification strength.
Version control, code review, testing, continuous integration, security, observability, architecture and production monitoring all still matter — more than ever, because agents create changes faster than humans can review them by hand. So the executor never simply says “I finished.” It produces evidence:
- Tests passed and acceptance criteria satisfied.
- Security checks succeeded.
- Performance remained within limits.
- Required interfaces were preserved.
- Observed behavior matches the requested outcome.
When evidence fails, the work is not complete. That changes the psychology of development: we stop rewarding activity, stop treating generated code as progress, and stop confusing a pull request with completion. What matters is whether the desired state has been reached.
Three forces
Humans declare. Agents reason. Systems verify.
None of the three should try to become the other two. Intent-Driven Engineering gives each part of the system its proper responsibility.
HumansDeclare
Define the desired outcome and decide what matters: intent, judgment, boundaries, architecture and acceptance.
When humans prescribe every implementation step, they prevent agents from reasoning.
AgentsReason
Explore possible implementations and perform the work: exploration, implementation, iteration, testing and evidence generation.
When agents define the business objective themselves, we surrender human accountability.
SystemsVerify
Tests, policies, pipelines, security controls and observability determine whether the result satisfies the rules.
When governance exists only as prose, we hope everyone follows it.
Progressive Intent
Do not write the perfect intent. Write the smallest one that can produce evidence.
Reality always knows something the specification does not. An API behaves differently than expected. A dependency has an undocumented constraint. A model hits an edge case nobody anticipated. Traditional planning responds by predicting more before starting. Progressive Intent responds differently.
1
Start with enough
The smallest intent capable of producing useful evidence.
2
Run it
Let the executor work against real systems, not assumptions.
3
Observe reality
See what the system reveals that the plan did not predict.
4
Add only what’s proven
Refine only the constraint that the evidence shows is necessary.
Intent-Driven Engineering is not anti-procedure. It is anti-unnecessary procedure.
Ordering, side effects, regulated steps, recovery procedures and certain security controls must be deterministic, and there procedure is right. Use goals where reasoning adds value. Use deterministic instructions where variation creates risk. That distinction will become one of the defining engineering skills of the AI era.
More than a coding technique
When intent becomes the contract, it becomes an operating model.
The value of every role shifts toward intent, boundaries and evidence — and feature teams get smaller, because they no longer rebuild the execution machinery for every story.
| Business analysts | More valuable when they transform ambiguous needs into clear outcome contracts. |
|---|---|
| Architects | More valuable when they establish boundaries without over-constraining execution. |
| Developers | More valuable when they supervise agents, understand systems, validate evidence and own outcomes beyond individual code changes. |
| QA | More valuable when they focus on evaluation strategy rather than repetitive execution. |
| Shared-services teams | More valuable when they provide reusable skills, policies, MCP connectors, hooks, tests and governance every feature team can use. |
The feature team owns the intent
Shared services provide reusable capabilities. Agents perform much of the execution. Deterministic infrastructure enforces organizational law. Evidence connects all of it.
What we have not built
No giant central orchestrator controlling every team. No massive enterprise specification. No attempt to predict every workflow. Just boundaries and contracts that allow intelligent execution inside controlled space.
Room and walls, at the same time
AI systems need room to reason. Enterprises need boundaries. Intent defines the room, governance defines the walls, evidence tells us whether we reached the destination, and progressive refinement lets the system learn without losing control.
If you remember one definition
Intent-Driven Engineering states the desired outcome, the necessary constraints and the evidence of success in the smallest form that can succeed — then allows humans, agents and tools to determine how best to achieve it.
Better promptingMore AIFewer developers
The goal is a better engineering system: one where intelligence operates without chaos, humans stay responsible without micromanaging execution, and results are accepted because they are proven, not because someone said they were finished.
Next: how it actually runs.
Progressive IDE, the execution model: State. Run. See. Refine. Lock. Every Repogenic case study is this discipline applied to a real system, with the evidence left in the repository.
Adapted from Chapter 7 of The Intent-Driven Enterprise. The free ebook is available here; more on the method at intent-driven-engineering.com and LearnTeachMaster.org.