# 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 ```bash # 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 ```bash # Build the site to public/ directory hugo # Build with drafts included hugo -D ``` ### Deployment ```bash # 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 ```bash # 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.