Software EngineeringAI
Spec Driven Development: Vibes and Stuff
Notes on using spec-driven development
Notes on using spec-driven development
After years of building software using development methodologies such as Agile, I recently started to read about spec-driven development. After completing a boot camp on Machine Learning and AI, I became curious about how to utilize AI to create new features effectively. I decided to try spec-driven development to create a simple personal website as a simple project to use as a starting point.
Using spec-driven development is a useful pattern because it allows for a structured approach that treats AI agents like a team of distributed developers, each with clear responsibilities.
The core idea behind this approach is that before writing any code, you create detailed specification documents that any agent (human or AI) can follow independently.
The initial outputs will be markdown files that detail everything, such as the project overview, all of the details around the tech stack and architecture of the project, as well as the UI and UX guidelines.
The breakdown of the files is:
Let me walk you through my real workflow. I use Cursor's planning mode (though this works with any AI assistant that supports longer context windows).
I start with a comprehensive prompt that describes the entire project:
Create detailed specs for spec-driven development that will be used
by agents. The project is to create a website for a full-stack software
engineer who has been in the industry for multiple years with experience
in 3D, medical technology, and the education space. The site will have
a blog page, a contact page for mentoring inquiries, and links for
LinkedIn and GitHub. Create the spec documents in a way that they can
be easily distributed across multiple agents.
The AI then asks clarifying questions about tech stack preferences, design aesthetics, and specific requirements. This back-and-forth usually takes 10-15 minutes, but it's time incredibly well spent.
The AI generates a set of markdown files in a ~/specs folder:
specs/
├── 01_project_overview.md
├── 02_technical_stack.md
├── 03_ui_ux_guidelines.md
├── 04_data_architecture.md
├── 05_feature_specs.md
└── 06_agent_handoff.md
Each file is detailed and opinionated. For example, my 03_ui_ux_guidelines.md doesn't just say "make it look good." It specifies:
## Color Palette
- Primary: For text and backgrounds
- Accent: Used sparingly for CTAs
- Secondary: For metadata
## Typography
- Headings
- Body
- Code
This level of specificity eliminates 90% of the back-and-forth later.
Here's where it gets interesting. You have two approaches:
Option A: Single "Master Orchestrator" Agent
Give one powerful AI agent access to all the specs and let it build the entire project:
You are a Senior Full-Stack Engineer tasked with building a professional
portfolio website. Detailed specifications have been prepared in the /specs
directory. Your goal is to implement the entire project following these
documents precisely.
Start by initializing the project structure and the core UI system.
Option B: Multi-Agent Tracks
Distribute work across multiple AI sessions (or even different AI tools), each handling a specific track:
Each agent gets a focused prompt referencing only the specs relevant to their track. For example:
You are responsible for Track 1: Foundation & UI System.
Your Context:
- Reference specs/01_project_overview.md for project vision
- Reference specs/02_technical_stack.md for tech stack
- Reference specs/03_ui_ux_guidelines.md for design system
Your Tasks:
1. Initialize Next.js project with Tailwind and TypeScript
2. Set up tailwind.config.ts with the minimalist theme
3. Build core UI components (Button, Input, Card)
4. Create a global Header and Footer layout
Focus ONLY on the foundation and UI system.
After using this approach, I've identified three key benefits:
AI agents don't have persistent memory across sessions. If you restart your IDE or switch tools, the agent forgets your previous conversations. With specs, you can pick up exactly where you left off. The specifications are the source of truth.
When AI agents have clear, written specifications, they're far less likely to "improvise" solutions that don't align with your vision. They're not filling in gaps with guesses—they're following a blueprint.
This is huge for complex projects. You can literally have multiple AI coding sessions open simultaneously, each working on different tracks. As long as they follow the folder structure and naming conventions in the specs, merging their work is straightforward.
I recently used this approach to also build an admin dashboard while simultaneously having another agent build the authentication system. Both referenced the same 02_technical_stack.md and 04_data_architecture.md files, ensuring compatibility.
I found that the first version was around 85% correct. The rest were minor adjustments—color tweaks, spacing refinements. No major architectural rewrites.
Include "Why" Statements
In the 02_technical_stack.md file, the reasoning behind the technologies is also explained, which helps the AI understand the priorities and make trade-offs when it encounters edge cases.
Version Your Specs
As requirements evolve, update the spec files and commit them to git. They become living documentation that's far more useful than scattered Slack messages or vague PRD documents.
The actual development workflow looks like this:
If you want to experiment with this approach, start small. Next time you're about to ask an AI to build something, pause and ask yourself:
Write down your answers in markdown files. Then give those files to your AI assistant and watch the quality of output improve dramatically.
Have you tried spec-driven development or something similar? I'd love to hear about your experiences. You can reach out through my contact page or connect with me on LinkedIn.