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

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.