Giving AI Better Instructions
Understanding how spec-driven development can improve outputs from AI coding assistants
Everything we build starts with defining what we want to accomplish. We may have a vision in mind, but communicating it clearly and accurately is not that easy. As software is increasingly shaped through natural language, instead of traditional coding, the way we express our intent matters more than ever. While AI coding assistants make it easier than ever to create software, the results can be inconsistent. Small changes in phrasing can produce dramatically different outputs. That’s why it sometimes takes a series of prompts to get the code to behave as expected.
The conversational nature of AI tools makes it easy to forget just how challenging communication can be. We often misunderstand each other’s intent despite discussing what to do at length. AI models only know what we explicitly tell them. So, it's unlikely that they will perfectly understand our intent with vague prompts. Therefore, we need to become proficient at translating our abstract ideas into precise instructions. The more effectively we communicate with AI, the more effectively we can use it to move from concept to outcome.
Why Structured Communication With AI Matters
The parallels between human-to-human communication and human-to-AI communication.
Communication is essential for collaboration. It helps us articulate our thinking to other people, allowing us to work together to transform ideas into something real. However, everyone’s thinking is informed by their unique context. When multiple people have a conversation, each person uses their own context to interpret what’s being said. This has two possible outcomes: everyone either comes to the same conclusion or different conclusions. Often, the second outcome is more likely, which is why we spend so much time and effort getting people aligned.
If we don’t actively identify and bridge the gaps, people can easily end up pursuing diverging and even conflicting outcomes. Even though they may have discussed, defined, and decided what to do, each person’s understanding might differ. When we communicate effectively, we create a shared understanding. This minimizes the likelihood of mistakes and maximizes the likelihood of achieving our goals and objectives. Most of us can appreciate the value of structure and clarity in human-to-human communication. However, we often fail to recognize that this is equally important in human-to-AI communication.
The simplicity of the chat interfaces makes the experience of using AI no different from having a conversation with a real person. However, we often have unrealistic expectations of what AI can actually do with very little information. An AI Model can’t really decipher your specific intent or vision based on a few sentences. The quality of AI outputs depends on the quality of the inputs (the context we provide). Many of us are familiar with prompt engineering as a way to optimize AI outputs. Prompting is really just having a structured conversation with AI. Therefore, when “talking” to AI, it’s useful to treat it like a conversation with a smart, capable coworker: How would you instruct them to complete a task? How much information would you provide? How would you structure that information?
You May Also Like: Effective Communication, Building With AI, AI And Critical Thinking
What Is Spec-Driven Development
Spec-driven development focuses on using clear specifications to direct AI coding assistants. A written specification (or spec) is a comprehensive document that captures the project context. It explicitly describes the goals, expectations, success criteria, etc. It clearly defines what we want to accomplish. When you ask an AI coding assistant to do something (e.g., build an app, create a feature, etc.), you include this spec along with your basic prompt. This gives the AI model structured context on the task you are asking it to perform.
Spec-driven development benefits both the developers and the AI coding assistant:
Developers get a detailed outline of what they want to build, what the interface should look like, and how it should be implemented. They can also use the documentation to define, clarify, and align on what they need to deliver.
The AI model gets structured instructions to guide the planning and execution of the development work. They can also refer to the spec and validate their work against it, which helps them take on larger tasks without getting lost.
Spec-Driven Development Is For Everyone
We can all use spec-driven development to improve the outputs from AI coding assistants.
Spec-driven development is inherently slow at the beginning. You are spending time thinking about what you want to build and fleshing out the details, instead of going straight to development with a simple prompt. While building an app with just a few sentences is clearly more appealing than writing a detailed document, research indicates that AI models referencing specifications output better, more accurate code than those without them. In many cases, the full potential of coding assistants can only be achieved using structured methods such as spec-driven development.
With the emergence of AI coding assistants, anyone can use AI to build software. Even if you have never written specifications before, you can use AI assistants (ChatGPT, Claude, etc.) to help you write one. You are essentially just creating a narrative that describes how you want something (a website, an app, a dashboard, etc.) to look and function. In the future, the best programmers may be the ones who can communicate most effectively. They may not even be “programmers” in the traditional sense. They might just be people who are effective communicators.
In the near future, the person who communicates most effectively will be the most valuable programmer. And literally, if you can communicate effectively, you can program.
— Sean Grove, Alignment Research at OpenAI
Why Do Specifications Improve AI-Generated Code
Specifications help us use structured communication to optimize AI outputs.
Not everyone with access to AI can achieve the same outcomes. Our ability to instruct AI to do exactly what we want directly influences how effectively we can use it. People with a deeper understanding of AI models and greater coding expertise will likely be able to use AI to generate better code. However, we can still improve AI outputs without any specialized knowledge or skills. We just need to get better at communicating with AI. We need to provide more precise instructions to get better results. Specifications are a great way to do that. By incorporating specs into our AI coding workflows, we can generate better code with fewer prompts.
We're moving towards building using human language instead of machine language. AI coding assistants can manage most (if not all) development work. While AI models can understand natural language, they can’t read our minds. They ultimately rely on us to provide context. This means we need to refine how we communicate with these assistants to generate better code. When we enter a prompt, they attempt to figure out what you are trying to achieve based on the context you provide. A spec provides a clear, unambiguous, and detailed description of our intent.
Specifications have always been an essential part of the development process.
A product team’s goal is to create a solution to a problem that the user cares about. The specific output they produce is code. The solution that their users interact with is a result of this code. However, writing the code is only one piece of the puzzle. It takes a lot of structured communication to decide what code needs to be written. One of the primary ways teams solidify this decision is through specifications (or specs). The spec provides a detailed overview of the work that needs to be done. It could take the form of documents like a project plan, product requirements document (PRD), 1-pager, etc. Regardless of the format, a spec helps them align on what needs to be done. It gives them a concrete artifact to discuss, debate, and refer to.
Development teams have always used specifications to guide their work. A spec describes the requirements, scope, and constraints for their deliverable (the thing they need to build). It gives them the information they need to plan the development tasks and execute them. The success of their efforts can be evaluated based on how closely the final product meets the spec. If we assume that AI’s capabilities are equivalent to a human developer, it makes sense that they would require a spec to materialize our vision precisely. AI can certainly handle the planning and execution of development work, but it still needs a clear target to work towards. When we start with vague prompts, it takes us multiple rounds of prompting to create what we actually want.
Specifications help us clarify and refine our ideas.
Clarity is critical regardless of who does coding (developers or AI coding assistants). When development teams lack clarity, they are forced to interpret vague ideas and create plans based on an incomplete or even inaccurate understanding of the overall goals. This inevitably leads to mistakes and rework. Similarly, when we ask an AI coding assistant to build something without providing sufficient context, we don’t get great results. So, we have to keep prompting it to make tweaks until we get something we’re satisfied with. When we approach development without sufficient clarity, we just end up wasting valuable time, effort, and resources.
A specification helps us bring clarity to the development process. It turns our thinking into a concrete product idea: an idea that's specified in enough detail that an engineer can go and build it. The process of writing a specification helps us clarify our vision. We visualize a finished version of our idea and work backwards to figure out the details: What will it look like? What specific functionality will it have? How will people interact with it? And so on. The discipline of writing and reviewing specifications helps development move faster because it increases the likelihood of writing the right code to solve the right customer problem. It solidifies our ideas before we proceed to build something, helping us work more efficiently.
By writing things down, we make them long-lived, durable, and official… we believe deeply in the core value of writing down what we’re doing. We think it makes us better, more effective, and more efficient developers.
— Marc Booker, VP/Distinguished Engineer at AWS Kiro
How To Adopt Spec-Driven Development
There are several ways to incorporate specs into your coding workflows:
Option 1 (Effort: Low-Moderate | Spec Detail: Low-Moderate)
You can make a specifications file (spec.md) with a description of the app or feature (outlining the capabilities, dependencies, etc.). You can add as much or as little as you would like. When using an AI coding assistant, you can upload (or tag) this spec file as context along with your basic prompt (”I want to build an app that does XYZ”).
Option 2 (Effort: Low-Moderate | Spec Detail: Medium)
You can ask an AI tool (a general AI assistant like ChatGPT, Claude, etc.) to create a specifications file for you by providing a short description of what you are trying to build: “Make a specifications file (spec.md) for an feature that does XYZ.” You can review and refine this spec as desired. When using an AI coding tool, you can upload (or tag) this spec file as context along with your basic prompt.
Option 3 (Effort: Moderate | Spec Detail: Medium-High)
You use task management templates to generate specifications and task lists. These templates include markdown files with detailed instructions to guide AI coding assistants. There are many templates out there, and it takes some experimenting to figure out what works best for you. I have found ai-dev-tasks from Ryan Carson especially useful. When using an AI coding tool, you can upload (or tag) these templates as context along with your basic prompt. The AI will generate a spec and a task list for you to review and refine.
Conclusion
Effective communication will become an incredible force multiplier when using AI.
In the future, those who can communicate their intent to AI models with the most clarity will have the most leverage. As the AI models continue to improve, every little percentage increase in output quality will matter more and more. While AI can handle most of the execution work for us, we still need to refine how we communicate with these assistants to get the best results. The ability to translate complex, high-level ideas into simple, structured, and precise language will be critical. Not just for building software with AI, but for any application of AI. Structured communication is a product of structured thinking. Therefore, we need to sharpen our critical thinking and communication skills to direct AI effectively.