Building this blog with spec-driven development
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 leastEvery technical decision lives in a markdown file inside the repo, with a status: proposed, accepted, rejected or replaced. Nothing gets implemented without one.
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.mdAn 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.11Decisions 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 AstroAt 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.22Plans live in .ai/strikethroo/ and project knowledge in .ai/kenkeep/. The decisions stay in specs/.↩︎
So far the blog has five plans:
01 astro-blog-setup
02 design-c-components
03 media-years-and-test-content
04 benji-style-annotations-and-doodles
05 production-launch-readinessThe 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. 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”.
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 not mine yet. 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.