claude-code-ultimate-guide

Claude Code Ultimate Guide

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

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 · AI FinOps · LLM Market Snapshot · 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 claude-code-ultimate-guide-mcp@1.3.6
codex mcp add claude-code-guide -- npx -y claude-code-ultimate-guide-mcp@1.3.6

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

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

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. Maintenance instructions belong in the machine-readable documentation, not in this README.

Complementary ecosystem

No single repository needs to cover learning, installation, curation, reference material, and every specialized interface. Choose the resource that matches the current task.

Need	Resource	What it provides
Verify Claude Code behavior	Official Claude Code documentation	Primary product documentation
Learn architecture, trade-offs, security, and workflows	Claude Code Guide	Explanations, decision guides, operational checks, and examples
Discover community projects	awesome-claude-code	Curated links across the ecosystem
Install a collection of configurations	everything-claude-code	Packaged agents, skills, hooks, and configurations
Browse installable templates	claude-code-templates	Template catalog and CLI distribution
Start from official skill examples	anthropics/skills	Anthropic-maintained skill examples
Browse the skills marketplace	skills.sh	Search and installation routes for published skills
Curate Claude Code hooks	awesome-claude-code-hooks	Curated list of Claude Code hooks
Work outside software development	Claude Cowork Guide	Workflows for knowledge workers
Compare coding-agent capabilities	AI Coding Agents Matrix	Cross-agent feature comparison

This short list was reviewed on 2026-08-31. Project activity, installation methods, and scope can change. Browse the public Ecosystem and Compare pages first. The AI Ecosystem source, Third-Party Tools source, and Resource Evaluations retain the deeper evidence.

Updates

Guide changes and Claude Code product releases answer different questions:

Feed	Tracks	Source
Guide Changelog	New pages, corrections, and major repository revisions	CHANGELOG.md
Claude Code Releases	Claude Code product versions and operational impact	Release source
RSS Feed	Published guide and product updates in a feed reader	Generated by the website

Recent guide additions include:

• Mistral Large 4 evaluation: October 6 launch evidence, promotional pricing, independent results, regional inference, and pending weights; integrated into the market snapshot and AI ecosystem.
• Loop & Graph Engineering (source): bounded feedback, workflow state, stopping rules, recovery, and judgment allocation.
• Subscription Strategy (source): seats, APIs, gateways, self-hosting scenarios, and team-scale decision gates.
• Cross-Session Messaging (source): peer discovery, delivery, security boundaries, and correlated-drift controls.

Use the changelog for the complete history. The README should expose only a small current selection.

Languages and translations

English is the canonical edition. French is maintained in this repository. Simplified Chinese, Ukrainian, and Latin American Spanish are independent community editions with separate update schedules.

Language	Edition
English	Canonical guide
Français	French guide maintained in this repository
简体中文	Community edition by JAYcodr
Українська	Community edition by gerasimsergey
Español latinoamericano	Community edition by Richardls

The translation status page records maintainers, source commits, coverage, measured lag, and review status.

Repository map

guide/
├── ultimate-guide.md       Complete reference
├── learning-path/          Guided course
├── core/                   Architecture, tools, context, methods
├── security/               Hardening, isolation, privacy, governance
├── ecosystem/              Agents, MCP, tools, inference, knowledge
├── roles/                  Adoption, learning, evaluation, careers
├── ops/                    Observability, metrics, economics, gateways
├── workflows/              Task-oriented delivery guides
└── diagrams/               Mermaid diagrams with text fallbacks

examples/                   Reusable agents, skills, hooks, and workflows
machine-readable/           Structured indexes and release data
mcp-server/                 Packaged guide access for MCP clients
quiz/                       Local knowledge validation
docs/resource-evaluations/  Reviewed external resources
whitepapers/                French and English long-form sources

The detailed guide index, examples catalog, and tool index are the canonical navigation pages for those directories.

Contributing

Corrections, missing evidence, broken links, examples, quiz questions, and documentation improvements are welcome. Read CONTRIBUTING.md before opening a pull request.

Useful contribution routes:

• Report an incorrect or outdated claim through GitHub Issues.
• Submit an external resource through the resource evaluation process.
• Propose a focused guide or workflow with its sources, boundaries, and verification method.
• Improve an example without weakening its existing security checks.

Maintainer

Florian Bruniaux maintains this guide.

GitHub · LinkedIn · Portfolio

Explore the ecosystem

These projects extend the workflow without duplicating this tool:

• Install with claude-code-plugins: move from explanations to installable templates.
• Validate with ctxharness: test whether documented context and instructions still match the repository.
• Secure with agentsec-triage: connect security guidance to a versioned operational feed.
• Continue with Claude Cowork Guide: switch to workflows designed for knowledge workers and non-developers.

Browse the complete open-source galaxy

License

The guide uses CC BY-SA 4.0. Reusable templates use CC0 1.0. Check the repository license files before redistributing mixed content.

Watch GitHub Releases or subscribe to the RSS feed for updates.

---

Version 3.44.1 | Updated daily · Oct 7, 2026