↓Skip to main content

Building Software with Spec-Driven Development

·5 mins
SpecDrivenDevelopment SoftwareEngineering AI OotBD

Spec-driven development is quickly becoming a core skill for modern developers.

With AI tools getting better every day, the way we write software is changing: from writing code first to defining clear specs first. In this post, which is the summary of an “Out of the Box Developer” podcast session, we will see what it is, how it works in practice, and how you can start using it today.

What Is Spec-Driven Development? #

At its core, spec-driven development means writing a clear specification of what you want before writing code — and then letting AI help generate that code.

As Yugo explains:

We can actually start creating code just from the specs. When I have a specification — what is the goal, what is the feature, the acceptance tests — you can turn it into code.

This is different from:

  • TDD (test-driven development)
  • BDD (behavior-driven development)

Here, the spec becomes the main driver, not tests or behavior descriptions.

The Three Levels of Spec-Driven Development #

According to the discussion, there are three common approaches:

1. Spec-First #

You just write a spec and then ask the AI to help write the code. Any fixes you do, you apply directly to the generated code.

It is a good starting point and flexible, but can drift away from the original spec.

2. Spec-Anchored #

You keep the specification in your codebase. When you need changes, you update the spec and then regenerate or adjust code accordingly.

It is better for consistency, easier to maintain and common in real teams.

3. Spec-as-Source #

The spec is the only source of truth, you never edit code directly. All changes happen through the spec.

It gives maximum consistency, but hard to adopt and requires strong discipline and tooling.

Most teams today stay between spec-first and spec-anchored.

Why This Matters in the AI Era #

Pedro: AI is not just to generate the code. AI is to generate the spec as well.

This creates a new workflow:

  1. Use AI to understand the system
  2. Generate a draft spec
  3. Review and refine it
  4. Generate code from it

But there’s a catch.

Pedro: You can end up with thousands of lines of code from one spec… then you still have bottlenecks like code review and quality.

So specs don’t remove problems — they move them earlier in the process.

Two Types of Specifications You Should Know #

Pedro introduced a very useful distinction:

1. High-Level Specs (Project Context) #

These define:

  • Architecture
  • Tech stack
  • Rules and patterns

Pedro: This is what the project is — standards, architecture, style. This stays in your repo and evolves over time.

Think of it like:

  • “We use Java 21 + Spring Boot”
  • “Controllers cannot call repositories directly”

These act like a team rulebook.

2. Feature Specs #

These define:

  • What a feature should do
  • Inputs, outputs, behavior

Yugo: “It is about what needs to be built — the features, the user stories, what the system should do.

Both are essential. Without context, your feature specs will produce inconsistent code.

Real Insight: Specs Improve Team Onboarding #

One of the most practical benefits is onboarding.

Yugo: Every time we have a new joiner, we need someone to teach everything… and we always forget something.

With spec-driven development:

Yugo: The agent starts to teach the developer because there is a rule written in the higher-level document.

That’s powerful:

  • New developers learn faster
  • Standards are enforced automatically
  • Fewer mistakes early on

Live Coding Workflow (What Actually Happens) #

In the live demo, Yugo showed a real workflow using an AI coding agent.

Step 1: Define Context #

Create files like:

  • agent.md → rules and behavior
  • architecture.md → tech stack
  • project.md → system overview

Example:

  • Java 21
  • Spring Boot
  • LangChain4j
  • Local storage

Step 2: Generate a Spec #

Prompt:

Write a spec to display recorded audios in the UI

AI generates:

  • Objective
  • Requirements
  • Constraints
  • Architecture approach

Yugo: It was exactly what I was looking for… I didn’t need extreme detail — the AI figured out the expected behavior.

Step 3: Review the Spec #

Important rule:

Yugo: It has to be short enough so a human can read it… otherwise it becomes forgotten documentation.

Step 4: Generate Code #

Then simply:

Implement this spec

The AI:

  • Writes code
  • Creates endpoints
  • Adds logic

Step 5: Run, Fix, Repeat #

Here’s where things get interesting:

Pedro: You can say: run it, fix any issues, make it work… run tests until everything passes.

The AI can:

  • Run tests
  • Detect errors
  • Fix them
  • Retry automatically

But it’s not perfect.

Yugo: We still need someone to understand what’s going on… even with AI.

Key Lessons From the Demo #

  • The better your spec, the better the output
  • AI can loop through errors and fix them
  • Backend works better than frontend (for now)
  • You still need developers to validate results

Does This Replace Developers? #

Short answer: no.

Yugo’s answer is clear:

It’s less about writing code. You need to understand the intention and the purpose of the feature.

And also:

Yugo: Developers still need to understand how to validate if the implementation makes sense.

So your focus shifts to:

  • Understanding problems
  • Designing solutions
  • Reviewing outputs

When Should You Use It? #

Good fit: #

  • Enterprise features
  • Structured projects
  • Teams with standards

Not ideal: #

  • Quick prototypes
  • Hackathons
  • “Just show something fast” scenarios

Yugo: For proof of concept… spec-driven development feels slower.

Common Challenges #

  • Specs can become too long
  • Frontend is harder to generate
  • Requires good prompts and structure
  • Needs solid tests

Also, creativity-heavy areas (like UI or data visualization) are harder. It’s very difficult to describe precisely what the output should look like… especially with visualization.

Practical Tips to Get Started #

  • Start with spec-first, not spec-as-source
  • Keep specs short and readable
  • Separate:
    • project rules
    • feature specs
  • Use AI to:
    • draft specs
    • refine ideas
  • Always review before generating code
  • Add tests early

Final Thoughts #

Spec-driven development is not the future — it’s already here. It changes how we think about building software: from writing code first to thinking first, specifying clearly, and then generating code.

Pedro: The more context you give, the better output you get.

So your real job is not just coding — it’s clarity of thinking.

YouTube link to the original OotBD session