From setup to multi-agent workflows
Claude Code
Best Practices
Press → to start
01 — CLAUDE.md
The Golden Rule
- Loaded into every session — injected before your first message
- Include only what Claude cannot infer from code and that changes behavior
- Removal test: "Would removing this cause mistakes?" No → cut it
- Structure: WHAT (stack) / WHY (one line) / HOW (conventions, gotchas)
Concise & Imperative
## Code Conventions
- TypeScript strict mode, no `any`.
- Named exports only.
- Prefer `const` arrow for components.
- TypeScript strict mode, no `any`.
- Named exports only.
- Prefer `const` arrow for components.
Verbose Prose
When writing TypeScript, we always use strict mode. The reason for this is that it catches more errors at compile time. We also don't use `any`…
01 — CLAUDE.md
Three-Level Hierarchy
| Level | Location | Target | Tokens |
|---|---|---|---|
| Global | ~/.claude/CLAUDE.md | < 30 lines | ~150 |
| Project | <root>/CLAUDE.md | < 100 lines | ~700 |
| Directory | <subdir>/CLAUDE.md | < 10 lines | ~70 |
| Combined | < 150 lines | < 1,500 |
- More specific overrides general — directory beats project beats global
- Directory files only load when Claude works in that subtree
- Global skills & agents also load everywhere — only install if truly universal
Size Impact
At 500+ lines (~3,500 tokens, 1.75% of context): review for bloat.
At 2,000+ lines (~14K tokens, 7%): Claude starts ignoring instructions.
01 — CLAUDE.md
Format & Tooling
Format Rules
- Imperative mood — "Use named exports" not "We prefer…"
- Bullets & tables only — no prose paragraphs
- Two nesting levels max — keep flat
- Critical rules at the top — primacy bias
Tooling
/init— bootstrap CLAUDE.md from codebase.claude/rules/*.md— split into topic files (auto-loaded)/claude-md-improver— audit for staleness, gaps, redundancy
02 — Context Management
The 200K Token Budget
System prompt, CLAUDE.md, MCP schemas, conversation, tool results — all share one window.
| Context Usage | Quality | Speed |
|---|---|---|
| < 50K tokens | Optimal recall | Fast |
| 50K – 100K | Good, occasional misses | Moderate |
| 100K – 150K | Noticeable degradation | Slower |
| 150K+ | Auto-compresses, detail lost | Slowest |
The hidden cost: input compounds. Every turn re-sends full history.
20 turns × 100K avg = 2M tokens processed.
Same work in 4 sessions × 25K = 500K → 4× cheaper.
20 turns × 100K avg = 2M tokens processed.
Same work in 4 sessions × 25K = 500K → 4× cheaper.
02 — Context Management
Staying Lean
Key Commands
/compact [hint]— compress conversation (at ~80%)/clear— wipe everything (on topic switch)/usage— monitor token usage
Auto-Compaction
Triggers at 83.5% (~167K). Each pass is lossy:
~80% → ~60% → ~40% fidelity. CLAUDE.md bypasses this — reloaded every turn.
6 Lean Strategies
- Precise questions — one file, not "how does auth work?"
- Let Claude read files — tool results compress; pastes don't
- Scope tools tightly — specific globs, not repo-wide
- Offload to subagents — parent gets summary
- /clear between topics
- Monitor with /usage
Target: keep active context under 100K for quality.
03 — Long-Term Memory
Stateless by Design
Claude forgets everything between sessions. "Memory" = markdown files injected at startup.
Both CLAUDE.md & MEMORY.md reload every turn — they bypass auto-compaction and survive /compact.
Load Order
~/.claude/CLAUDE.md— global preferences<project>/CLAUDE.md+ subdirectories~/.claude/projects/<hash>/MEMORY.md— personal memories- Session files via
/addor@
CLAUDE.md
- Manual — written by you/team
- Committed to git (shared)
- Prescriptive: "do X, don't do Y"
- Stable, intentional directives
MEMORY.md
- Auto — Claude decides what to save
- Local only (never in git)
- Descriptive: learnings & corrections
- 200-line hard limit
03 — Long-Term Memory
Auto Memory & Lifecycle
4 Memory Types
Saved to ~/.claude/projects/<hash>/memory/
- User — role, preferences, expertise
- Feedback — corrections from sessions (most important)
- Project — architecture, decisions, ongoing work
- Reference — pointers to external systems
200-Line Limit
Only first 200 lines loaded. Use MEMORY.md as a concise index → topic files for details.
Capture → Promote → Prune
Session correction
↓ "remember this" / /memory
MEMORY.md (raw, personal)
↓ promote validated items (weekly)
CLAUDE.md (structured, shared)
↓ prune stale entries (monthly)
/dev/null
Without this cycle, MEMORY.md bloats and important things get truncated past line 200.
04 — The Toolbox
Everything in One Place
Claude Code has a lot of moving parts. This is the complete map — what each piece does, when it fires, and what it costs you.
Configuration & Instructions
| Mechanism | What It Is | Triggered By | Context Cost | Best For |
|---|---|---|---|---|
| CLAUDE.md | Markdown instructions loaded every session | Automatic (startup) | ~500–1,500 tok | Project conventions & rules |
Rules .claude/rules/ |
Path-scoped instructions (YAML frontmatter + markdown) | Automatic (when matching files are touched) | On demand only | File-type-specific guidelines |
Settings settings.json |
Permissions, model choice, hooks config, allowed/denied tools | Automatic (startup) | Zero (config only) | Permissions & guardrails |
Memory MEMORY.md |
Auto-saved notes from corrections & preferences | Automatic (first 200 lines at startup; rest on demand) | ~200–500 tok | Persistent cross-session learning |
04 — The Toolbox
Slash Commands (3 Types)
Slash commands look the same but work very differently under the hood.
| Type | What It Is | Triggered By | Context Cost | Examples |
|---|---|---|---|---|
| Built-in Commands | CLI actions — no model involvement at all. 30+ commands. | User types /command |
Zero | /clear /compact /cost /model /init /doctor /memory /permissions /mcp /hooks /status |
| Skill-Based Commands | Invoke the Skill tool → loads specialized prompt + tools into context | User types /command |
On demand (when invoked) | /commit /review-pr /simplify /loop /batch /debug /claude-api |
| Custom Commands / Skills | Markdown templates (.claude/commands/ or .claude/skills/) |
User types /project:name or auto-match |
On demand (full template injected) | /project:fix-lint /user:standup |
The difference matters: Built-in commands are free. Skill-based commands load instructions into context (tokens). Custom commands inject their entire markdown file as a prompt.
04 — The Toolbox
Agents & Execution
These control how work gets done — delegation, parallelism, and isolation.
| Mechanism | What It Is | Triggered By | Context Cost | Best For |
|---|---|---|---|---|
| Subagents | Child agents with isolated context | Model (Task tool) | Own window (isolated) | Heavy research & parallel work |
| Agent Teams | Multi-agent coordination with mailbox communication | Model or user request | 1M per agent (isolated) | Large-scale parallel refactors |
| Custom Agents | Named personas with specialized prompts | User (--agent flag) |
Prompt overhead only | Consistent review / audit roles |
| Worktrees | Isolated git working directories per agent | User (--worktree) or Agent Teams |
Zero (filesystem only) | Safe parallel edits without conflicts |
04 — The Toolbox
When to Use What
The mental model: three layers, one key distinction.
Guide Behavior (Advisory)
- CLAUDE.md — what Claude should always know
- Rules — what Claude should know per file type
- Memory — what Claude learned across sessions
- Commands / Skills — reusable prompts & workflows
- Custom Agents — specialized personas
Extend & Enforce
- Settings — what Claude is allowed to do
- Hooks — what must happen (only deterministic one)
- MCP Servers — what Claude can reach
- Plugins — full extension packages (skills + agents + hooks + MCP)
- Subagents / Agent Teams / Worktrees — how work is split & isolated
Key insight:
MCP extends what Claude can do (new tools).
Hooks enforce what Claude must do (deterministic).
Settings control what Claude can see and touch.
Everything else guides what Claude should do (advisory).
05 — Slash Commands
Built-in Commands
Handled by the CLI — no model involvement, zero token cost.
/helpShow commands & shortcuts/clearWipe conversation history/compact [hint]Compress conversation/context <path>Add files/dirs/URLs/initGenerate starter CLAUDE.md/modelSwitch model mid-session/costToken & cost usage/reviewReview uncommitted changes/doctorDiagnose environment/configManage settings
05 — Slash Commands
Skill-Based & Custom
Skill-Based
Load specialized instructions into context on demand.
/commit auto-commit with message/review-pr <num> review a GitHub PR/simplify 3 parallel agents + auto-fix/loop [interval] recurring tasks/batch parallel with worktree isolation/frontend-design production-grade UI/gsd:* GSD framework phasesCustom Commands
Markdown templates with $ARGUMENTS placeholder.
# .claude/commands/test.md
Write unit tests for: $ARGUMENTS
Requirements:
- Use existing test framework
- Cover happy path + edge cases
Write unit tests for: $ARGUMENTS
Requirements:
- Use existing test framework
- Cover happy path + edge cases
.claude/commands/ → /project:name
~/.claude/commands/ → /user:name
06 — Skills
Claude's Package Ecosystem
SKILL.md= YAML frontmatter + markdown instructions — zero permanent context cost- Auto-triggered by description match, or manually via
/command - Hot reload (edit + test instantly) + forked context (runs in isolation)
Install & Scope
/plugin— interactive browser/plugin install <source>— from GitHub- Manual — drop in
.claude/skills/
Project skills = this project only.
Global skills = everywhere (loads every session).
Top Skills
| Frontend Design | Distinctive UI (277K+) |
| Simplify | 3 agents review + fix |
| CLAUDE.md Improver | Audit & optimize |
| Skill Creator | Generate new skills |
| Planning w/ Files | Plans as markdown |
Browse official plugins: github.com/anthropics/claude-code/tree/main/plugins
07 — MCP Servers
External Systems via JSON-RPC
Servers spawn on startup → tools discovered → schemas injected into system prompt.
Every tool schema = fixed token cost per turn, whether used or not.
| Server | Tools | Token Overhead |
|---|---|---|
| Context7 | 2–4 | ~800 – 1,500 |
| Notion | 8–12 | ~2,500 – 4,000 |
| GitHub | 10–15 | ~3,000 – 5,000 |
| Playwright | 15–20 | ~5,000 – 8,000 |
| Jira | 20+ | ~17,000 |
| 5 servers loaded | ~58 | ~55,000 |
55K tokens consumed before your first message.
07 — MCP Servers
Optimization
Tool Search (Deferred Loading)
Tools registered by name only (~10 tokens each). Full schemas fetched on demand.
51K → 8.5K = 95% reduction
On-Demand Strategy
- Always active — core workflow (GitHub, Context7)
- On-demand —
mcp-on playwright/mcp-off - Document strategy in CLAUDE.md
Decision Tree
Need external API?
→ MCP Server
Reusable prompt workflow?
→ Skill
Heavy/parallel subtask?
→ Subagent
Otherwise
→ Built-in tools
08 — Autonomous Loops
RALPH — Filesystem as Memory
A while loop that invokes Claude with the same prompt. Each iteration = fresh session. State lives on disk.
The 5-Step Cycle
- Read — PRD, progress file, codebase
- Plan — gap analysis, update implementation plan
- Log — AGENTS.md with learnings for next iteration
- Execute — implement next item, commit, mark done
- Repeat — until all items checked off
Why It Works
- Git as memory — avoids repeating mistakes
- Fresh context — no degradation over time
- Self-healing — failed iterations leave artifacts
- PRD-driven — clear success criteria
while true; do
claude -p "Read PRD.md and
PROGRESS.md. Implement next
unchecked item. Commit."
sleep 10
done
claude -p "Read PRD.md and
PROGRESS.md. Implement next
unchecked item. Commit."
sleep 10
done
08 — Autonomous Loops
/loop & When to Use What
/loop [interval] <prompt or /command> — default 10m, max 50 concurrent, 3-day expiry. Dies with terminal.
RALPH (External Script)
- Multi-hour autonomous dev
- PRD-driven feature implementation
- Survives session restart
- Fresh context every iteration
/loop (Built-in)
- Deploy / CI monitoring
- PR babysitting
- Recurring quality checks
- Quick interval-based tasks
/loop 5m check the deploy status
/loop 30m /simplify
/loop 1h run tests and fix failures
/loop 30m /simplify
/loop 1h run tests and fix failures
Guardrails: --max-budget-usd for cost caps · max iteration count in scripts · periodic git diff review
09 — Multi-Agent
Decompose Across Agents
Subagents (Task Tool)
- Child agent with isolated context
- Runs autonomously, returns summary only
- Parent stays clean — child does heavy lifting
- Best for: research, multi-file reads
Agent Teams (experimental)
- Each agent: own git worktree + 1M-token context
- Team Lead plans & delegates; specialists execute in parallel
Deep dive on next slide →
Worktrees
claude --worktree name (add --tmux)
Each gets independent builds, tests, branches.
When to Use What
- Subagents — research, multi-file reads
- Agent Teams — large coordinated refactors
- Worktrees — manual parallel sessions
09 — Multi-Agent
Agent Teams — Swarm Mode
Architecture: Team Lead plans & delegates (never writes code).
Specialist agents (Frontend, Backend, Testing, Docs, Architecture) each get their own
git worktree + 1M-token context.
Enable:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
How It Works
- Plan — Lead creates task breakdown with dependencies
- Spawn — Specialist agents launched in isolated worktrees
- Execute — Agents work in parallel; coordinate via task board + @mentions
- Synthesize — Lead merges results and resolves conflicts
Best Use Cases
- Large refactors across many files
- Multi-layer features (frontend + backend + tests simultaneously)
- Debugging with competing hypotheses
- Research tasks with parallel exploration
Team Patterns
| Pattern | How | When |
|---|---|---|
| Leader | Delegate & synthesize | Default — most tasks |
| Swarm | Peer-to-peer comms | Large refactors |
| Pipeline | Sequential handoff | Code → test → review |
| Watchdog | Long-running + gates | CI monitoring |
Token cost: 4–15× more than single agent.
Reserve for high-value, complex tasks.
Powered by TeammateTool (13 ops: spawn, lifecycle, coordination, sync).
Reserve for high-value, complex tasks.
Powered by TeammateTool (13 ops: spawn, lifecycle, coordination, sync).
09 — Multi-Agent
Swarm Mode in Practice
Custom Agents + Context Architecture
🤖 Claude Code
│
├─ 👷 shadcn-expert .claude/
│ ├ shadcn theme MCP ├─ Task/
│ └ shadcn component MCP │ └─ context_01.md
│ │
├─ 🔒 vercel-ai-sdk-expert ├─ Doc/
│ └ latest vercel ai sdk │ ├─ ui-implementation.md
│ v5 docs │ ├─ vercel-ai-sdk-plan.md
│ │ └─ stripe-integration-plan.md
├─ 🎨 stripe-expert │
│ └ latest stripe docs │
│ │
└─ 📚 context7 │
Each agent has specialised MCP servers and writes context files for the team.
Agent Teams Terminal UI
Background tasks
12 agents
❯ @team-lead
Team: x-dl-web-interface (12)
@tester: Reading 5 files…
@config-setup: Reading ~/x-dl
@styler: Editing web/src/App.css
@app-integrator: working
@component-creator: Running Verify all components
@api-server: Running List all task dirs
@vite-setup: idle
@qa-tester: Reading web/vite.config.ts
@backend-builder: Reading 4 files…
@component-builder: Reading 3 files…
@frontend-builder: Running env | grep CLAUDE_CODE
Real-time view: 12 specialist agents working in parallel, each with its own worktree.
09 — Multi-Agent
Choosing the Right Tool
| Subagents | Agent Teams | Swarm Mode | /batch | |
|---|---|---|---|---|
| Coordination | None | Dep tracking + mailbox | Peer-to-peer comms | None |
| Isolation | Shared worktree | Own worktree | Own worktree | Auto worktree |
| Context | Parent's | 1M each | 1M each | Independent |
| Token cost | Low | 4–15× | 4–15× | Per-task |
| Best for | Research | Coordinated features | Large refactors | Similar edits |
Worktrees
claude --worktree name (add --tmux)
Each gets independent builds, tests, branches.
Hooks
Pre/post tool callbacks in .claude/settings.json.
Auto-format, audit logging, security gates.
Integrations
- VS Code — official extension, inline panels
- JetBrains — CLI +
--ideflag - GitHub —
/review-pr,--from-pr 123, Actions CI - Chrome —
--chromefor visual debugging
10 — GSD Framework
Solving Context Rot
The problem: Claude degrades at 40–50% context utilization.
Traditional: one long session → quality decays.
GSD: keep sessions small and fresh — state lives in files.
Traditional: one long session → quality decays.
GSD: keep sessions small and fresh — state lives in files.
5 Core Principles
- Context Engineering — thin orchestrators delegate to fresh subagent contexts
- Spec-Driven — every task has explicit success criteria, no vibe coding
- Aggressive Atomicity — 2–3 tasks per plan, each fits ~50% of a fresh window
- Wave Parallelism — Wave 1 (blocking) → Wave 2 (parallel) → Wave 3 (dependent)
- Goal-Backward Verification — verify output against goals, 1 commit = 1 task
Install: npx get-shit-done
10 — GSD Framework
The Lean Orchestrator
┌──────────────┐
│ Orchestrator │ ← reads specs, assigns, tracks
└──────┬───────┘
│
┌────┴────┬────────┐
▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐
│Sub 1│ │Sub 2│ │Sub 3│ ← fresh 200K each
└─────┘ └─────┘ └─────┘
↓
File-based state
4 Phases
Design → Plan → Execute → Verify
/gsd:new-project · /gsd:plan-phase · /gsd:execute-phase
Traditional
- One long session
- Quality degrades (rot)
- Ad-hoc task granularity
- Unclear commit history
GSD
- Fresh context per task
- Consistent quality
- 2–3 tasks/plan, atomic
- 1 commit = 1 task
11 — Desktop App
Claude Code on Desktop
The Code tab in Claude Desktop runs the same engine as the CLI — with a visual layer on top.
Visual Workflow
- Diff review — review changes file-by-file with inline commenting before creating PRs
- App preview — embedded browser; Claude starts dev servers, takes screenshots, and auto-verifies changes
- PR monitoring — CI status bar with auto-fix (Claude fixes failing checks) and auto-merge (squash when green)
- Connectors — one-click MCP setup for GitHub, Slack, Linear, Notion — no JSON editing
Sessions & Environments
- Parallel sessions — sidebar tabs, each with automatic Git worktree isolation
- Scheduled tasks — recurring tasks (daily code reviews, dependency checks) that fire automatically
- Remote/cloud sessions — run on Anthropic's cloud, continue after closing the app, monitor from web or mobile
- SSH sessions — connect to cloud VMs, dev containers, or remote servers through the desktop UI
Run
/desktop in the CLI to move your current session into the app.
11 — Desktop App
Desktop vs CLI
| Feature | CLI | Desktop |
|---|---|---|
| Diff review | text-based | Visual + inline comments |
| App preview | — | Embedded browser, auto-verify |
| PR monitoring | Manual | CI bar, auto-fix, auto-merge |
| Sessions | Separate terminals | Sidebar tabs + auto worktrees |
| Recurring tasks | cron / CI pipelines | Built-in scheduled tasks |
| File attachments | — | Images, PDFs, drag-and-drop |
| Remote / cloud | — | Anthropic-hosted, persist on close |
| SSH sessions | — | Connect via desktop UI |
| Scripting | --print, Agent SDK | — |
| Third-party providers | Bedrock, Vertex, Foundry | — |
| Agent teams | Supported | — |
Shared config: CLAUDE.md, MCP servers, hooks, skills, and settings all carry over between Desktop and CLI.
That's it. The rest is practice.
Build something great.
Press ← to go back