I wanted the absence of a photo to say something. Not “loading,” not “TODO,” but a piece of the site’s voice that’s interesting in itself. Something deterministic, so the same workshop entry always renders the same art, and themed, so a paint tile reads differently from a 3D-print tile.

Below this post is the playground. Type a seed, pick a kind, hit shuffle, same machinery the workshop tiles use.

What I rejected

I started with static SVG riso, two-color silkscreen with offset duplicates and a grain pattern. It was the cleanest thing to build (pure functions, build-time, zero runtime JS, theme-aware via CSS variable cascade) and I had a working version inside an afternoon.

It looked polluted. Every tile carried the same dot grain. The shapes were too small. Cropping at varying tile aspects produced the worst of both worlds, a tiny silhouette stranded in a sea of paper. The signature was everywhere, which meant nowhere.

So I researched the alternatives and asked two questions: what visual register do I actually want, and what’s the smallest tool that gets me there.

Canvas2D won. The “polluted” feeling from the SVG attempt wasn’t the medium, it was loose rules. Hand-rolled gives stricter rules for free.

What ended up working

Each kind of tile gets its own composer function: compose3d, composeLaser, composePaint, etc. The composer takes the tile’s actual (width, height) and lays out a multi-element scene that fills it. No fixed reference frame, no “scale this 500-unit illustration to fit min(w,h)”, that’s what produced the postage-stamp problem.

The 3D-print tile is a parametric city of isometric boxes scattered across the tile. Laser is a blueprint with a grid + central machine drawing. Paint is overlapping painterly smears with brush marks. Each kind picks a fixed five-token palette, [outline, mid-dark, accent, accent, lightest], so all paint tiles read clay-on-paper, all wood tiles read deep-red on paper, the workshop type is the visual identity.

Determinism is a tiny PRNG (xmur3 hash → sfc32 stream, ~30 lines, public-domain). Same slug → same float sequence → same composition. Adding a new workshop entry produces new art automatically; renaming an entry produces different art (intentional, the slug is the identity).

Theme awareness is getComputedStyle(document.documentElement).getPropertyValue('--clay'). When the user hits T to toggle workshop / editorial / dark, the canvas re-paints with the freshly resolved tokens. Same seed, same composition, different colors.

Things I had to fight

Aspect ratio. First pass scaled everything by min(w, h) and centered. Worked for square tiles, looked terrible on wide hero strips and tall span-2 cells. Fixed by passing (w, h) directly to each composer and letting it decide how to fill, some kinds (laser grid, wood grain) bleed full-frame, some (cube) stay roughly square but use the room for spacing, some (filmstrip vertical bars) span all the way across.

Theme retint without flicker. The canvas paints whatever color the tokens currently resolve to. Before the script runs, the canvas is empty, there’s a CSS class (kind-laser etc.) on the canvas that paints a sensible bg color in the meantime. SSR-safe: no JS, the right base color shows through, then on requestAnimationFrame the script paints over it.

TypeScript-strict + tuple indexing. Palette is a readonly [string, string, string, string, string]. Static index p[0] is string. Computed index p[i] is string | undefined under noUncheckedIndexedAccess. Solved by i % 3 === 0 ? p[1] : i % 3 === 1 ? p[2] : p[3], verbose, but no as casts and no helper. Worth the trade.

The architecture

src/lib/generative/
  seeded.ts     PRNG (xmur3 → sfc32)
  canvas.ts     Composers + paint() + paintFromElement()
  index.ts      Barrel
src/ui/
  Generative.astro     <canvas> + script + theme:toggle listener
  GenerativeLab.astro  Interactive playground (you're looking at it below)

paint() is pure. It takes a CanvasRenderingContext2D, dimensions, seed, kind, and palette and returns nothing. paintFromElement() is the DOM glue: reads data-seed and data-kind from the canvas, resolves the palette via getComputedStyle, calls paint(). The whole engine is around 500 lines including comments.

GenerativeLab is the same engine wired to inputs. It’s a DS leaf, the same component is listed on /design-system and embedded here in this post via the writing-post demo: frontmatter slot.

What I learned

Hand-rolling beats picking a library when the use case is small and the visual contract is yours. d3 / paper / three would all have worked. None of them would have been fewer lines than what I wrote, and I’d have inherited their priors about what “art” looks like. Canvas2D is just a drawing surface, no priors, no overhead.

The thing that fixed the “polluted” feel wasn’t switching from SVG to Canvas. It was committing to strict per-kind rules, bigger shapes, bleed off the frame, fixed palette per kind, no universal grain overlay. The SVG version with those rules would have looked fine too. The medium was a rounding error; the rules were everything.

Play

Type a seed, pick a kind, hit shuffle. Toggle the site theme (T key, or the panel bottom-right) and watch the art retint without a re-render of the page.

It’s not a bug

The rule is older than CSS-the-spec. Print typography has worked this way for centuries: when two block-level elements meet vertically, the larger of their two surrounding margins wins. The smaller one is absorbed.

This makes sense if you think of margin not as space I want around me but as the minimum distance I require from my neighbour. Two elements both saying “I want 32px of breathing room” don’t need 64px between them, they need 32px, and they both get what they asked for.

When it breaks

The rule breaks when a parent’s margin starts to collapse with its first child’s margin. You add a wrapper, the wrapper has no padding, and suddenly the child’s margin-top punches a hole through the parent and pushes the parent down.

Three escape hatches, in increasing order of weight:

1. padding-top: 1px on the parent. Cheap and ugly.
2. display: flow-root on the parent. The newest, cleanest answer.
3. A flex or grid container. Margin collapse doesn’t happen inside flex/grid, period.

I default to flow-root now. It’s a one-line opt-out with no layout side-effects.

The thing I keep forgetting

margin-block is the logical-property version. margin-block-start and margin-block-end collapse exactly the same way margin-top and margin-bottom do, but the rule still confuses my brain because the names don’t say “vertical” anymore. RTL languages still get vertical collapse on the block axis. Nothing changes, but the mental model has to update.

Redbooth’s Scrum Poker Cards — a set of beautifully illustrated planning poker cards. Each card has an idiom matching the effort: “Piece of cake” for 2, “Here be dragons” for the unknown, “Monster task” for 100. They even had a platypus for 5, because ornitorinco rhymes with cinco in Spanish.

The repo was just SVGs and a README. I starred it, forked it, and forgot about it.

The idea that wouldn’t die

Every few months I’d see the repo in my GitHub profile and think: “These cards should be a real app.” Then I’d close the tab and do something else.

Last week I ran out of excuses. I wanted to:

• Play with WebSockets — specifically PartyKit, which runs on Cloudflare Workers
• Try PostHog — anonymous analytics without the Google Analytics guilt
• Deploy something on Cloudflare Pages — been using it for static sites, never for a real app
• Build with Claude Code — see how far AI pair programming goes on a greenfield project
• Ship something I’d actually use — my team does sprint planning every two weeks

Yes, there are 200 planning poker tools already. I don’t care. I’m building for fun.

What I built

scrumpoker.work — a free, real-time planning poker app with the original Redbooth card illustrations.

The basics work:

• Create a session, get a shareable URL
• Anyone joins by entering their name — no accounts
• Pick a card, host reveals, see results with stats
• Sessions are ephemeral — nothing stored anywhere

The fun parts:

• When you select a card, the idiom floats up like you’re calling it out: “Here be dragons!”
• Vote reveal shows contextual messages: “Ship it! 🚀” when everyone agrees, “We have absolutely no idea 🤯” when votes spread from 1 to 100
• Confidence toggle — vote 8 with “confident” vs vote 8 with “no idea” tells the team very different things
• Outlier detection — if you vote 13 when everyone else voted 3, the app asks “why?”
• Topic queue — host adds stories upfront, team votes through them in order

The tech stack

PartyKit is the interesting one

I’ve built WebSocket servers before — with Socket.io, with raw ws, even with Durable Objects directly. PartyKit abstracts all of it into something that feels like writing a React component.

One class. onConnect, onMessage, onClose. Room state lives in memory. Broadcasting is a for-loop. The whole server is one file, ~300 lines, handling:

• Player join/leave with stable identity (UUID in localStorage)
• Vote collection and reveal
• Host management and transfer
• Topic queue navigation
• Kick with confirmation
• Auto-reveal when all players vote
• 5-second grace period for reconnection (tab switch, reload)

Deploy is npx partykit deploy. That’s it. It runs on Cloudflare’s edge globally.

The reconnection problem

The hardest part wasn’t the features — it was handling reconnections. When a user reloads their browser, their WebSocket connection dies and a new one opens. Every user has a connection ID that changes on reconnect. If you use the connection ID as identity (like I did initially), the server thinks it’s a new player every time.

I went through 5 iterations:

1. Name matching (fragile — what about duplicate names?)
2. Grace periods with name lookup (race conditions)
3. “Replaced” messages to old tabs (infinite reconnection loops)
4. BroadcastChannel for tab coordination (helped, but didn’t fix the root)
5. Stable UUID in localStorage — the actual fix

The final approach: each browser gets a UUID stored in localStorage. The server maps stableId → player, not connectionId → player. Reconnects silently swap the socket. Other users see nothing. Tab switches use BroadcastChannel to coordinate which tab owns the connection.

Should have done this from the start. The lesson: your player identity should never be your transport identity.

Building with Claude Code

I built 90% of this with Claude Code in a single session. Not as a party trick — as genuine pair programming.

What worked well:

• Parallel agents — “create the server, the components, and the pages” in one message, three agents working simultaneously
• Iterating on UI — “the cards are cut by the container” → immediate fix with explanation
• Feature brainstorming — I pasted 10 feature ideas from a ChatGPT conversation, we evaluated each one together, picked 3 to build
• The boring stuff — SEO meta tags, schema markup, legal pages, robots.txt, sitemap — all generated correctly in parallel

What needed correction:

• First build had no card illustrations — the Card component never loaded the SVGs
• WebSocket host fallback used ?? instead of || — empty string is truthy
• Initial player identity used connection IDs (see reconnection saga above)
• Several as casts that violated my strict TypeScript rules

The pattern: Claude Code is great at generating the 80% and iterating on feedback. The 20% where it guesses wrong, you catch by testing. Having strict TypeScript and a tsc -b check after every change caught most issues before they reached the browser.

Numbers

• 26 commits in one session
• ~4,500 lines of code (including server)
• 14 illustrated cards from the original Redbooth set
• 5 card presets (All, Fibonacci, Simple, T-Shirt, Powers of 2)
• 0 databases — everything ephemeral
• 685KB JS bundle — needs code splitting, but works
• $0/month to run — Cloudflare Pages free tier + PartyKit hobby tier

What’s next

The TODO list has ideas parked:

• Code splitting to reduce bundle size
• Dark mode
• Sound effects (optional)
• Silent poker (multi-round bias reduction)
• Import topics from Jira/Linear
• i18n (Portuguese, Spanish)

But honestly? It works. My team can use it next sprint. That’s enough.

Try it

scrumpoker.work — create a session, share the link, estimate some stories.

Source code: github.com/letanure/Scrum-poker-cards

The card illustrations are CC BY 3.0 by Redbooth. Thank you for making them — 7 years later, they’re finally in a real app.

Why it matters

A keyboard-driven, fuzzy-searchable, command-runnable surface collapses three different UI patterns into one:

1. Navigation (where can I go?)
2. Search (what is here?)
3. Action (what can I do?)

When all three live in the same input, users stop context-switching between mouse and keyboard.

What “feels instant” means

Try the demo embedded in the live post (lands with chunk 1.4). The sweet spot for input → result rendering is under 100ms. Past that, you can feel the lag. Past 200ms, you start typing again.

How to build one that doesn’t suck

(…rest of post…)

130 skills. I could not remember 10 of them.

The real problems

Overlap. Three different skills triggered when I said “review this PR.” Project commands, personal skills, and a plugin — all doing roughly the same thing. Claude picked one. Sometimes the wrong one.

No organization. Some skills are global (my writing voice). Some are project-specific (test patterns for a monorepo). Some are useful only for personal projects (SEO, marketing). They were all loaded everywhere, all the time.

New machine = amnesia. My skills lived in ~/.claude/skills/, my commands in ~/.claude/commands/, plugins were installed manually. No way to reproduce the setup on another machine. No way to remember what I had.

Context waste. Every skill description sits in Claude’s context, every session. 25 marketing skills loaded while I was writing code at work. That is wasted tokens doing nothing.

What I wanted

1. One repo, one command, full Claude Code setup on any machine
2. Global skills that work everywhere
3. Per-project profiles that suppress irrelevant skills
4. Vendor skills from other developers without copy-pasting
5. A way to find the right skill for the task

The solution: a setup repo

Everything lives in one private git repo. Symlinked into ~/.claude/ so Claude discovers it automatically.

claude-setup/
  skills/              → symlinked to ~/.claude/skills/
    me:write-like-me/
    me:commit.md
    me:linear-issue.md
    me:toolkit/
  commands/            → symlinked to ~/.claude/commands/
  vendor/
    mattpocock-skills/ → git submodule
  vendor.json          → which vendor skills to enable
  plugins.json         → which plugins to install
  toolkit.default.json → task-to-skill mapping
  manual-checklist.md  → things that need manual setup
  setup.sh             → THE one command

New machine:

git clone --recursive git@github.com:you/claude-setup.git
cd claude-setup
./setup.sh

The script symlinks skills and commands, initializes vendor submodules, checks which plugins are installed, and prints a checklist for everything it can not automate (MCP servers, API keys).

Naming: know what is yours

With 130 skills from 8 sources, I could not tell which were mine, which came from plugins, which were vendor skills.

Prefixes fixed this:

Now when I see me:write-like-me vs superpowers:brainstorming vs marketing-skills:seo-audit, I know exactly where each comes from.

Vendor skills without copy-pasting

I wanted to use skills from other developers, but not copy files. Git submodules solved this.

vendor.json controls which skills get symlinked and what prefix they use:

{
  "mattpocock/skills": {
    "path": "vendor/mattpocock-skills",
    "prefix": "mapo",
    "enabled": [
      "write-a-prd",
      "prd-to-issues",
      "improve-codebase-architecture",
      "request-refactor-plan"
    ]
  }
}

setup.sh reads this and creates symlinks like mapo:write-a-prd pointing to the submodule. Update vendor skills with git submodule update. Enable or disable one by editing the list.

Per-project profiles: the toolkit skill

The biggest win. A skill called me:toolkit that maps tasks to the right skill based on where you are.

Two profiles: work and personal. Each project gets a .claude/toolkit.json (gitignored) that tells Claude which profile to use and what to suppress.

{
  "profile": "work",
  "project": "bunch-platform",
  "suppress": ["marketing-skills:*", "mapo:obsidian-vault"],
  "overrides": {
    "test": ["/test (project command)"],
    "start a task": ["/task (project command)"]
  }
}

When I open Claude in a work repo, marketing skills are suppressed. When I open a personal project, everything is available.

Running /me:toolkit setup in a new project scans package.json, git remote, and existing .claude/commands/ to suggest the right profile automatically.

Running /me:toolkit shows the task map: “want to create an issue? use me:linear-issue. Want to plan a feature? start with mapo:write-a-prd.”

Skill size matters

Skills eat context when loaded. A 200-line skill burns tokens every time you invoke it.

The rule I follow now:

The main skill file is a router. Core rules and a quick reference table. Deep context per medium, examples, extended patterns — all in references/ files that Claude reads only when needed.

A Slack message uses 76 lines of context. A blog post uses 76 + the blog guide reference. Progressive loading, not a wall of instructions.

Health checks

A SessionStart hook runs check-links.sh every time Claude starts. If symlinks are broken (repo moved, submodule not initialized), it warns you immediately.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "$HOME/.claude/hooks/check-setup.sh",
        "timeout": 5
      }]
    }]
  }
}

Silent when healthy. Warns when something is wrong.

What I would do differently

Start with fewer skills. I installed everything, then had to clean up. Better to add skills as you hit real needs.

Name from the start. The me: prefix convention would have saved confusion if I had it from day one.

Profile early. Suppressing marketing skills in work repos should have been the default. 25 skill descriptions in context for no reason.

Template repo

I am working on a public template version of this setup — no personal skills, just the structure, scripts, and config format. Fork it, add your skills, run setup.sh.

What is next

• Test the toolkit routing in real projects for a few weeks
• Add vendor skills from Vercel (react-best-practices, composition-patterns) and Google Labs (shadcn-ui)
• Explore whether Claude Code will add native skill scoping per project — that would replace the toolkit suppress hack
• Build a voice maintenance skill that periodically checks if my writing skill still matches how I actually write

If you are drowning in Claude Code skills and can not find the one you need, the problem is not the skills. It is the organization. Fix that first, then add more.

It’s been a quietly transformative rule.

What useEffect is for

Effects exist to synchronise React’s render output with something outside of React: the DOM (focus management, scroll position), the network (subscriptions, polling), the platform (timers, observers). If the thing you’re synchronising lives inside React’s own world, state, props, context, then the synchronisation should happen during render, not after it.

What it’s not for

The list of things useEffect is not for, but is constantly used for:

• Computing derived values from props. Just compute them in the render body.
• Resetting local state when a prop changes. Use a key prop on the parent.
• Caching expensive calculations. Use useMemo. Or don’t, most calculations aren’t expensive.
• Calling a function “when the component renders”. A render is the function being called. You’re asking for a callback after the call you just made.
• Keeping two pieces of state in sync. One of them is redundant. Delete it.

Why it matters

Each useEffect has a hidden cost: it adds a moment in time after render where the world is almost consistent but not quite. You set state in an effect; the user sees the wrong thing for a frame; the effect fires; the component re-renders; now it’s right.

Multiply by ten effects in a deep tree and you have a UI that flickers in subtle, uncatchable ways. The bug report says “sometimes the X is wrong for a moment”. The cause is six useEffect calls deep in a component tree, each waiting one render cycle to update the next.

The fix is usually deletion

The most common fix when I find a misused useEffect is to delete it entirely and move the logic into the render body. That feels wrong, surely something has to happen “after”?, but it’s almost always right. The render body runs every render. State changes already trigger re-renders. There’s no missing step.

A fire alarm should ring when there’s a fire. Most of what we use it for is a kettle boiling.

Ask any AI to build you a UI and you’ll get Tailwind. Every single time. className="flex items-center justify-between p-4 rounded-lg shadow-md bg-white dark:bg-gray-800" — you know the drill.

There’s nothing wrong with Tailwind. But I wanted to go the other direction. What if the component library was just CSS? No React. No Vue. No runtime. A single CSS file you drop into any project and suddenly you have buttons, forms, cards, modals, everything.

So I started building one. Mostly for fun, partly to learn, and a little bit because I think the idea has legs.

The Pitch

The core idea: build the visual layer once in pure CSS, then reuse it everywhere. Want React components? Wrap the classes. Vue? Same classes, different wrapper. Angular, Svelte, htmx, plain HTML? Same CSS file, same classes.

<button class="ui-button ui-button--primary">Click me</button>

That works today in every framework that exists and every framework that will exist next year.

But I didn’t want just a bag of utility classes. I wanted real components with a structured API — modifiers, elements, tokens, documentation, visual tests. Something that feels like a proper design system, not a stylesheet.

How I Got to Cascade Layers

I started the way most people would: reset at the top, base styles, then components, then utilities. Classic ITCSS triangle. But ITCSS manages priority through selector specificity, and specificity is a nightmare at scale. You end up writing increasingly specific selectors just to override something simple.

CSS Cascade Layers fix this. One line declares the priority order:

@layer reset, tokens, base, primitives, components.styles, components.tokens, utilities, themes;

Done. Utilities always beat components. Themes always beat utilities. No specificity wars, no !important. The architecture emerged naturally from ITCSS but with modern tools doing the heavy lifting.

The Theme Problem

Here’s what I’m really trying to solve: most component libraries bake in a visual identity. Material UI looks like Material UI. Mantine looks like Mantine. You can tweak colors, sure, but the bones are recognizable.

I want the same code to produce completely different visual outputs. Material’s rounded buttons or sharp corporate ones. Spacious layouts or dense data-heavy interfaces. All driven by tokens, not by rewriting components.

Every component uses a three-tier fallback:

var(--ui-button-height, var(--ui-row-2, #{t.$row-2}))

Override the component token for one button. Override the global token for all buttons. Or do nothing and get sensible defaults. Swap a theme file and the whole library transforms.

That’s the goal, at least. Early days.

What’s Actually Built

60+ components across the usual categories — buttons, forms, cards, tables, modals, navigation. 16 layout primitives for common page structures. Utility classes for spacing, display, text.

Some things I’m proud of:

• Drop a folder, get a component. Create the files in the right directory and the build system discovers it, compiles it, generates docs, adds it to the site. No registration, no config.
• Visual regression tests in Docker. Every component has a Playwright screenshot test. Change a token and you see exactly what breaks before merging.
• Linters that enforce the architecture. Hardcoded a color value? The linter catches it. Used a token without a fallback? Caught. Put a global token in the wrong layer? Caught.

What’s Not Great

The learning curve is real. The token system has three layers, components split across two cascade layers, there’s BEM naming, logical properties, SCSS variables. It’s a lot to hold in your head for a first contribution.

No JavaScript. A toggle switch looks right but doesn’t toggle. A dropdown renders beautifully but doesn’t open. The CSS handles appearance; you wire up behavior. Framework wrappers will solve this eventually, but they don’t exist yet.

Docs are verbose. Documentation is driven by JSON config files, which is great for consistency and terrible for writing speed.

Why Bother?

Honestly? It’s fun. I’m learning a ton about cascade layers, modern CSS features, token architecture, and what it takes to build something that scales to 60+ components without turning into a mess.

Will it be useful to anyone else? Maybe. The framework-agnostic angle is genuinely appealing. CSS doesn’t break between major versions. It doesn’t need migration guides. It just works.

And if nothing else, next time an AI suggests Tailwind, I’ll have an alternative ready.

That was a mistake. INP measures something FID never could: how long your whole interaction took, not just how long the browser took to start handling it.

What INP measures

For every click, tap, or key press during a session:

1. The browser starts a clock.
2. Your event handler runs.
3. Eventually the browser paints whatever you changed.
4. The clock stops.

The 75th-percentile longest interaction across the session is your INP.

Why FID was misleading

FID only measured the gap between input and handler start. If your handler took 800ms, then the browser took another 200ms to paint, FID would report 0ms, because the handler started immediately. The user waited a full second.

INP catches the entire delay, which is what the user experiences. A 200ms threshold for “good” is generous in this framing, anything above that and the UI feels sluggish.

What to actually do

A practical workflow:

1. Find the slowest interactions in your real user data (Chrome’s Web Vitals extension, RUM tools).
2. Profile the worst one. The flame graph almost always shows one of: a sync layout thrash, a long-running event handler, or a cascade of React re-renders that each scheduled the next.
3. Break the work into chunks. Yield to the browser between them. scheduler.yield() is now the right tool; before it landed, setTimeout(0) was the workaround.
4. Move work off the interaction path entirely where possible. The user clicks, you optimistically update, you do the real work in the background.

The thing I keep saying

Most slow interactions aren’t slow because of the thing the user clicked on. They’re slow because the click handler kicked off a render that kicked off a layout that kicked off another render that finally painted. The fix is rarely “make this part faster”, it’s “do less of this on the interaction path”.

So, this came up in an interview recently: there was a single slow component I was not allowed to change. I fixed it with a quick React.memo wrap during the interview, but later I thought, hey, why stop there? Let me share how I handled it and some other ways to tackle this problem.

TL;DR

Got a slow component that’s freezing your app? Can’t touch its code? Here’s your survival kit:

• React.memo - Stop pointless re-renders when props haven’t changed
• State isolation - Move the slow stuff away from your fast UI
• Lazy loading - Make it someone else’s problem (later)
• useDeferredValue - Let users type while the slow component catches up
• Nuclear options - iframe, web worker, or virtual scrolling when all else fails

Try the solutions yourself in the sandbox below

Open in CodeSandbox

The Problem

There’s a slow component I can’t change. My job is to keep the UI responsive while it exists on the page.

Goals:

• Keep typing fast.
• Avoid re-rendering the slow component on every keystroke.
• Improve initial load if possible.

function App() {
  const [value, setValue] = React.useState("");
  return (
    <div>
      <input value={value} onChange={(e) => setValue(e.target.value)} />
      <VerySlowComponent />
      <span>Length: {value.length}</span>
    </div>
  );
}

We cannot edit <VerySlowComponent />. Everything else is fair game.

Solutions

1. React.memo (quick win)

Wrap your slow component in React.memo to tell React, “Hey, only re-render me if my props actually change.” This works great as long as you don’t pass any changing props. It’s like putting a “Do Not Disturb” sign on your component’s door.

const SlowComponent = React.memo(function SlowComponent({ data }) {
  const result = heavyCalculation(data);
  return <div>{result}</div>;
});

Now, SlowComponent chills and only wakes up when data changes, not every time unrelated state updates happen. Nice!

2. Isolate State

Move stateful input into a separate subtree so the slow component never re-renders. Keep the input and its state in a different branch; render the slow part as a sibling, memoized. No props flow from the input to the slow component, so it stays idle.

// Isolate state in a sibling subtree
import { memo, useState } from "react";

const MemoSlow = memo(VerySlowComponent);

function FastPanel() {
  const [value, setValue] = useState("");
  return (
    <>
      <input value={value} onChange={(e) => setValue(e.target.value)} />
      <div>Length: {value.length}</div>
    </>
  );
}

function App() {
  return (
    <div style={{ display: "grid", gap: 12 }}>
      <MemoSlow />
      <FastPanel />
    </div>
  );
}

Because the FastPanel’s state changes don’t flow into MemoSlow, the slow component never re-renders.

3. Lazy Load the Slow Component

Why load the slow component right away if you don’t need it? Use React.lazy and Suspense to load it only when you want it (saving your app from feeling sluggish at startup).

const SlowComponent = React.lazy(() => import("./SlowComponent"));

function App() {
  const [show, setShow] = React.useState(false);

  return (
    <>
      <button onClick={() => setShow(!show)}>Toggle Slow Component</button>
      <React.Suspense fallback={<div>Loading...</div>}>
        {show && <SlowComponent />}
      </React.Suspense>
    </>
  );
}

This way, your app loads faster and only asks the slow component to join the party when needed. This does not stop re-renders later; it improves first paint.

4. Defer Non-Urgent Updates

Another option is to defer updates so typing stays smooth. In this example, we still render the slow component but lazy load it, and pass in the input value. Typing stays responsive while the slow part shows up with a loading fallback.

import { Suspense, lazy, useState } from "react";

const Slow = lazy(() =>
  import("./shared/VerySlowComponent").then((m) => ({
    default: m.VerySlowComponent,
  }))
);

function App() {
  const [value, setValue] = useState("");

  return (
    <div style={{ display: "grid", gap: 8 }}>
      <input
        placeholder="Type something"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
      <Suspense fallback={<p>Loading slow part…</p>}>
        <Slow query={value} />
      </Suspense>
      <div>Length: {value.length}</div>
    </div>
  );
}

This way you keep the input responsive, get a nice loading state, and still handle the slow component without blocking typing.

5. Defer with useDeferredValue and useTransition

React 18 gives us concurrent features to mark updates as non-urgent. With useDeferredValue and useTransition, you can keep typing responsive while slow components update a bit later.

import { useState, useDeferredValue, useTransition } from "react";
import { VerySlowComponent } from "./shared/VerySlowComponent";

export default function DeferTransition() {
  const [value, setValue] = useState("");
  const deferred = useDeferredValue(value);
  const [, startTransition] = useTransition();

  return (
    <div>
      <input
        value={value}
        onChange={(e) => {
          const v = e.target.value;
          startTransition(() => setValue(v)); // mark as non-urgent
        }}
      />
      <div>Length (deferred): {deferred.length}</div>
      <VerySlowComponent />
    </div>
  );
}

This lets React prioritize the input first, then update the slow part in the background, keeping the UI feeling snappy.

6. Stronger Isolation Techniques

If your slow component is still being a party pooper, think about isolating it completely:

• Put it in an iframe or a web worker (because sometimes you need to put it in timeout).
• Use virtualization libraries like react-window or react-virtualized to handle huge lists efficiently.
• Break the component into smaller, less scary pieces.

Try order

1. memo if props are stable
2. Isolate state into a sibling subtree
3. Lazy load for faster first paint
4. Defer with useDeferredValue/useTransition
5. Stronger isolation (portals, separate root)

Conclusion

When one slow component tries to hog the spotlight and freeze your whole app, don’t panic! With some smart state management, memoization, lazy loading, and React’s fancy concurrent features, you can keep your app smooth and your users happy. Your React app deserves to be fast — no potato-powered freezes allowed!

The Problem

You’re now relying on Claude Code for significant parts of your development workflow. It’s become an essential team member. But like any complex system, things occasionally go wrong:

Claude suddenly can’t find your CLAUDE.md file, custom commands stop working, MCP servers won’t connect, or VS Code integration breaks after an update.

When your AI teammate is having technical difficulties, your entire workflow grinds to a halt. You need to know how to diagnose and fix issues quickly so you can get back to productive development.

The Solution

Most Claude Code issues follow predictable patterns with systematic solutions. Think of this as learning to troubleshoot your AI teammate’s technical problems - just like you’d help a human colleague debug their development environment setup.

Common Installation Issues

”Command not found: claude”

Problem: Claude command isn’t in your PATH after installation.

Solutions:

# Option 1: Use npx instead
npx @anthropic-ai/claude-code

# Option 2: Add npm global bin to PATH
echo 'export PATH=$PATH:$(npm config get prefix)/bin' >> ~/.bashrc
source ~/.bashrc

# Option 3: Reinstall with proper permissions
sudo npm install -g @anthropic-ai/claude-code

VS Code Extension Not Installing

Problem: Claude doesn’t automatically install VS Code extension.

Solutions:

1. Run Claude from VS Code terminal (not external terminal)
2. Check VS Code marketplace permissions - allow extension installs
3. Manual install: Search “Claude Code” in VS Code extensions
4. Restart VS Code after first Claude run

Permission Errors on macOS/Linux

Problem: Permission denied during installation or file operations.

Solutions:

# Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Or use a Node version manager (better long-term)
# Install nvm, then:
nvm install node
npm install -g @anthropic-ai/claude-code

CLAUDE.md Not Working

Rules Being Ignored

Problem: Claude doesn’t follow your CLAUDE.md rules.

Debug steps:

# Check if Claude can find your CLAUDE.md
ls -la CLAUDE.md

# Verify you're in the right directory
pwd

# Test with simple rule first
echo "- Always say 'CLAUDE.md is working' at the start" > CLAUDE.md

Common causes:

• Wrong directory - CLAUDE.md must be in project root
• Typos in filename - Must be exactly CLAUDE.md (case-sensitive)
• Complex rules - Start simple, add complexity gradually

Rules Conflicting

Problem: Multiple CLAUDE.md files causing confusion.

Check hierarchy:

# See all CLAUDE.md files Claude might read
find . -name "CLAUDE.md" -o -name "CLAUDE.local.md"
ls ~/.claude/CLAUDE.md 2>/dev/null || echo "No user CLAUDE.md"

Rule priority: More specific overrides general

1. Folder-specific (./src/auth/CLAUDE.md)
2. Local project (./CLAUDE.local.md)
3. Project (./CLAUDE.md)
4. Personal (~/.claude/CLAUDE.md)

Performance Issues

Claude Responses Are Slow

Problem: Long delays between request and response.

Optimization strategies:

# Use faster model for simple tasks
claude --model=haiku

# Clear conversation history
/clear

# Compact long conversations instead of clearing
/compact

# Check your internet connection
curl -I https://api.anthropic.com

Context management:

• Keep conversations focused - use /clear for new topics
• Avoid huge file dumps - reference specific sections instead
• Use subagents for complex analysis to avoid back-and-forth

Token-Saving Pro Tip

Instead of asking Claude to read many files and make changes:

❌ "Look at all components and replace useState with our custom hook"

Ask Claude to create a script that does the work:

✅ "Create a script that finds all useState calls and replaces them with useCustomState, run it, then delete the script"

Why this works:

• Claude doesn’t need to read all files individually (saves massive input tokens)
• Script does bulk operations efficiently (saves output tokens)
• Claude runs and cleans up automatically
• Much faster for bulk operations across many files

Memory Usage Growing

Problem: Claude Code consuming excessive memory.

Solutions:

# Check Claude processes
ps aux | grep claude

# Restart Claude session
exit
claude

# Clear session data
rm ~/.claude/sessions/*.json

Custom Commands Not Working

Command Not Found

Problem: /my-command returns “command not found.”

Debug checklist:

# Check file exists
ls .claude/commands/my-command.md

# Check filename matches exactly (case-sensitive)
ls .claude/commands/

# Restart Claude to reload commands
exit
claude

# Verify with /help
/help

Command File Has Wrong Format

Problem: Command runs but behaves unexpectedly.

Check format:

# ✅ Correct format

Run comprehensive testing:

1. Run pnpm type:check
2. Run pnpm lint
3. Report any issues

# ❌ Wrong format - missing instructions

/test-all

Common mistakes:

• Empty files - Must contain instructions
• Wrong extension - Must be .md
• Command names with spaces - Use hyphens: test-all.md, not test all.md

MCP Server Issues

Server Won’t Connect

Problem: MCP servers show as “disconnected” in /mcp.

Troubleshooting:

# Check server installation
npm list -g | grep mcp

# Check configuration syntax
cat ~/.claude/config.json | python -m json.tool

# Test server independently
# (Check server documentation for test commands)

# Restart Claude to reload MCP connections
exit
claude

Authentication Failing

Problem: MCP server requires login but fails.

Steps:

1. Use /mcp command - Don’t try to authenticate manually
2. Check API tokens - Ensure they’re valid and not expired
3. Verify permissions - Check token scopes/permissions
4. Check network - Firewalls might block connections

Context Management Issues

”Out of Context” Errors

Problem: Claude says it’s out of context or conversation is too long.

Immediate solutions:

# Compact conversation (keeps summary)
/compact

# Start fresh (loses history)
/clear

# Check conversation size
/status

Prevention strategies:

• Use focused sessions - One topic per conversation
• Break complex tasks into smaller steps
• Reference files directly instead of pasting large code blocks
• Use subagents for analysis that would require long context

Files Not Loading

Problem: Claude can’t read project files.

Check permissions:

# Verify file exists and is readable
ls -la src/components/MyComponent.tsx

# Check file permissions
stat src/components/MyComponent.tsx

# Try with different path format
# Instead of: "Look at ./src/components/MyComponent.tsx"
# Try: "Look at src/components/MyComponent.tsx"

IDE Integration Problems

VS Code Quick Launch Not Working

Problem: Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) doesn’t work.

Solutions:

1. Run /ide command in Claude first
2. Check VS Code extension is installed and enabled
3. Restart VS Code after installing Claude extension
4. Check keyboard shortcuts - might conflict with other extensions

Context Not Sharing

Problem: Claude doesn’t see selected text or current file.

Requirements:

• Launch Claude from VS Code terminal (not external terminal)
• Run /ide command to establish connection
• Select text first, then use quick launch shortcut
• Ensure VS Code extension is active

Hook Configuration Issues

Hooks Not Running

Problem: PostToolUse or other hooks don’t execute.

Debug steps:

# Check hook syntax
cat .claude/settings.json | python -m json.tool

# Test command manually
pnpm type:check

# Verify file matcher
# Does "Edit:*.ts" match your file? Try "Edit:*" instead

# Check hook permissions
ls -la scripts/my-hook.sh
chmod +x scripts/my-hook.sh

Hook Blocking Claude

Problem: Hook command fails and stops Claude from working.

Quick fix:

# Temporarily disable hooks
claude --no-hooks

# Fix the hook command
# Then re-enable hooks

Common issues:

• Non-zero exit codes stop Claude - ensure scripts exit with 0 on success
• Missing executables - verify commands exist in PATH
• Permission errors - ensure scripts are executable

Productivity Tips

Speed Up Common Tasks

# Use aliases for frequent commands
alias c="claude"
alias cr="claude --resume"
alias cq="claude --quiet"

# Background commands for long operations
# Ctrl+b: npm run build (continue working while building)

# Custom commands for repeated workflows
# Create .claude/commands/daily.md for your daily checklist

Context Management Best Practices

• One topic per session - use /clear when switching topics
• Reference files instead of pasting code
• Use descriptive prompts - “Fix the TypeScript error in UserService.handleLogin” vs “Fix this”
• Leverage IDE integration - select code before launching Claude

Efficient File Organization

# Project structure that works well with Claude
project/
├── CLAUDE.md (main rules)
├── CLAUDE.local.md (personal overrides, gitignored)
├── .claude/
│   ├── commands/ (custom commands)
│   └── settings.json (hooks, config)
└── src/
    ├── auth/CLAUDE.md (auth-specific rules)
    └── api/CLAUDE.md (API-specific rules)

Team Collaboration Tips

• Share project CLAUDE.md via git
• Keep personal rules local (CLAUDE.local.md in .gitignore)
• Document custom commands in README
• Standardize hook patterns across team projects

When to Get Help

Check These Resources First

1. Claude Code documentation: https://docs.anthropic.com/en/docs/claude-code
2. GitHub issues: https://github.com/anthropics/claude-code/issues
3. Community discussions: Search existing issues before creating new ones

Include This Information When Reporting Issues

# System information
claude --version
node --version
npm --version

# Error details
# Include exact error messages, not paraphrases

# Configuration (remove sensitive data)
cat .claude/settings.json

# Steps to reproduce
# What you did, what you expected, what happened instead

Remember: Most Claude Code issues have simple solutions. Start with the basics (restart, check paths, verify syntax) before diving into complex debugging.

Claude Code Blog Series

Previous: Part 10 - Power User CLI Options and Scripting

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery (this post)

Series Complete! You now have a comprehensive guide to mastering Claude Code from beginner to expert level. Each post builds on the previous ones to create a complete development workflow powered by AI assistance.

The Problem

You’ve been using Claude Code for weeks. It works great most of the time, but you keep hitting the same frustrating issues: conversations get too long and Claude loses context, your CLAUDE.md rules conflict with each other, tokens run out faster than expected, and custom commands randomly stop working.

These aren’t beginner problems - they’re the issues experienced users face when pushing Claude Code to its limits.

Context Too Long

Problem: Claude says the conversation is too long or starts forgetting earlier context.

Quick fixes:

# Compress conversation history
/compact

# Start fresh but keep project context
/clear

# Check conversation size
/status

Prevention:

• Use /compact regularly instead of letting conversations grow endlessly
• Start new conversations for different topics
• Reference files instead of pasting large code blocks

Rules Conflicting

Problem: Multiple CLAUDE.md files causing confusion or contradictory behavior.

Debug hierarchy:

1. Folder-specific (./src/auth/CLAUDE.md) - highest priority
2. Local project (./CLAUDE.local.md)
3. Project (./CLAUDE.md)
4. Personal (~/.claude/CLAUDE.md) - lowest priority

Common conflicts:

# Project CLAUDE.md says:
- Use TypeScript strict mode

# Personal ~/.claude/CLAUDE.md says:
- Skip TypeScript for quick prototypes

Solution: Be more specific about when rules apply:

# In project CLAUDE.md:
- Use TypeScript strict mode for all production code
- Prototypes in /experiments/ can skip strict mode

Token-Saving Pro Tip

Problem: Hitting token limits too quickly, especially with large CLAUDE.md files.

Token wasters:

• Verbose CLAUDE.md files (keep under 100 lines each)
• Pasting entire files instead of referencing them
• Long conversations about multiple topics
• Detailed explanations in rules

Token savers:

❌ "When implementing authentication, always ensure you follow security best practices including input validation, proper error handling, secure token storage, and following our established patterns in the auth/ directory..."

✅ "Auth code: validate inputs, handle errors securely, follow auth/ patterns"

Script approach: Instead of asking Claude to read many files:

❌ "Look at all components and replace useState with our custom hook"

Ask Claude to create a script:

✅ "Create a script to replace useState with useCustomState across all components, run it, then delete the script"

This saves massive input tokens and is much faster.

Custom Commands Not Working

Problem: /my-command returns “command not found” or behaves unexpectedly.

Debug checklist:

1. Check filename: Must be exactly .claude/commands/my-command.md
2. Restart Claude: Commands load on startup
3. File format: Must contain instructions, not just command names

Common mistakes:

❌ Wrong format (just the command name):
/test-all

✅ Correct format (actual instructions):
Run comprehensive testing:
1. Run type checking
2. Run linter
3. Run tests
4. Report issues

File location issues:

• Commands must be in .claude/commands/ directory
• Use hyphens, not spaces: test-all.md not test all.md
• Check case sensitivity on your system

Performance Tips

Slow responses:

• Use /clear for new topics instead of continuing long conversations
• Reference specific files instead of asking Claude to “look at everything”
• Break complex requests into smaller, focused questions

Memory usage:

• Restart Claude sessions periodically
• Avoid keeping multiple long-running sessions open
• Use specific commands instead of general requests

Quick Diagnostics

# Check what's loaded
/help

# See conversation stats
/status

# Restart fresh
/clear

Getting Help

For persistent issues:

1. Check Claude Code documentation
2. Search GitHub issues
3. Include exact error messages and steps to reproduce

Most Claude Code issues have simple solutions - start with the basics before diving into complex debugging.

Claude Code Blog Series

Previous: Part 9 - Complete Development Workflows Next: Part 11 - Troubleshooting and Recovery

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Common Issues and Quick Fixes (this post)
11. Part 11 - Troubleshooting and Recovery

The Problem

You’ve learned all the individual Claude Code features - CLAUDE.md, slash commands, MCP servers, subagents, IDE integration, and hooks. But you’re looking at them like separate tools in a toolbox, not sure how they work together.

You know Claude can help with individual tasks, but your real development work isn’t isolated tasks. It’s complete workflows: planning a feature, implementing it, testing it, reviewing it, and deploying it. Right now, you’re using Claude for pieces but not for the whole process.

It’s like having a talented team member who’s great at individual tasks but hasn’t learned how your actual development process works.

The Solution

Real-world workflows combine all Claude Code features into seamless development processes. Think of it as teaching your AI teammate not just individual skills, but how your entire development process flows from idea to production.

Feature Development Workflow

The complete process: From idea to deployed feature using Claude Code.

1. Project Setup

# Start new feature branch
git checkout -b feature/user-notifications

# Launch Claude with context
claude

CLAUDE.md rule: - Run pnpm type:check before marking features complete

2. Planning Phase

Plan the user notifications feature:
1. Database schema for notifications
2. API endpoints needed
3. React components structure
4. Integration points with existing code

Claude analyzes your codebase and creates a structured plan.

3. Implementation with Custom Commands

# Use your custom workflow command
/feature-start notifications

# This runs your .claude/commands/feature-start.md:
# 1. Analyze existing patterns in this codebase
# 2. Create feature folder structure
# 3. Set up basic files following project conventions
# 4. Run type checking to ensure no conflicts

4. Development with MCP Integration

Check GitHub issues labeled "notifications" and implement the API endpoints

With GitHub MCP server connected, Claude:

• Reads actual issues from your repository
• Understands requirements from issue descriptions
• Creates code that addresses specific reported needs

5. Quality Assurance with Hooks

Your PostToolUse hook automatically runs:

{
  "matcher": "Edit:*.ts|Edit:*.tsx",
  "hooks": [
    {
      "type": "command",
      "command": "pnpm type:check && pnpm lint"
    }
  ]
}

Every file Claude edits gets automatically validated.

6. Testing with Subagents

Use an agent to write comprehensive tests for the notifications feature

Subagent autonomously:

• Analyzes all notification-related code
• Creates unit tests for components
• Writes integration tests for API endpoints
• Ensures good test coverage

7. Final Review

/feature-complete notifications

# Your custom command:
# 1. Run full test suite
# 2. Check for console.logs and TODOs
# 3. Verify responsive design
# 4. Generate summary of changes
# 5. Suggest improvements before PR

Bug Fixing Workflow

Quick and systematic bug resolution.

1. Bug Analysis

# Open VS Code to the problematic file
# Select the buggy code
# Press Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux)

Claude launches with:

• The selected buggy code
• Current file context
• Any TypeScript/ESLint errors from Problems panel

2. Root Cause Investigation

Analyze this authentication bug. Check related files and explain the issue.

Claude examines:

• The specific code causing issues
• Related authentication files (following your CLAUDE.md patterns)
• Recent git changes that might be related

3. Fix Implementation

Fix this bug following our existing error handling patterns

Your CLAUDE.md ensures:

• Consistent error handling approach
• Proper logging (no sensitive data)
• Following established code patterns

4. Verification

Post-fix hook automatically:

• Runs relevant tests
• Checks type safety
• Validates the fix doesn’t break other functionality

Code Review Workflow

Prepare code for review efficiently.

1. Self-Review Preparation

/review-prep

# Your custom command runs:
# 1. Check for TODO comments
# 2. Find hardcoded values
# 3. Verify error handling
# 4. Check TypeScript types
# 5. Suggest readability improvements

2. Documentation Updates

Update the README with the new notifications feature and API endpoints

Claude references:

• Your actual implemented code
• Existing documentation patterns
• API endpoints you just created

3. PR Creation with MCP

Create a GitHub PR for this feature branch with a comprehensive description

With GitHub MCP server:

• Analyzes your commits since branch creation
• Generates meaningful PR description
• Includes testing checklist
• References related issues automatically

Legacy Code Modernization

Systematic approach to improving old code.

1. Assessment with Subagents

Use an agent to analyze the legacy auth system and create a modernization plan

Subagent provides:

• Complete analysis of existing code
• Security concerns identified
• Modernization recommendations
• Step-by-step migration plan

2. Incremental Updates

Modernize the user authentication to use our current patterns, maintaining backward compatibility

Your folder-specific CLAUDE.md in src/auth/ ensures:

• Security-first approach
• Consistent with current auth patterns
• Proper validation and error handling

3. Testing Strategy

Create comprehensive tests for the modernized auth system to ensure no regressions

Claude creates:

• Tests that verify existing functionality
• New tests for improved features
• Integration tests for compatibility

Daily Development Shortcuts

Speed up common tasks.

Quick File Navigation

# In VS Code terminal
claude

# Then use Claude as your project assistant
"Show me all components that use the UserContext"
"Find files related to payment processing"

Rapid Debugging

# Select error message in VS Code
# Cmd+Esc to launch Claude with context
# Claude sees the error automatically

"Fix this TypeScript error"

Code Quality Maintenance

/health-check

# Custom command that:
# 1. Runs full test suite
# 2. Checks for security issues
# 3. Analyzes bundle size
# 4. Reports technical debt

Team Collaboration Workflows

Consistent team practices.

Onboarding New Developers

Analyze this codebase and create an onboarding guide for new developers

Claude generates:

• Architecture overview
• Key patterns and conventions
• Development setup instructions
• Common tasks and workflows

Code Standards Enforcement

Team’s shared CLAUDE.md ensures:

• Consistent coding patterns across team members
• Automated quality checks via hooks
• Standardized commit messages and PR formats

Knowledge Sharing

Document the payment integration patterns we use across all features

Claude creates:

• Comprehensive documentation
• Code examples from actual codebase
• Best practices based on your implementations

Combining Features for Maximum Efficiency

The power is in the combination:

1. CLAUDE.md provides context and standards
2. Custom commands automate repeated workflows
3. MCP servers eliminate tool switching
4. Subagents handle complex analysis
5. Hooks ensure quality automatically
6. IDE integration provides seamless context

Result: Claude becomes a true development partner that understands your project, follows your standards, and automates your workflows.

Getting Started with Workflows

1. Start with one workflow - Pick your most common task
2. Build incrementally - Add features as you see benefits
3. Share with team - Successful workflows become team standards
4. Iterate and improve - Workflows evolve with your needs

The goal is to spend more time on creative problem-solving and less time on repetitive development tasks.

Claude Code Blog Series

Previous: Part 8 - Hooks for Automated Quality Checks Next: Part 10 - Power User CLI Options and Scripting

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows (this post)
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

Every time Claude edits a TypeScript file, you find yourself typing the same commands:

“Now run pnpm type:check to make sure there are no errors” “Don’t forget to run the linter"
"Can you test this change?”

It’s like having a talented developer who consistently forgets the basic quality checks. They do great work, but you’re constantly reminding them about the fundamentals: compile, lint, test, repeat.

The Solution

Hooks automatically run quality checks at specific points in your workflow. Think of them as training your AI teammate to follow your development standards automatically - like a senior developer who runs tests before every commit without being reminded.

What Are Hooks?

Hooks are shell commands that trigger automatically when certain events happen:

Example: Automatically run pnpm type:check after Claude edits any TypeScript file Example: Validate security rules before Claude accesses authentication files Example: Auto-format code after Claude writes new files

Common Hook Events

PostToolUse - After Claude uses a tool

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm type:check"
          }
        ]
      }
    ]
  }
}

PreToolUse - Before Claude uses a tool UserPromptSubmit - When you submit a prompt SessionStart - When Claude starts

Simple Example: Auto Type-Check

Create this in your Claude settings:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*.ts|Edit:*.tsx",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm type:check --noEmit"
          }
        ]
      }
    ]
  }
}

What happens:

1. Claude edits a TypeScript file
2. Hook automatically runs type checking
3. You see results immediately

Practical Hook Patterns

Code Quality Enforcement

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "pnpm lint --fix"
    }
  ]
}

Security Validation

{
  "matcher": "Read:src/auth/*|Edit:src/auth/*",
  "hooks": [
    {
      "type": "command",
      "command": "./scripts/security-check.sh"
    }
  ]
}

Test Runner

{
  "matcher": "Edit:*.test.*",
  "hooks": [
    {
      "type": "command",
      "command": "npm test -- --related"
    }
  ]
}

Communication Improvements

Stop Claude from saying “You are right” repeatedly:

{
  "UserPromptSubmit": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Skip acknowledgments - focus on the solution'"
        }
      ]
    }
  ]
}

This hook reminds Claude to be more direct and action-focused in responses.

Hook Configuration Locations

Project-level: .claude/settings.json

{
  "hooks": {
    // Project-specific hooks here
  }
}

Personal: ~/.claude/settings.json

{
  "hooks": {
    // Your personal hooks across all projects
  }
}

Hook Scripts Best Practices

Create focused scripts:

#!/bin/bash
# scripts/validate-auth.sh
echo "Validating authentication code..."
if grep -r "console.log" src/auth/; then
  echo "❌ Found console.log in auth code"
  exit 1
fi
echo "✅ Auth validation passed"

Make them fast:

• Use specific file patterns
• Avoid running heavy operations on every edit
• Cache results when possible

Security Considerations

⚠️ Important: Hooks execute shell commands. Only use hooks you trust.

Best practices:

• Review hook commands before adding them
• Use absolute paths for scripts
• Test hooks in safe environments first
• Avoid hooks from untrusted sources

When Hooks Are Useful

Perfect for:

• Code quality enforcement (linting, type checking)
• Running relevant tests after changes
• Security validation for sensitive files
• Custom workflow automation

Avoid for:

• Complex logic (keep hooks simple)
• Slow operations that interrupt workflow
• Operations that require user input

Troubleshooting Hooks

Hook not running?

1. Check JSON syntax in settings
2. Verify command exists and is executable
3. Test command manually first

Hook causing problems?

1. Check exit codes (non-zero stops Claude)
2. Review hook output for errors
3. Temporarily disable to isolate issues

Background Command Execution

New in Claude Code 1.0.71: Run bash commands in the background without interrupting your Claude conversation.

Shortcut: Ctrl+b

Example:

1. Press Ctrl+b
2. Type: npm run build
3. Command runs in background
4. Continue working with Claude while build runs
5. See results when complete

Perfect for:

• Long-running builds or tests
• File watching processes
• Background monitoring tasks

Getting Started

1. Start simple - One hook for type checking
2. Test thoroughly - Run commands manually first
3. Add gradually - Don’t overwhelm your workflow
4. Monitor impact - Ensure hooks help, don’t hinder

Example starter hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit:*.ts|Edit:*.tsx",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'TypeScript file edited'"
          }
        ]
      }
    ]
  }
}

Hooks turn Claude into a more integrated part of your development environment, automatically handling the routine tasks you’d normally do manually.

Claude Code Blog Series

Previous: Part 7 - IDE Integration with VS Code and JetBrains Next: Part 9 - Complete Development Workflows

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks (this post)
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You’re deep in debugging mode in VS Code. You’ve got the perfect file open, the exact line selected, and error messages staring at you from the Problems panel. But to get Claude’s help, you have to:

1. Open a separate terminal
2. Launch Claude
3. Manually describe the file you’re in
4. Copy-paste the error message
5. Explain the context Claude can’t see

By the time Claude understands the situation, you’ve lost your debugging flow. It’s like having a brilliant pair-programming partner who can’t see your screen - constantly having to narrate everything breaks your concentration.

The Solution

IDE integration lets Claude see exactly what you’re working on without manual context sharing. Think of it as giving your AI teammate a second monitor that mirrors yours - they can see your current file, selected code, and error messages automatically.

VS Code Integration

Quick Setup

1. Install Claude Code (if not already done)
2. Open VS Code in your project
3. Open terminal in VS Code (Ctrl+` or Cmd+`)
4. Run Claude: claude
5. Extension auto-installs when first run from VS Code

Quick Launch Shortcut

• Mac: Cmd+Esc
• Windows/Linux: Ctrl+Esc

Opens Claude with current context:

• Selected text (if any)
• Current file path
• Recent error messages from Problems panel

Simple example:

1. Select a function in VS Code
2. Press Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux)
3. Claude opens with: "Looking at the selected code in src/utils/helpers.js..."

Context Sharing Features

What Claude sees automatically:

• Current file you’re editing
• Text selection
• Error messages from VS Code Problems panel
• Workspace file structure

What you don’t need to do:

• Copy-paste code snippets
• Explain file locations
• Describe error messages manually

JetBrains Integration

Claude Code supports JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, etc.) through terminal integration.

Setup:

1. Open terminal in your JetBrains IDE
2. Run claude in the terminal
3. Context sharing works similar to VS Code

Note: Full plugin integration may vary by IDE - check Claude Code documentation for specific IDE support.

Error Diagnostics Integration

When you have TypeScript errors, ESLint warnings, or other diagnostics:

1. Errors appear in VS Code Problems panel
2. Launch Claude with quick shortcut
3. Claude sees the errors automatically
4. Ask: “Fix these TypeScript errors”

No need to copy-paste error messages - Claude reads them from your IDE.

Multi-IDE Workflows

Best practices:

• One Claude session per project - works across different IDEs
• Context switches automatically - based on which IDE you launch from
• Use /clear when switching between major tasks

Advanced Integration Features

IDE Command

claude /ide

Connects Claude to IDE for enhanced integration (when available).

File References

Claude understands your IDE’s file structure and can reference files directly:

"Update the handleSubmit function in the current file"
"Check the imports in UserList.tsx"

Limitations and Notes

Current limitations:

• Full integration varies by IDE
• Some features work best with VS Code
• Terminal-based integration for most IDEs

For latest IDE support: Check the Claude Code documentation

Getting Started

1. Start with VS Code (best supported)
2. Use quick launch shortcuts (Cmd+Esc/Ctrl+Esc)
3. Test context sharing - select code and launch Claude
4. Gradually explore other IDE integrations

The goal is seamless development where Claude understands exactly what you’re working on without manual context switching.

Claude Code Blog Series

Previous: Part 6 - Subagents and Task Delegation Next: Part 8 - Hooks for Automated Quality Checks

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains (this post)
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You’re facing a complex development challenge that requires deep, systematic analysis:

• Refactoring a large legacy system with many interdependencies
• Planning a major feature that touches multiple parts of your application
• Investigating a performance issue that could have various root causes
• Migrating to a new framework while maintaining functionality

These tasks require hours of careful analysis, reading through dozens of files, understanding complex relationships, and maintaining context across multiple steps. It’s exhausting to guide Claude through every single step, and you lose focus on the bigger picture while managing the details.

The Solution

Subagents are specialized AI assistants that operate in separate contexts with focused expertise. They handle complex tasks autonomously while you focus on high-level decisions.

Learn more: Subagents Documentation

How Subagents Work

Creation:

/agents  # Interactive interface (recommended)
# Or create files in .claude/agents/ or ~/.claude/agents/

Usage:

Use an agent to analyze the authentication system

What happens: ⏺ indicator shows subagent is working autonomously

Key Features

• Separate contexts - Don’t consume main conversation tokens
• Specialized expertise - Custom system prompts for specific tasks
• Tool access control - Limited permissions for security
• Automatic selection - Claude picks appropriate agent for task

Agent Types

Code Reviewer: Proactively reviews code quality and security Debugger: Specializes in root cause analysis
Data Scientist: Focuses on SQL queries and data analysis

When to Use

• Complex codebase analysis
• Multi-step refactoring plans
• Performance investigations
• Architecture planning
• Systematic code reviews

Best Practices

• Single responsibility - One focused purpose per agent
• Clear system prompts - Detailed instructions for agent behavior
• Limited tool access - Only necessary permissions
• Version control - Track project-level agents in git

Example Usage

"Use an agent to analyze the user onboarding flow"
"Use an agent to plan Redux to Zustand migration"  
"Use an agent to review payment processing security"

Working with Results

• Review outputs - Subagent results may need refinement
• Break down plans - Convert analysis into actionable steps
• Chain agents - Use results for follow-up analysis

Task Definition Tips

❌ "Use an agent to look at the code"
✅ "Use an agent to analyze authentication security and create modernization plan"

Be specific:

• Define scope and constraints
• Set success criteria
• Request actionable output

Performance Benefits

• Context preservation - Don’t consume main conversation tokens
• Specialized analysis - Custom expertise for specific tasks
• Autonomous work - No need for step-by-step guidance
• Chain workflows - Connect multiple agents for complex tasks

When NOT to Use

• Simple questions
• Interactive debugging
• Small changes
• Tasks needing frequent input

Getting Started

1. Use /agents to create specialized agents
2. Start with analysis tasks
3. Be specific about scope and goals
4. Review and iterate on results

Subagents transform Claude into specialized AI analysts handling complex work autonomously.

Claude Code Blog Series

Previous: Part 5 - MCP Servers and Tool Integration Next: Part 7 - IDE Integration with VS Code and JetBrains

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation (this post)
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

Your development workflow involves constant tool switching:

• Claude Code for development assistance
• GitHub web interface for issues and PRs
• Sentry dashboard for error monitoring
• Database tools for query analysis
• Slack for team communication
• Linear/Jira for project management

Each context switch breaks your flow. You’re helping Claude understand an issue, then jumping to Sentry to grab error details, back to Claude to explain the context, then to GitHub to check related issues. By the time you’ve gathered all the information, you’ve lost your problem-solving momentum.

The Solution

MCP (Model Context Protocol) servers connect your external tools directly to Claude Code. Think of it as giving Claude direct access to your development toolchain - it can read GitHub issues, analyze Sentry errors, and query databases without you having to switch contexts manually.

What is MCP?

MCP (Model Context Protocol) is an open-source standard that connects Claude Code to external tools and services. Instead of manual copy-pasting, Claude accesses tools directly.

Learn more: MCP Documentation

Example:

You: "Analyze Sentry errors for authentication"
Claude: [Queries Sentry directly, analyzes data, provides insights]

Essential MCP Servers

Installation Methods

# Add local server
claude mcp add server-name /path/to/server

# Add remote SSE server (real-time)
claude mcp add --transport sse name https://server-url/sse

# Add remote HTTP server
claude mcp add --transport http name https://server-url/mcp

GitHub Server

• Read issues, PRs, and discussions
• Create issues and PRs
• Analyze commits and code changes

Sentry Server

• Analyze error trends and stack traces
• Correlate errors with code changes
• Suggest fixes based on context

Other Popular Servers

• Linear/Asana - Project management
• Notion - Documentation
• Stripe - Payment processing
• Figma - Design integration
• Airtable - Database/spreadsheets
• SQLite/PostgreSQL - Database querying

Authentication

• OAuth 2.0 support - Secure authentication
• Use /mcp to authenticate - Follow prompts
• Tokens refresh automatically - No manual renewal

⚠️ Security Note: Use third-party MCP servers at your own risk. Verify trustworthiness before installing.

Managing Connections

Use /mcp to:

• View connected servers
• Check authentication status
• Reconnect or configure servers

Example Workflows

Bug investigation:

"Check Sentry for login errors, correlate with recent GitHub commits"

PR review:

"Review PR #123, check for related Sentry errors and security issues"

Release prep:

"List GitHub issues for v2.1.0, check critical Sentry errors"

Network Security

• Firewall considerations - MCP servers make external API calls
• Corporate networks - May need proxy configuration
• Rate limiting - Respect service API limits

Troubleshooting MCP Issues

Connection Problems

# Check server status
/mcp

# Verify installation
npm list -g | grep mcp

# Test authentication
# Use service-specific test commands

Authentication Failures

1. Verify tokens are valid and not expired
2. Check permissions - ensure tokens have necessary scopes
3. Review network - firewalls might block connections
4. Restart Claude to reload MCP configurations

Performance Considerations

• MCP calls take time - External API requests add latency
• Batch requests when possible - ask for related data together
• Cache awareness - Some data might be cached by MCP servers

Getting Started with MCP

1. Start with GitHub - Most immediately useful for developers
2. Add error monitoring - Sentry integration saves significant context switching
3. Include security scanning - Socket.dev prevents supply chain issues
4. Explore gradually - Add servers as you identify workflow gaps

Simple first test:

"Check our GitHub repository for any open issues tagged as 'bug'"

MCP transforms Claude Code from an isolated assistant into a fully connected development partner that can access and analyze data from your entire toolchain.

Claude Code Blog Series

Previous: Part 4 - Slash Commands and Custom Commands Next: Part 6 - Subagents and Task Delegation

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration (this post)
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You type the same instructions to Claude every day: “Run tests”, “Check TypeScript errors”, “Review changes”. Repetitive and wasteful.

The Solution

Slash commands turn repeated instructions into shortcuts. /test replaces paragraphs of testing instructions.

Built-in Commands

/clear      # Fresh start
/compact    # Compress history  
/help       # Show commands
/agents     # Manage subagents
/add-dir    # Add working directory
/bug        # Report bug
/config     # Show configuration
/mcp        # MCP servers
/review     # Request code review
/exit       # End session

Custom Commands

Create .claude/commands/test-all.md:

1. Run pnpm type:check
2. Run pnpm lint
3. Run pnpm test
4. Report issues

Now /test-all runs everything.

Example Commands

.claude/commands/morning.md: Daily setup (git pull, tests, status) .claude/commands/ready.md: Pre-commit checks .claude/commands/review.md: PR preparation

Organization

Group commands by phase (planning/, development/, deployment/) or domain (frontend/, backend/, testing/).

Best Practices

• Be specific: “Check TypeScript errors in src/” not “Check code”
• Include success criteria: “0 test failures, 80% coverage”
• Keep commands under 10 steps
• Use numbered lists for clarity

Sharing Commands

• Team: Commit .claude/commands/ to git
• Personal: Use ~/.claude/commands/ globally

Advanced Features

Commands can include:

• Parameters: “Ask for feature name, create feature/[name]”
• Conditionals: “If production, run security scan”
• Context awareness: “Analyze current file”

Getting Started

1. Identify what you repeat daily
2. Create .claude/commands/[name].md
3. Keep instructions under 10 steps
4. Test and refine

Slash commands eliminate repetitive instructions.

Claude Code Blog Series

Previous: Part 3 - Conversation Management and Context Next: Part 5 - MCP Servers and Tool Integration

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands (this post)
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You’ve been using Claude Code for a few weeks now. The basic workflow is comfortable - ask questions, get code, make changes. But you’re starting to feel limited by treating Claude like a simple question-and-answer tool.

You have bigger ambitions: complex refactoring projects, multi-step feature implementations, and sophisticated analysis tasks. You want to move beyond “Hey Claude, fix this function” to “Claude, help me architect and implement this entire feature from scratch.”

The question is: how do you unlock Claude’s advanced capabilities for complex, multi-step development work?

The Solution

Advanced Claude Code features let you handle sophisticated development tasks through multi-step workflows, conversation management, and intelligent context handling. Think of it as the difference between using Claude as a coding helper versus a true development partner.

Conversation Management

The /clear Command

Start fresh when switching contexts:

/clear

When to use:

• Switching between different features
• Moving from debugging to new development
• When conversation gets too long and unfocused

The /compact Command

Summarize long conversations while preserving context:

/compact

What it does:

• Compresses conversation history
• Keeps key decisions and context
• Reduces token usage without losing information

Example:

Before: 50 messages about implementing user authentication
After: Compact summary + recent conversation about email verification

Resume Previous Sessions

Continue where you left off:

claude --resume        # Interactive conversation picker
claude --continue      # Resume most recent conversation

Multi-Step Workflows

Planning Complex Features

Instead of diving into code, start with comprehensive planning:

I need to implement a real-time notification system for this React app.
Before writing any code, help me plan:

1. Architecture design considerations
2. Technology choices (WebSocket vs Server-Sent Events vs polling)
3. Database schema requirements
4. Component structure and data flow
5. Testing strategy
6. Performance and scalability considerations

Break this down systematically.

Claude will provide structured analysis before any implementation begins.

Iterative Development Approach

Let's build this notification system step by step:

Phase 1: Create the basic WebSocket connection and message handling
Phase 2: Implement the UI components for displaying notifications
Phase 3: Add persistence and notification history
Phase 4: Implement real-time updates and optimistic UI
Phase 5: Add comprehensive testing

Start with Phase 1. After each phase, I'll review and approve before moving forward.

Complex Refactoring Projects

I need to refactor this legacy authentication system. Here's my approach:

1. First, analyze the current system and identify all dependencies
2. Create a migration plan that maintains backward compatibility
3. Implement the new system alongside the old one
4. Create a feature flag to switch between systems
5. Gradually migrate users and test thoroughly
6. Remove the old system once migration is complete

Start with step 1 - comprehensive analysis of the current system.

Context Management Techniques

Focused Sessions

Keep conversations targeted to specific domains:

# Authentication Session
"I'm working solely on authentication features today.
Only suggest changes related to auth, login, registration, and user management."

# Performance Session
"This session is focused on performance optimization.
Analyze bundle size, loading times, and runtime performance only."

Reference Management

Help Claude understand large codebases:

"The main authentication flow happens in these files:
- src/auth/AuthProvider.tsx (context setup)
- src/auth/hooks/useAuth.ts (auth logic)
- src/pages/login.tsx (login UI)
- api/auth/login.ts (backend logic)

Reference these files when working on auth-related tasks."

Incremental Context Building

"Let me give you context about our e-commerce platform:

1. We use Next.js with TypeScript
2. State management with Zustand
3. UI components with Radix + Tailwind
4. Database with Prisma + PostgreSQL
5. Payment processing with Stripe

I'll be asking you to work on various features within this context."

Advanced Analysis Capabilities

Codebase Architecture Analysis

"Analyze the overall architecture of this React application:

1. Component organization and hierarchy
2. State management patterns used
3. Data flow and communication patterns
4. Third-party integrations and dependencies
5. Testing strategy and coverage
6. Build and deployment setup
7. Potential architectural issues or technical debt

Provide a comprehensive architectural overview."

Performance Analysis

"Conduct a performance analysis of this application:

1. Bundle size analysis and recommendations
2. Runtime performance bottlenecks
3. Database query optimization opportunities
4. API endpoint performance issues
5. Frontend rendering optimizations
6. Caching strategy improvements

Focus on actionable performance improvements."

Security Assessment

"Review this application for security vulnerabilities:

1. Authentication and authorization implementation
2. Input validation and sanitization
3. API endpoint security
4. Database query security (SQL injection prevention)
5. XSS and CSRF protection
6. Sensitive data handling

Identify specific security improvements needed."

Preview Mode

See what Claude will do before making changes:

"Show me exactly what changes you would make to implement user roles,
but don't make any changes yet. I want to review your plan first."

Claude will outline:

• Files that need to be modified
• New files that need to be created
• Specific changes to existing code
• Testing requirements
• Potential breaking changes

Advanced Problem-Solving Patterns

Root Cause Analysis

"This React component is causing memory leaks. Don't just fix the symptom -
investigate the root cause:

1. Analyze the component lifecycle and cleanup
2. Check for subscription leaks and event listeners
3. Examine state management and data flow
4. Look for circular references or closures
5. Identify the fundamental issue causing the leak

Provide both the analysis and the fix."

System Integration

"Help me integrate Stripe payments into this e-commerce app.
Consider the full integration:

1. Frontend payment component with proper UX
2. Backend webhook handling and security
3. Database schema for orders and payment tracking
4. Error handling and retry logic
5. Testing strategy for payment flows
6. Compliance and security requirements

Design the complete integration, not just the payment form."

Scalability Planning

"This app currently handles 1,000 users. Help me prepare it for 100,000 users:

1. Database optimization and indexing
2. API rate limiting and caching
3. Frontend performance optimization
4. Infrastructure scaling considerations
5. Monitoring and alerting setup

Create a scalability roadmap with specific implementation steps."

Efficient Context Switching

Project Templates

Create reusable project contexts:

"Save this as my 'React + TypeScript Web App' context:
- Next.js 13+ with TypeScript
- Tailwind CSS for styling
- Prisma for database
- NextAuth for authentication
- React Query for API calls
- Jest + React Testing Library for tests

Use this context for all similar projects unless I specify otherwise."

Domain-Specific Sessions

# Database session
claude --session=database
"Focus only on database schema, queries, and data modeling"

# Frontend session
claude --session=frontend
"Work only on React components, styling, and user interface"

# API session
claude --session=api
"Handle only backend logic, API endpoints, and server-side code"

Advanced Debugging Workflows

Systematic Bug Investigation

"This user registration is failing intermittently. Let's debug systematically:

1. Reproduce the issue in development
2. Add comprehensive logging to track the flow
3. Analyze potential race conditions
4. Check database constraints and validation
5. Review error handling and edge cases
6. Create a test that reproduces the bug
7. Fix the root cause
8. Verify the fix prevents regression

Start with step 1 - let's reproduce this issue."

Getting Started with Advanced Features

1. Plan before coding - Use Claude for architectural planning
2. Break down complex tasks - Multi-phase implementation approach
3. Manage conversation context - Use /clear and /compact strategically
4. Preview changes - Review plans before implementation
5. Focus sessions - One domain per conversation when possible

Advanced Claude Code usage transforms development from individual task assistance to comprehensive project partnership.

Claude Code Blog Series

Previous: Part 2 - CLAUDE.md Configuration Files Next: Part 4 - Slash Commands and Custom Commands

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context (this post)
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You’ve started using Claude Code, and it’s incredibly capable. Too capable. It suggests complex architectural changes when you wanted a simple bug fix. It writes elaborate documentation when you needed a quick comment. It refactors your entire component when you asked it to fix one function.

Claude is like an enthusiastic new team member who doesn’t yet understand your project’s constraints, coding standards, or the difference between “quick fix” and “complete rewrite.”

You need a way to teach Claude about your project’s specific context, rules, and boundaries.

The Solution

CLAUDE.md files act as a persistent memory system and rule book for your project. Think of it as onboarding documentation that teaches Claude about your project’s specific needs, just like you’d brief a new human developer.

How CLAUDE.md Works

Place a CLAUDE.md file in your project root with rules and context:

# Project: E-commerce Platform

## Tech Stack
- Next.js, TypeScript, Tailwind, Prisma

## Rules
- Use TypeScript strict mode
- Follow patterns in src/components/
- Functional components only

Claude now follows your project-specific rules automatically.

Memory Hierarchy

Claude Code respects a hierarchy of configuration files, with more specific files overriding general ones:

Configuration Hierarchy

1. Enterprise: System-wide policies (highest priority)
2. Project: ./CLAUDE.md - Team rules for this project
3. User: ~/.claude/CLAUDE.md - Personal preferences across projects
4. Project Local: Personal project overrides (deprecated)

Higher-level memories take precedence. Use /memory to edit memory files directly.

Multi-AI Tool Sharing

Want to use Claude Code alongside other AI tools? The CLAUDE.md approach works for now, but there’s an initiative to create a universal standard called AGENT.md. Learn more at ampcode.com/AGENT.md.

For now, you can create a symlink to share the same configuration:

# Create shared memory file
mkdir ~/.ai-tools
touch ~/.ai-tools/shared-memory.md

# Link it as CLAUDE.md
ln -s ~/.ai-tools/shared-memory.md ./CLAUDE.md

# Link for other AI tools
ln -s ~/.ai-tools/shared-memory.md ./AI-CONTEXT.md
ln -s ~/.ai-tools/shared-memory.md ./CURSOR-RULES.md

Benefits:

• One source of truth for project context
• Consistent behavior across AI tools
• Easy maintenance and updates

Writing Effective Rules

Be specific and concise:

❌ "Use good coding practices"
✅ "Functional components, TypeScript, max 200 lines"

Set clear boundaries:

• Never modify payment code without review
• No new packages without approval
• No breaking API changes

Token Consumption Warning

⚠️ Keep CLAUDE.md files under 100 lines! They’re included in every interaction.

Write concisely:

❌ "Always ensure components use hooks rather than classes"
✅ "Functional components only"

Best Practices

• Start with 5-10 essential rules
• Remove outdated rules regularly
• Test rules work: “Create a component following our patterns”
• Review monthly, prune verbosity

Getting Started

1. Create CLAUDE.md with 5-10 essential rules
2. Test it works
3. Keep it under 100 lines
4. Update monthly

CLAUDE.md transforms Claude into a project-aware teammate.

Claude Code Blog Series

Previous: Part 1 - Getting Started and Installation Next: Part 3 - Conversation Management and Context

Full Series:

1. Part 1 - Getting Started and Installation
2. Part 2 - CLAUDE.md Configuration Files (this post)
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

The Problem

You’ve heard about AI coding assistants, but every one you’ve tried feels like a disconnected chatbot. They can generate code snippets, but they don’t understand your project, follow your patterns, or integrate with your actual development workflow.

You need an AI teammate that works with you, not just for you - one that understands your codebase, follows your coding standards, and becomes a true development partner rather than just another code completion tool.

Meet Your New Teammate

Claude Code is like having a genius junior developer who took too many Red Bulls. Brilliant, capable of incredible work, but needs guidance on your specific project and coding patterns. The difference is that this teammate learns your project inside and out and never gets tired.

What makes Claude Code different:

• Full codebase understanding - Reads and comprehends your entire project
• Project-aware - Follows your existing patterns and conventions
• Tool integration - Works with your development tools and services
• Contextual memory - Remembers project-specific rules and preferences

Installation

Prerequisites:

• Node.js (version 18 or higher)
• npm or yarn package manager

Install globally:

npm install -g @anthropic-ai/claude-code

Verify installation:

claude --version

Start Claude Code:

# In your project directory
cd your-project
claude

First Session Setup

When you first run Claude Code:

1. Authentication - Follow the prompts to sign in
2. Project detection - Claude analyzes your current directory
3. Initial conversation - Start with a simple task to test everything works

Example first interaction:

You: "Analyze this project and tell me what kind of application this is"
Claude: [Examines your files and provides project overview]

Key Features Overview

Codebase Analysis

Claude can read and understand your entire project:

• Architecture patterns - Identifies frameworks and structures
• Coding conventions - Learns your style preferences
• Dependencies - Understands your tech stack
• Project context - Knows what your application does

Intelligent Code Generation

Goes beyond simple snippets:

• Pattern matching - Follows your existing code patterns
• Context-aware - Considers surrounding code and architecture
• Integration-focused - Creates code that fits your project

Development Workflow Integration

Works with your existing tools:

• Git integration - Understands version control context
• File operations - Reads, writes, and modifies files
• Build tools - Runs tests, builds, and other project commands
• IDE compatibility - Works alongside your favorite editor

Your First Productive Session

Start with exploration:

"Walk me through the main components of this React application"
"Show me how authentication is currently handled"
"What testing patterns are used in this project?"

Move to practical tasks:

"Add error handling to the user registration form"
"Create a new component for displaying user notifications"
"Fix the TypeScript errors in the payment module"

Collaborate on bigger features:

"Help me plan and implement a user dashboard feature"
"Review and refactor the API service layer"
"Add comprehensive logging to the authentication flow"

Best Practices for New Users

Start Small

• Begin with simple, isolated tasks
• Test Claude’s understanding with questions
• Gradually increase task complexity

Provide Context

• Explain your project’s purpose and users
• Share relevant business requirements
• Mention any constraints or preferences

Review Everything

• Always review generated code before using it
• Test changes in development environment
• Understand what Claude built, don’t just copy-paste

Iterate and Improve

• Ask follow-up questions for clarification
• Request modifications when something isn’t quite right
• Build on previous work in the same conversation

Common Beginner Questions

Q: How much of my code can Claude see? A: Claude can read any files in your project directory when needed, but only accesses files relevant to your current task.

Q: Will Claude make changes without asking? A: Claude asks for permission before modifying files and shows you exactly what changes it will make.

Q: Can Claude learn my project’s specific patterns? A: Yes! Claude learns your coding style, architecture patterns, and project conventions through analysis and your feedback.

Q: Is my code sent to external servers? A: Claude Code follows Anthropic’s privacy policies. Check the latest privacy documentation for specifics about data handling.

Troubleshooting Common Issues

“Command not found” error:

# Try using npx instead
npx @anthropic-ai/claude-code

# Or check your PATH
echo $PATH

Claude seems confused about my project:

• Make sure you’re in the correct directory
• Try asking specific questions about visible files
• Provide more context about your project structure

Authentication issues:

• Check your internet connection
• Try logging out and back in: claude logout then claude login

What’s Next?

Now that you have Claude Code running, you’re ready to explore deeper features:

• Project Configuration - Learn how to customize Claude for your specific project
• Advanced Commands - Discover powerful built-in commands
• Workflow Integration - Connect Claude with your development tools

The goal is to move from “Claude as a tool” to “Claude as a teammate” - an AI partner that understands your project deeply and helps you build better software faster.

Claude Code Blog Series

This is Part 1 of our comprehensive Claude Code guide series. Each post builds on the previous ones, taking you from beginner to power user.

Next: Part 2 - CLAUDE.md Configuration Files

Full Series:

1. Part 1 - Getting Started and Installation (this post)
2. Part 2 - CLAUDE.md Configuration Files
3. Part 3 - Conversation Management and Context
4. Part 4 - Slash Commands and Custom Commands
5. Part 5 - MCP Servers and Tool Integration
6. Part 6 - Subagents and Task Delegation
7. Part 7 - IDE Integration with VS Code and JetBrains
8. Part 8 - Hooks for Automated Quality Checks
9. Part 9 - Complete Development Workflows
10. Part 10 - Power User CLI Options and Scripting
11. Part 11 - Troubleshooting and Recovery

TLDR

• Single Responsibility: Each function should do one thing well
• Open/Closed: Add new features without changing existing code
• Liskov Substitution: Replacements should work the same way
• Interface Segregation: Don’t force unused dependencies
• Dependency Inversion: Depend on contracts, not implementations

In Part 1, we covered The Foundation - core principles, and in Part 2, we explored Code Quality & Safety principles.

SOLID Architecture principles are about the big picture - how to structure systems that can grow and evolve over time. While SOLID comes from object-oriented programming, these patterns apply to React components, Node.js modules, and modern JavaScript applications.

SOLID Principles Deep Dive

SOLID is the foundation of object-oriented architecture. These 5 principles work together to create flexible, maintainable systems.

SOLID

Also known as: The 5 OOP Principles

Definition: 5 OOP principles for clean architecture: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion.

Why it matters: Creates flexible, maintainable systems that can evolve without breaking existing code.

When to break this rule: Simple applications where the overhead of full SOLID compliance outweighs the benefits.

Note: We covered Single Responsibility Principle in Part 1. Here are the other 4 principles:

Open/Closed Principle (OCP)

Open for extension, closed for modification

Simple explanation: You should be able to add new features without changing existing code.

React component example

// ❌ Must modify existing code to add new behavior
const WelcomeNotification = ({ user }: { user: User }) => {
  const getMessage = () => {
    if (user.type === 'premium') {
      return 'Welcome Premium User!';
    } else if (user.type === 'basic') {
      return 'Welcome!';
    }
    // To add 'enterprise' - must modify this function
  };
  
  return <div>{getMessage()}</div>;
};

// ✅ Can extend without modifying existing code
const welcomeStrategies = {
  premium: (user: User) => `Welcome ${user.name}! Enjoy your premium features.`,
  basic: (user: User) => `Welcome ${user.name}!`,
  enterprise: (user: User) => `Welcome ${user.name}! Your enterprise dashboard awaits.`
};

const WelcomeNotification = ({ user }: { user: User }) => {
  const strategy = welcomeStrategies[user.type] || welcomeStrategies.basic;
  return <div>{strategy(user)}</div>;
};

Node.js API example

// ❌ Must modify to add new user types
app.post('/api/welcome', (req, res) => {
  const { user } = req.body;
  
  if (user.type === 'premium') {
    // Premium welcome logic
  } else if (user.type === 'basic') {
    // Basic welcome logic
  }
  // To add 'enterprise' - must modify this endpoint
});

// ✅ Extensible without modification
const welcomeHandlers = {
  premium: async (user: User) => {
    await emailService.sendPremiumWelcome(user);
  },
  basic: async (user: User) => {
    await emailService.sendBasicWelcome(user);
  }
};

app.post('/api/welcome', async (req, res) => {
  const { user } = req.body;
  const handler = welcomeHandlers[user.type] || welcomeHandlers.basic;
  await handler(user);
  res.json({ success: true });
});

Liskov Substitution Principle (LSP)

Subtypes must be substitutable for their base types

Simple explanation: If you have different implementations of the same interface, you should be able to swap them without breaking anything.

React component example

// ❌ Different components with inconsistent interfaces
const BasicButton = ({ label, onClick }: { label: string; onClick: () => void }) => {
  return <button onClick={onClick}>{label}</button>;
};

const PremiumButton = ({ 
  label, 
  onClick, 
  theme 
}: { 
  label: string; 
  onClick: (event: any) => void; // Different signature!
  theme: string; // Extra required prop!
}) => {
  return <button className={theme} onClick={onClick}>{label}</button>;
};

// ✅ Consistent interfaces - can be swapped freely
interface ButtonProps {
  label: string;
  onClick: () => void;
  theme?: string;
}

const BasicButton = ({ label, onClick, theme = 'default' }: ButtonProps) => {
  return <button className={theme} onClick={onClick}>{label}</button>;
};

const PremiumButton = ({ label, onClick, theme = 'premium' }: ButtonProps) => {
  return <button className={theme} onClick={onClick}>{label}</button>;
};

Node.js service example

// ❌ Services with inconsistent interfaces
const basicEmailService = {
  send: (to: string, subject: string, body: string) => {
    // Send basic email
  }
};

const premiumEmailService = {
  send: (to: string, subject: string, body: string, priority: 'high' | 'low') => {
    // Requires extra parameter - breaks substitution
  }
};

// ✅ Consistent interfaces - can be swapped freely
interface EmailService {
  send(to: string, subject: string, body: string, options?: any): Promise<void>;
}

const basicEmailService: EmailService = {
  send: async (to, subject, body) => {
    // Send basic email
  }
};

const premiumEmailService: EmailService = {
  send: async (to, subject, body, options = {}) => {
    // Send premium email with optional features
  }
};

Interface Segregation Principle (ISP)

Clients shouldn’t depend on interfaces they don’t use

Simple explanation: Don’t force a component or function to depend on methods it doesn’t need. Make small, focused interfaces instead of big ones.

React component example

// ❌ Fat interface - component forced to depend on methods it doesn't use
interface UserService {
  getUser(id: string): Promise<User>;
  createUser(data: any): Promise<User>;
  deleteUser(id: string): Promise<void>;
  generateReport(): Promise<string>;
  sendNotifications(): Promise<void>;
}

const UserProfile = ({ userId, userService }: { 
  userId: string; 
  userService: UserService; // Depends on methods it doesn't need
}) => {
  const [user, setUser] = useState(null);
  
  useEffect(() => {
    userService.getUser(userId).then(setUser); // Only uses getUser
  }, [userId]);
  
  return <div>{user?.name}</div>;
};

// ✅ Focused interfaces - components only depend on what they need
interface UserReader {
  getUser(id: string): Promise<User>;
}

const UserProfile = ({ userId, userReader }: { 
  userId: string; 
  userReader: UserReader; // Only depends on reading
}) => {
  const [user, setUser] = useState(null);
  
  useEffect(() => {
    userReader.getUser(userId).then(setUser); // Clear dependency
  }, [userId]);
  
  return <div>{user?.name}</div>;
};

Node.js API example

// ❌ Fat service interface
const userController = {
  getProfile: async (req, res, userService: UserService) => {
    const user = await userService.getUser(req.params.id); // Only needs getUser
    res.json(user);
  }
};

// ✅ Focused service dependencies
interface UserReader {
  getUser(id: string): Promise<User>;
}

interface UserWriter {
  createUser(data: any): Promise<User>;
  updateUser(id: string, data: any): Promise<User>;
}

const userController = {
  getProfile: async (req, res, userReader: UserReader) => {
    const user = await userReader.getUser(req.params.id);
    res.json(user);
  },
  
  updateProfile: async (req, res, userWriter: UserWriter) => {
    const user = await userWriter.updateUser(req.params.id, req.body);
    res.json(user);
  }
};

Dependency Inversion Principle (DIP)

Depend on abstractions, not concretions

Simple explanation: Don’t depend on specific implementations. Depend on interfaces so you can easily swap out different implementations.

Why “inversion”? Traditionally, high-level modules (business logic) depend on low-level modules (database, file system). DIP inverts this - both should depend on abstractions.

Node.js service example

// ❌ Traditional dependency flow - high-level depends on low-level
const UserService = () => {
  const saveUser = async (user: User) => {
    // Direct dependency on specific implementations
    await fetch('/api/mysql/users', { // Hard-coded to MySQL API
      method: 'POST',
      body: JSON.stringify(user)
    });
    
    console.log('User saved'); // Hard-coded to console logging
    // Hard to test, hard to change database or logger
  };
  
  return { saveUser };
};

// ✅ Inverted dependencies - both depend on abstractions
interface Database {
  save(user: User): Promise<void>;
}

interface Logger {
  log(message: string): void;
}

const createUserService = (db: Database, logger: Logger) => {
  const saveUser = async (user: User) => {
    await db.save(user); // Depends on abstraction
    logger.log('User saved'); // Depends on abstraction
  };
  
  return { saveUser };
};

// Easy to test with mocks, easy to swap implementations
const userService = createUserService(mysqlDatabase, consoleLogger);

React component example

// ❌ Component with hard-coded dependencies
const UserForm = () => {
  const [user, setUser] = useState({});
  
  const handleSubmit = async () => {
    // Direct dependency on specific API endpoint
    await fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify(user)
    });
    
    // Direct dependency on specific analytics service
    gtag('event', 'user_created', { user_id: user.id });
  };
  
  return <form onSubmit={handleSubmit}>...</form>;
};

// ✅ Component depends on abstractions
interface UserService {
  saveUser(user: User): Promise<void>;
}

interface Analytics {
  track(event: string, data: any): void;
}

const UserForm = ({ userService, analytics }: { 
  userService: UserService;
  analytics: Analytics;
}) => {
  const [user, setUser] = useState({});
  
  const handleSubmit = async () => {
    await userService.saveUser(user); // Depends on abstraction
    analytics.track('user_created', { user_id: user.id }); // Depends on abstraction
  };
  
  return <form onSubmit={handleSubmit}>...</form>;
};

Benefits:

• Testability: Inject mocks for testing
• Flexibility: Swap implementations without changing business logic
• Maintainability: Changes to low-level modules don’t affect high-level modules

Common Pitfall: Trying to apply all SOLID principles at once instead of gradually refactoring towards them as the system grows.

Summary

SOLID principles are the foundation of good object-oriented design. They work together to create systems that are:

• Flexible: Easy to extend and modify
• Testable: Components can be tested in isolation
• Maintainable: Changes don’t ripple through the entire system

Start with Single Responsibility and Dependency Inversion - these give you the biggest bang for your buck.

Coming next: Part 4 covers System Architecture patterns like CQRS and Hexagonal Architecture, and Part 5 explores Advanced Principles for elegant code.

Remember: good architecture is not about following every pattern - it’s about making intentional choices that serve your specific needs.

TLDR

• CQRS: Separate read/write operations for better performance
• Hexagonal Architecture: Isolate business logic from external services

In Part 3, we covered SOLID Architecture principles. Now let’s explore System Architecture patterns that help you build systems that can scale and evolve.

System Architecture Patterns

These patterns help you structure React applications and Node.js APIs, moving beyond single components to system-wide organization.

CQRS (Command Query Responsibility Segregation)

Definition: Separate read operations (queries) from write operations (commands). In React/Node.js, this means different hooks, API endpoints, and state management for reading vs writing data.

Simple explanation: Don’t use the same code path for getting data and changing data. They have different needs and performance requirements.

Why it matters: Read and write operations have different performance characteristics, caching needs, and error handling. Separating them allows each to be optimized independently.

When to use:

• Complex forms with heavy validation
• Different permissions for reading vs writing
• Performance-critical apps where reads and writes need different optimization
• Large teams where query logic and mutation logic change at different rates

When NOT to use:

• Simple CRUD operations where read/write are basically the same
• Small applications where the separation adds unnecessary complexity
• Prototypes or MVPs where you need to move fast

React custom hook example

// ❌ Mixed read/write operations - same hook for everything
const useUser = (userId: string) => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);

  const fetchUser = async () => {
    setLoading(true);
    // Complex query with joins and calculations
    const response = await fetch(
      `/api/users/${userId}?include=profile,stats,preferences`
    );
    const userData = await response.json();
    setUser(userData);
    setLoading(false);
  };

  const updateUser = async (data: any) => {
    setLoading(true);
    // Uses same complex endpoint for simple updates
    await fetch(`/api/users/${userId}`, {
      method: "PUT",
      body: JSON.stringify(data),
    });
    // Re-fetches complex data after simple update
    await fetchUser();
    setLoading(false);
  };

  return { user, loading, updateUser, fetchUser };
};

// ✅ Separated read and write hooks
const useUserQuery = (userId: string) => {
  return useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetch(`/api/users/${userId}`).then((res) => res.json()),
  });
};

const useUserMutation = () => {
  return useMutation({
    mutationFn: ({ userId, data }: { userId: string; data: any }) =>
      fetch(`/api/users/${userId}`, {
        method: "PUT",
        body: JSON.stringify(data),
      }).then((res) => res.json()),
  });
};

React component example

// ❌ Component with mixed concerns
const UserProfile = ({ userId }: { userId: string }) => {
  const { user, loading, updateUser } = useUser(userId);

  const handleNameChange = async (newName: string) => {
    // Heavy operation for simple field update
    await updateUser({ name: newName });
  };

  if (loading) return <div>Loading...</div>;
  return (
    <div>
      <h1>{user.name}</h1>
      <p>Followers: {user.stats.followers}</p>
      <button onClick={() => handleNameChange("New Name")}>Change Name</button>
    </div>
  );
};

// ✅ Component with separated concerns
const UserProfile = ({ userId }: { userId: string }) => {
  const { data: user, isLoading } = useUserQuery(userId);
  const updateUser = useUserMutation();

  const handleNameChange = (newName: string) => {
    updateUser.mutate({ userId, data: { name: newName } });
  };

  if (isLoading) return <div>Loading...</div>;
  return (
    <div>
      <h1>{user.name}</h1>
      <button onClick={() => handleNameChange("New Name")}>Change Name</button>
    </div>
  );
};

Node.js API example

// ❌ Same endpoint for different needs
app.get("/api/users/:id", async (req, res) => {
  // Heavy query for display
  const user = await db.getUserWithStats(req.params.id);
  res.json(user);
});

app.put("/api/users/:id", async (req, res) => {
  // Simple update but uses heavy query for validation
  const user = await db.getUserWithStats(req.params.id);
  await db.updateUser(req.params.id, req.body);
  res.json({ success: true });
});

// ✅ Separated by concern
// Read endpoint - optimized for display
app.get("/api/users/:id/profile", async (req, res) => {
  const user = await db.getUserWithStats(req.params.id);
  res.json(user);
});

// Write endpoint - optimized for updates
app.put("/api/users/:id", async (req, res) => {
  const exists = await db.userExists(req.params.id);
  if (!exists) {
    return res.status(404).json({ error: "User not found" });
  }

  await db.updateUser(req.params.id, req.body);
  res.json({ success: true });
});

Benefits:

• Performance: Reads and writes can be optimized independently
• Maintainability: Query logic and mutation logic can evolve separately
• Team Collaboration: Different developers can work on reads vs writes

Common Pitfall: Over-engineering simple forms where read/write are basically the same operation.

Hexagonal Architecture (Ports & Adapters)

Definition: Keep business logic separate from external services (databases, APIs). Use interfaces to connect them.

Simple explanation: Your core logic shouldn’t care where data comes from - database, file, or API.

When to use: Complex business rules that need testing independently. When NOT to use: Simple CRUD apps or prototypes.

Node.js API tightly coupled to external services

// ❌ Business logic mixed with infrastructure
app.post("/api/register", async (req, res) => {
  const { name, email } = req.body;

  if (!email.includes("@")) {
    return res.status(400).json({ error: "Invalid email" });
  }

  // Direct dependencies - hard to test
  const existing = await db.findUser(email);
  if (existing) {
    return res.status(409).json({ error: "User exists" });
  }

  await db.createUser(name, email);
  await emailService.sendWelcome(email);

  res.json({ success: true });
});

// ✅ Core business logic separated from infrastructure
// Define interfaces (ports)
interface UserRepo {
  findByEmail(email: string): Promise<User | null>;
  save(user: User): Promise<User>;
}

interface EmailService {
  sendWelcome(user: User): Promise<void>;
}

// Pure business logic
const createUserService = (userRepo: UserRepo, emailService: EmailService) => {
  const registerUser = async (userData: { name: string; email: string }) => {
    if (!userData.email.includes("@")) {
      return { success: false, error: "Invalid email" };
    }

    const existing = await userRepo.findByEmail(userData.email);
    if (existing) {
      return { success: false, error: "User exists" };
    }

    const user = await userRepo.save(userData);
    await emailService.sendWelcome(user);

    return { success: true, user };
  };

  return { registerUser };
};

// HTTP adapter
app.post("/api/register", async (req, res) => {
  const userService = createUserService(userRepo, emailService);
  const result = await userService.registerUser(req.body);

  if (result.success) {
    res.json({ user: result.user });
  } else {
    res.status(400).json({ error: result.error });
  }
});

Benefits:

• Testability: Test business logic with mocks
• Flexibility: Easy to swap databases or email services
• Maintainability: Business logic isolated from infrastructure

Common Pitfall: Over-architecting simple applications.

Summary

CQRS and Hexagonal Architecture are powerful patterns for structuring React and Node.js applications. They help you build systems that can scale, evolve, and remain testable as they grow.

CQRS helps you optimize reads and writes independently - perfect for React Query patterns and API design.

Hexagonal Architecture keeps your business logic pure and testable - ideal for complex applications with multiple integrations.

Both patterns build on the SOLID principles from Part 3 and help you create systems that can adapt to future needs without major rewrites.

Coming next: Part 5 covers Advanced Principles - the subtle patterns that separate good developers from great ones.

Remember: architecture is about trade-offs - choose patterns that solve your specific problems, not just because they’re trendy.

TLDR

• Law of Demeter: Avoid deep object chaining
• Composition over Inheritance: Combine small parts instead of extending classes
• Tell Don’t Ask: Let objects manage their own state
• Convention over Configuration: Smart defaults over explicit setup
• Principle of Least Astonishment: Behave as users expect

We’ve covered The Foundation in Part 1, Code Quality & Safety in Part 2, SOLID Architecture in Part 3, and System Architecture in Part 4.

Advanced Principles are the subtle patterns that separate good developers from great ones. These make code truly elegant and maintainable.

Advanced Principles

These principles help you write code that’s not just functional, but intuitive and pleasant to work with.

Law of Demeter (Don’t Talk to Strangers)

Definition: A function should only talk to its immediate friends - don’t reach through objects to talk to their friends.

Simple explanation: Avoid chaining calls like user.profile.settings.theme.color. Each object should only know about its direct dependencies.

Why it matters: Reduces coupling, makes code less fragile to changes, and prevents the “breaking chain” problem where changes deep in the structure break code far away.

When to use:

• Complex object hierarchies
• API design where you want to prevent tight coupling
• Component props design to avoid props drilling

When NOT to use:

• Simple utility functions or data transformations
• Well-established patterns like array.map().filter()
• Configuration objects where chaining is expected

// ❌ Violates Law of Demeter - too much chaining
const UserProfile = ({ user }: { user: User }) => {
  return (
    <div>
      <h1>{user.profile.name}</h1>
      <p style={{ color: user.settings.theme.color }}>
        Posts: {user.profile.stats.posts}
      </p>
    </div>
  );
};

// ✅ Follows Law of Demeter - service handles deep access
const getUserDisplayData = (user: User) => {
  return {
    name: user.getName(),
    textColor: user.getThemeColor(),
    postCount: user.getPostCount(),
  };
};

const UserProfile = ({ user }: { user: User }) => {
  const { name, textColor, postCount } = getUserDisplayData(user);

  return (
    <div>
      <h1>{name}</h1>
      <p style={{ color: textColor }}>Posts: {postCount}</p>
    </div>
  );
};

Benefits:

• Maintainability: Changes to deep objects don’t break surface code
• Testability: Easier to mock and test components

Common Pitfall: Creating unnecessary wrapper functions for simple property access.

Composition over Inheritance

Definition: Build complex functionality by combining simple components rather than creating complex inheritance hierarchies.

Simple explanation: Instead of creating a “BaseComponent” that others extend, create small, focused components that can be combined in different ways.

Why it matters: More flexible, easier to test, and avoids the “fragile base class” problem where changes to parent classes break child classes.

When to use:

• React component design patterns
• Building reusable UI components
• Creating flexible API interfaces
• When you need multiple behaviors that can be mixed and matched

When NOT to use:

• Simple cases where inheritance is clearer
• Well-established patterns (like extending Error classes)
• When you need polymorphism with shared behavior

// ❌ Inheritance-heavy approach
class BaseButton {
  constructor(protected text: string) {}
  render() {
    return `<button>${this.text}</button>`;
  }
}

class PrimaryButton extends BaseButton {
  render() {
    return `<button class="primary">${this.text}</button>`;
  }
}

class LoadingButton extends BaseButton {
  constructor(text: string, private loading: boolean) {
    super(text);
  }
  render() {
    return `<button disabled="${this.loading}">${
      this.loading ? "Loading..." : this.text
    }</button>`;
  }
}

// ❌ What if we need LoadingPrimaryButton? Multiple inheritance problem!

// ✅ Composition approach
interface ButtonProps {
  text: string;
  variant?: "primary" | "secondary";
  loading?: boolean;
  onClick?: () => void;
}

const Button = ({
  text,
  variant = "secondary",
  loading,
  onClick,
}: ButtonProps) => {
  return (
    <button
      className={`button ${variant}`}
      onClick={onClick}
      disabled={loading}
    >
      {loading ? "Loading..." : text}
    </button>
  );
};

// ✅ Easy to combine behaviors
const PrimaryButton = (props: Omit<ButtonProps, "variant">) => (
  <Button {...props} variant="primary" />
);

const LoadingPrimaryButton = (
  props: Omit<ButtonProps, "variant" | "loading">
) => <Button {...props} variant="primary" loading={true} />;

Benefits:

• Flexibility: Mix and match behaviors as needed
• Testability: Easy to test individual behaviors

Common Pitfall: Creating too many small components when a simple solution would work better.

Tell, Don’t Ask

Definition: Objects should tell other objects what to do, not ask them for data and make decisions for them.

Simple explanation: Instead of asking an object for its data and then deciding what to do, tell the object what you want done and let it handle the details.

Why it matters: Encapsulates logic where it belongs, reduces coupling, and makes code more maintainable by keeping related logic together.

When to use:

• State management where logic belongs with the data
• API design where you want to encapsulate business rules
• React components that should manage their own state
• Reducing prop drilling and state management complexity

When NOT to use:

• Simple data structures without behavior
• When you genuinely need raw data for multiple purposes
• Pure calculation functions that transform data

// ❌ Asking for data and making decisions externally
const ShoppingCart = () => {
  const [cart, setCart] = useState({ items: [], discount: 0 });

  const handleCheckout = () => {
    // Asking for data and calculating externally
    let total = 0;
    cart.items.forEach((item) => {
      total += item.price * item.quantity;
    });
    checkout(total);
  };

  return <button onClick={handleCheckout}>Checkout</button>;
};

// ✅ Tell objects what to do
class ShoppingCartModel {
  private items: CartItem[] = [];

  calculateTotal(): number {
    return this.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );
  }

  checkout(): CheckoutData {
    return { items: this.items, total: this.calculateTotal() };
  }
}

// ✅ React component tells the cart what to do
const ShoppingCart = () => {
  const [cart] = useState(() => new ShoppingCartModel());

  const handleCheckout = () => {
    const checkoutData = cart.checkout(); // Tell the cart to checkout
    processCheckout(checkoutData);
  };

  return <button onClick={handleCheckout}>Checkout</button>;
};

Benefits:

• Encapsulation: Business logic stays with the data
• Maintainability: Changes to rules happen in one place

Common Pitfall: Creating overly complex objects when simple data structures would suffice.

Convention over Configuration

Definition: Provide sensible defaults and follow established patterns so developers don’t have to configure everything explicitly.

Simple explanation: Make the common case easy by having smart defaults. Only require configuration for the uncommon cases.

Why it matters: Reduces boilerplate, speeds up development, and makes codebases more predictable by following established patterns.

When to use:

• Folder structure organization
• API endpoint naming
• Component file naming and organization
• State management patterns
• Default configurations

When NOT to use:

• When your needs genuinely differ from conventions
• When conventions would confuse your team
• When explicit configuration improves clarity

// ❌ Everything requires explicit configuration
const routes = {
  users: {
    list: { path: "/api/users", method: "GET", handler: "UserController.list" },
    create: {
      path: "/api/users",
      method: "POST",
      handler: "UserController.create",
    },
    get: {
      path: "/api/users/:id",
      method: "GET",
      handler: "UserController.get",
    },
  },
};

// ❌ Manual API client configuration
const apiClient = new ApiClient({
  baseURL: "https://api.example.com",
  timeout: 5000,
  headers: { "Content-Type": "application/json" },
  errorHandler: (error) => {
    /* custom error handling */
  },
});