claude-code-ultimate-guide README

The project's README from github.com/FlorianBruniaux/claude-code-ultimate-guide. As one markdown file: README.md.

Claude Code Ultimate Guide

Florian Bruniaux Florian BRUNIAUX · AI Founding Engineer @ Méthode Aristote
13 years from developer to CTO / VP Eng · Blog ↗ · Projects ↗

Open the interactive guide

Guide version 3.43.0 Updated Sep 10, 2026, guide version 3.43.0 Guide license: CC BY-SA 4.0 MCP server available through npx

Learn Claude Code, build reliable agents, and scale their use safely. The website is the primary reading and discovery interface. This repository contains the canonical Markdown sources, reusable files, machine-readable indexes, and contribution history.

Start here: complete a first task online · browse the guide portal · open the complete sitemap · read the Markdown source

Choose your next step

The table below is generated from machine-readable/navigation.json. The same contract feeds the public sitemap, so the repository and website expose the same intent model.

Intent Browse online
Start Guide portal · Quick Start · Learning Paths · Quick Reference · AI Roles
Build Agent Harness Engineering · Loop & Graph Engineering · Context Engineering · Memory Systems · Workflows · Methodologies · MCP or CLI? · Examples
Scale Security · Enterprise Governance · Observability · Team Metrics · Team Adoption · Subscription Strategy · AI Unit Economics · Team Knowledge · API Gateway
Resources Resource Hub · Downloads · Cheat Sheets · Ebooks · Diagrams · Ecosystem · Compare · Glossary · FAQ · Guide MCP Server · Related Projects
Updates Guide Changelog · Claude Code Releases · RSS Feed

Why this guide exists

Claude Code documentation explains the product. This guide connects product behavior to engineering decisions: what belongs in context, when to use an agent instead of a skill, how to verify generated work, and which controls matter when usage moves beyond one developer.

Need Start with
Understand Claude Code internals Architecture and Tools Reference
Design agent systems Agent Harness Engineering and Loop & Graph Engineering
Structure AI-assisted delivery Methodologies and Workflow Guides
Establish a security boundary Security Hardening and Sandbox Isolation
Validate understanding Knowledge Quiz and Recap Cards

The guide favors explicit trade-offs and verifiable procedures. Where evidence is incomplete, the relevant page should preserve that limit instead of presenting one workflow as universal.

Start

Install Claude Code

Choose one installation method:

# npm, macOS, Linux, or Windows
npm install -g @anthropic-ai/claude-code

# macOS with Homebrew
brew install claude-code

# macOS or Linux native installer
curl -fsSL https://claude.ai/install.sh | sh

Windows PowerShell also supports:

irm https://claude.ai/install.ps1 | iex

Verify the installation and authenticate:

claude --version
claude doctor
claude auth login

The Quick Start chapter documents installation alternatives, authentication, updates, permission modes, and common first-day failures.

Complete a first task

Open a small repository with a clean or understood Git state, then start Claude Code:

cd your-project
claude

Give Claude a bounded request that includes the expected result and verification:

Explain how this project runs its tests. Do not modify files.
Name the relevant commands and cite the files that define them.

Before asking Claude to edit code, add a project-level CLAUDE.md that records the commands and constraints Claude must follow:

# Project instructions

## Commands
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
- Do not edit generated files.
- Do not change dependencies without approval.
- Run the relevant tests before claiming completion.

Continue with the first workflow or use the starter CLAUDE.md templates.

Choose a learning path

Situation Suggested route
New to Claude Code Seven-module learning path
Already using the CLI Core Concepts, then Context Engineering
Senior developer or tech lead Methodologies, Agent Harness Engineering, then Production Safety
Engineering manager or CTO Adoption Approaches, Team Metrics, then Subscription Strategy
Security or platform role Security Hardening, Enterprise Governance, then Observability
Product manager or designer Product Manager Guide or Design-to-Code Workflow
Non-developer knowledge worker Claude Cowork Guide

For a personalized route, use the repository onboarding prompt:

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

Build

Agent engineering

An agent is one component of a larger system. The surrounding harness controls context, tools, permissions, state, stopping conditions, recovery, and evaluation.

Resource Decision it supports
Agent Harness Engineering Identify the controls required around an agent loop
Loop & Graph Engineering Choose bounded feedback loops or explicit workflow graphs
Agent Harness Map Distinguish runtimes, orchestrators, frameworks, control planes, and support tools
Agentic Tools Compare selected coding agents and orchestration products
Agent Evaluation Test behavior, regressions, and task-level outcomes
Harness Glossary Align terminology across design and review

Context and memory

Context quality affects every tool call and decision. Start with project instructions, add specialized context only when a recurring task needs it, and test whether the extra material changes behavior.

Resource Focus
Context Engineering Context budget, modular instructions, assembly, and measurement
Memory Systems Native memory, cross-session systems, team sharing, and retention risks
Context Engineering Tools Output compression, retrieval, gateways, and context inspection
Context Audit Measure a project's context architecture
Team AI Instructions Maintain shared instructions across a development team

Workflows

Goal Workflow
Implement with tests first TDD with Claude
Define behavior before implementation Spec-First Development
Separate planning from execution Plan-Driven Development
Compare independent candidates Best-of-N
Coordinate several agents Agent Teams
Build bounded autonomous loops Agentic Software Factories
Review code systematically Code Review
Prepare a contribution another team can review AI-Assisted Open Source Contributions
Diagnose unfamiliar repositories Exploration Workflow

Browse every workflow for task management, GitHub Actions, production reliability, event-driven agents, design-to-code, PDF generation, search, and team instructions.

Choose the smallest interface

Claude Code can call local commands, skills, agents, hooks, plugins, and MCP servers. More infrastructure adds setup, permissions, failure modes, and maintenance.

If the task needs Prefer
A deterministic local command CLI or script
Reusable instructions and supporting files Skill
A separate context and role Agent
A response to a lifecycle event Hook
A packaged collection of capabilities Plugin
A typed interface to a remote service MCP server

Use the MCP or CLI decision guide and the trade-off framework before introducing another integration.

Scale

Reliability and security

Concern Primary resource Operational companion
Permissions and prompt injection Security Hardening Permissions Audit
Isolation of untrusted execution Sandbox Isolation Native Sandbox
Production changes and rollback Production Safety Production Reliability
Sensitive data and retention Data Privacy Enterprise Governance
Active testing of authorized applications Agentic Pentesting DarkMoon and Strix Evaluation
MCP and extension supply chain MCP Ecosystem Threat Database
Delegation readiness Specification Completeness Audit Agent Evaluation

Security claims and threat counts change as sources are added or corrected. Use the linked database and guides as the current source instead of copying their counts into project documentation.

Evaluation and operations

Need Resource
Trace agent behavior and failures Observability
Attribute AI-assisted changes AI Traceability
Evaluate team outcomes Team Metrics
Calculate task-level cost AI Unit Economics
Operate infrastructure workflows DevOps & SRE
Route governed API traffic API Gateways

A green structural check proves only what it inspected. Runtime behavior, task acceptance, security boundaries, and business outcomes require separate evidence.

Organization and economics

Decision Resource
Roll out Claude Code across a team Adoption Approaches
Define usage tiers and approvals Enterprise Governance
Preserve team knowledge Team Knowledge Base
Compare subscriptions, APIs, and gateways Subscription Strategy
Compare hosted and local inference Local vs Cloud Inference
Map changing AI roles AI Roles

The economics pages separate observed costs from estimates and scenarios. Recalculate them with your workload, acceptance criteria, review effort, and risk constraints.

Use the format that fits the task

Format Use it for Read online Source or download
Complete reference Deep explanations and linked sections Ultimate Guide Markdown
Daily reference Commands, shortcuts, and checks Quick Reference Markdown
Guided course Progressive exercises with retained evidence Learning Paths Course sources
Runnable material Agents, skills, hooks, workflows, and scripts Examples Files
Visual explanation Architecture, context, security, and workflow maps Diagrams Diagram sources
Knowledge check Questions with documentation links Quiz Question sources
Printable reference One concept per page in French and English Cheat Sheets Card sources
Long-form edition Offline PDF and EPUB Ebooks Downloads
Machine-readable index Search and retrieval by an AI assistant Guide MCP llms.txt and reference.yaml

MCP Server: Use the guide from any coding client

Install the guide as a stdio MCP server and query it from Claude Code, Codex, Cursor, VS Code, or another MCP client.

claude mcp add --scope user claude-code-guide -- npx -y [email protected]
codex mcp add claude-code-guide -- npx -y [email protected]

Project-scoped Claude Code configuration belongs in .mcp.json:

{
  "mcpServers": {
    "claude-code-guide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}
Capability Count Names
Tools 17 compare_versions, diff_official_docs, get_changelog, get_cheatsheet, get_digest, get_example, get_release, get_threat, init_official_docs, list_examples, list_threats, list_topics, read_section, refresh_official_docs, search_examples, search_guide, search_official_docs
Resources 6 claude-code-guide://agent-harnesses, claude-code-guide://distribution-channels, claude-code-guide://llms, claude-code-guide://reference, claude-code-guide://releases, claude-code-guide://translations
Prompts 1 claude-code-expert
Companion commands 5 /ccguide:daily, /ccguide:diff-docs, /ccguide:init-docs, /ccguide:refresh-docs, /ccguide:search-docs

The list operations and search index use bundled content. Section, example, cheatsheet, changelog, digest (get_digest), and threat tools can fetch GitHub content and write a 24-hour local cache. The official-doc initialization and refresh tools fetch Anthropic documentation and write separate local snapshots.

Canonical technical guide, installation, privacy, limitations, and dated statistics

Package README and diagnostics

Companion commands rendered from the repository: /ccguide:daily, /ccguide:diff-docs, /ccguide:init-docs, /ccguide:refresh-docs, /ccguide:search-docs.

Load the guide into another assistant

Use the small index for discovery:

curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/llms.txt

Use reference.yaml when the assistant needs structured topic routes and links into the full guide. Maintenanc

claude-code-ultimate-guide (FlorianBruniaux/claude-code-ultimate-guide)

Searching Database…

6.2K ·GitHub
Claude-code-ultimate-guide
What is this?A deep, 430K+ line guide to Claude Code covering agentic workflows, hooks, skills, MCP servers, security, and production practices, paired with runnable templates and quizzes to learn from.
Is this a guide to read or a tool to run?It's mainly a Markdown-based learning guide with a companion website, quizzes, cheat sheets, and ebooks, but it also ships a runnable MCP server so any MCP-compatible client can query the guide's content directly.
How do I start using this guide?Install Claude Code first, complete a small bounded task to learn the basics, then pick a learning path based on your role (new user, senior dev, security role, engineering manager, etc.) from the guide portal.
Do I need Claude Code itself before this is useful?Yes — the guide assumes you're installing and using Claude Code (or another MCP client like Codex, Cursor, or VS Code); the Quick Start chapter walks through installation, authentication, and a first bounded task.
How reliable are the security and threat numbers in the guide?The authors explicitly warn that security claims and threat counts change as sources are added or corrected, so live numbers should be pulled from the linked database rather than copied into your own docs.
Can I use the guide's MCP server fully offline?Most listing and search operations use bundled content, but tools that fetch sections, examples, cheat sheets, changelogs, or threat data pull live GitHub content and cache it locally for 24 hours; official-doc tools fetch Anthropic's docs separately.
What formats does the guide come in besides the website?It also ships as a Quick Reference, a seven-module course (Learning Paths), runnable Examples, architecture diagrams, a knowledge quiz, French/English cheat sheets, and offline PDF/EPUB ebooks.
What does the guide's bundled MCP server expose?It exposes 17 tools (like searchguide, getcheatsheet, getthreat), 6 resources, 1 prompt, and 5 companion slash commands such as /ccguide:daily, letting an agent search and pull guide content, cheat sheets, changelogs, and threat data on demand.
How do I decide between a skill, an agent, a hook, or an MCP server for a task?The guide recommends matching the interface to the task: a CLI/script for deterministic commands, a Skill for reusable instructions, an Agent for a separate context/role, a Hook for lifecycle events, a Plugin for packaged capabilities, and an MCP server only for a typed interface to a remote service.
Who is each section of the guide aimed at?The 'Start' and 'Build' sections target developers learning Claude Code and designing agent systems, while 'Scale' targets security, platform, and engineering-management roles handling governance, observability, and adoption.
What are similar projects?Baize, claude-code-best-practice, vibe-coding-cn, context-engineering-intro, awesome-claude-code, how-claude-code-works, vibe-wise, agor
Which topics is it in?mcp-servers, slash-commands, coding-assistant, ai-security, agentic-coding, vibe-coding, ai-assistant, cheatsheet, ebook, ai-coding, best-practices, enterprise
Creator
FlorianBruniaux
Size
48.2 MB
Stars
6.2K
Updated
CommitOct 17Releasev3.44.1Oct 06
Age
9mo
Commits · 90 Days