Building a gem.

Building a CLI for turning job applications into marketing campaigns. Jojo helps you create personalized, engaging applications that stand out from the crowd. It generates tailored cover letters, optimizes your resume for ATS, and even creates a custom portfolio website for each application. With Jojo, you can turn your job search into a marketing campaign that gets noticed.

Building a personal URL shortener deployable via SFTP on shared hosting.

How to use Claude to create a custom exercise program

Recently, I decided to get back into regular exercise after a long period of inactivity. Rather than following a generic workout plan from a fitness app, I wanted something personalized to my specific situation, equipment, and goals. I turned to Claude to help me create a comprehensive four-week exercise program. The results seem great so far.

Here’s how to get an AI to design something that actually works for you.

Starting with the right prompt

The key to getting a useful exercise program from Claude is being specific about your situation. I provided details about:

• My current fitness level and recent activity history
• My specific goals (rebuilding strength and cardio endurance)
• Equipment I had available (resistance bands, household stairs, a yoga mat, and a Nintendo Switch with Ring Fit Adventure)
• My constraints and needs (requiring detailed exercise descriptions since I’m a structured exercise novice)

Claude responded with a complete four-week program that included exercises, nutrition guidance, progress tracking suggestions, and motivational tips. The level of detail was just about right. Each exercise came with form instructions and links to video demonstrations.

The workout schedule

To get concrete, actionable guidance rather than generic advice, I asked for a full 28-day calendar with specific day-of-week workouts:

• Monday, Wednesday, Friday: Strength training
• Tuesday, Thursday: Light cardio and mobility work
• Saturday: Optional gentle recovery
• Sunday: Complete rest

The program also showed clear progression across the four weeks. Week 1 started with wall pushups and assisted squats to build a foundation. By Week 4, I was doing incline pushups, unassisted bodyweight squats, and using resistance bands for rows and shoulder presses.

Sometimes the exercises look a bit too easy, so I’m interested to see how this progressive schedule will work in practice. And I can always adjust the plan later if needed.

From text to calendar

The written workout schedule (and exercise descriptions, and diet advice, etc) was great, but I wanted something I could actually put in my calendar. I asked Claude to generate an .ics file that I could import into my calendar app.

Claude’s first attempt had a bug. It skipped December 25th (Christmas Day), which threw off all the subsequent dates. To avoid this kind of error and make things easier to test, fix, and update later, I asked Claude create a script to generate the calendar instead of manually coding each event.

This worked out well for a few reasons:

1. The script was much easier to debug and verify
2. I now have a reusable tool that I can modify if I want to adjust the schedule or create future workout programs
3. The initial script had a small bug, but it was easy to fix through an iterative conversation with Claude.

Here’s what the core of the calendar generation script looks like:

def create_event(date, day_of_week, week_num, location='Home'):
    """Create an iCalendar event string"""
    week_key = f'week{week_num}'
    workout = WORKOUTS.get(day_of_week, {}).get(week_key)
    
    if not workout:
        return None
    
    event = ['BEGIN:VEVENT']
    
    if workout.get('all_day'):
        # All-day event for rest days
        event.append(f'DTSTART;VALUE=DATE:{format_date(date)}')
        event.append(f'DTEND;VALUE=DATE:{format_date(date)}')
    else:
        # Timed event with duration
        start_hour = 10 if day_of_week == 'saturday' else 9
        start_time = date.replace(hour=start_hour, minute=0)
        duration = workout.get('duration', 30)
        end_time = start_time + timedelta(minutes=duration)
        
        event.append(f'DTSTART:{format_datetime(start_time)}')
        event.append(f'DTEND:{format_datetime(end_time)}')
    
    # Add event details
    event.append(f'SUMMARY:{workout["summary"]}')
    event.append(f'DESCRIPTION:{workout["description"]}')
    
    return '\n'.join(event)

The script organizes workouts in a dictionary structure, making it easy to modify individual workouts without touching the calendar generation logic. Each day’s workout includes the exercises, duration, and detailed descriptions that show up in my calendar. It’s not perfect and it lacks some features and finesse, but for quick generation that’s easy to tweak, it’s exactly what I needed.

When I tried the initial script, I noticed it was using a deprecated Python function (datetime.utcnow()). After the issue was mentioned, Claude corrected it by switching to the modern timezone-aware approach:

# Old (deprecated)
datetime.utcnow()

# New (timezone-aware)
datetime.now(timezone.utc)

I’m not sure why it wasn’t correct in the first place, since Claude did run and test the code before sharing it with me. Perhaps because it was “only” a warning? In any case, Claude is pretty good at iterative improvement and this was quickly resolved.

What worked well

Personalization

The more specific I was about my context, the better the recommendations. If you want to the AI to tailor something specific for you, then has to know some specifics about you. Tell it about your equipment, experience level, and goals.

Detailed instructions

As someone without much fitness experience, I needed more than just exercise names. The AI provided form basic instructions, video links, and safety notes.

Progress tracking

Ask for suggestions around measuring improvements beyond just body weight. Like how many reps of an exercise to target or long to do things like holding a plank.

Nutrition guidance

If you’re looking to build muscle, then protein targets based on weight will help. Practical examples of how to hit those numbers throughout the day is also nice.

Code as a deliverable

Getting a Python script rather than just a static file means I have a tool I can reuse and modify. If I want to adjust the workout times or change which days are rest days, I can do that easily.

What could be better

The experience wasn’t perfect. A few observations:

Video links sometimes incorrect

The form instruction videos Claude linked to are YouTube videos that weren’t always for the exact exercise that was recommended. Fortunately, the written descriptions were often good enough to figure things out.

Claude on the web doesn’t do Ruby

While I asked for a Ruby script to generate the calendar, Claude on the web only supports Python for something it can test. In fact, it insisted on using Python when it couldn’t get Ruby to install in its sandbox. Not a big deal, but something to be aware of if you prefer a specific programming language.

The bigger picture

This experience taught me that Claude can be genuinely useful for creating structured, personalized plans in domains where you need expertise but don’t have it yourself. The key is to:

1. Be specific about your situation and constraints
2. Ask for deliverables in formats you can actually use (calendar files, scripts, documents)
3. Iterate when something isn’t quite right
4. Take what you get and make it your own
5. It’s easy to fool yourself into thinking that the AI is doing a great job if you don’t have the expertise to evaluate the output. Be critical and test things out. If it’s medical advice, check with a professional.

It’s good to have a template now for creating custom exercise programs. Next time I want to get back into shape or continue the existing program, I can just tweak the prompt and have a new plan generated.

Speaking of templates…

Creating your own custom exercise program

If you want to create your own custom exercise program, here’s this basic template I used:

You are an expert AI personal trainer. Please create a customized
exercise plan for me.

Current fitness level: [Describe your recent activity, strength level, 
and any relevant history]

Goals: [What do you want to achieve?]

Available equipment: [List everything you have access to]

Constraints: [Time limitations, experience level, injuries, etc.]

Request: Create a [duration] exercise plan that includes:
- A daily workout schedule with specific exercises, sets, and reps
- Detailed descriptions and/or video links for proper form
- Progress tracking suggestions
- Nutritional guidance to support my goals
- Motivational tips

Please format the schedule as a table showing what to do each day.

Then, if you want a calendar file:

Create a Python script that generates an `.ics` file that I can import into my
calendar. This will be easier to debug and modify.

You can ask for the .ics file directly, but it may be more error-prone.

The nice thing about this approach is the customized nature of it. What we used to get from fitness apps was generic plans based on broad categories of users. Now, we can get something tailored to our individual needs. Not just picking from a set of predefined workout templates. And since it is tailored to you, and generated on demand, having the calendar file is also a big plus.

Illustration by VectorElements on Unsplash

Building a Phaser 2D grid game with Claude

The experiment

This project started with a simple question: How well could an AI coding assistant help me build a game using a framework I’d never touched before?

I’ve spent years writing JavaScript - the language was familiar territory. I had a passing acquaintance with game development concepts. But TypeScript? I was a novice. Phaser? Absolutely zero experience. I expected Claude to excel with TypeScript (plenty of training data), but suspected Phaser knowledge would be sparse.

The central questions:

• Can Claude navigate a less-common API well enough to build something real?
• Will I understand the generated code well enough to modify and extend it?
• What does it take to give an AI assistant enough context to be genuinely useful rather than just generating plausible-looking code that doesn’t work?

I decided to find out. This is the story of building “Infection: Germs vs White Cells” - a turn-based grid game where players compete to dominate the board through strategic dot placement and chain reaction explosions. More importantly, it’s about what I learned collaborating with AI on unfamiliar territory.

The foundation: Getting started

I chose a tech stack that mixed familiar and new territory: Phaser 3 for the game engine, Vue 3 for UI, TypeScript for type safety, and Vite for fast development builds. Vue would handle menus and overlays while Phaser managed gameplay.

The first challenge was connecting Vue and Phaser - they’re designed for different purposes and don’t naturally integrate. After researching examples, we settled on an EventBus pattern. PhaserGame.vue became the bridge component that initializes the Phaser game and sets up bidirectional communication through events.

// Phaser scene emits events to Vue
EventBus.emit('current-scene-ready', this);
EventBus.emit('level-completed', { winner: 'player' });

// Vue listens and responds
EventBus.on('level-completed', (data) => {
  // Update UI, show victory screen, etc.
});

This pattern worked well throughout the project. Phaser handled game logic, Vue handled UI chrome, and they stayed cleanly separated.

The initial gameplay came together surprisingly fast. Within the first session, we had a working grid where players could click cells, place dots, and see them explode when cells reached capacity. The turn system worked. Player indicators updated correctly. The win condition detected when one player controlled the entire board.

Claude was excellent at generating boilerplate and structure for familiar patterns. The Vue-Phaser bridge? That exists in lots of projects. Basic game loops? Common pattern. TypeScript interfaces for game state? Standard stuff.

Core mechanics: Making it feel like a game

Once the foundation worked, we focused on game feel. The core mechanic is simple: click a cell to add a dot. When dots exceed a cell’s capacity, the cell explodes and distributes dots to adjacent cells. This can trigger chain reactions that flip opponent cells to your color.

Cell capacity depends on position:

• Corner cells hold 2 dots (2 neighbors)
• Edge cells hold 3 dots (3 neighbors)
• Interior cells hold 4 dots (4 neighbors)
• Blocked cells hold nothing and don’t contribute to neighbor capacity

The explosion logic needed timing. If chain reactions happened instantly, players couldn’t follow what was happening. We added a 300ms delay between explosions, just enough to watch the cascade unfold without feeling sluggish.

Next we needed variety, different board sizes, obstacles that blocked certain cells, and increasing difficulty. We needed levels. Rather than storing levels in a database, we defined them in code as a linked list structure. Each level points to the next, making navigation intuitive:

const currentLevel = this.getCurrentLevel();
const nextLevel = currentLevel.next();
if (nextLevel) {
  this.loadLevel(nextLevel);
} else {
  this.handleGameOver(winner);
}

We also added undo functionality, because clicking the wrong cell feels terrible in a strategy game. The game tracks the last 50 moves and can roll back the board state. This feature can also be quite useful for testing and debugging.

Making it polished: UI and UX

A working game isn’t the same as a game that feels good to play. We spent time on visual polish - dots that pulse when placed, smooth animations, satisfying sound effects for placement and chain reactions.

The Settings scene let players configure their experience: sound effects on/off, player colors, which level set to play. The responsive design ensured the grid centered properly on different screen sizes.

The tricky part was state preservation. When players navigated from the game to settings and back, they expected their game to still be there. This required careful management of Phaser’s scene lifecycle - sleep and wake rather than destroy and recreate. We’ll come back to this because it caused one of our biggest bugs.

Building AI opponents: From random to strategic

A game against yourself gets boring quickly. We needed a computer opponent, but I didn’t want to build a perfect player - that’s no fun either. Instead, we implemented four difficulty levels with escalating sophistication.

Easy AI picks random valid moves. No strategy, just valid placement.

Medium AI looks for tactical opportunities:

• Explode fully loaded cells (capacity reached)
• Claim corner and edge cells (harder for opponent to capture)
• Otherwise pick randomly

Hard AI adds offensive tactics:

• Prioritize full cells adjacent to opponent cells (capture on explosion)
• Explode full cells next to opponent’s full cells (trigger counter-chains)
• Fall back to medium strategy

Expert AI evaluates positional advantage using “ullage” (remaining capacity). It seeks cells where adding a dot gives advantage over all adjacent opponent cells, forcing the opponent into difficult positions.

Each level specifies its AI difficulty, so players face escalating challenge as they progress through a level set.

The development approach: start simple, iterate to complexity. We built the dumbest thing that could work (random moves), then made it smarter incrementally based on playtesting feedback.

Architecture evolution: When code gets messy

Here’s where I made my first major mistake: I put too much in Game.ts. In self-defense, I didn’t know yes what the architecture should look like yet. So I deferred those decisions until later by putting everything in one place.

At first, this seemed fine. The game logic lived in the game scene. Makes sense, right? But as features accumulated, Game.ts grew to over 1000 lines. It handled grid creation, cell capacity calculations, explosion logic, AI moves, UI updates, state persistence, settings management, and level progression. Reading it required holding too many concepts in your head at once.

The pain became obvious when bugs appeared. Tracking down a state persistence bug meant wading through explosion logic and UI code. Fixing the play order required understanding grid creation. Everything touched everything.

We needed a separation of concerns. Not for “clean code” aesthetics, but because the cognitive complexity made changes risky and debugging slow.

The refactoring happened incrementally, driven by specific pain points:

GameStateManager emerged when state bugs appeared. We needed one clear place responsible for saving and loading game state to Phaser’s registry, handling undo history, and tracking level progression.

GridManager split out when grid logic got complex. Cell capacity calculations, blocked cell handling, hover states, and visual styling didn’t belong mixed with game logic.

GameUIManager formed when UI updates scattered throughout the code. One change to the player indicator required hunting through multiple methods. Now UI creation and updates live in one place.

SettingsManager centralized the synchronization between localStorage and Phaser’s registry. Settings read priority became explicit: registry first, then localStorage, then defaults.

BoardStateManager extracted the core game logic - explosion mechanics, chain reactions, win condition detection. This became the pure game engine, separate from Phaser rendering concerns.

Each refactoring happened when the pain became clear, not as a planned “rewrite day.” We didn’t wait for the perfect time to refactor. We refactored when the current structure made the next feature difficult.

The linked list structure for levels proved elegant. Rather than tracking level indices and bounds-checking arrays, levels just know their next level. The code reads naturally: if (currentLevel.isLast()) instead of if (currentLevelIndex >= levels.length - 1).

After refactoring, most manager classes stayed under 500 lines with single, clear responsibilities. The Game scene itself still exceeds 800 lines (it orchestrates all the managers and handles complex scene lifecycle), but the cognitive load dropped dramatically. You can now understand GridManager without knowing anything about state persistence or AI strategy.

The testing awakening

I need to confess something: I allowed a lot of code to be written before writing tests.

My rationale seemed sound at the time. I was learning Phaser’s architecture and didn’t want to constantly rewrite tests as I figured out the right patterns. Better to get something working first, then add tests once the architecture stabilized.

This was expensive.

Without tests, every refactoring risked breaking something. I’d extract GameStateManager and then manually click through the entire game to verify level progression still worked. I’d modify explosion logic and hand-test edge cases by setting up specific board states. Bugs appeared, got fixed, then reappeared weeks later because nothing prevented regression.

The wake-up call came during a refactoring that broke the undo system in a subtle way. The game worked for new games, but loading a saved game with undo history crashed. I’d fixed this bug before. Now it was back.

We needed comprehensive test coverage.

Working with Claude, we built a four-phase testing plan:

Phase 1: Core data structures (69 tests)

• Level class: linked list navigation, property access, last level detection
• LevelSet class: level management, traversal, bounds checking

Phase 2: Manager classes (196 tests)

• SettingsManager: localStorage/registry sync, defaults, read priority
• GameStateManager: save/load, undo/redo, move history limits
• LevelSetManager: loading definitions, level set switching
• BoardStateManager: game logic, explosions, win conditions

Phase 3: Game logic (88 tests)

• GridManager: cell capacity, blocked cells, hover states
• ComputerPlayer: all four difficulty levels, move validation

Phase 4: UI layer (49 tests)

• GameUIManager: element creation, updates, positioning

We used Vitest because it’s fast, has excellent TypeScript support, and provides a clean testing API. Tests lived next to their source files: GridManager.ts and GridManager.test.ts in the same directory.

The test suite currently has 514 tests across 20 test files, and they run in about 1.2 seconds. Fast enough to run on every save during development.

Writing tests after the fact taught me something: test-driven development exists for good reasons. The tests we wrote exposed edge cases we’d never considered. They caught bugs that would have appeared weeks later. They made refactoring safe instead of terrifying.

If I started this project over, I’d write tests earlier. Not because tests are “best practice,” but because they would have saved me days of debugging time.

🪲 Key challenges and debugging victories

The real learning happened when things broke. Here are four bugs that taught me the most about Phaser, systematic debugging, and AI collaboration.

Challenge 1: The settings scene reset bug

Symptom: Navigate to Settings, change nothing, click Back. The game resets to the first level. Your in-progress game vanishes.

First instinct: The state isn’t being saved. We added logging to GameStateManager. The state was saving perfectly. The state was loading correctly too. What?

Root cause: We were using scene.start() to transition between Game and Settings scenes. This method destroys the current scene and creates a fresh instance of the target scene. When returning to Game, we got a brand new Game scene that ran its create() method, which loaded the first level by default.

The fix: Phaser scenes have a lifecycle: create() runs once when the scene is first instantiated. wake() runs when a sleeping scene becomes active again. We needed:

// In Game scene
navigateToSettings() {
  this.scene.sleep();  // Not scene.start()
  this.scene.launch('Settings');
}

// In Settings scene
goBack() {
  this.scene.stop();
  this.scene.wake('Game');  // Wake the sleeping scene
}

We also added a settingsDirty flag. If settings actually changed, the Game scene’s wake() method reloads them. Otherwise, it just resumes.

Lesson: Understanding framework lifecycles matters. Claude knew the general pattern but didn’t initially suggest wake/sleep because the Phaser API wasn’t in its training data as heavily. Providing links to current Phaser 3.90 documentation helped tremendously. Without docs, Claude would continue to guess based on older API versions, wasting time.

Challenge 2: Level progression bug

Symptom: Complete the first level, click “Next Level.” You see the first level again instead of level 2.

The investigation: We added logging to track what level was being loaded:

console.log(`[GameStateManager] Saved state:
  ${JSON.stringify(boardState)}`);
console.log(`[BoardStateManager] Setting state:
  ${JSON.stringify(boardState)}`);

The logs revealed the issue: we were saving an empty boardState to the registry, which triggered the “new game” code path that loaded level 1.

Root cause: The level completion logic set a loadNextLevel flag, but the state persistence logic also saw an empty board and saved it. This was a race condition where both actions happened simultaneously, and the empty state won.

The fix: Prioritize the loadNextLevel flag. Check it before looking at board state:

wake() {
  const savedState = this.stateManager.loadFromRegistry();

  if (savedState?.loadNextLevel) {
    const nextLevel = this.currentLevel.next();
    if (nextLevel) {
      this.loadLevel(nextLevel);
      return;  // Exit early
    }
  }

  // Otherwise restore board state
  if (savedState?.boardState) {
    this.restoreBoardState(savedState.boardState);
  }
}

Lesson: The linked list structure actually helped here. The code if (nextLevel) makes it obvious we’re checking if a next level exists. With array indices, we’d have if (currentLevelIndex + 1 < levels.length), which is more error-prone.

Challenge 3: Level set changes not taking effect

Symptom: User selects a different level set in Settings, clicks “Play Game.” They see the old level set instead.

Root cause: The Game scene wasn’t checking if settings changed while it was sleeping. It would wake up and continue with the old LevelSetManager.

The fix: The settingsDirty flag from Challenge 1 solved this too. When settings change, the flag gets set. On wake, if the flag is set, reload all settings:

wake() {
  const settingsDirty = this.game.registry.get('settingsDirty');

  if (settingsDirty) {
    this.reloadAllSettings();
    this.game.registry.set('settingsDirty', false);
  }

  // ... rest of wake logic
}

We also needed defensive logic. What if the user changed both player color AND level set? Both changes needed to take effect together, not sequentially with potential state corruption between them.

Lesson: State synchronization across scene transitions requires explicit change detection. Don’t assume data hasn’t changed while your scene slept.

Challenge 4: Memory leaks from event listeners

Symptom: During manual testing, I noticed the browser memory footprint growing as I transitioned between scenes repeatedly. Something was leaking.

The investigation: We added event listener counting to each scene:

shutdown() {
  console.log(`[${this.constructor.name}] Listeners before cleanup:
    ${this.events.listenerCount('pointerdown')}`);
  this.cleanupEventListeners();
  console.log(`[${this.constructor.name}] Listeners after cleanup:
    ${this.events.listenerCount('pointerdown')}`);
}

The counts kept growing. Event listeners weren’t being cleaned up on scene transitions.

The fix: We added explicit cleanup methods to every scene using TDD. First, write a test that verifies listeners are removed:

it('should clean up all button event listeners on shutdown', () => {
  scene.create();
  const beforeCount = scene.events.listenerCount('pointerdown');
  expect(beforeCount).toBeGreaterThan(0);

  scene.cleanupButtonListeners();

  const afterCount = scene.events.listenerCount('pointerdown');
  expect(afterCount).toBe(0);
});

Then implement cleanup:

shutdown() {
  this.cleanupButtonListeners();
  this.cleanupGridListeners();
  this.cleanupUIListeners();
}

We built a live testing dashboard (npm run test:live) that shows real-time event listener counts during rapid scene transitions. You can watch the numbers and verify they don’t accumulate.

[Screenshot: Live testing dashboard showing event listener metrics would go here]

Lesson: Building testing infrastructure surfaced issues we didn’t know existed. The process of creating the dashboard forced us to think about how to measure cleanup, which led us to Phaser’s listenerCount() API and revealed leaks throughout the codebase. We now have 95% test automation for event cleanup validation and zero known memory leaks.

Common thread: Each bug revealed itself through evidence gathering (logging, instrumentation) rather than guessing. This pattern became the foundation for our systematic debugging approach.

The debugging discipline

These four challenges revealed something important: guessing doesn’t scale, even for AI.

Early in the project, Claude would hit a bug and immediately suggest a fix. Didn’t work? Try another. Still broken? Try a third. This guess-and-check thrashing wasted hours and often made problems worse.

I had access to Jesse Vincent’s systematic debugging “superpowers” (think of them as process discipline plugins for Claude). They just weren’t being enforced. After enough frustration, I made the systematic debugging superpower mandatory in CLAUDE.md - the project documentation file that guides Claude’s behavior. The protocol is straightforward:

1. Gather evidence first - Add logging to understand what’s actually happening, not what you think is happening
2. Analyze patterns - Compare working vs broken implementations
3. Test single hypotheses - Make one targeted change to test a theory
4. Fix root causes - Address the actual problem, not symptoms

It also includes this note: “Systematic debugging is 5x faster than guess-and-check thrashing.”

Before adding this additional directive, Claude would often suggest fixes immediately: “Try changing this API call” or “Maybe add this flag.” After adding it, Claude would first suggest adding instrumentation: “Let’s add logging to see what values we’re actually getting.”

The difference was dramatic. Bugs that previously took hours to solve took 30 minutes. We stopped creating bugs while fixing bugs.

Full disclosure: I’m a senior developer and I knew better. But curiosity got the best of me. One of my goals was understanding AI behavior patterns to collaborate more effectively on future projects. I wanted to see if Claude could guess its way to solutions.

The answer: Sometimes, but unreliably. With sufficient context, guessing (or pattern recognition that looks like guessing) often worked. On unfamiliar frameworks like Phaser, it usually failed.

Key insights:

• For Claude: Evidence before action. Always.
• For me: Enforce systematic approaches through CLAUDE.md, don’t rely on AI self-discipline.

For scene lifecycle bugs, we added comprehensive logging:

create() {
  console.log(`[${this.constructor.name}] ===== SCENE CREATE START =====`);
  // ... scene creation code ...
  console.log(`[${this.constructor.name}] ===== SCENE CREATE END =====`);
}

wake() {
  console.log(`[${this.constructor.name}] ===== SCENE WAKE START =====`);
  const settings = this.game.registry.get('settingsDirty');
  console.log(`[${this.constructor.name}] Settings dirty: ${settings}`);
  // ... wake logic ...
}

This logging made scene transitions visible. We could see exactly when create() ran vs wake(), what data each method received, and what order operations occurred in. Bugs became obvious instead of mysterious.

Working with Claude: What worked, what didn’t

Hiring managers care about productivity and code quality. Here’s an honest assessment of where AI helped, where it struggled, and what that means for development teams.

What worked well

Boilerplate and structure: Claude excels at generating TypeScript interfaces, class structures, and common patterns. Need a manager class with standard CRUD operations? Claude writes it in seconds.

Pattern recognition: “This looks like the command pattern” or “This is similar to the observer pattern we used for events” - Claude connects new problems to solved problems effectively.

Architectural improvements: When I recognized Game.ts had grown too large at 1000+ lines, Claude suggested extraction patterns that made sense. The refactoring strategies were sound once the problem was identified.

Test writing: Once we established a pattern for one test file, Claude could generate similar tests for other classes. The 514 tests would have taken weeks to write manually.

Systematic debugging: Once convinced to use the systematic debugging superpower, Claude followed it reliably. This helped enormously and saved a ton of time.

What required guidance

Phaser API specifics: This was the biggest challenge. Claude’s training data apparently has much less Phaser content than TypeScript or Vue. It would suggest API calls that sounded plausible but didn’t exist, or use patterns from older Phaser versions.

The solution: Provide links to current Phaser 3.90 documentation. When I sent Claude snippets from official docs, suggestions became more accurate. Without docs, Claude would guess, and guessing wasted time.

Project-specific architecture decisions: Claude couldn’t decide whether to use localStorage vs Phaser’s registry, or when to extract a manager class vs keep code together. These decisions required human judgment based on project context. Clearer instructions in CLAUDE.md helped, but some decisions still needed human guidance.

Refactoring timing: Claude would sometimes suggest refactoring when we needed to ship, or suggest shipping when the code really needed cleanup. The “when” required human intuition.

Testing discipline: Without explicit guidance, Claude would tend to neglect testing. It would happily write feature after feature without suggesting tests. The comprehensive test suite only happened because I explicitly requested it and then added requirements to CLAUDE.md.

Claiming victory too early: Claude would repeatedly declare a bug fixed after a potential fix. Before any verification it was ready to mark the item as complete and move on. It needed reminders to verify that changes actually worked.

The CLAUDE.md evolution

CLAUDE.md started as a basic README: project structure, how to run tests, basic architecture notes.

It evolved into the project brain - a comprehensive guide that overrides Claude’s default behavior:

## 🚨 MANDATORY DEBUGGING PROTOCOL

**FOR ANY TECHNICAL ISSUE - ALWAYS use systematic debugging**

**FORBIDDEN PATTERNS (cause more bugs than they fix):**
- "Quick fixes" and guesswork - **STRICTLY PROHIBITED**
- Trying random API calls without understanding root cause
- Making multiple changes at once

Before this protocol existed, Claude would get caught in guessing loops. Try a fix, doesn’t work, try another, still broken, try a third. The mandatory protocol broke this pattern.

We documented every resolved bug: symptoms, root causes, fixes. When similar issues appeared later, the documentation provided patterns to recognize.

The key realization: Documentation is bidirectional. I taught Claude about the project, and the process of explaining things to Claude clarified my own understanding. Writing clear instructions forced me to think clearly about solutions. Some of the lessons learned here will be added to the global ~/.claude/CLAUDE.md file for future projects.

Bottom line: AI assistance works best as a partnership. The human brings judgment, context, and architectural vision. The AI brings speed, consistency, and tireless execution of well-defined tasks. Neither replaces the other.

Lessons learned

Here’s what I’d tell my past self, or anyone starting a similar project.

Technical lessons

1. Test early, test often

Writing tests after code cost significant rework time. Tests exposed edge cases we’d never considered. They caught regressions before they shipped. They made refactoring safe.

If I restarted this project, tests would come first. Not as “best practice” dogma, but as a practical time-saving tool.

2. Scene lifecycle matters

Understanding create() vs wake() vs sleep() vs shutdown() is critical in Phaser. The wrong method causes subtle bugs. The right method makes everything work.

3. Registry over localStorage

We used Phaser’s registry as the single source of truth for runtime state, with localStorage only for persistent settings. This prevented synchronization bugs between storage systems.

4. Separation of concerns reduces cognitive load

This isn’t about “clean code” aesthetics. When Game.ts exceeded 1000 lines, making changes became risky because every change could affect multiple unrelated features. After extracting manager classes, each file became understandable in isolation.

5. Linked lists for sequential navigation

The linked list structure for levels made code readable: currentLevel. next() instead of array index math. It also made the progression concept explicit in the data structure.

6. Event cleanup is not optional

Memory leaks accumulate silently. Without explicit cleanup and testing, the browser’s memory footprint grows. Players might not notice on first play, but the leak still exists.

AI collaboration lessons

1. Documentation is bidirectional

Teaching Claude about the project clarified my own thinking. Writing instructions forced clear problem statements. The CLAUDE.md file became as valuable for me as for the AI.

2. Systematic approaches scale

Ad-hoc debugging doesn’t work on complex projects. The mandatory debugging protocol saved enormous amounts of time by preventing guess-and-check thrashing.

3. Start simple, iterate to complexity

We didn’t architect everything perfectly from day one. We built the simplest thing that could work (random AI, basic grid) then made it more sophisticated incrementally. This approach worked much better than trying to design the perfect system upfront.

4. Context files matter

CLAUDE.md became the project brain. It captured architectural decisions, debugging patterns, resolved bugs, and mandatory workflows. Without it, every conversation started from zero.

5. AI is better with constraints

Claude works best with clear protocols and explicit constraints. “Debug this bug” leads to guessing. “Follow the systematic debugging protocol to investigate this bug” leads to instrumentation and evidence gathering.

Process lessons

1. Git commit messages tell the story

Using conventional commits (feat:, fix:, refactor:, test:) made history searchable. When debugging the level progression bug, searching for “fix: level” immediately found commit 0eb8769. When preparing this blog post, running git log --oneline --reverse showed the project evolution clearly.

2. Refactoring is continuous

We didn’t schedule “refactoring week.” We refactored when current structure made the next feature difficult:

• Game.ts hit 1000+ lines → extracted GameStateManager
• State bugs appeared → extracted BoardStateManager
• Grid logic got complex → extracted GridManager
• UI updates scattered → extracted GameUIManager

Each refactoring addressed immediate pain, not theoretical future problems.

3. Build testing infrastructure

The live testing dashboard (npm run test:live) seemed like overkill for a simple game. But building it forced us to think about how to measure event cleanup, which revealed the listenerCount() API, which exposed leaks we didn’t know existed. The infrastructure paid for itself.

4. Document gotchas immediately

Every resolved bug went into CLAUDE.md immediately. The documentation prevented the same bug from reappearing and provided patterns for similar issues. Future me thanked past me repeatedly.

The final numbers

What AI-assisted development produced:

Code quality metrics:

• 514 tests across 20 test files (started with 0, grew through 4-phase testing plan)
• 95% test automation for event cleanup validation
• ~1.2 second test suite execution time (fast enough to run on every save)
• Zero known memory leaks after systematic cleanup and monitoring

Architecture:

• 9 core manager classes handling distinct concerns (extracted from monolithic Game.ts)
• 10 Phaser scenes managing game flow (Boot → Preloader → Splash → MainMenu → Game/About/Tutorial/Settings → LevelOver → GameOver)
• 4 AI difficulty levels implementing escalating strategic sophistication

Content:

• Multiple level sets with 5-7 levels each
• Variable board sizes and blocked cell patterns for strategic variety
• 100+ commits documenting the evolution with conventional commit format

The game is playable, maintainable, and well-tested. More importantly, the codebase is understandable. A developer new to the project could read GridManager without knowing anything about AI strategy, or modify explosion logic without understanding state persistence. That’s what separation of concerns actually buys you.

Was it worth it?

Absolutely.

I built a working game using a framework I’d never used, and the code is maintainable enough that I’d be comfortable handing it to another developer. That’s the real test.

Claude bridged knowledge gaps effectively where it had training data (TypeScript, design patterns). Where it lacked context (Phaser specifics, project architecture), providing documentation and clear constraints made it productive.

The discipline of testing and documentation paid dividends. The 514-test suite catches regressions before they reach production. The CLAUDE.md file captures institutional knowledge that would otherwise live only in my head. The systematic debugging protocol prevents guess-and-check thrashing that wastes hours.

Key insight: AI works best with clear constraints and feedback. Without the debugging protocol, Claude would guess. With it, Claude would gather evidence. Without test requirements, Claude would skip tests. With requirements, it wrote comprehensive coverage.

The game is playable and reasonably fun. The AI provides genuine challenge. The animations feel responsive. Is the architecture perfect? Honestly, I don’t know. But it’s good enough to ship, iterate on, and extend - which is the point.

Would I do it again? Absolutely, but I’d establish testing discipline earlier and encode systematic approaches in CLAUDE.md from day one.

Try it yourself

Want to see the results or dig into the implementation?

• Play the game - Try it in your browser (no installation required)
• View the source - Explore the code with full commit history
• Read CLAUDE.md
  • See the “project brain” that guided development decisions

If you’re considering AI-assisted development, especially with unfamiliar frameworks, here’s what I learned works:

• Provide current documentation when the AI lacks training data (links to official docs beat guessing every time)
• Establish systematic approaches early (debugging protocols, testing requirements)
• Write tests as you go, not retrospectively
• Use a context file (CLAUDE.md) to capture architecture decisions and patterns
• Expect to teach the AI your project specifics - documentation is bidirectional

The partnership model: You bring judgment, architectural vision, and domain knowledge. AI brings speed, consistency, and tireless execution of well-defined tasks. Neither replaces the other, but together they can tackle unfamiliar territory effectively.

Now go build something.

Building a simple 2D grid-based game using Phaser and Claude AI.

Building a daily privacy-first creative storytelling puzzle game

When I set out to create Stormoji, I wanted to combine the daily engagement of Wordle with the creative freedom of storytelling. The result is a single-page web application where players see four random emojis each day and weave them into imaginative narratives. What started as a simple idea evolved into a technical exploration of deterministic algorithms, privacy-first architecture, and the challenges of creating consistent experiences without a backend.

The concept: daily creativity with shared challenges

Like Wordle, everyone sees the same emojis each day. But unlike Wordle’s single correct answer, every story is unique. The app presents four emojis selected from eight categories: smileys, people, animals, food, activities, objects, symbols, and travel. It challenges players to incorporate them all into a coherent narrative.

The privacy-first approach was fundamental from the start. No accounts, no servers, no data collection. Everything happens locally in the browser, with stories automatically saved to localStorage for up to six months. This creates an intimate creative space where users can express themselves without worries about their stories being stored or analyzed.

The core technical challenge: deterministic randomness

The biggest technical hurdle was ensuring that every user sees the same four emojis each day, regardless of when they visit or what device they use. With no backend to coordinate this, the solution had to be entirely client-side.

I implemented a deterministic random selection algorithm using date-based seeding. The process works like this:

1. Date-based seed generation: Convert today’s date to a YYYY-MM-DD format string, which becomes the seed
2. Seeded random function: Use a sine-based pseudo-random number generator that produces identical results for the same seed
3. Category selection: Randomly select four different emoji categories using the seeded random function
4. Emoji selection: Pick one emoji from each selected category
5. Deterministic shuffle: Use a Fisher-Yates shuffle with the same seed to randomize the final order

This ensures that on any given day, all users receive identical emoji combinations, creating that shared daily experience that gives these games their social nature.

Building the CSV export feature

As users started accumulating stories, they wanted a way to preserve their stories in case they lost their phones, changed computers, or switched browsers. This led to implementing a CSV export feature, which proved slightly more complex than initially expected.

The main challenges were:

Proper CSV escaping: Stories can contain commas, quotes, and newlines—all characters that break CSV formatting. I created an escape function that wraps fields containing special characters in double quotes and escapes internal quotes by doubling them.

Browser compatibility: The export uses the Blob API to generate the file and a temporary anchor element to trigger the download. This works in all modern browsers but requires careful cleanup to prevent memory leaks.

User experience: The export needed to handle edge cases gracefully. If a user has no stories, they see a notification instead of triggering an empty download. Success and error states are clearly communicated through toast notifications.

I also redesigned the header menu, replacing the settings gear icon with a hamburger menu that provides access to both the About dialog and the new Export History option. The dropdown includes click-outside detection and responsive positioning for mobile devices.

Lessons learned

Building Stormoji reinforced several valuable lessons about modern web development:

Deterministic algorithms are powerful: Using date-based seeding solved the shared daily experience problem without requiring any server-side coordination. The same approach could be applied to other daily challenge applications. In fact, I later reused this basic algorithm for another project, SlightlyMoreAwesome.

Privacy-first doesn’t mean feature-poor: Despite being entirely client-side, the app includes story persistence, export functionality, and a rich user experience.

CSV is deceptively complex: What seems like a simple format has many edge cases. Proper escaping of special characters is crucial for generating files that work reliably in spreadsheet applications.

Vanilla JavaScript is still viable: The entire application runs without frameworks, build tools, or dependencies. This results in instant loading, zero overhead, and maximum compatibility. Sometimes the simplest solution is the best one.

Throughout development, I tried to maintain a clean architecture that keeps the code maintainable while delivering all the features that were planned.

The architecture: simplicity by design

The application follows a clean separation of concerns:

Data layer: localStorage with JSON serialization, handling story storage and automatic cleanup of entries older than six months

Business logic: Deterministic emoji selection, story management, and export functionality

Presentation layer: Responsive CSS with mobile-first design, semantic HTML, and accessible interactions

Event handling: Modular JavaScript with proper cleanup to prevent memory leaks

This architecture makes the code maintainable and easy to understand, while still providing features users expect from a modern web application.

Looking forward

Stormoji demonstrates that sophisticated web applications don’t always need complex infrastructures. Yet every implementation detail was an opportunity to learn or reinforce some detail of web development. Still, there remain several avenues for future improvement and exploration:

• History import: Allow users to import previously exported CSV files to restore their story history across devices
• Opt-in access to a read-only backend: For users who want to see an AI generated story based on the day’s emojis without storing any personal data. It could be annotated with information on how the story references each emoji. Think of it as a kind of “hint” system. The output could be cached an/d/or pre-coumputed.
• Dark mdoe: Because all apps are better with dark mode… right?

If you’re interested in trying it out, visit stormoji.com to see today’s emoji challenge. Or dive into the source code to see how all these pieces come together in a single, dependency-free deliverable.

Building a gem.

Introduction

If you’ve built Rails applications in the last few years, you’ve probably felt the pressure to adopt GraphQL. The sales pitch is compelling: a more flexible API, happier frontend developers, and an end to the dreaded over-fetching of data. Companies like GitHub and Shopify have embraced it, and the ecosystem of tools keeps growing. It’s easy to feel like you’re falling behind if you haven’t jumped on the GraphQL bandwagon.

But here’s the thing: while GraphQL can be a powerful tool for certain applications, it’s become a default choice without enough critical examination of its trade-offs. After spending several years building and maintaining Rails applications both with and without GraphQL, I’ve found that its carrying costs often outweigh its benefits for typical Rails applications.

This isn’t just about the initial learning curve or setup time. It’s about the ongoing maintenance burden, the hidden complexity costs, and the often-overlooked strengths of Rails’ conventional approach to API design. In many cases, the problems that GraphQL promises to solve can be addressed more simply using Rails’ built-in tools and well-established patterns.

Let’s explore why GraphQL might be more complexity than your Rails application needs, and how to make this evaluation for your own projects.

Why GraphQL seems attractive

Let’s be honest: GraphQL’s appeal is far from superficial. When you first see a well-designed GraphQL API in action, it feels like magic. Imagine you’re building a dashboard that displays user profiles with their recent orders and reviews. With a traditional REST API, you might need three or four separate endpoints, carefully orchestrated on the frontend. With GraphQL, you simply write a query that exactly matches your data needs:

query {
  user(id: 123) {
    name
    recentOrders(last: 5) {
      amount
      status
    }
    reviews(last: 3) {
      rating
      content
    }
  }
}

This kind of flexibility makes frontend developers extraordinarily happy. They get precisely the data they need, no more and no less. No more wrangling multiple API endpoints or dealing with over-fetched data. No more adding backend endpoints every time the frontend needs a slightly different data shape.

The benefits seem to stack up quickly:

First, there’s the elegant solution to the chronic problem of over-fetching. Instead of receiving every field from your User model when you only need the name, you get exactly what you asked for. In a world where mobile data usage matters, this can seem like a compelling advantage.

Then there’s the development workflow. Frontend teams can work more independently, experimenting with different data requirements without needing constant backend changes. They can iterate faster, and the self-documenting nature of GraphQL schemas means they always know exactly what data is available.

The single endpoint approach also feels cleaner than maintaining dozens of REST endpoints. Rather than debating whether something should be its own endpoint or included in an existing one, you can just add it to your schema and let clients decide when to request it.

For teams juggling multiple frontend applications – perhaps a web app, a mobile app, and a partner API – GraphQL’s flexibility seems particularly appealing. Each client can request its own specific data shape without requiring custom endpoints.

These benefits are real, and they’ve driven GraphQL’s adoption at companies dealing with complex data requirements and multiple client applications. But as we’ll explore in the next section, implementing and maintaining these capabilities comes with significant costs that aren’t immediately obvious from the demos and documentation.

The real costs of GraphQL implementation

While GraphQL’s benefits shine in demos, its costs become apparent once you start implementing it in a real Rails application. Let’s look at what actually happens when you add GraphQL to your typical Rails app.

First, there’s the initial setup. Even with helpful gems like graphql-ruby, you’re looking at significant work to get started. Every model that needs to be exposed requires a new type definition:

module Types
  class UserType < Types::BaseObject
    field :id, ID, null: false
    field :name, String, null: false
    field :email, String, null: false
    field :orders, [Types::OrderType], null: false
    field :reviews, [Types::ReviewType], null: false
    
    def orders
      BatchLoader::GraphQL.for(object.id)
        .batch do |user_ids, loader|
          Order.where(user_id: user_ids).group_by(&:user_id)
            .each { |user_id, orders| loader.call(user_id, orders) }
      end
    end
  end
end

See that orders method? That’s handling N+1 queries, one of the first problems you’ll encounter. While Active Record makes it easy to includes(:orders) in a regular Rails controller, with GraphQL you’ll need to implement batch loading for every relationship. Tools like batch-loader help, but they add another layer of complexity to your codebase.

Authorization becomes more complex too. Instead of handling permissions in your controllers, you now need to think about field-level authorization:

module Types
  class UserType < Types::BaseObject
    field :email, String, null: false do
      authorize! :admin
    end
    
    def self.authorize!(role)
      raise GraphQL::UnauthorizedError unless context[:current_user]&.has_role?(role)
    end
  end
end

But the real maintenance burden comes from keeping your schema in sync with your models. Add a field to your User model? You’ll need to update the UserType. Add a new relationship? That’s a new type definition and possibly new batch loading code. What used to be handled automatically by Active Record now requires explicit schema updates.

Testing becomes more involved as well. Instead of testing REST endpoints that map cleanly to controller actions, you’re now testing queries and mutations that can touch multiple parts of your schema. A single query might need to verify authorization, resolve relationships, and handle errors across several types:

RSpec.describe "Users Query" do
  let(:query) do
    <<~GRAPHQL
      query($id: ID!) {
        user(id: $id) {
          name
          email
          orders {
            amount
          }
        }
      }
    GRAPHQL
  end

  it "returns user data with orders" do
    user = create(:user)
    create_list(:order, 3, user: user)
    
    result = MyAppSchema.execute(
      query,
      variables: { id: user.id },
      context: { current_user: create(:admin_user) }
    )

    # Now check the deeply nested response structure
    expect(result.dig("data", "user", "orders")).to be_present
    expect(result.dig("data", "user", "orders").length).to eq(3)
  end
end

Performance monitoring becomes trickier too. Instead of clear controller actions that map to specific business operations, you’re dealing with arbitrary queries that can access your data in countless ways. Tools like Scout or New Relic need extra configuration to make sense of GraphQL operations, and debugging production issues often requires more context to understand exactly what data was being requested.

The schema documentation, while automatic, needs constant attention. As your schema grows, keeping the documentation clear and useful becomes its own maintenance task. Unlike Rails’ REST conventions, which are widely understood, GraphQL schemas need to be carefully documented to be useful to client developers.

These costs compound over time. Each new feature adds complexity to your schema, each new relationship needs careful performance consideration, and each new team member needs to understand not just Rails conventions, but your specific GraphQL implementation choices.

Rails’ built-in solutions are often sufficient

One of Rails’ greatest strengths has always been its sensible defaults and conventional solutions. While these might seem boring compared to GraphQL’s flexibility, they often solve the same problems with significantly less complexity.

Let’s tackle the common problems that drive teams to GraphQL, and look at how Rails already solves them:

“But we need to avoid N+1 queries!”

Rails has had a solution for this since the beginning. Active Record’s eager loading is both powerful and easy to use:

def index
  users = User.includes(:orders, :reviews)
    .where(active: true)
    .limit(10)
  
  render json: users
end

“But we need flexible response shapes!”

Rails serializers have you covered. Using a gem like active_model_serializers or even just plain Ruby objects, you can create multiple representations of your data:

class UserSerializer < ActiveModel::Serializer
  attributes :id, :name
  
  attribute :full_data, if: :admin?
  has_many :recent_orders
  has_many :recent_reviews
  
  def recent_orders
    object.orders.last(5)
  end
  
  def admin?
    current_user.admin?
  end
end

“But we need to combine multiple resources!”

Rails controllers can handle this elegantly:

def dashboard
  user = User.includes(:orders, :reviews).find(params[:id])
  
  render json: {
    user: UserSerializer.new(user),
    recent_activity: ActivitySerializer.new(user.recent_activity),
    account_summary: AccountSerializer.new(user.account)
  }
end

“But what about caching?”

Rails’ caching is battle-tested and works great with JSON endpoints:

class OrdersController < ApplicationController
  def index
    orders = Rails.cache.fetch(["orders", params[:page]], expires_in: 1.hour) do
      Order.page(params[:page]).to_json
    end
    
    render json: orders
  end
end

“But we need versioning!”

Rails has conventional patterns for API versioning that are well understood:

module Api
  module V1
    class UsersController < ApplicationController
      # V1 implementation
    end
  end
  
  module V2
    class UsersController < ApplicationController
      # V2 implementation with new fields
    end
  end
end

“But our frontend needs different data shapes for different screens!”

Instead of one massive GraphQL schema, consider scope-specific endpoints that map to your UI needs:

module Api
  class UserProfileController < ApplicationController
    def show
      user = User.includes(:profile_data).find(params[:id])
      render json: UserProfileSerializer.new(user)
    end
  end
  
  class UserDashboardController < ApplicationController
    def show
      user = User.includes(:dashboard_data).find(params[:id])
      render json: UserDashboardSerializer.new(user)
    end
  end
end

The beauty of these Rails solutions isn’t just their simplicity – it’s that they compose well together and follow patterns that any Rails developer can understand. They leverage Rails’ performance optimizations, work seamlessly with the asset pipeline and caching, and integrate naturally with the rest of your Rails tooling.

Most importantly, these solutions scale with your application’s actual needs. Need more complex data fetching? Add a query object. Need more sophisticated caching? Rails’ caching framework can handle it. Need to optimize payload size? Use jbuilder or custom serializers to send exactly what you need.

Hidden operational costs

While we’ve discussed the technical implementation costs of GraphQL, there’s a whole category of operational costs that often go unconsidered until they hit your team in production. Let’s explore these hidden costs that can significantly impact your team’s velocity and operational efficiency.

The learning curve tax

Every new Rails developer knows what users_controller#show does. But drop a new developer into a GraphQL codebase, and they’re facing questions like:

# What's the difference between these again?
field :total, Integer, null: true
field :total, Integer, null: false
field :total, Integer  # Wait, what's the default?

# Why isn't this working?
def orders
  object.orders  # Oops, N+1 query!
end

# How do I handle authorization here?
field :secret_data, String do
  # Is this the right place for auth?
end

Even experienced Rails developers need time to become productive with GraphQL. This learning curve isn’t just about syntax – it’s about understanding resolver patterns, type systems, schema design, and performance implications. While your senior developers might pick it up quickly, you’re adding complexity for every new hire and junior developer.

The debugging tax

When something goes wrong in a REST endpoint, the debugging process is straightforward: check the logs, find the controller action, and follow the stack trace. With GraphQL, debugging becomes more complex:

# Your logs might show this query:
{
  user(id: "123") {
    orders {
      items {
        product {
          price
        }
      }
    }
  }
}

# But where's the N+1 query coming from?
# Is it in the orders resolver?
# The items resolver?
# The product resolver?

Your APM tools like New Relic or Scout need additional configuration to make sense of GraphQL operations. Stack traces become less helpful because the entry point is always your GraphQL engine. And good luck trying to quickly reproduce an issue when you need to reconstruct the exact query that caused it.

The documentation tax

With REST, your API documentation often follows naturally from your controller actions and serializers. With GraphQL, maintaining clear documentation becomes a constant task:

module Types
  class OrderType < Types::BaseObject
    field :status, String, 
      null: false,
      description: "Order status (pending, processing, shipped, delivered)"
    
    field :total, Integer,
      null: false,
      description: "Order total in cents"
      
    # Multiply this by every field in your schema...
  end
end

While GraphQL is self-documenting in theory, in practice you need to maintain descriptions, deprecation notices, and usage examples. This documentation needs to be kept in sync with your implementation, and it needs to be detailed enough for client developers to use effectively.

The testing tax

Testing complexity increases exponentially with GraphQL. Instead of testing discrete controller actions, you’re testing combinations of fields and resolvers:

# A simple REST controller test
RSpec.describe UsersController do
  it "returns user data" do
    get :show, params: { id: user.id }
    expect(response).to be_successful
    expect(json_response[:name]).to eq user.name
  end
end

# The equivalent GraphQL test
RSpec.describe Types::QueryType do
  let(:query) do
    <<~GQL
      query($id: ID!) {
        user(id: $id) {
          name
          orders {
            status
            items {
              product {
                name
                price
              }
            }
          }
        }
      }
    GQL
  end
  
  it "returns nested user data" do
    result = execute_query(query, variables: { id: user.id })
    # Now check the deeply nested response structure
    # Don't forget to test authorization at each level
    # And error handling
    # And N+1 query protection
  end
end

The production support tax

When production issues occur, the complexity of GraphQL makes them harder to diagnose and fix:

• Performance problems are harder to isolate because a single query might touch dozens of resolvers
• Error reporting becomes more complex because errors can occur at multiple levels of the query
• Capacity planning is trickier because client queries can be arbitrarily complex
• Query complexity limits and timeouts need careful tuning to prevent DOS vulnerabilities

Each of these costs might seem manageable in isolation, but they compound over time and across team size. A five-person team might handle these overhead costs, but as your team grows, these costs scale with each new developer, each new feature, and each new client application.

When GraphQL makes sense (and when it doesn’t)

After all this criticism of GraphQL, you might be wondering if there’s ever a right time to use it. The answer is yes – GraphQL can be the right choice, but the conditions need to justify its complexity.

When GraphQL might be worth the cost

You should consider GraphQL when your application has:

• Multiple, significantly different clients: If you’re building separate web, mobile, and partner API experiences that each need very different data shapes, GraphQL’s flexibility becomes valuable. GitHub is a perfect example – they serve their web UI, mobile apps, and third-party integrations all from the same GraphQL API.

• Complex, nested data requirements: If your frontend frequently needs to fetch deeply nested, interconnected data that would require multiple REST roundtrips, GraphQL can simplify this orchestration. Think social networks where you need user profiles, their posts, comments on those posts, and profiles of users who commented – all in one view.

• A large, dedicated API team: When you have the resources to properly maintain, monitor, and optimize a GraphQL implementation, its benefits become more achievable. Companies like Shopify can justify GraphQL because they have teams dedicated to their API infrastructure.

When to skip GraphQL

Stick with Rails’ conventional REST API patterns when:

• Your application is primarily CRUD: If most of your endpoints map cleanly to resource actions (create, read, update, delete), REST already handles this perfectly. Adding GraphQL would be overengineering.

# This is all you need for most cases
resources :orders do
  resources :line_items
  member do
    post :refund
    post :ship
  end
end

• Your data shape is relatively stable: If your frontend needs aren’t constantly changing and you don’t have radically different client requirements, REST endpoints with well-designed serializers will serve you well.

• You have a small to medium team: If you can’t dedicate significant engineering resources to GraphQL infrastructure, the maintenance burden will likely outweigh the benefits.

Making the decision

Before adopting GraphQL, ask yourself:

1. Can Rails’ built-in tools solve our current problems?
2. Do we have the engineering resources to properly implement and maintain GraphQL?
3. Are our API requirements complex enough to justify the overhead?
4. Have we measured the actual performance impact of our current REST implementation?

Remember, you can always start with a REST API and add GraphQL later if needed. Many teams have found success with a hybrid approach – using REST for simple CRUD operations and GraphQL for more complex data requirements.

Final thoughts

GraphQL isn’t bad technology – it’s just often misapplied. For many Rails applications, the conventional REST approach, combined with thoughtful use of Rails’ built-in tools, provides a simpler, more maintainable solution. Before jumping on the GraphQL bandwagon, make sure its benefits truly outweigh its considerable carrying costs for your specific use case.

🔍 In software development, simpler solutions tend to lead to happier teams and more maintainable codebases in the long run. Sometimes the “boring” solution is exactly what your application needs.

Introduction: Organizing Your Tools

Ever notice how the messiest parts of your code are often where you’re handling different cases or variations? Maybe it’s different file formats, payment methods, or shipping calculations. That’s exactly what we’re going to tackle today with one of the most practical object-oriented design principles: ‘Encapsulate what varies.’

Think of it like organizing your tools. Instead of having screwdrivers and wrenches scattered throughout the shop and house, you put them all in one toolbox. Now, when you need to change or add a tool, you know exactly where to go. That’s what we mean by encapsulation in code – taking the parts that might change and putting them in a well-defined place. Okay, yes. There is that one screwdriver that always ends up in the kitchen drawer, but sometimes a little duplication is better than an unhappy spouse.

In this article, we’ll look at how this principle can transform messy, hard-to-maintain code into something clean and flexible. I’ll show you real examples in Ruby, and by the end, you’ll have a new tool for keeping your code organized and easy to change.

The Core Principle Explained

Encapsulate what varies is all about isolating the parts of your code that might change. It’s a simple idea, but it can have a big impact on how you structure your code. By putting the things that vary in one place, you make your code more flexible and easier to maintain.

Imagine you’re working on an woodworking platform that sells many types of dressers. Each dresser can be of a different type and have a different assembly process for one kind of dresser. If you scatter these variations throughout your code, or conflate them with other code you’ll end up with a tangled mess that’s hard to understand and change.

By encapsulating what varies, you can isolate these differences in one place. This makes your code easier to read, test, and extend. When you need to add a new dresser type or change the assembly logic, you know exactly where to look.

A Practical Example

🔍 In this post, we’ll use Ruby 3.1 for code examples with endless methods for brevity, but the principles here apply to any object-oriented language.

Here’s a simple example to illustrate the concept. Suppose you have a class that builds a dresser based on the dresser type. You could write a single method that handles all these variations:

class DresserBuilder
  def self.construct(type)
    case type
    when :armoire
      dresser = Armoire.new
    when :highboy
      dresser = Highboy.new
    when :bombe
      dresser = Bombe.new
    else
      raise ArgumentError, "Unknown dresser type: #{type}"
    end

    dresser.select_wood
    dresser.cut_pieces
    if type == :armoire
      dresser.join_traditionally
    else
      dresser.join_with_screws
    end
    dresser.finish

    puts "Dresser built!"

    dresser
  end
end

# Usage
armoire = DresserBuilder.construct(:armoire)
# => Dresser built!

This code works, but it’s not very flexible. What if you need to add a new dresser type or change the assembly process for one kind of dresser? You’d have to modify this method, which violates the Open/Closed Principle of SOLID.

Let’s apply the ’encapsulate what varies’ principle to this code. We’ll create a separateDresserFactory class to handle the creation of different dresser types. This class will encapsulate the choice of dresser type and return the appropriate dresser object:

class DresserFactory
  def self.make(type)
    case type
    when :armoire
      Armoire.new
    when :highboy
      Highboy.new
    when :bombe
      Bombe.new
    else
      raise ArgumentError, "Unknown dresser type: #{type}"
    end
  end
end

class DresserBuilder
  def self.construct(type)
    dresser = DresserFactory.make(type)

    dresser.select_wood
    dresser.cut_pieces
    if type == :armoire
      dresser.join_traditionally
    else
      dresser.join_with_screws
    end
    dresser.finish

    puts "Dresser built!"

    dresser
  end
end

# Usage
armoire = DresserBuilder.construct(:armoire)
# => Dresser built!

Now we can easily add new types without modifying the Dresser class. This is better, but what if the assembly process varies between dresser types? You’d have to modify the Dresser class again.

Strategy Pattern

Let’s take it a step further and use the Strategy pattern to encapsulate the assembly process in separate classes. This way, each dresser type can have its own assembly logic, and we can easily change that without changing the Dresser class:

class DresserFactory
  BLUEPRINTS = {
    armoire: Armoire,
    highboy: Highboy,
    bombe: Bombe
  }.freeze

  def self.make(type)
    BLUEPRINTS.fetch(type) { 
      raise ArgumentError, "Unknown dresser type: #{type}"
    }.new
  end
end

module Assembleable
  def assemble = raise NotImplementedError
end

class AbstractDresser
  include Assembleable
end

class Armoire < AbstractDresser
  def assemble
    select_wood
    cut_pieces
    join_traditionally
    finish_with_lacquer
  end

  private

  def select_wood = puts "Selecting wood for armoire"
  def cut_pieces = puts "Cutting pieces for armoire"
  def join_traditionally = puts "Assembling armoire traditionally"
  def finish_with_lacquer = puts "Finishing armoire with lacquer"
end

class DresserBuilder
  def self.construct(type)
    dresser = DresserFactory.make(type)
    dresser.assemble

    puts "Dresser built!"

    dresser
  end
end

# Usage
armoire = DresserBuilder.construct(:armoire)
# => Selecting wood for armoire
# => Cutting pieces for armoire
# => Assembling armoire traditionally
# => Finishing armoire with lacquer
# => Dresser built!

Now, each dresser type has its own class, and the Dresser class delegates the assembly process to the appropriate type. We’ve also taken this opportunity to update the DresserFactory class to trade the case statement for a hash of blueprints for each dresser type. This way, adding a new type is as simple as adding a new entry to the hash.

Common Patterns That Apply This Principle

The ’encapsulate what varies’ principle is closely related to several design patterns that help you manage change in your code. Above, we used the Strategy pattern to encapsulate the assembly process for different dresser types and the Factory Method pattern to create instances of these types.

Tips for Identifying Varying Elements

When applying the ’encapsulate what varies’ principle, it’s essential to identify the parts of your code that are likely to change. Here are some tips to help you spot these elements:

• Look for conditional logic: If you have a lot of if statements or case blocks that handle different cases, those are good candidates for encapsulation.
• Think about future requirements: Consider what might change in the future and how you can isolate those changes.
• Separate concerns: If you have different concerns mixed together in one class or method, try to separate them into distinct components.
• Code analysis: Use tools like static code analysis or code reviews to identify parts of your code that change frequently.

Common Pitfalls

While the ’encapsulate what varies’ principle is a powerful tool for managing change, there are some common pitfalls to watch out for:

• Overengineering: Don’t go overboard and create unnecessary abstractions. Keep it simple and refactor only when it makes sense.
• Premature optimization: Don’t try to predict every possible change upfront.
• Ignoring SOLID principles: Remember that encapsulation is just one part of good object-oriented design. Make sure your code follows other principles like the Single Responsibility Principle and the Open/Closed Principle.
• Not testing variations: When you encapsulate what varies, make sure to test each variation thoroughly. It’s easy to introduce bugs when you refactor code, so testing is crucial.

Keep these pitfalls in mind as you apply this principle in your code. With practice, you’ll get better at identifying the parts that might change and encapsulating them effectively.

Conclusion

The ’encapsulate what varies’ principle is a powerful tool for managing change in your code. By isolating the parts that are likely change, you make your code more flexible, maintainable, and testable. Whether you’re working on an e-commerce platform, a game engine, or a woodworking platform, this principle can help you keep your code organized and easy to extend.

And yes, sometimes that screwdriver will still end up in the kitchen drawer, but sometimes that’s just where it needs to be to maintain household harmony.

🔍 This post is part of the SOLID++ series where we are exploring principles of object-oriented design beyond the five SOLID principles.