The Complete Claude Code Guide: From First Steps to Multi-Agent Workflows

18 min read

claude-code, multi-agent, workflow, automation, ai-development, tutorial, guide

A practitioner's guide to Claude Code: workspace setup, daily commands, MCP tools, multi-agent orchestration, and production workflows.


From skeptic to power user: everything I learned building multi-agent AI workflows.


Table of Contents

Part 1: Getting Started

Part 2: Multi-Agent Fundamentals

Part 3: Advanced Orchestration

Part 4: Production Workflows

Appendix


Part 1: Getting Started

My Journey to Claude Code

I didn't start as a believer.

When Claude Code first launched, I was skeptical. Another AI coding tool? I'd seen too many demos that promised revolution and delivered autocomplete. My workflow was fine. VS Code, GitHub Copilot, ChatGPT in a browser tab when needed. Why change?

But a colleague kept raving about it. "It's not autocomplete," she said. "It's like having a senior developer who never sleeps, never gets annoyed, and actually remembers what you talked about three hours ago."

I decided to give it a week.

That was six months ago. I can't imagine going back.

What Claude Code Actually Is

Claude Code is Anthropic's official command-line interface for Claude. But calling it a CLI undersells what it does.

It's an AI-native development environment. It reads your codebase. It remembers your conversations. It runs commands. It creates files. It orchestrates other AI agents. It connects to external tools through something called MCP (Model Context Protocol). It learns your patterns through custom skills.

Think of it less as a tool and more as a persistent collaborator that happens to live in your terminal.

The Mental Shift

The biggest adjustment wasn't technical—it was mental.

I had to stop thinking of AI as a question-answering service. Claude Code isn't something you query. It's something you work with.

When I approach a complex feature now, I don't think "How do I code this?" I think "How do I describe what I need so Claude can help me build it?"

The description matters more than typing speed. Clarity matters more than keyboard shortcuts. Understanding your goal matters more than knowing every API.

What Changed

After six months with Claude Code:

Speed: Tasks that took hours now take minutes. Not because I type faster, but because I delegate better. Claude handles the repetitive parts while I focus on decisions.

Quality: My code is more consistent. Claude remembers the patterns we established. It catches when I deviate from our conventions. It suggests tests I would have forgotten.

Learning: I learn constantly. Every time Claude solves something differently than I would have, I see a new approach. It's like pair programming with someone who has different experience than me.

Scope: I take on bigger projects. Things that seemed too ambitious for one person become manageable when you have a tireless collaborator.

The Compound Effect

The real power isn't any single feature. It's how they compound.

My workspace setup remembers everything. My custom skills encode my best practices. My MCP connections give Claude access to real data. My command library automates my recurring tasks.

Each layer builds on the previous. Each week, my setup gets a little better. The productivity gap between "me with Claude Code" and "me without" widens continuously.

Why This Guide Exists

When I started, I spent weeks discovering capabilities by accident. The documentation is good, but it can't capture workflows that emerge from real use. I wanted to create the guide I wished I had.

This isn't about every feature. It's about the features that matter—the patterns that compound, the setups that save hours, the mental models that make everything click.

Whether you're just starting or looking to level up, I hope my journey helps accelerate yours.


Setting Up Your Workspace

The moment I took Claude Code seriously was when I stopped treating it like a tool and started treating it like a workspace. That shift required organization.

Most guides jump straight to commands. But commands without structure is chaos. You end up with scattered files, forgotten contexts, and a growing mess that makes Claude less helpful over time.

Let me show you how I organize everything.

The Two-Domain Architecture

The fundamental insight: there are two kinds of things in my workspace.

Assets — The actual stuff. Code, images, videos, PDFs. Things that exist independent of my thinking about them.

Knowledge — My understanding of stuff. Notes, analyses, journals. The intellectual work I do on top of assets.

These two domains live in separate places:

My Workspace/
├── projects/           # Assets: actual code
├── learning/           # Assets: course materials
├── media/              # Assets: images, videos
├── archive/            # Assets: cold storage
│
└── vault/              # Knowledge: all my notes
    ├── _inbox/         # Quick capture
    ├── projects/       # Notes ABOUT projects
    ├── research/       # Research outputs
    ├── technical/      # Technical docs
    └── personal/       # Journal, career

The Decision Rule

When I create something, one question determines where it goes:

Is this the thing itself, or notes about the thing?

The SwiftUI component I'm building? That goes in projects/SwiftUI-Components/. My notes about SwiftUI patterns I've learned? Those go in vault/technical/swiftui-patterns.md.

A research paper PDF I downloaded? media/papers/. My analysis of that paper? vault/research/topic-name/.

This sounds simple but it's transformative. I never wonder where something is. The decision rule is unambiguous.

Why This Matters for Claude

Claude Code works best when it knows where to look.

When I say "check my research on LLM agents," Claude looks in vault/research/. When I say "update the authentication component," Claude looks in projects/. The structure creates predictability.

More importantly, Claude can reference my prior work. If I've already analyzed a topic, Claude finds that analysis before starting fresh. My knowledge compounds instead of fragmenting.

The Vault Structure

The knowledge side deserves more detail:

vault/
├── _inbox/             # Quick capture (empty this weekly)
├── _templates/         # Obsidian templates
├── _attachments/       # Images, generated files
│
├── projects/           # Project notes (not code)
├── research/           # Research outputs
│   └── [topic]/        # One folder per research area
├── technical/          # Technical documentation
├── financial-analysis/ # Finance workflow outputs
├── presentations/      # Deck workflow outputs
│
└── personal/
    ├── journal/        # Daily entries
    └── career/         # Career planning

Each major workflow has its home. Research outputs go to vault/research/. Finance analyses go to vault/financial-analysis/. This means I can always find previous work on a topic.

Naming Conventions

Consistency in naming saves cognitive load:

TypeConventionExample
Folderskebab-caseswiftui-components/
Markdownkebab-case.mdapi-patterns.md
Dated workYYYY-MM-DD-topic2026-01-21-aapl/
JournalYYYY-MM-DD.md2026-01-21.md

I don't think about these anymore. The convention is automatic.

CLAUDE.md Files

Every major directory can have a CLAUDE.md file—special instructions for Claude when working in that area.

My root CLAUDE.md contains:

  • High-level workspace structure
  • Key commands and their purposes
  • Conventions Claude should follow
  • References to important registries

Project-specific CLAUDE.md files contain:

  • Project-specific patterns
  • Technology choices
  • Testing conventions
  • Deployment notes

Claude reads these automatically. It's like giving Claude a briefing before every conversation.

Setting Up from Scratch

If you're starting fresh:

  1. Create the basic structure — Assets folders at top level, vault for knowledge
  2. Add a root CLAUDE.md — Describe your workspace, list key conventions
  3. Set up your vault _inbox — This is where quick captures go
  4. Create your first project folder — With its own CLAUDE.md
  5. Connect to Obsidian — The vault works beautifully with Obsidian for manual editing

Don't over-engineer initially. The structure evolves as you use it. Start simple, add complexity as needed.


Essential Daily Commands

Claude Code has dozens of commands. I use about ten daily.

These aren't the flashiest commands—no 27-agent research workflows here. These are the mundane ones that save me hours every week through sheer repetition.

Quick Capture: /capture

The command I use most often:

/capture "Idea for improving the auth flow - use session tokens instead of JWTs"

This does something simple but powerful: it routes the note to the right place automatically.

  • Technical observation? Goes to vault/technical/
  • Project idea? Goes to the relevant project notes
  • Random thought? Goes to vault/_inbox/

Claude makes the routing decision based on content. I don't choose a destination. I just capture.

Journal Entry: /journal

My daily reflection command:

/journal

Claude prompts me through a structured daily entry:

  • What did I accomplish?
  • What did I learn?
  • What's blocking me?
  • What's the plan for tomorrow?

The entry goes to vault/personal/journal/YYYY-MM-DD.md with proper frontmatter.

Quick Inbox: /inbox

Sometimes I want to capture without Claude making routing decisions:

/inbox "Look into that new React compiler"

Goes straight to vault/_inbox/. No analysis, no routing. Pure speed.

Research Summary: /research-quick

For quick research without the full 11-agent workflow:

/research-quick "differences between JWT and session tokens"

Claude does focused research and returns a summary. No file creation, no elaborate process. Just an answer when I need context.

Context Check: /context

Essential for longer conversations:

/context

Shows current context window usage. When it gets high, I know to wrap up or summarize before continuing.

More useful variation:

/context dump

Exports the current conversation state to a file. I use this when context is filling up but I'm not done with a task.

Parallel Execution: /parallel

When I have independent tasks:

/parallel "run tests" "lint code" "check types"

All three run simultaneously. For tasks that don't depend on each other, parallel execution saves significant time.

The Daily Pattern

My typical day:

Morning:

/journal                    # Previous day reflection
/inbox "thoughts..."        # Capture overnight ideas
/context                    # Check where I am

During work:

/capture "insight..."       # Capture as I work
/research-quick "question"  # Quick research
/parallel "test" "lint"     # Run checks

End of day:

/changelog                  # Document what changed
/context dump               # Save state if needed
/journal                    # Daily reflection

These ten commands handle 80% of my interactions with Claude Code.


Building Your Second Brain

I've tried every note-taking system. Evernote. Notion. Roam. Logseq. Apple Notes. Plain text files. Each worked for a while, then collapsed under its own complexity.

The problem wasn't the tools. It was the friction. Taking notes was easy. Finding them later was hard.

Claude Code changed this. Not because it's a better note-taking app—it's not a note-taking app at all. But because it makes notes usable.

The Integration with Obsidian

My vault is an Obsidian vault. This matters because:

Local files: Everything is markdown on my disk. No sync issues, no vendor lock-in.

Wikilinks: I can link notes with [[note-name]]. The graph of connections emerges naturally.

Plugins: Obsidian's plugin ecosystem adds features without complexity.

Works with Claude: Claude Code reads and writes to the same files. There's no import/export.

How Claude Uses My Vault

When I start a research workflow, Claude's first action is Phase 0: Context Discovery.

It searches my vault for related prior work. If I researched a similar topic three months ago, Claude finds that research and builds on it instead of starting fresh.

This is the compound effect. Every note I take becomes potential context for future work.

Templates That Reduce Friction

Obsidian templates + Claude workflows = consistent structure.

My research template:

---
created: "[date:YYYY-MM-DDTHH:mm:ss]"
type: research
tags: [research]
---

# [title]

## Key Questions
-

## Sources
-

## Findings
-

## Implications
-

When Claude runs /research, it creates notes with this structure. Consistency means findability.

Search That Works

Before Claude, I relied on Obsidian's search. It's good, but it's keyword-based.

Now I use Claude's semantic understanding:

/vault-search "that analysis I did about authentication tokens"

Claude doesn't just match keywords. It understands the request and finds the relevant note even if I don't remember exact terms.


MCP Tools: Connecting to Everything

Model Context Protocol—MCP—is where Claude Code becomes truly powerful.

Without MCP, Claude is smart but isolated. It can read your files and run commands, but it can't check your email, query your database, scrape a website, or access APIs.

With MCP, Claude connects to everything.

What MCP Actually Is

Think of MCP servers as adapters. Each server exposes specific capabilities to Claude:

[Claude Code] ←→ [MCP Server] ←→ [External Service]

When I set up the Firecrawl MCP server, Claude gains the ability to scrape web pages. When I set up the arXiv server, Claude can search academic papers.

My Current MCP Setup

ServerPurposeWhat It Enables
FirecrawlWeb scrapingScrape pages, extract content
ExaSemantic searchWeb search with AI understanding
Context7Library docsAccess documentation for any library
arXivAcademic papersSearch and download research
AlphaVantageFinancial dataStock prices, fundamentals
Apple HealthHealth dataQuery my health metrics
TwitterSocial dataRead tweets (read-only)
GitHubRepository opsPRs, issues, commits
ChromeBrowser controlAutomate web interactions
claude-memWorking memoryPersist context across sessions

Each server adds capabilities. Together, they make Claude feel omniscient.

How Claude Uses MCP

When I ask something requiring external data, Claude automatically uses the appropriate tool:

Me: "What's Apple's stock price?" Claude: [Uses AlphaVantage] "Apple is trading at $189.84..."

Me: "Find recent papers on transformer architectures" Claude: [Uses arXiv] "I found 15 relevant papers..."

I don't invoke MCP tools directly. Claude decides when to use them.


Part 2: Multi-Agent Fundamentals

Why One Claude Isn't Enough

I resisted multi-agent workflows for months. They seemed complex. Orchestrating multiple AI agents felt like premature optimization.

Then I hit a wall.

My research quality plateaued. No matter how good my prompts got, single-Claude research felt shallow. It would find obvious sources, miss nuances, and declare conclusions prematurely.

The problem wasn't Claude's capability. It was perspective.

The Single-Agent Trap

A single agent does everything: research, analyze, synthesize, critique. But this creates a subtle problem.

When one agent finds information and then analyzes it, there's no fresh perspective. The same "mind" that collected the data interprets it. Confirmation bias sneaks in.

The Multi-Agent Insight

Multiple agents create separation of concerns:

  • Researcher finds information
  • Analyst interprets patterns
  • Critic challenges conclusions
  • Synthesizer combines perspectives

The analyst hasn't seen the raw research process. The critic doesn't know why the analyst reached certain conclusions. This separation creates genuine diversity.

When Multi-Agent Matters

Single agent works well for:

  • Quick questions with clear answers
  • Code generation with defined requirements
  • Simple analysis with obvious conclusions

Multi-agent shines for:

  • Research requiring multiple perspectives
  • Analysis where confirmation bias is risky
  • Complex decisions with significant stakes

The rule: if you'd want a second opinion from a human, you probably want a second agent.


The Skills System

Commands are things I invoke explicitly. /research runs research.

Skills are different. They activate automatically when the context matches.

When I ask for "ideas," the brainstorm skill activates. When I'm building a dashboard, the design-system skill loads. When I'm debugging, sequential-thinking engages.

The Skill vs. Command Decision

Use a command when:

  • User must explicitly request the action
  • It orchestrates a multi-step workflow
  • It produces deliverable output

Use a skill when:

  • Behavior should auto-apply based on context
  • It modifies how work is done, not what work to do

Commands are verbs: "do this." Skills are adverbs: "do things this way."

My Active Skills

SkillTriggers OnWhat It Does
Brainstorm"ideas," "explore"Divergent/convergent ideation
Sequential ThinkingComplex problemsStep-by-step with confidence
Design SystemDashboard generationDigital Craft tokens
Python Data AnalysisData analysisPandas patterns
MCP ResilienceMCP failuresRetry logic
Error HandlingWorkflow failuresRecovery patterns
Quality GatesEnd of workflowsVerification

Document Generation

Claude Code doesn't just write text—it generates real documents.

The Document Commands

/pdf "report.md"            # Generate PDF from markdown
/slides "deck"              # Generate PowerPoint presentation
/spreadsheet "data"         # Generate Excel workbook
/docx "proposal"            # Generate Word document

Each command understands its target format's strengths.

Multi-Format Output

Major workflows generate multiple formats automatically.

The /deck workflow outputs:

  • PowerPoint file (main deck)
  • PDF (for sharing)
  • Markdown (for reference)
  • Speaker notes

The /research workflow outputs:

  • Markdown report
  • PDF (formatted)
  • Executive summary

Research Workflows

My /research workflow runs 11 specialized agents. It's the workflow I use most often.

The 11-Agent Architecture

Phase 0: Context Discovery
  └─ Explore agent (find prior work)

Phase 1: Research (3 agents in parallel)
  ├─ Academic Researcher
  ├─ Web Researcher
  └─ News Researcher

Phase 2: Analysis (3 agents in parallel)
  ├─ Source Analyzer
  ├─ Pattern Detector
  └─ Gap Analyzer

Phase 3: Quality Assurance (2 agents)
  ├─ Fact Checker
  └─ Bias Detector

Phase 4: Synthesis (2 agents)
  ├─ Synthesizer
  └─ Executive Summary

The Output

Research outputs go to vault/research/[topic]/:

vault/research/llm-agents-2026/
├── research-report.md
├── executive-summary.md
├── sources.md
├── gaps.md
└── data/
    └── sources.json

Context Engineering

Context is everything in AI work. Every interaction happens within a context window. What's in that window determines how well Claude can help.

The Context Problem

Two failure modes:

Context Starvation: Not giving Claude enough information.

Context Pollution: Filling the window with irrelevant information.

Both lead to worse outputs.

My Context Strategies

Progressive Disclosure: Load minimum context initially. Expand as required.

Context Partitioning: Multi-agent workflows partition context across agents.

Reference Over Inclusion: Reference files by path instead of pasting.

State Management: Periodically save state with /context dump.

Monitoring Context Usage

/context
UsageAction
0-40%Continue normally
40-60%Avoid large workflows
60-80%Compress first
80-95%Dump and restart

Part 3: Advanced Orchestration

Multi-Agent Orchestration

Running multiple agents is easy. Coordinating them effectively is the hard part.

The Orchestration Dimensions

Timing — When does each agent run? Dependencies — Which agents need outputs from which others? Data flow — What information passes between agents? Synthesis — How do outputs combine?

Parallel vs. Sequential

Parallel Execution: Agents that don't depend on each other run simultaneously.

Sequential Execution: When Agent B needs Agent A's output, they run in order.

Hybrid Patterns: Within phases: parallel. Across phases: sequential.

Phase Design

Phase 0: Context Discovery
Phase 1: Gathering (parallel)
Phase 2: Processing (parallel)
Phase 3: Quality Assurance (parallel)
Phase 4: Synthesis (sequential)
Phase 5: Output (sequential)

Quality Gates

AI-generated content can be confidently wrong.

Quality gates are checkpoints where outputs are verified before proceeding.

What Quality Gates Check

CheckWhat It Catches
Citation VerificationClaims without sources
Source QualityUnreliable sources
Confidence CalibrationOverconfident claims
Internal ConsistencyContradictions
Gap IdentificationMissing aspects

The Quality Report

# Quality Report

## Overall Score: 87/100

## Verified Claims
✓ Revenue figures (Source: SEC 10-Q)

## Flagged Items
⚠ Projection based on analyst estimates

## Unverified Claims
✗ "Industry insiders suggest..."

## Recommendation
Ready for use with noted caveats.

Ralph Loops

I noticed Claude would quit too early. I'd ask for 80% test coverage and get a few tests and "I've improved coverage." But coverage was still at 50%.

Ralph loops fix this.

The Core Concept

Don't stop until the completion promise is detected.

/ralph-loop "Improve test coverage to 80%. Output <promise>80% COVERAGE</promise> when done."

Claude runs. Checks coverage. Writes tests. Repeats until 80%. Then outputs the promise. Loop ends.

Writing Good Prompts

Clear Current State: Current test coverage: 45%

Measurable Target: Target: 80% coverage

Binary Completion: Output <promise>80% COVERAGE ACHIEVED</promise> when coverage >= 80%

Safety Limits

  • Maximum iteration cap (default: 20)
  • Stall detection (exit if no progress for 3 iterations)
  • Checkpoints saved

Presentation Frameworks

My /deck workflow codifies frameworks from McKinsey, BCG, Sequoia, Amazon, and Apple.

The Eight Frameworks

FrameworkUse WhenSlides
McKinsey Pyramid + SCQAExecutive decisions10-15
Hypothesis-DrivenStrategic recommendations12-20
Sequoia PitchInvestment pitches10
Amazon PRFAQProduct launches6-10
Assertion-EvidenceTechnical audiences15-25
Marketing StrategyCampaign pitches15-20
Agency CreativeCreative concepts15-25
Apple KeynoteProduct keynotes30-50

Core Principles

Answer First: Lead with the recommendation.

Action Titles: Slide titles should be complete sentences.

One Message Per Slide: If a slide makes two points, split it.


Part 4: Production Workflows

Deep Research

My standard /research runs 11 agents. /deep-research is 27 agents across 12 phases, targeting 100+ sources.

The Architecture

Phase 0   → Context Discovery
Phase 1   → Research Planning
Phase 2   → Primary Search (5 parallel agents)
Phase 3   → Paper Retrieval
Phase 4   → Citation Chain Recursion
Phase 5   → Quality Assurance (4 agents)
Phase 5.1 → Credibility Deep Dive (4 agents)
Phase 5.5 → Fact-Check Feedback Loop
Phase 6   → Advanced Analysis (3 agents)
Phase 7   → Synthesis (3 agents)
Phase 8   → Visualization (2 agents)
Phase 9   → Report Generation
Phase 10  → Integration

Citation Chain Recursion

Foundational papers often sit 2-3 citations away from current research. The recursion finds them.

Resource Consumption

Metric/research/deep-research
Agents1127
Tokens~300K~750K
Runtime5-10 min30-60 min
Sources25-50100+

Marketing Workflows

My /marketing workflow: 12 agents across 4 sub-workflows.

The Sub-Workflows

/marketing "Product"           → Full 4-phase (12 agents)
/marketing-research "Product"  → Research only (3 agents)
/marketing-strategy "Product"  → Strategy only (3 agents)
/marketing-creative "Product"  → Creative only (3 agents)
/marketing-execution "Product" → Execution only (3 agents)

Phase 1: Research

Market Intel: Market sizing, competitors, pricing Social Research: Listening, sentiment, feedback SEO Content: Keywords, content gaps

Phase 2: Strategy

Strategy Architect: Positioning, personas, messaging Channel Strategist: Channels, influencers, email Validation Agent: Fact-checks all claims

Phase 3: Creative

Creative Lead: Concepts, visual direction Content Producer: Headlines, copy, CTAs Video Producer: Scripts, storyboards

Phase 4: Execution

Media Planner: Budget, pacing, channels Analytics Architect: KPIs, attribution, testing Viz Generator: Positioning maps, journey visualizations


Building Custom Skills

Skills activate automatically when context matches.

Anatomy of a Skill

.claude/skills/[skill-name]/
├── SKILL.md           # Core instructions
├── scripts/           # Automation helpers
├── references/        # Detailed docs
└── assets/            # Templates

The Critical Frontmatter

---
name: skill-name
version: 1.0.0
description: Specific triggers for activation.
---

Bad: "Helps with context management" Good: "Export current task state to markdown when context > 60%"

What Makes a Good Skill

  • Specific triggers beat broad ones
  • Process over content
  • Consistent output formats
  • Integration enables chaining

From Commands to Workflows

Commands are explicit invocations. Workflows are orchestrated multi-agent processes.

Design Principles

Phase 0 Always: Check for prior related work.

Parallel Where Possible: Independent work runs simultaneously.

Explicit Dependencies: Document what each agent needs.

Structured Handoffs: Pass summaries, not raw data.

Quality Gates: Verify before synthesis.

Graceful Degradation: Handle failures without total failure.


Appendix

Quick Reference

Workflow Comparison

WorkflowAgentsRuntimeOutput
/research115-10 minResearch report
/deep-research2730-60 minLiterature review
/finance710-15 minFinancial analysis
/marketing1215-20 minGTM strategy
/deck1010-15 minPresentation

Context Guidelines

UsageAction
0-40%Continue normally
40-60%Avoid large workflows
60-80%Compress first
80-95%Dump and restart

Command Cheat Sheet

Daily Commands

/capture "note"        # Smart routing
/journal              # Daily entry
/inbox "note"         # Quick capture
/context              # Check usage
/context dump         # Export state

Research & Analysis

/research "topic"             # 11-agent research
/deep-research "topic"        # 27-agent review
/finance "TICKER"             # Financial analysis

Document Generation

/pdf "content"        # Generate PDF
/slides "topic"       # PowerPoint
/spreadsheet "data"   # Excel
/docx "document"      # Word

Workflow Control

/parallel "cmd1" "cmd2"   # Run in parallel
/ralph-loop "task"        # Iterative loop
/cancel-ralph            # Stop loop

Agent Configuration Examples

Research Agent

Task({
  subagent_type: "research-analyst",
  model: "opus",
  prompt: `Research [topic]. Find:
    - Academic sources
    - Industry perspectives
    - Recent developments
    Return structured findings.`
})

Quality Gate Agent

Task({
  subagent_type: "code-reviewer",
  model: "opus",
  prompt: `Verify claims:
    [claims]

    For each: source, verification, confidence.`
})

Final Thoughts

Six months with Claude Code transformed how I work. Not because of any single feature, but because of how capabilities compound.

The workspace structure enables Claude to find prior work. The vault preserves knowledge. MCP connects to external data. Skills encode best practices. Workflows orchestrate complex processes. Quality gates ensure reliability.

Each layer builds on the previous. Each week, the system gets a little better.

If you're just starting: focus on the basics. Workspace structure. Daily commands. Building the habit.

If you're looking to level up: pick one area to deepen. Multi-agent orchestration. Custom skills. Quality gates. Go deep before broadening.

Claude Code is the most significant productivity tool I've adopted in years. Not because it works for me—because it works with me.


This guide consolidates lessons from six months of daily use. For specific command references, see the Command Cheat Sheet.