# Engineering Intent Documents

A short artifact capturing the build direction between a raw idea and a formal specification — problem, users, goals, constraints.

**Rests on:** Product Requirements Documents

*Software Engineering · Spec-Driven Development*


## Why learn this

Why learn this? Because starting any project with a vague goal is like trying to cook a meal without reading the recipe first. You might end up with something edible, but likely not what you wanted. An engineering intent document is a short, clear plan that locks in exactly what you are building before you spend hours (or dollars) creating it. It stops the common problem where the finished product looks nothing like the original idea—a issue known as spec drift, which happens when the work gradually moves away from the initial plan. Without this document, you rely on guesswork. With it, you have a single source of truth that ensures the code matches the goal.


## The intuition

Think of the last time someone asked you for help with a task vaguely, such as 'clean up my office'. You would immediately ask follow-up questions: 'Which room?', 'Does this include trash or just filing?', and 'How much time do I have?'. A raw idea is like that initial vague request: messy, full of assumptions, and open to interpretation. An engineering intent document captures the answers to those clarifying questions in writing before any real work begins. It is not the final detailed plan; it is the agreement on direction. It typically addresses four things: What problem are we solving? Who does this affect? What does success look like? What limits do we have? 

Consider a business that wants to improve customer service. Instead of just saying 'make support better', they write an engineering intent statement: 'We aim to reduce the time customers spend on hold by 30% within six months by building a chatbot that handles common password resets. The budget is $5,000, and it must work on both mobile and desktop.' This specific example forces clarity. It turns a fuzzy wish into a concrete target with numbers, users, and boundaries defined.


## An analogy

Imagine you are hiring a contractor to renovate your kitchen. You tell them, 'I want it to feel more open.' If they start tearing down walls immediately, they might remove a crucial support column or choose cabinets that don't fit your storage needs. Before any hammer swings, you sit down with them and write out an intent statement: 'We want to combine the kitchen and living room into one large space for entertaining. The budget is $15,000. We must keep the existing plumbing for the sink.' These notes guide the contractor’s detailed blueprints later on. They are not the blueprint itself—you wouldn't build from these notes alone—but they ensure the final result aligns with your vision. The analogy holds until construction starts: the intent document sets the stage, but does not replace the technical instructions.


## Definition

An engineering intent document is a brief written plan that defines the core problem, target users, goals, and constraints of a project before detailed technical work begins, ensuring the final output matches the original objective.


## How it connects

This practice sits within Spec-Driven Development, which is simply the approach of using written plans to guide coding rather than guessing. It links directly to Product Requirements Documents, which are more detailed and formal versions of your intent that list specific features next. It also connects to Acceptance Criteria, which are the specific conditions you check to see if the job is done, derived from the goals set in your intent document.


## The mathematics

Mathematics underlies the structure of a good engineering intent document, even though we will not compute anything numerical. The branch at play is set theory, though we will not use symbols. A set is a collection of distinct things. Think of a set of goals, a set of users, a set of constraints. The document is about defining these sets clearly and unambiguously. The essential operation is that of intersection: the product you build is the intersection of what the users need, what your goals demand, and what your constraints permit. Without a written document, these sets are hazy; with one, you can check if a requirement belongs to the intersection or falls outside. The document is a way to carve out that intersection on paper before code exists.

Let U be the set of users, G be the set of goals, C be the set of constraints. The buildable product scope S is the intersection: S = U ∩ G ∩ C. Each element in S is a requirement that we can proceed to specifying.


## A worked example

```
Imagine you are defining the users and goals for a personal finance app. Your raw idea is 'a budgeting app'. You decide to write the engineering intent. You list the primary user segment: young professionals in India, aged 25-35. You list goals: reduce monthly overspending by 20% for users who track expenses; increase savings rate by 5% on average. Constraints: must work offline on low-end Android phones; must comply with local data privacy laws. Let's check the intersection: a feature idea, 'auto-categorize expenses using AI', would require internet for initial training, but the constraint says offline. That feature falls outside the intersection. You note it as a future possibility.

Step 1: Users = {young professionals, India, 25-35}   # This set defines who the product serves.
Step 2: Goals = {reduce overspending by 20%, increase savings by 5%}   # These are the measurable outcomes.
Step 3: Constraints = {offline, low-end Android, data privacy}   # These are the limits within which we must work.
Step 4: Feature 'AI categorization' is not in Constraints, so it is not in the intersection.   # This feature would violate the offline requirement, so it is excluded from the current build.

Result: The engineering intent document has a clear intersection: the product will serve the user set, achieve the goals, and work within the constraints. Features outside this set are marked as future enhancements.
```


## From scratch, in Python

```python
from datetime import date

class EngineeringIntent:
    def __init__(self, problem, users, goals, constraints):
        self.problem = problem
        self.users = users
        self.goals = goals
        self.constraints = constraints
        self.created = date.today()

    def summary(self):
        print(f"Problem: {self.problem}")
        print(f"Users: {', '.join(self.users)}")
        print(f"Goals: {', '.join(self.goals)}")
        print(f"Constraints: {', '.join(self.constraints)}")

intent = EngineeringIntent(
    problem="Users overspend monthly and want to save more.",
    users=["Young professionals", "India", "25-35 age group"],
    goals=["Reduce overspending by 20%", "Increase savings by 5%"],
    constraints=["Offline functionality", "Low-end Android", "Data privacy compliance"]
)

intent.summary()
```


## What the code does

Line by line: `from datetime import date` imports the date module to get today's date. Next, we define a class named `EngineeringIntent`. A class is a blueprint for creating objects. We use `__init__` to initialize an object with the four essential attributes: problem, users, goals, constraints. Each attribute is stored on the object. The method `summary` prints a readable version of the document. Then we create an instance `intent` by passing the actual values. Finally, we call `intent.summary()` to display the document. This is plain Python, no frameworks, showing the structure of the document.


## Common misconceptions

**Intent document is just a to-do list** — It is just a list of tasks, like 'build landing page', 'set up backend'.

A to-do list is about implementation steps. The intent document is about the why and the who — the problem, users, goals, constraints. It should not prescribe specific technologies or tasks. In fact: The intent document answers 'what are we doing and why', not 'how'. Implementation details come later in the specification.

**Intent document is the specification** — Once I write the intent, I can start coding; it's detailed enough.

The intent lacks the granular details a specification has: exact requirements, API contracts, data models, acceptance criteria. Coding from it invites guesswork. In fact: The intent is the starting point; you must expand it into a formal specification with detailed requirements and tests before coding.

**The document is for the AI only** — I only need to write this if I'm using an AI coding agent; for human teams, we just talk.

Human teams also need a shared written record; memory and verbal discussions are ambiguous and fade. A written artifact prevents misalignment. In fact: The document serves any team — human or AI — as the single source of truth for direction.

**A longer intent document is better** — I should write as much as possible to cover every scenario.

An overly long document becomes hard to read and maintain, and may introduce speculative constraints that are not real, causing over-engineering. In fact: Keep it short, focused on essential elements: problem, users, goals, constraints. Detail belongs to the specification.


## In short

The engineering intent document is your project's north star — a short, clear statement of the problem, users, goals, and constraints. It sits between the initial spark of an idea and the detailed blueprint. It ensures everyone — including AI agents — is building the right thing. Use it as the foundation for all downstream specification work.


## Where this is used

In modern AI, engineering intent documents are crucial, especially with AI coding agents. In large language model (LLM) based development, you feed the model a well-defined intent document to generate the specification and then the code. For example, with a tool like GitHub Copilot or Cursor, you might write: 'Generate a Python script to calculate monthly budget based on the intent: problem, users, goals, constraints.' The model uses that context to produce code that fits. In small models running on devices, the intent document guides the design of a lightweight model with specific constraints. In retrieval-augmented generation (RAG), the intent document helps scope the query: 'What are the user goals?' to retrieve relevant requirements. In agentic systems, the intent document is the root instruction: an agent planning to build a feature reads the intent and then breaks down tasks. In everyday applied ML, an intent document prevents wrong problem framing: a data scientist might explicitly write 'predict churn' but the intent clarifies 'reduce churn by 20% this year' — which changes the metric. Developers write these documents in markdown in the repository, and tools like Jira or Confluence manage them. When done badly — a vague intent or none at all — the AI generates off-target code, and the human misses the mismatch until later.


---

Read this on the web: https://basavapurushottam.com/learn-ai/engineering-intent-documents
