Old wine in a new bottle? Playing with spec-driven development

leadership ISD
  • spec-driven development
  • spec kit
  • claude code
  • ai
  • github
TL;DR: I built this site with spec-driven development using Spec Kit and Claude Code. The structure and documentation impressed me, the rigidity did not, and a lot of it felt familiar to anyone who has managed a project.
A bottle labelled OLD pouring its contents into a bottle labelled NEW.

It was in my backlog for the summer: create a personal website. I wanted to learn about spec-driven development (SDD), so I built it (yeah, this site) with SDD.

What is SDD?

One might say that spec-driven development (SDD) is the “new agile” or the “new SDLC” in the age of AI. It is a process, indeed, that uses the specification as a base. SDD works in phases: (a) specify, (b) plan, (c) tasks, (d) implement.

What I did

I used Spec Kit, an open toolkit for spec-driven development, together with Claude Code as the AI coding agent. Spec Kit gives you a set of commands that walk you through the workflow, and the agent does the writing while I stayed in charge of the decisions.

The pieces:

It is not my first time developing a website (it is the second hehehe). I used GitHub with Claude and VS Code in the first one, so I decided to go with a similar setup. GitHub has a framework called “Spec Kit”. I asked Claude to help me set up everything.

I started with the Spec Kit on the console, using Claude Code, but I got bored of it and moved to VS Code, still with Claude Code.

Claude Code confirming Spec Kit initialised cleanly, with every step green and the speckit command names listed.

Back to what matters, project ready, let’s go step by step of how I developed my first feature:

/speckit-constitution

This phase sets the principles. I typed the principles below (created with Claude’s help) and it created my constitution. The constitution is used by the entire project, not only the first feature.

This is a personal website for Cristiane, built as a Jekyll static site hosted on GitHub Pages.

Principles:

  • Keep it simple and maintainable. Prefer clear, conventional code over clever solutions.
  • All content (blog posts, projects, curation items) lives in easy-to-edit Markdown or data files, never hardcoded in HTML.
  • The site must build with Jekyll and work on GitHub Pages for free.
  • Pages must be fast, mobile-friendly, and accessible.
  • Minimal JavaScript; only add it when there is a clear need.
  • Always test locally with bundle exec jekyll serve before pushing.
  • I am new to this, so explain what you change and why as you go, in plain language.

/speckit-specify

After a chat with Claude about the type of website I wanted, we ended up with: “Build a personal website for Cristiane as a Jekyll static site hosted on GitHub Pages with five sections: Home, Portfolio/Resume, Projects, Blog, and Curation.”

It created a whole spec with 5 user stories. Each one with priority and acceptance scenarios:

The generated spec showing User Story 1, Home Page and Site Navigation, with its priority, independent test and four acceptance scenarios.

Besides that, the spec also included edge cases, requirements, and success criteria.

And this is how my first feature was created.

/speckit-plan

Claude told me: “Next is the planning step, where the AI decides the technical structure. The plan is the blueprint everything else follows.”

Claude Code listing the site structure it built — config, layouts, includes, pages and assets — and the commit that followed.
“Big milestone: Claude Code built the entire site, all five sections, with the correct structure.”

/speckit-implement

It validates against the spec.

After implementing the first feature, I decided to move to VS Code, so the other features were all created through VS Code with Claude Code CLI.

Discussion

I like how structured the artifacts are now with my 10 features. How it always goes back to the constitution, constantly checking against the principles. How it validates if there is any dependency between stories and tasks, or even features (when I got excited with the project and asked so many things it had to break down into more than one feature). It has a lot of documentation on my repo. I was not expecting that.

Basically, this is the process:

  1. 1 Specify The what and the why
  2. 2 Plan The how, technically
  3. 3 Tasks The work, step by step
  4. 4 Implement Build it, check the spec

So, what is really new?

Many questions are on my mind right now, and they could be the starting point for the next post: