In words
What it is, why it matters, and what it is like.
Why am I learning 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 idea, in plain terms
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.
Where this sits
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.
