KARTIK CHANDRA BISWAS
← Back to blog

Spec-Driven Development in Practice: Building a Book Catalog App with AI

  • SDD
  • Software Engineering
  • AI Coding
  • React
  • Node.js
  • SQLite

I recently explored Spec-Driven Development (SDD) by building a full-stack Book Catalog web application.

GitHub: https://github.com/onsaurav/sdd-book-catalog

What is SDD?

Spec-Driven Development is a software development approach where the written specification becomes the single source of truth.

In simple words: The spec is the boss. The code is the output.

Instead of starting with code, SDD starts with a clear specification that defines what the software should do, why it should exist, what rules it must follow, and how success will be measured.

From that spec, we create:

  • a technical plan
  • small implementation tasks
  • code
  • tests
  • review checkpoints

This creates a disciplined flow:

SPEC → PLAN → TASKS → IMPLEMENT → TEST → DEPLOY

And when requirements change, the spec changes first. Then the plan, tasks, and implementation follow.

Why SDD matters

AI coding tools have made writing code faster than ever. But fast code is not always correct code.

The real problem now is not typing speed. The real problem is drift.

Drift happens when the generated code looks reasonable but quietly solves the wrong problem, misses an edge case, invents behavior, or ignores a requirement that was never clearly written down.

This is where SDD becomes valuable.

It replaces vague “vibe coding” with a written contract. The AI agent does not guess the product. It follows the spec.

A good SDD process helps answer important questions before implementation:

  • What exactly should the system do?
  • What should happen when input is invalid?
  • What data model should never change casually?
  • What are the edge cases?
  • What does “done” actually mean?
  • How do we verify the result?

How I applied SDD in this project

For this project, I built a Book Catalog web app where users can manage a shared catalog of books.

The project uses:

  • React with Vite for the frontend
  • Node.js and Express for the backend
  • SQLite for the database
  • REST API for communication
  • Authentication for protected actions

The application supports:

  • viewing books
  • adding books
  • editing book details
  • archiving books instead of hard deleting them
  • restoring archived books
  • login-protected modification actions
  • ISBN validation and normalization
  • search, filtering, sorting, and pagination
  • backend tests for schema, validation, authentication, and book APIs

The most important part of the project is the specs/ folder.

It contains:

  • spec.md as the source of truth
  • plan.md for technical decisions
  • tasks.md for small implementation steps

This structure helped keep the project controlled. The goal was not just to generate code quickly, but to make sure the code matched the intended behavior.

What I learned

SDD is not just documentation.

It is a development discipline.

The best part of SDD is that it creates review gates. You do not jump from idea to implementation in one step. You move through specification, planning, task breakdown, implementation, and testing.

That makes the process easier to review, easier to debug, and much safer when using AI coding agents.

For small projects, SDD creates clarity. For larger projects, it creates consistency. For AI-assisted development, it creates control.

The biggest lesson for me:

Good software does not start with code. It starts with a clear specification.

Project repo: https://github.com/onsaurav/sdd-book-catalog

Contact