Started: March 11, 2026 | Status: In progress
I’m redesigning this blog from Hugo to Astro, using AI coding agents (Claude Code, Claude Desktop, Codex) as my primary collaborators. This page documents the real process — the prompts I write, the questions agents ask, the plans they produce, and the decisions I make. If you’re curious about what agentic coding looks like in practice, follow along.
The migration: Hugo + Blackburn → Astro 5, Tailwind CSS, AstroPaper theme, Cloudflare Pages
How to read this: Each part below is a chapter of the redesign. Newest entries are at the top.
Part 1: Write the Spec — Mar 11-12, 2026
Goal: Go from “I want to redesign my blog” to a spec that an AI agent can execute against.
Output Artifacts
Day 1 — Picking a template (Mar 11)
I started by browsing Astro themes on astro.build/themes and Vercel’s Astro templates. I looked at a bunch of them, evaluating for clean design, readability, and that hard-to-name quality of feeling right.
The one I kept coming back to was AstroPaper — clean layout, good typography, nice page transition animations, and not over-designed. It felt like a solid foundation I could build on rather than fight against.
Then I did something deliberately low-tech: I wrote the spec by hand, in a notebook. No AI, no editor. Just thinking through what I actually want from the new site. Here’s the digitized version of those notes:
The handwritten spec (digitized)
Redesign my blog and personal website annjose.com. It is currently built with Hugo and an old theme called blackburn. Content lives in a GitHub repo; static pages are hosted on GitHub Pages. Here’s what I want:
- Tech stack: Astro, Tailwind CSS, with a good theme (leaning toward AstroPaper)
- Design: Clean UI with enough whitespace but not wasted space. Beautiful colors and fonts. Mobile responsive. Light and dark mode.
- Custom routes for pages I want to host on the domain — e.g. /books, /notes, /photos
- About Me page
- Projects page to showcase what I’ve worked on (liked the layout at adamfortuna.com/projects as inspiration, but don’t want to copy it)
- Blog features:
- Good syntax highlighting (lots of technical content)
- Floating table of contents on the right that follows scroll and highlights current section
- Tags, tag management, possibly a tag cloud
- Next/previous post links with titles
- OG images for every post
- A comment system that blocks spam but isn’t ad-heavy like Disqus — could I build my own with something like InstantDB and email-based auth?
- Future (post-launch): Some authenticated routes accessible only to family. URL-based access with generated GUIDs for sharing private pages.
Day 2 — The spec meets Claude (Mar 12)
I opened Claude Desktop and gave it the handwritten spec with one instruction: “Review these requirements and tell me what you make of it. Ask clarifying questions.”
Claude did something I didn’t expect — before asking anything, it explored the entire codebase and live site on its own. It spawned two agents in parallel: one crawled the repo structure, the other fetched annjose.com and the AstroPaper demo. Only after building its own understanding did it come back with questions.
It asked two rounds of clarifying questions — here are the key decisions that came out of that exchange:
| Decision | What I chose |
|---|---|
| Fork Astro Paper or build from scratch? | Fork and customize |
| Hosting platform | Cloudflare Pages |
| Existing Disqus comments | Static HTML embed (export old, Giscus for new) |
| Migrate all 58 posts? | Yes, all of them |
| Private routes / auth | Defer to Phase 2 |
| Projects page format | Side projects & open source, card grid layout |
The result: an 8-phase migration plan spanning ~14 days. The critical path is a content migration script that converts all 58 posts from Hugo format (TOML front matter, Hugo shortcodes) to Astro format (YAML front matter, MDX). Everything else builds on that.
See the first version of the spec.
Reviewing and refining the spec
The initial spec was solid but needed pressure-testing. I reviewed it and came back with 7 questions covering scope, naming, URLs, deployment strategy, Astro 6 compatibility, and gaps. This kicked off two more rounds of back-and-forth that significantly shaped the final spec.
Key refinements from the review:
- Scope split: Moved the Projects page and Auth to “Wave 2” (post-launch enhancements), keeping Wave 1 focused on the core site, blog migration, and deployment. Also renamed “Phase 2” (which was overloaded — used for both implementation phases and deferred features) to “Wave 1” vs “Wave 2” to avoid ambiguity.
- URL migration strategy: New posts live at
/blog/<slug>/instead of Hugo’s/post/<slug>/. Old URLs preserved via Cloudflare_redirectswith 301 redirects — no broken links. - Coexistence plan: The old Hugo site stays live at annjose.com while the new Astro site is tested at
annjose.pages.dev. DNS cutover happens only when the new site is fully validated. - Astro version: AstroPaper hasn’t been updated for Astro 6 yet, so we start on Astro 5 and upgrade before launch (Phase 7 in the plan).
- Repo strategy: I almost let the agent create a new repo, but caught it — that would lose all git history. Instead, we’re using an
astrobranch in the same repo, with a repo rename (myblog→annjose.com) and branch rename (master→main) at cutover.
The agent also ran a gap analysis and found several things neither of us had mentioned:
- MathJax → KaTeX migration (2 posts use math expressions)
- Git submodule cleanup (
public/and theme submodules need removal on the astro branch) - Missing from Wave 1 overview: RSS feed, page migration (/about, /ammachi, /epsilla, /redesign)
- Analytics: The spec mentioned Google Analytics, but the site actually uses Counterscale (self-hosted on Cloudflare Workers). Fixed throughout.
- Automated tests: Added Playwright e2e tests, Lighthouse CI, and a link checker — none of which were in the original spec.
The final spec has 10 decisions, 8 implementation phases across ~14 days, a full folder structure reference, and a verification checklist. See the full diff of the spec refinements and the final version of the spec.
What I learned
Don’t start with the AI. Start with your own thinking — even on paper. The handwritten spec forced me to decide what I actually want before an agent started suggesting things. The AI’s job was to pressure-test it and add structure, not to dream it up from scratch. Also: the agent’s first move was to explore, not ask. It built context before engaging. That’s a good pattern for humans too.
The review rounds taught me something else: read the spec like a skeptic, not an approver. The agent produced a thorough plan, but it had a “new repo” default that would have lost git history, wrong analytics (GA instead of Counterscale), and naming collisions I only caught by reading carefully. The AI is good at structure and completeness; the human is good at catching things that feel wrong.
Next up: kicking off the migration script and scaffolding the Astro project.