Adding a Reading List to My Hugo Blog with SpecKit
After nearly 15 years of maintaining my Hugo-based blog, I decided it was time to add a new feature inspired by Molly White's book list: a reading list to showcase the books I've enjoyed. This is the perfect opportunity to demonstrate how SpecKit can integrate with existing projects without disrupting years of careful customization.
The Starting Point: A Mature Hugo Blog
My blog at den.dev is built with Hugo and uses a modified version of the Congo theme. It features custom layouts, Tailwind CSS styling, and a decade's worth of content—exactly the kind of established project where introducing new functionality can be tricky.
Bootstrapping SpecKit into the Project
Using the SpecKit CLI, I ran specit init here directly in my project folder. This added the necessary SpecKit structure—prompts, memory, scripts, and templates—without affecting my existing Hugo configuration, themes, or content.
Defining the Constitution: Project Constraints
The constitution established critical ground rules: Hugo as the sole build tool, theme-based styling only, zero external dependencies, and maintaining the existing content-first approach. This ensured SpecKit would work within my blog's constraints rather than trying to reinvent it.
Specifying the Reading List Feature
I defined clear requirements: a books page at /books, data sourced from TOML files, grid layout with cover images, star ratings, and footer navigation. The specification phase captured both the visual design and technical implementation details.
The Clarify Phase: Catching Blind Spots
This was where SpecKit truly shined. The AI identified several underspecified areas I hadn't considered:
- Book ordering (decided: most recently finished first)
- Pagination (set to 20 books per page)
- Handling currently reading books (special "currently reading" styling)
- Data validation approach (skip invalid entries silently)
Planning and Task Generation
The generated plan correctly identified Hugo's structure and created appropriate tasks: creating data files, content pages, templates, partials for book cards, and footer navigation updates—all while respecting the existing theme and build process.
Key Takeaways for Existing Projects
This process demonstrated that SpecKit excels at incremental additions to mature projects when you:
- Establish clear constraints in the constitution
- Leverage the clarify phase to catch oversight
- Maintain human oversight throughout the process
- Work in isolated branches to prevent breaking changes
The result was a perfectly integrated reading list that matched my blog's existing design and infrastructure—proof that AI-assisted development can enhance rather than disrupt well-established projects.
Comments
Post a Comment