In the last year, many of us have started writing code differently.
We describe what we want, let AI generate an answer, review it, tweak the prompt, and try again. This loop—prompt, retry, adjust—has quietly become part of our daily workflow.
At first, it feels incredibly productive. But as the complexity of the task increases, something changes. The iteration cycle becomes longer, outputs become inconsistent, and the effort shifts from solving the problem to refining the prompt.
This is where a subtle but important shift in approach can help: moving from prompt-driven development to spec-driven development.
The Problem: Prompt → Retry → Guess
Most AI-assisted workflows today look something like this:
- Write a prompt describing the task
- Review the generated output
- Adjust the prompt
- Repeat until it looks acceptable
In practice, this often simplifies to:
Prompt → Retry → Guess
![]()
Figure: Prompt-driven vs spec-driven workflow comparison
For simple tasks, this works well. But for anything involving multiple inputs, constraints, or edge cases, the process can become unpredictable.
In my experience, the challenge is not the model—it is the lack of structure in how we describe the problem.
A Shift in Thinking: From Prompts to Specifications
Instead of asking AI to “figure it out,” spec-driven development introduces a simple idea:
Define the problem clearly before asking for a solution.
A specification (spec) is not a long document—it is a structured way of describing:
- Inputs
- Outputs
- Constraints
- Edge cases
When this structure is provided upfront, the interaction changes significantly.
Rather than iterating on vague prompts, you are guiding the system with a clear contract.
What This Looks Like in Practice
Let’s take a simple example: an order summary API (for example, a backend service hosted on Azure App Service).
Without a Spec (Typical Prompt)
“Write an API that returns order details for a user.”
A model can generate something reasonable, but in practice, the responses often vary:
- Field names may be inconsistent
- Pagination may be missing
- Edge cases (no orders, large datasets) may not be handled
- Structure may change across iterations
Example response (typical output):
{
"userId": 123,
"orders": [
{ "id": 1, "amount": 250 }
]
}
With a Spec (Structured Input)
Now consider providing a simple specification:
Specification:
- Input:
- Output:
- userId
- orders[]
- orderId
- totalAmount
- orderDate
- pagination
- page
- pageSize
- totalRecords
- Constraints:
- Default pageSize = 10
- Return empty list if no orders
- Handle large datasets efficiently
Example response (based on the spec):
{
"userId": 123,
"orders": [
{
"orderId": 1,
"totalAmount": 250,
"orderDate": "2024-01-10"
}
],
"pagination": {
"page": 1,
"pageSize": 10,
"totalRecords": 50
}
}
Why This Tends to Work
The difference here is not just stylistic—it is structural.
An unstructured prompt leaves room for interpretation. A spec reduces ambiguity by defining expectations explicitly.
In practice, I have observed that providing structured inputs like this often leads to the following:
- More consistent field naming
- Better handling of edge cases
- Reduced need for repeated prompt refinement
Rather than relying on trial-and-error, the interaction becomes more predictable and aligned with expectations.
Applying This to Existing Code (Refactor Scenario)
This approach becomes even more useful when applied to existing code.
Instead of asking:
“Fix the bug in the Auth controller”
You can define expected behavior:
- Input validation rules
- Response formats
- Error handling
- Authorization behavior
The task then becomes aligning the implementation with the defined spec.
This shifts the interaction from guesswork to validation—comparing current behavior with intended behavior.
Example Comparison (Auth Scenario)
Without Spec (Typical Prompt)
“Fix the login issue in Auth controller”
Possible outcomes include:
- Partial validation added
- Inconsistent error responses
- No clear handling of repeated failed attempts
With Spec (Defined Behavior)
Spec defines:
- Validate username and password
- Return consistent error responses
- Lock account after 5 failed attempts
- Do not expose internal errors
Resulting behavior:
- Input validation is consistently applied
- Error responses follow a defined structure
- Edge cases like account lockout are handled explicitly
This mirrors the same pattern seen in the API example—moving from ambiguity to clearly defined behavior.
A Practical Way to Start
You do not need new tools or frameworks to try this.
A simple workflow that has worked well in practice:
- Ask – Describe the problem (prompt, discussion, or notes)
- Write a spec – Define inputs, outputs, constraints
- Refine – Remove ambiguity
- Generate – Use the spec as input
- Validate – Compare output with the spec
This adds a small upfront step, but it often reduces back-and-forth iterations later.
The Practical Challenge
One important point to note:
Writing a good spec requires understanding the problem.
Spec-driven development does not eliminate complexity—it surfaces it earlier.
In many cases, the hardest part is not writing code, but clearly defining:
- What the system should do
- What it should not do
- How it should behave under edge conditions
This is also why specs evolve over time. They do not need to be perfect upfront. They improve as your understanding improves.
Where This Approach Helps
From what I have seen, this approach is most useful in scenarios where the problem involves multiple inputs, defined contracts, or structured outputs such as APIs, schema-driven systems, or refactoring existing code where consistency matters.
Where It May Not Be Necessary
For simpler tasks such as small scripts, minor UI changes, or quick experiments, a detailed specification may not add much value. In those cases, a straightforward prompt is often sufficient.
A Note on Tools
Tools like GitHub Copilot, Azure AI Studio, and AI-assisted workflows in Visual Studio Code tend to be more effective when given clear, structured inputs.
Spec-driven development is not tied to any specific tool. It is a way of thinking about how we interact with these systems more effectively.
References
Final Thoughts
Many discussions around AI-assisted development focus on what tools can do.
This approach focuses on something slightly different:
How developers can structure problems more effectively before implementation.
In my experience, moving from prompts to specs does not eliminate iteration, but it makes that iteration more predictable and purposeful.
Log in
