claude-code-ultimate-guide

name	claude-code-ultimate-guide
description	Master Claude Code with this comprehensive guide covering architecture, workflows, security, methodologies (TDD/SDD/BDD), 271-question quiz, and 181 production templates
triggers	["how do I use the claude code ultimate guide","show me claude code best practices and patterns","help me learn claude code workflows and methodologies","what are claude code security threats and vulnerabilities","explain claude code architecture and mental models","guide me through TDD/SDD/BDD with claude code","find claude code examples and templates","test my claude code knowledge with quiz questions"]

claude-code-ultimate-guide

Skill by ara.so — Claude Code Skills collection.

Expert guidance for the Claude Code Ultimate Guide — a 24K+ line comprehensive resource covering Claude Code from beginner to power user, including architecture deep-dives, agentic workflows, security hardening (28 CVEs tracked), methodology guides (TDD/SDD/BDD), 271-question quiz, and 181 production-ready templates.

What This Guide Provides

Educational depth + practical templates:

• Mental models: How Claude Code works internally (architecture, context flow, tool orchestration)
• Decision frameworks: When to use agents vs skills vs commands (trade-off analysis)
• Security-first: Only guide with threat database (28 CVEs + 655 malicious skills)
• Methodology workflows: TDD/SDD/BDD comparison + step-by-step implementation
• 48 Mermaid diagrams: Visual architecture, patterns, security flows
• 271-question quiz: Validate understanding across 7 modules
• 181 templates: Production-ready examples in TypeScript, Python, Rust, Go, etc.

Installation & Access

Option 1: MCP Server (Recommended — No Cloning)

Add to ~/.claude.json:

{
  "mcpServers": {
    "claude-code-guide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "claude-code-ultimate-guide-mcp"]
    }
  }
}

Usage:

# Search the guide
claude "Use claude-code-guide to search for 'security threats'"

# Get specific section
claude "Use claude-code-guide to read the TDD methodology section"

# Get cheatsheet
claude "Use claude-code-guide to show me the cheatsheet"

# List examples by topic
claude "Use claude-code-guide to list all rust examples"

Option 2: Clone Repository

git clone https://github.com/FlorianBruniaux/claude-code-ultimate-guide.git
cd claude-code-ultimate-guide

# Browse structure
ls -la guide/        # 24K+ lines of documentation
ls -la examples/     # 181 production templates
ls -la quiz/         # 271 questions across 7 modules

Option 3: Interactive Onboarding (No Setup)

claude "Fetch and follow the onboarding instructions from: https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/tools/onboarding-prompt.md"

Key MCP Server Tools

When using the MCP server, you have access to 17 tools:

// Search across all guide content
search_guide({ query: "agentic workflows", maxResults: 5 })

// Read specific sections
read_section({ 
  section: "guide/methodologies/tdd-with-ai.md" 
})

// Get quick reference
get_cheatsheet()

// Find templates
search_examples({ 
  query: "typescript react", 
  language: "typescript" 
})

// Get specific example
get_example({ path: "examples/typescript/react-tdd.md" })

// Security threat lookup
get_threat({ cveId: "CVE-2024-1234" })
list_threats({ category: "prompt-injection" })

// Compare versions
compare_versions({ 
  from: "3.39.0", 
  to: "3.40.0" 
})

13 slash commands also available:

/ccguide:search security
/ccguide:read guide/security/security-hardening.md
/ccguide:cheatsheet
/ccguide:examples typescript
/ccguide:quiz beginner

Repository Structure

claude-code-ultimate-guide/
├── guide/                    # 24K+ lines documentation
│   ├── ultimate-guide.md     # Main comprehensive guide
│   ├── cheatsheet.md         # 1-page daily essentials
│   ├── architecture/         # Internal workings
│   ├── methodologies/        # TDD/SDD/BDD workflows
│   ├── security/             # Threat modeling, CVEs
│   ├── diagrams/             # 48 Mermaid visualizations
│   └── learning-path/        # 7-module progression
├── examples/                 # 181 production templates
│   ├── typescript/
│   ├── python/
│   ├── rust/
│   ├── go/
│   └── workflows/
├── quiz/                     # 271 questions
│   ├── beginner/
│   ├── intermediate/
│   └── advanced/
├── tools/                    # Utilities
│   ├── onboarding-prompt.md
│   └── self-assessment.md
└── mcp-server/              # MCP implementation

Core Concepts & Workflows

1. Architecture Mental Models

Claude Code's Master Loop:

graph LR
    A[User Request] --> B[Context Assembly]
    B --> C[Tool Selection]
    C --> D[Model Invocation]
    D --> E[Tool Execution]
    E --> F{More Tools?}
    F -->|Yes| C
    F -->|No| G[Response]
    
    style A fill:#3498db
    style G fill:#2ecc71

Key insight: Claude Code orchestrates tools in a loop. Understanding this helps you design effective prompts and know when to split complex tasks.

2. Agent vs Skill vs Command Decision Framework

// AGENT — Long-running, multi-step, adaptive
// Example: Refactor entire codebase following TDD
{
  role: "tdd-refactor-agent",
  goal: "Refactor auth module with 100% test coverage",
  constraints: ["Red-Green-Refactor cycle", "No breaking changes"]
}

// SKILL — Domain expertise, reusable across sessions
// Example: "Apply TDD workflow to new feature"
{
  name: "tdd-workflow",
  triggers: ["write tests first", "tdd this feature"],
  knowledge: "guide/methodologies/tdd-with-ai.md"
}

// COMMAND — Single execution, explicit tool call
// Example: "Run tests and show coverage"
/test --coverage

Decision tree:

• Multi-step adaptive? → Agent
• Reusable expertise? → Skill
• One-shot execution? → Command

3. TDD Workflow with Claude Code

# 1. Start with failing test (RED)
claude "Write a failing test for user registration validation"

# 2. Minimal implementation (GREEN)
claude "Implement just enough code to make the test pass"

# 3. Refactor (REFACTOR)
claude "Refactor the validation logic while keeping tests green"

# 4. Repeat
claude "Next test: email uniqueness constraint"

Full workflow: See guide/methodologies/tdd-with-ai.md

4. Security Threat Awareness

28 CVEs tracked in database:

# Check for prompt injection vulnerabilities
claude "Use claude-code-guide to get threat info for CVE-2024-5184"

# List all model-confusion attacks
claude "Use claude-code-guide to list threats in category 'model-confusion'"

Common threats:

• Prompt Injection: User input manipulating agent behavior
• Tool Misuse: Agents accessing unauthorized resources
• Context Leakage: Sensitive data in prompts/logs
• Supply Chain: Malicious skills (655 tracked)

See: guide/security/security-hardening.md

Real-World Examples

Example 1: TDD React Component (TypeScript)

// examples/typescript/react-tdd-component.md

// Step 1: Write test first
import { render, screen, fireEvent } from '@testing-library/react';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('validates email format before submission', () => {
    render(<LoginForm onSubmit={jest.fn()} />);
    
    const input = screen.getByLabelText('Email');
    const submit = screen.getByRole('button', { name: 'Login' });
    
    fireEvent.change(input, { target: { value: 'invalid-email' } });
    fireEvent.click(submit);
    
    expect(screen.getByText('Invalid email format')).toBeInTheDocument();
  });
});

// Step 2: Minimal implementation
export const LoginForm: React.FC<Props> = ({ onSubmit }) => {
  const [email, setEmail] = useState();
   [error, setError] = ();
  
    = () => {
    e.();
     (!.(email)) {
      ();
      ;
    }
    ({ email });
  };
  
   (
    
  );
};

Prompt to Claude Code:

claude "Follow TDD workflow from the guide:
1. I'll describe a feature
2. You write the test first (RED)
3. Then minimal implementation (GREEN)
4. Then refactor suggestions (REFACTOR)

Feature: Login form with email validation and password strength meter"

Example 2: Secure Agentic Workflow (Python)

# examples/python/secure-agent-workflow.py

from typing import List, Dict
import os

class SecureAgentWorkflow:
    """
    Demonstrates security best practices from guide/security/
    - Input sanitization
    - Tool allowlisting
    - Audit logging
    """
    
    def __init__(self, allowed_tools: List[str]):
        self.allowed_tools = set(allowed_tools)
        self.audit_log = []
    
    def execute_task(self, user_input: str, context: Dict) -> str:
        # 1. Sanitize input (prevent prompt injection)
        sanitized = self._sanitize_input(user_input)
        
        # 2. Log for audit trail
        self._log_action("task_start", {
            "input": sanitized,
            "context_keys": list(context.keys())
        })
        
        # 3. Tool allowlist enforcement
        requested_tools = self._extract_tools(sanitized)
        if not requested_tools.issubset(self.allowed_tools):
            forbidden = requested_tools - self.allowed_tools
            raise PermissionError(f"Tools not allowed: {forbidden}")
        
        # 4. Execute with minimal permissions
        result = ._execute_with_restrictions(sanitized, context)
        
        
        ._log_action(, {: (result)})
        
         result
    
     () -> :
        
        dangerous_patterns = [
            ,
            ,
            ,
            
        ]
        sanitized = text
         pattern  dangerous_patterns:
            sanitized = sanitized.replace(pattern, )
         sanitized
    
     ():
        
        .audit_log.append({
            : action,
            : metadata,
            : datetime.now().isoformat()
        })
        
        ()


workflow = SecureAgentWorkflow(
    allowed_tools=[, , ]
)


workflow.execute_task(
    ,
    context={: }
)


workflow.execute_task(
    ,  
    context={}
)

Prompt to Claude Code:

claude "Using the secure agent workflow pattern from the guide:
1. Review my agent code for security vulnerabilities
2. Apply input sanitization from guide/security/security-hardening.md
3. Add tool allowlisting
4. Implement audit logging
5. Show before/after diff"

Example 3: Multi-Agent SDD Pattern (Rust)

// examples/rust/multi-agent-sdd.rs

// Spec-Driven Development with multiple specialized agents
// Pattern from guide/methodologies/sdd-with-ai.md

/// Agent 1: Spec Writer
/// Generates formal specifications from requirements
pub struct SpecAgent;

impl SpecAgent {
    pub fn generate_spec(requirements: &str) -> ApiSpec {
        // Claude Code prompt:
        // "Write OpenAPI 3.0 spec for: {requirements}"
        ApiSpec {
            version: "3.0.0".into(),
            endpoints: vec![
                Endpoint {
                    path: "/users".into(),
                    method: Method::POST,
                    request: Schema::object(vec![
                        ("email", Schema::string_format("email")),
                        ("password", Schema::string_min_length(8))
                    ]),
                    response: Schema::object(vec![
                        ("id", Schema::uuid()),
                        ("created_at", Schema::datetime())
                    ])
                }
            ]
        }
    }
}

/// Agent 2: Test Generator
/// Creates contract tests from spec
pub struct ;

  {
      (spec: &ApiSpec)  <Test> {
        
        
        spec.endpoints.().(|endpoint| {
            Test {
                name: (, endpoint.path),
                assertions: [
                    Assertion::(),
                    Assertion::(&endpoint.response),
                    Assertion::()
                ]
            }
        }).()
    }
}



  ;

  {
      (spec: &ApiSpec, tests: &[Test])   {
        
        
        
        .()
    }
}



  () {
      = ;
    
    
      = SpecAgent::(requirements);
    (, serde_json::(&spec).());
    
    
      = TestAgent::(&spec);
    (, tests.());
    
    
      = ImplAgent::(&spec, &tests);
    (, code);
    
    
    (&tests, &code)..();
}

Prompt to Claude Code:

claude "Set up SDD multi-agent workflow:
1. I provide requirements
2. Spec agent writes OpenAPI spec
3. Test agent generates contract tests
4. Implementation agent writes code
5. Verification agent runs tests

Start with: User authentication API with JWT tokens"

Configuration & Customization

MCP Server Configuration

// ~/.claude.json
{
  "mcpServers": {
    "claude-code-guide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "claude-code-ultimate-guide-mcp"],
      "env": {
        // Optional: customize behavior
        "GUIDE_DEFAULT_RESULTS": "10",
        "GUIDE_INCLUDE_DIAGRAMS": "true"
      }
    }
  }
}

Custom Learning Path

# Self-assessment to get personalized path
claude "Use claude-code-guide to run /ccguide:assessment"

# Answer questions about:
# - Experience level (beginner/intermediate/advanced)
# - Primary language (TypeScript/Python/Rust/Go)
# - Focus area (security/methodologies/architecture/workflows)

# Receive custom path like:
# 1. Start: guide/learning-path/module-1-foundations.md
# 2. Then: guide/methodologies/tdd-with-ai.md
# 3. Practice: examples/typescript/tdd-examples/
# 4. Quiz: quiz/intermediate/methodologies.md

Skill Integration

# skills/claude-code-expert.md
---
name: claude-code-expert
description: Expert in Claude Code workflows using ultimate guide knowledge
triggers:
  - apply best practices from the guide
  - use claude code ultimate guide methodology
---

When the user requests Claude Code guidance:
1. Use the `claude-code-guide` MCP server to search relevant sections
2. Apply patterns from examples/ directory
3. Reference security guidelines for sensitive operations
4      


   
   
   
   

Common Patterns & Use Cases

Pattern 1: Progressive Learning Path

# Week 1: Foundations
claude "Use claude-code-guide to read learning-path/module-1-foundations.md"
claude "Use claude-code-guide to quiz me on beginner concepts"

# Week 2: Methodologies  
claude "Use claude-code-guide to read methodologies/tdd-with-ai.md"
claude "Show me examples/typescript/tdd-examples/"
claude "Use claude-code-guide to quiz me on TDD patterns"

# Week 3: Architecture
claude "Use claude-code-guide to read architecture/master-loop.md"
claude "Explain the decision tree for agents vs skills vs commands"

# Week 4: Security
claude "Use claude-code-guide to read security/security-hardening.md"
claude "List all CVEs related to prompt injection"

Pattern 2: On-Demand Expertise

# During development, pull specific guidance
claude "I'm implementing a new API. Use claude-code-guide to show me the SDD workflow"

# When stuck, search for solutions
claude "Use claude-code-guide to search for 'debugging multi-agent workflows'"

# Before committing, security check
claude "Use claude-code-guide to list security threats for my agentic workflow"

Pattern 3: Template-Driven Development

# Find template for your stack
claude "Use claude-code-guide to search examples for 'python fastapi tdd'"

# Get full template
claude "Use claude-code-guide to get example examples/python/fastapi-tdd-template.md"

# Customize for your project
claude "Adapt this template for a GraphQL API with subscription support"

Troubleshooting

MCP Server Not Found

Symptom:

Error: MCP server 'claude-code-guide' not found

Solution:

# Verify npx can access package
npx -y claude-code-ultimate-guide-mcp --version

# Check ~/.claude.json syntax
cat ~/.claude.json | jq .

# Restart Claude Code
# macOS: cmd+shift+p → "Reload Window"
# Linux/Win: ctrl+shift+p → "Reload Window"

Search Returns No Results

Symptom:

search_guide({ query: "authentication" }) // Returns []

Solution:

# Try broader terms
search_guide({ query: "auth" })

# Use topic-based search
list_topics() // See all available topics
search_guide({ query: "security" })

# Check specific sections
read_section({ section: "guide/security/authentication.md" })

Quiz Questions Too Hard/Easy

Solution:

# Take self-assessment first
/ccguide:assessment

# Start with recommended module
# Beginner → quiz/beginner/
# Intermediate → quiz/intermediate/  
# Advanced → quiz/advanced/

# Review concepts before quiz
claude "Use claude-code-guide to read the foundations module before quizzing me"

Examples Don't Match My Stack

Solution:

# Search by language
search_examples({ language: "rust" })

# Search by framework
search_examples({ query: "fastapi" })

# Ask for adaptation
claude "Use this TypeScript example but convert it to Python with FastAPI:
[paste example]"

Integration with Other Tools

With Cursor

# Add MCP server to Cursor config
# ~/.cursor/config.json (same format as ~/.claude.json)

# Use in Cursor prompts
"@claude-code-guide search for testing patterns"

With GitHub Copilot

# Reference guide in comments
# copilot will use context from open files

# Open relevant guide section in editor
code guide/methodologies/tdd-with-ai.md

# Then prompt copilot:
# "Follow the TDD workflow from the open guide file"

With Custom Agents

# agents/my_agent.py

from mcp import Client

class GuideAwareAgent:
    def __init__(self):
        self.guide = Client("claude-code-guide")
    
    async def get_best_practice(self, topic: str) -> str:
        results = await self.guide.call(
            "search_guide",
            {"query": topic, "maxResults": 3}
        )
        return results[0]["content"]
    
    async def execute_with_guidance(self, task: str):
        # Look up best practice first
        guidance = await self.get_best_practice(task)
        
        # Apply guidance to task
        return self.apply_pattern(task, guidance)

Advanced Usage

Custom Quiz Generation

# Generate quiz from any guide section
claude "Use claude-code-guide to read security/security-hardening.md
Then create 10 multiple-choice questions testing understanding of:
- Threat models
- CVE mitigation strategies  
- Tool allowlisting
Format like quiz/advanced/security.md"

Diff-Based Learning

# Compare guide versions to learn what changed
claude "Use claude-code-guide to compare versions 3.39.0 and 3.40.0
Explain what new patterns were added and why"

# Track official Anthropic docs changes
claude "Use claude-code-guide to diff official docs since last week
Highlight breaking changes"

Building Custom Skills from Guide

# Extract pattern into reusable skill
claude "Use claude-code-guide to read methodologies/tdd-with-ai.md
Create a skill file skills/tdd-enforcer.md that:
1. Triggers on 'write tests first'
2. Refuses to write implementation before tests
3. Uses Red-Green-Refactor cycle
4. References guide sections for explanation"

Resources & Further Reading

Within this guide:

• Full guide: guide/ultimate-guide.md (24K+ lines)
• Quick reference: guide/cheatsheet.md (1 page)
• Learning path: guide/learning-path/ (7 modules, 8-11 hours)
• Visual diagrams: guide/diagrams/ (48 Mermaid diagrams)
• Threat database: guide/security/threat-database.md (28 CVEs)

External resources:

• Website: https://cc.bruniaux.com/
• MCP Package: https://www.npmjs.com/package/claude-code-ultimate-guide-mcp
• Release notes: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/releases
• Awesome list: https://github.com/hesreallyhim/awesome-claude-code

Complementary guides:

• everything-claude-code: https://github.com/beanlab/everything-claude-code (battle-tested configs)
• claude-cowork-guide: https://github.com/FlorianBruniaux/claude-cowork-guide (non-dev use cases)

Summary Cheatsheet

# === MCP Server Usage ===
# Search guide
claude "Use claude-code-guide to search for {topic}"

# Read section
claude "Use claude-code-guide to read {path}"

# Get cheatsheet
claude "Use claude-code-guide to show cheatsheet"

# Find examples
claude "Use claude-code-guide to search examples for {query}"

# === Learning Path ===
# Self-assessment
claude "Use claude-code-guide to run /ccguide:assessment"

# Quiz me
claude "Use claude-code-guide to quiz me on {topic}"

# === Security ===
# Check CVE
claude "Use claude-code-guide to get threat {CVE-ID}"

# List threats
claude "Use claude-code-guide to list threats in category {category}"

# === Version Tracking ===
# Compare versions
claude "Use claude-code-guide to compare versions {from} {to}"

# Get changelog
claude "Use claude-code-guide to get changelog"

Daily workflow:

1. Morning: Review cheatsheet for pattern reminders
2. During dev: Search guide for specific patterns
3. Before commit: Security threat check
4. End of week: Take quiz to validate learning

Repository: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
License: CC BY-SA 4.0
Maintained by: Florian Bruniaux