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 Jekyll and hosted on GitHub Pages. The blog focuses on mobile development, technical leadership, consulting, and career advice. The site uses the Minima theme and is deployed at http://jaimzuber.com.

Development Commands

Running the Development Server

bundle exec jekyll serve

The site will be available at http://localhost:4000. Note: Changes to _config.yml require restarting the server.

Building the Site

bundle exec jekyll build

Outputs to the _site/ directory (which is generated and should not be edited directly).

Installing Dependencies

bundle install

Content Structure

Blog Posts

  • Located in _posts/ directory
  • Must follow the naming convention: YYYY-MM-DD-title.md
  • Front matter template: ```yaml — layout: post title: “Post Title” subtitle: “Optional subtitle that appears in post list” date: YYYY-MM-DD HH:MM:SS -0600 categories: [category1, category2] redirect_from:

    • /old-url-path

      ```

  • The subtitle field is optional and will display in italics under the post title on the home page

Categories

The site uses a custom permalink structure: /:categories/:title:output_ext

Common categories include:

  • consultant-fu - Consulting and career advice
  • ai - AI and machine learning topics
  • drafts - Work in progress (handled via collections)

Redirects

The site uses jekyll-redirect-from plugin. Add redirect_from to post front matter to maintain old URLs when renaming or restructuring posts.

Site Configuration

Key settings in _config.yml:

  • Theme: Minima 2.0
  • Markdown: kramdown
  • Plugins: jekyll-feed, jekyll-redirect-from
  • Google Analytics: Configured with UA-135184114-1
  • Collections: Drafts collection configured for unpublished content (noindex, no sitemap)

Custom Includes and Layouts

  • _layouts/home.html - Custom home page layout with subtitle support
  • _includes/footer.html - Custom footer
  • _includes/head.html - Custom head with favicon configuration
  • _includes/social.html - Social media links (Bluesky, Mastodon, LinkedIn, GitHub)
  • assets/minima-social-icons.svg - Custom social icons including Bluesky
  • assets/main.scss - Custom CSS for bolder/larger headings and subtitle styling
  • Bluesky: jaimzuber.com
  • Mastodon: @jaimzuber@mspsocial.net
  • GitHub: sharpfive
  • LinkedIn: jaimzuber

Content Guidelines

When creating or editing blog posts:

  • Date format in filenames and front matter should be consistent with existing posts
  • Use -0600 timezone (Central Time)
  • Categories should be lowercase and hyphenated
  • The blog focuses on technical topics, particularly iOS/Swift development, consulting, and career advice

Writing Style and Voice

The blog has a distinctive conversational and direct voice. When drafting or editing posts, follow these style guidelines:

Tone and Approach

  • First-person narrative: Write from personal experience using “I” and “my”
  • Direct and conversational: Talk directly to the reader, use contractions, keep it casual
  • Opinionated: State opinions directly without hedging. Don’t be afraid to take a stance
  • No fluff: Get to the point quickly. Avoid padding with unnecessary words or superlatives
  • Practical focus: Emphasize real-world applications over theory

Formatting and Structure

  • Bold for emphasis: Use bold text to highlight key takeaways and important statements
  • Italics for commentary: Use italics for editorial asides, sarcasm, or meta-commentary
  • Short paragraphs: Break up text frequently. Single-line paragraphs are common for emphasis
  • Multiple sentences over em dashes: Instead of using em dashes to append lists (e.g., “They’re systems problems - audio capture, IPC, memory”), break into separate sentences (e.g., “They’re systems problems. Audio capture, IPC, memory management, battery life, on-device ML. This is native platform work.”)
  • Headers for organization: Use ### headers liberally to structure content into digestible sections
  • TL;DR sections: Consider adding summary sections at the top for longer posts

Writing Techniques

  • Rhetorical questions: Use questions to engage readers and transition between ideas
    • Example: “Sound convoluted? Yep.”
    • Example: “Wait, you’re working directly with this company?”
  • Personal anecdotes: Ground abstract concepts in personal experiences
  • Dry humor: Include witty asides and sarcastic observations naturally
  • Colloquial language: Use phrases like “thrown off the deep end,” “pounding the pavement”
  • Authentic voice: Sound like a real person, not corporate marketing

Technical Writing

  • Code examples: Use Jekyll’s highlight tag syntax for code blocks (e.g., {% highlight swift %}...{% endhighlight %})
  • Practical problems first: Start with the real-world problem, then show the solution
  • Acknowledge tradeoffs: Don’t pretend solutions are perfect. Point out downsides
  • Link to resources: Include relevant links to Swift Evolution proposals, WWDC videos, and community resources
  • Commentary on code: Explain why, not just what

Common Patterns

  • Strong statements: Don’t use wishy-washy language
    • Good: “This is a bad idea”
    • Bad: “This might not be the optimal approach in some circumstances”
  • Conversational asides: Use parenthetical comments naturally
    • Example: “(not that there’s anything wrong with that)”
    • Example: “(more on that somewhere down the road)”
  • Emphasize unexpected moments: Highlight turning points with bold or italics
    • Example: “Then it happened.”
    • Example: “Wait, you can do that?”

What to Avoid

  • Marketing speak or corporate jargon
  • Excessive politeness or formal language
  • Long-winded explanations when short ones will do
  • Hedging strong opinions (“might,” “perhaps,” “possibly”)
  • Over-explaining obvious points
  • AI-generated tropes:
    • “It’s not X, it’s Y” or “They’re not X, they’re Y” constructions
    • “It’s not just about X. It’s about Y” patterns
    • Any formulaic contrasts that sound like generated content
    • When making contrasts, use direct statements instead