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
claudeGive 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.
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