# Building this blog with spec-driven development

November 17, 2026

> First the spec, then the code. Even for a personal blog.

I wanted a personal blog for a long time. This time I built it the same way I build things at work: first the spec, then the code.

In this post I explain how the project is organised, what changed on the way and what is still open.

## Decisions before code

(the rule I break least)

Every technical decision lives in a markdown file inside the repo, with a status: proposed, accepted, rejected or replaced. <mark>Nothing gets implemented without one.</mark>

`specs/`

```
decisions/
  001-tech-stack.md
  002-design-and-frontend.md
  003-design-to-canvas.md
  004-astro.md
  005-ddev.md
design/
  brief.md
components/
  inventory.md
```

An accepted decision is not reopened. If new information appears, I write a new decision that replaces the old one. So the history stays in the repo, and I can see why something changed.

> Change only what the current task requires.
>
> — My own rules for the agent

## I started with Drupal

I work with Drupal every day, so the first plan was Drupal CMS with Canvas for the pages, on a small VPS. (Decisions 001, 002 and 003 are still in the repo, marked as partially replaced.)

Then I reviewed it with honest numbers. The articles would be written in CKEditor, so Canvas was only useful for the home and a few pages. And the VPS was around 10 € per month, plus updates, backups and security.

(yes, a Drupal developer picking Astro)

At the end, the goal of this blog is to write, not to show Drupal. So decision 004 moved everything to Astro: a static site on Cloudflare, articles in MDX inside the repo, and my own components. The cost now is the domain, less than 1 € per month, and there is no server to maintain.

A few hours later DDEV came back as the local environment (decision 005), because all my other projects use it and the ddev.com site already does the same with Astro.

This is the part where the specs paid off. Changing the stack was one new file that replaced three, not a long discussion with myself.

## Plans and tasks

For plans and tasks I use Strikethroo. A plan cites the decisions it depends on, gets split into tasks, and an agent executes them. Every task closes with its own check. (Plans live in `.ai/strikethroo/` and project knowledge in `.ai/kenkeep/`. The decisions stay in `specs/`.)

So far the blog has five plans:

`.ai/strikethroo/`

```
01 astro-blog-setup
02 design-c-components
03 media-years-and-test-content
04 benji-style-annotations-and-doodles
05 production-launch-readiness
```

The code is written by Claude Code from the plans. I review every change in the browser, in light and dark, before it gets committed.

## From design to code

The design started with a brief: what the blog should feel like, not how to draw it. Short and direct like the way I write, no hero images, no card grids, links that look like links.

The reference was [benji.org](https://benji.org). I took its principles (a narrow reading column, a lot of white space, notes in the margin) but not its look. Claude Design gave me three directions and I picked the third one, "Margins".

Brief → Claude Design → Component inventory → Plan → Astro component

*From a brief to a page made of components.*

The approved design was split into an inventory of components, and each plan built a part of it. The fonts are Spectral for the text, Bricolage Grotesque for titles, JetBrains Mono for code and dates, and Reenie Beanie for the notes in the margin.

## The handwritten notes

The notes are the signature of the blog: margin notes, side notes, highlights and the odd doodle. Each one is drawn once, the first time it scrolls into view, and then it stays.

They are real text, not images, so they can be read, translated and selected. If you prefer reduced motion, nothing animates and the notes are just there.

To be honest, the handwriting is <span class="hand-underline">not mine yet</span>. Reenie Beanie is a placeholder until I turn my own handwriting into a font.

## What is next

Before launching, the last plan prepares the site for production: CI, RSS, a sitemap, a 404 page, meta tags for search and social, and an `llms.txt` with Markdown copies of the articles for AI agents.

After that, the font with my handwriting. And then the important part: write.

If you have any feedback about the blog or about this way of working, just let me know.
