Claude Code Best Practices: What 74 Plans Taught Me

TL;DR -- Claude Code is dramatically more effective when you treat context as a finite resource and build systems around that constraint. After 17 phases, 74 plans, and a separate 9-phase content pipeline, I've distilled what works into 5 pillars: an 8-layer memory hierarchy in CLAUDE.md, skill-based on-demand knowledge, Agent Teams for parallel execution, iterative visual design loops, and disciplined context engineering. This guide covers all five with real metrics.

Most Claude Code Guides Miss the Point

Here's what I've learned after building an entire production portfolio site and a 7-skill content pipeline entirely with Claude Code: the tool is only as good as the system you build around it. Most guides I've seen stop at "install Claude Code, write your first prompt, build a simple app." That's like teaching someone to drive by showing them the ignition switch.

I've shipped 17 phases and 74 plans through a structured execution framework for a Next.js portfolio site. Separately, I built a 9-phase content generation pipeline with 47 requirements and 7 orchestrated skills. The design review scores on that portfolio site consistently hit 9+/10 for design and usability. None of that happened by accident -- it happened because I figured out how to make Claude Code's context system work for me instead of against me.

This guide covers the five things that actually matter. If you want copy-paste-ready configs and deeper documentation, the companion GitHub repo has everything.

The 8-Layer Memory Hierarchy: How Claude Code Best Practices Start with CLAUDE.md

Every Claude Code session loads context in layers. Understanding what loads when -- and what it costs -- is the single most important thing you can learn. Get this wrong and you'll burn context on instructions Claude doesn't need. Get it right and every session starts with exactly the right knowledge.

Here's the full 8-layer hierarchy I use across all my projects:

The critical insight: layers 1-5 are always-on. They load every single session regardless of what you're doing. That makes them expensive. Skills (layer 8) load their description (~1 line) at startup and the full content only when invoked. That makes them cheap. The memory hierarchy deep-dive in the companion repo walks through each layer with configuration examples.

I keep my global CLAUDE.md at 73 lines. It contains identity, core rules, model preferences, session management, compaction instructions, and the memory hierarchy table itself. Everything else goes into skills or project-level files. If it doesn't need to apply to every interaction, it doesn't belong in the always-on layers.

One Gotcha Worth Knowing

There's a known bug (GitHub #16299) where path-scoped rules in .claude/rules/ load globally instead of only for matching file paths. This means every rule file you create adds to your always-on context cost. I keep my global rules to 4 files with 29 total directives. Concise rules, not essay-length documentation.

Key Takeaway: The first 5 layers (Global CLAUDE.md through Project Local) load every session and cost you context whether you need them or not. Skills load their full content only on invocation. Put always-needed rules in CLAUDE.md, reference material in skills.

Skills vs CLAUDE.md: When to Use On-Demand Knowledge

The sizing decision between CLAUDE.md and skills is straightforward once you have a framework. I cover this in detail in the skills strategy guide, but here are the guidelines I use consistently:

• Under 50 lines: Inline in CLAUDE.md. The overhead of a skill file isn't worth it.
• 50-300 lines: Create a skill. It loads on demand, keeping your always-on context clean.
• 300-500 lines: Split across multiple skills with clear boundaries.
• Over 500 lines: Split and summarize. No single skill should be a knowledge dump.

The real power of skills shows up in composition. My generate-article skill orchestrates three other skills: article-writer, svg-generator, and seo-validator. The orchestrator skill knows when to invoke each composed skill, what inputs to pass, and how to handle the outputs. It never reimplements stage logic -- it coordinates.

This composition pattern means each skill stays focused. The article-writer handles a 7-stage SEO writing pipeline. The svg-generator handles motif selection, SVG rendering, and compliance checks. The seo-validator runs 25 deterministic checks. The orchestrator ties them together into a 5-stage macro pipeline: Brief, Write, SVG, Specialist, Validate.

I built 7 skills for my content generation pipeline, and the total always-on cost at session startup is roughly 7 lines (one description per skill). The full skill content -- over 2,000 lines across all 7 -- only loads when I actually need it. That's the difference between skills and CLAUDE.md: on-demand vs always-on.

Key Takeaway: Skills excel at composition -- orchestrator skills coordinate multiple specialized skills without reimplementing their logic. My generate-article skill orchestrates article-writer, svg-generator, and seo-validator, keeping each skill focused and the orchestrator lean.

Practical Example: Visual Design Review

My visual-design-review skill is ~200 lines covering Playwright MCP screenshot capture, 4-dimension scoring criteria, and the iterative review loop. If I put that in CLAUDE.md, every coding session would waste context on design review instructions. As a skill, it costs 1 line at startup and loads fully only during design review cycles.

How Claude Code Agent Teams Transform Parallel Workflows

Agent Teams let you spawn multiple Claude instances working in parallel on related tasks. The Agent Teams guide in the companion repo covers setup and advanced patterns. I've used three patterns extensively:

Pattern 1: Parallel Page Build

For my portfolio site, I needed multiple pages built simultaneously. The lead agent (always Opus) coordinated the overall architecture -- shared component library, routing structure, design tokens -- while teammates (Sonnet for standard pages, Opus for complex ones) built individual pages in parallel. Each teammate received the same design system reference and component API, so their outputs composed cleanly. This cut build time dramatically compared to sequential page-by-page construction.

Pattern 2: Design Review Team

Visual QA, accessibility checking, and responsive testing can all run simultaneously. I spawn a team where each teammate handles one dimension:

• Visual QA agent: Screenshots at 6 breakpoints (375, 768, 1024, 1280, 1440, 1920px), scores design and usability
• Accessibility agent: WCAG compliance, color contrast, keyboard navigation
• Responsive agent: Layout integrity across breakpoints, touch targets on mobile

Pattern 3: Research + Implement

For pillar content, I use a researcher teammate to gather and analyze sources while a writer teammate produces the article. The researcher runs with Opus for depth, the writer runs with Opus for quality. The lead synthesizes their outputs and enforces voice consistency.

Model Selection Strategy

Not every task needs the most powerful model. I apply this consistently:

The cost difference matters. Agent Teams use approximately 3-4x the tokens of a single session (Anthropic, 2026). With Opus as lead and 2 Sonnet teammates, a pillar article costs $8-12. With all-Opus teammates, it's higher but the quality ceiling rises measurably. I apply the same systematic approach to cost-performance tradeoffs that I use for iterative speed optimization -- measure, adjust, and find the sweet spot.

Orchestration in Practice

Knowing the patterns is one thing -- running them smoothly is another. After a dedicated orchestration hardening phase, I settled on a setup that eliminates friction.

Agent Teams run in tmux mode (teammateMode: "tmux" in settings.json), giving each teammate its own terminal pane. A launch-team.sh script kills any stale tmux session, creates a fresh one in the project directory, and launches Claude -- one command, clean slate every time. A shell alias (cddi) makes this a single keystroke from any terminal. The launch script example is in the companion repo.

Four coordination rules keep teams productive. Context injection: teammates start with amnesia, so always inject project libraries, patterns, and file paths into spawn prompts. File ownership: assign each teammate to non-overlapping paths -- two teammates writing the same file causes conflicts and lost work. Task sizing: 5-6 tasks per teammate is the sweet spot; fewer underutilizes parallelism, more causes context overload. Shutdown protocol: always clean up through the Lead agent, never kill tmux panes directly.

For subagents (single-task agents within a session), two defaults apply: use parallel subagents for independent tasks like file search and codebase exploration, and sequential subagents for debugging where each step depends on prior findings. For long-running operations like test suites, use run_in_background to keep the main thread free.

Key Takeaway: Agent Teams cost 3-4x the tokens of single sessions, but the parallelization speedup is dramatic. Use Opus for the lead (always), Sonnet for standard teammates, and escalate to Opus for complex architecture or security-critical work. Each teammate needs its own context via injection -- they start with amnesia.

The Visual Design Loop: How I Hit 9+/10 Design Scores

Most developers treat visual design as "write CSS, check in browser, ship." I document my full process in the visual design loop guide. In short, I run a structured loop with measurable scoring that consistently produces polished results.

The Four-Step Cycle

1. Build: Write the component HTML/CSS/JSX
2. Screenshot: Capture at multiple breakpoints using Playwright MCP
3. Review & Score: Evaluate against 4 dimensions with specific thresholds
4. Adjust: Apply targeted CSS fixes based on scored feedback

I limit this loop to 3-5 cycles per component. More than that means the approach is wrong, not the execution.

Scoring Criteria

Every design review cycle produces scores across four dimensions:

These aren't arbitrary numbers. After running dozens of design review cycles on the Ben Ryan portfolio site, I found that scores below 9/10 on design and usability correlate directly with issues users notice. The 8/10 threshold for creativity and content gives room for functional designs that don't need to be artistic masterpieces.

Over 17 phases of iterating on my portfolio site, the pattern became clear: the first cycle typically scores 6-7/10, the second hits 8/10, and by the third cycle you're at 9+/10 with targeted CSS fixes. The gains per cycle follow a steep curve -- most of the value comes from cycles 1-3.

What Makes This Work

The key is that the screenshot-review-adjust loop gives Claude concrete visual feedback rather than abstract descriptions. When Playwright MCP captures a screenshot at 375px wide and the review agent can see that the navigation overlaps the hero section, the fix is specific: "Add flex-direction: column to .nav-container below 768px." This is fundamentally different from "make the mobile navigation work better." I use this same philosophy of measurement-driven iteration when choosing hosting infrastructure -- quantify the problem, then fix it.

Key Takeaway: The screenshot-review-adjust loop produces 9+/10 design scores in 3-5 cycles. First cycle typically scores 6-7/10, second hits 8/10, third reaches 9+/10. Visual feedback beats abstract descriptions -- Claude sees the actual layout issue and fixes it specifically.

Context Engineering: 7 Rules for Managing Claude Code's Finite Resource

Context is the scarcest resource in Claude Code. Every token in the context window competes for attention. I expand on each of these in the context engineering guide. These 7 rules emerged from building two production projects with a combined 26 phases and 121 plans worth of execution.

Rule 1: CLAUDE.md Is Always-On (Expensive)

Only put things in CLAUDE.md that must apply to every single interaction. My global CLAUDE.md is 73 lines. My project CLAUDE.md files are under 200 lines. If you're over 500 lines, you're paying for context you don't use in most sessions.

Rule 2: Skills Are On-Demand (Cheap)

Put reference material, detailed procedures, and specialized knowledge in skills. They cost ~1 line at startup. The full content loads only when invoked. I have 7 skills in my content pipeline and 3 global skills -- total startup cost is roughly 10 lines across all of them.

Rule 3: Subagents Are Isolated Context

When you need to explore a codebase or research something, spawn a subagent. It runs in its own context window. Only the summary returns to your main session. This keeps your primary context clean for the work that matters. I use Haiku subagents for file search and codebase exploration -- they're fast, cheap, and the summary they return is typically all I need in the main session.

Rule 4: Agent Teams Are Parallel Isolated Contexts

Each teammate in an Agent Team has its own context window. The lead coordinates by passing structured inputs and collecting outputs. This means you can parallelize without polluting your main context with intermediate work from all threads.

Rule 5: Tell Claude What to Keep During Compaction

When context gets large, Claude compacts it. You control what survives by specifying compaction rules in CLAUDE.md. I always preserve: modified files and their purpose, current phase/task, test/build commands and results, design review feedback and scores, and architectural decisions made in the session.

Rule 6: Use /clear Between Unrelated Tasks

A clean session with a good prompt beats a long session with accumulated corrections. I use /clear between unrelated tasks. This is the cheapest way to reset context and start fresh with exactly the instructions you need.

Rule 7: Course-Correct Early

After 2 failed correction attempts, stop iterating. Use /clear and start fresh with a better prompt. This is counterintuitive -- it feels like you're losing progress. But a session that's going wrong rarely recovers by pushing harder. A fresh start with a refined prompt is almost always faster. I've learned this the hard way -- sessions where I pushed past the second failed correction ended up taking 3-4x longer than starting fresh would have.

Frequently Asked Questions

What's the minimum setup to start using Claude Code effectively?

Start with a project CLAUDE.md file under 100 lines covering your project's identity, tech stack, core rules, and coding conventions. The official Claude Code documentation covers installation and basic setup. Add skills for anything over 50 lines of reference material. This foundation takes 30 minutes to set up and pays for itself in the first session.

How much does an Agent Teams workflow cost compared to single-session work?

Agent Teams use approximately 3-4x the tokens of a single session. With Opus as lead and Sonnet teammates, expect $4-8 for standard tasks and $8-12 for pillar content. All-Opus teams cost more but produce measurably better results for complex architecture and quality-critical content.

Should I use Opus or Sonnet for my Agent Team teammates?

Use Sonnet as your default teammate model. Escalate to Opus for: complex architecture decisions, security-critical code (the same rigour I apply to WordPress security), performance-sensitive implementations, intricate animation choreography, and tasks requiring deep cross-codebase reasoning. Use Haiku for read-only subagents doing file search or codebase exploration.

How do I know if my CLAUDE.md is too long?

If your CLAUDE.md exceeds 200 lines at the project level or 100 lines globally, audit it. Move anything that doesn't apply to every session into skills or child directory CLAUDE.md files. The goal is a lean always-on context that loads the minimum instructions needed for every interaction.

Can I use the visual design loop without Playwright MCP?

Yes, but with reduced effectiveness. You can manually screenshot and paste images into Claude Code. Playwright MCP automates the capture at specific breakpoints, which makes the 3-5 cycle loop practical. Without automation, you'll likely limit yourself to 1-2 cycles per component.

Build the System, Then Let It Work

The common thread across all five of these practices is systems thinking. CLAUDE.md architecture is a system for loading the right context. Skills are a system for on-demand knowledge. Agent Teams are a system for parallel execution. The visual design loop is a system for measurable quality. Context engineering is a system for resource management.

After 17 phases and 74 plans on one project, plus 9 phases and 47 requirements on another, I'm convinced that the developers getting the most out of Claude Code aren't the ones writing better prompts -- they're the ones building better systems around the tool. The companion repo has the actual configs, skill files, and deep-dive documentation if you want to implement any of this yourself -- including example CLAUDE.md files for Next.js, content pipelines, and monorepo workspaces.

Claude Code is powerful. But power without structure is just expensive chaos. Build the structure first.