kestrelsnest-blog/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a personal blog built with Hugo static site generator. The site is deployed to https://blog.kestrelsnest.social and uses the "m10c" theme.

Common Commands

Development

# Start development server with drafts visible
hugo server -D

# Start development server without drafts
hugo server

# Kill existing Hugo server if port is in use
pkill -f "hugo server"

Building

# Build the site to public/ directory
hugo

# Build with drafts included
hugo -D

Deployment

# Deploy to production (builds and syncs to server)
./deploy

The deploy script builds the site and uses rsync to sync the public/ directory to the production server at social:../../var/www/blog/www. It uses the --delete flag to remove files on the server that aren't in the local public folder.

Content Management

# Create a new blog post
hugo new posts/my-new-post.md

# Create content using the default archetype
hugo new content-name.md

Architecture & Structure

Theme System

The blog uses the "m10c" theme but has two additional themes available (henry, kestrel). Theme switching is done via config.toml.

Content Organization

• /content/posts/ - Blog posts
• /content/now.md - "Now" page showing current activities
• /content/then.md - "Past" page with historical content
• /content/upcoming.md - "Future" page with upcoming events
• /content/mytweets.md - Local tweet archive page

Menu Structure

The site has four menu groups configured in config.toml:

• main: Home and Tags navigation
• secondary: Past, Now, Future pages
• tertiary: Local Tweet Archive
• featured: External links like the Random Recipe Project

Key Configuration

• Base URL: https://blog.kestrelsnest.social
• Author: Eric Wagoner
• Social links are configured in config.toml under params.social
• Default Open Graph image: /static/default-og.png

Important Notes

• The Hugo server automatically watches for changes in /archetypes, /assets, /content, /data, /layouts, /static, and /themes
• Posts are created with draft status by default (controlled by archetype)
• The site integrates with multiple social platforms and services in the Kestrel's Nest ecosystem

Temporal Pages Maintenance

When doing any work on the blog, check if the following pages need updates:

• /content/now.md - Current activities, projects, reading, playing, upcoming events
• /content/then.md - Completed projects, finished books/games, past events
• /content/upcoming.md - Future plans, events, projects in the pipeline

These three pages form a temporal view of Eric's life. New blog posts often signal changes that should be reflected here:

• A new project post might mean something moved from /upcoming to /now
• A project completion post means moving from /now to /then
• Event announcements should appear in /upcoming with dates/venues
• After events pass, move them to /then

Each page includes a "last updated" date in the opening paragraph—update this when making changes.

Eric's Writing Voice & Style Guide

When writing or editing blog posts, maintain Eric's distinctive voice and structural patterns:

Structural Patterns

1. Opening Elements

   • Start with an italicized tagline that captures the core insight (e.g., "Three thousand passing tests don't mean your system works")
   • Include a TL;DR section early in technical posts, using callout boxes for key summaries
   • Use horizontal rules (---) to separate major sections

2. Callout Boxes (use Hugo shortcode syntax)

   • Extensively use callout boxes for warnings, examples, quotes, and key insights
   • Types: info, warning, success, danger, note, quote, example
   • These are structural signposts, not decoration—they highlight critical information
   • Example: {{< callout type="info" title="Why This Matters" >}}...{{< /callout >}}

3. Section Structure

   • Use numbered breakdowns for complex topics (Bug Category #1, #2, etc.)
   • End sections with concrete metrics or results
   • Include "What's Next" or forward-looking sections in series posts

Tone & Voice Characteristics

1. Brutal Honesty with Technical Confidence

   • Be unflinchingly honest about failures and mistakes
   • Never self-pitying—own mistakes but frame as learning
   • Mix emotional vulnerability with technical precision
   • Examples: "The Most Embarrassing Bug," "My morale was at an all-time low" paired with detailed technical analysis

2. Concrete Over Abstract

   • Always ground statements in specific numbers, metrics, and examples
   • Replace abstract lists with detailed scenarios showing actual time breakdowns
   • Use real project names (LocallyGrown.net) and specific technologies (Rails, SvelteKit, Claude Code)
   • Before/after comparisons with actual measurements: "8-12 commits per week" → "40-50 commits per week"

3. Show the Work

   • Include code snippets (even wrong code) with explanations
   • Provide specific numbers: "314 commits in 18 days," "$1.3 million in annual sales"
   • Show actual dialogue or process breakdowns
   • Time breakdowns: "Total: 25 minutes. The thinking took 2. The transcription took 23."

4. Characteristic Phrases

   • "Here's what matters:"
   • "The numbers tell the story:"
   • "The real X was always Y"
   • "This wasn't about X. It was about Y."
   • Rhetorical questions followed by answers
   • Extensive parenthetical asides: "(after comparing Prisma, TypeORM, and others)"

5. Human Impact Focus

   • Always circle back to impact on real people—users, customers, communities
   • Frame personal victories as community victories
   • End with forward-looking perspective, not just resolution
   • Connect technical decisions to human consequences

6. Technical Communication

   • Never assume reader is technical—explain even when showing code
   • Balance technical specifics with human impact
   • Use technical details to prove points, not to show off
   • Include both the code AND the why

Content Patterns

1. Examples Over Explanation

   • Transform abstract concepts into concrete scenarios
   • Show specific workflows with timing breakdowns
   • Include real-world examples from actual projects
   • Use before/after comparisons with measurable differences

2. Data-Driven Narratives

   • Support claims with specific metrics
   • Track and report actual measurements
   • Use Git logs, analytics, user counts as evidence
   • Quantify time savings, performance improvements, impact

3. Acknowledgment & Gratitude

   • Credit others extensively (market managers, designers, contributors)
   • Acknowledge tools and their creators
   • Recognize community contributions
   • Human names for AI agents (Ray, Agatha, Ada) to maintain human-centered perspective

4. Balanced Disclaimers

   • Use callout boxes for important context or disclaimers
   • Acknowledge different approaches work for different people
   • "What This Isn't" sections to clarify boundaries
   • Respectful of different working styles and tools

Series & Long-Form Posts

For multi-part series (like the LocallyGrown series):

• Include series navigation at the end
• Link to related posts with clear context
• Use consistent callout styles across the series
• Build narrative arc across posts
• Reference earlier posts when relevant

Example Transformations

Abstract → Concrete:

Before: "Most of my time was spent on mechanical tasks"

After: "I tracked it once: 4 hours of actual coding work produced 3.5 hours of fixing typos, hunting syntax, and triple-checking. The ratio was backwards."

General → Specific:

Before: "The platform performs well"

After: "Response times are consistently under 2 seconds, even during peak Sunday night ordering when 200+ customers are browsing simultaneously."

Personal → Community:

Before: "I finally solved the problem"

After: "The fix went live Tuesday morning. By Wednesday, three market managers reported their volunteers could finally access the tools they needed. Physical workflow restored."

Voice Checklist for Posts

• Opens with italicized tagline
• Includes TL;DR with metrics (for technical posts)
• Uses 2-4 callout boxes for key insights
• Contains specific numbers and measurements
• Shows concrete examples, not just abstractions
• Balances vulnerability with technical confidence
• Includes impact on real people/communities
• Ends with forward-looking perspective
• Credits others and acknowledges contributions
• Uses characteristic phrases ("Here's what matters," "The numbers tell the story")

This voice reflects someone who is deeply technical, brutally honest about challenges, focused on real-world impact, and committed to serving communities—not just building software.