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](https://cc.bruniaux.com/guide/ultimate-guide/01-quick-start/) · [browse the guide portal](https://cc.bruniaux.com/guide/) · [open the complete sitemap](https://cc.bruniaux.com/sitemap/) · [read the Markdown source](./guide/ultimate-guide.md) ## Choose your next step The table below is generated from [`machine-readable/navigation.json`](./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](https://cc.bruniaux.com/guide/) · [Quick Start](https://cc.bruniaux.com/guide/ultimate-guide/01-quick-start/) · [Learning Paths](https://cc.bruniaux.com/learning/) · [Quick Reference](https://cc.bruniaux.com/cheatsheet/) · [AI Roles](https://cc.bruniaux.com/roles/) | | **Build** | [Agent Harness Engineering](https://cc.bruniaux.com/guide/agent-harness/) · [Loop & Graph Engineering](https://cc.bruniaux.com/guide/loop-graph-engineering/) · [Context Engineering](https://cc.bruniaux.com/context-engineering/) · [Memory Systems](https://cc.bruniaux.com/memory-systems/) · [Workflows](https://cc.bruniaux.com/guide/workflows/) · [Methodologies](https://cc.bruniaux.com/methodologies/) · [MCP or CLI?](https://cc.bruniaux.com/mcp-or-cli/) · [Examples](https://cc.bruniaux.com/examples/) | | **Scale** | [Security](https://cc.bruniaux.com/security/) · [Enterprise Governance](https://cc.bruniaux.com/guide/enterprise-governance/) · [Observability](https://cc.bruniaux.com/guide/observability/) · [Team Metrics](https://cc.bruniaux.com/team-metrics/) · [Team Adoption](https://cc.bruniaux.com/guide/adoption-approaches/) · [Subscription Strategy](https://cc.bruniaux.com/guide/subscription-strategy/) · [AI Unit Economics](https://cc.bruniaux.com/guide/ai-unit-economics/) · [Team Knowledge](https://cc.bruniaux.com/guide/team-knowledge-base/) · [API Gateway](https://cc.bruniaux.com/guide/api-gateway/) | | **Resources** | [Resource Hub](https://cc.bruniaux.com/resources/) · [Downloads](https://cc.bruniaux.com/downloads/) · [Cheat Sheets](https://cc.bruniaux.com/cheatsheets/) · [Ebooks](https://cc.bruniaux.com/whitepapers/) · [Diagrams](https://cc.bruniaux.com/diagrams/) · [Ecosystem](https://cc.bruniaux.com/ecosystem/) · [Compare](https://cc.bruniaux.com/compare/) · [Glossary](https://cc.bruniaux.com/guide/glossary/) · [FAQ](https://cc.bruniaux.com/faq/) · [Guide MCP Server](https://cc.bruniaux.com/mcp/) · [Related Projects](https://cc.bruniaux.com/projects/) | | **Updates** | [Guide Changelog](https://cc.bruniaux.com/changelog/) · [Claude Code Releases](https://cc.bruniaux.com/releases/) · [RSS Feed](https://cc.bruniaux.com/rss.xml) | ## 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](./guide/core/architecture.md) and [Tools Reference](./guide/core/tools-reference.md) | | Design agent systems | [Agent Harness Engineering](./guide/core/agent-harness.md) and [Loop & Graph Engineering](./guide/core/loop-graph-engineering.md) | | Structure AI-assisted delivery | [Methodologies](./guide/core/methodologies.md) and [Workflow Guides](./guide/workflows/) | | Establish a security boundary | [Security Hardening](./guide/security/security-hardening.md) and [Sandbox Isolation](./guide/security/sandbox-isolation.md) | | Validate understanding | [Knowledge Quiz](https://cc.bruniaux.com/quiz/) and [Recap Cards](https://cc.bruniaux.com/cheatsheets/) | 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: ```bash # 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: ```powershell irm https://claude.ai/install.ps1 | iex ``` Verify the installation and authenticate: ```bash claude --version claude doctor claude auth login ``` The [Quick Start chapter](./guide/ultimate-guide.md#1-quick-start-day-1) 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: ```bash cd your-project claude ``` Give Claude a bounded request that includes the expected result and verification: ```text 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: ```markdown # 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](./guide/ultimate-guide.md#12-first-workflow) or use the [starter CLAUDE.md templates](./examples/claude-md/). ### Choose a learning path | Situation | Suggested route | |---|---| | New to Claude Code | [Seven-module learning path](./guide/learning-path/README.md) | | Already using the CLI | [Core Concepts](./guide/ultimate-guide.md#2-core-concepts), then [Context Engineering](./guide/core/context-engineering.md) | | Senior developer or tech lead | [Methodologies](./guide/core/methodologies.md), [Agent Harness Engineering](./guide/core/agent-harness.md), then [Production Safety](./guide/security/production-safety.md) | | Engineering manager or CTO | [Adoption Approaches](./guide/roles/adoption-approaches.md), [Team Metrics](./guide/ops/team-metrics.md), then [Subscription Strategy](./guide/ops/subscription-strategy.md) | | Security or platform role | [Security Hardening](./guide/security/security-hardening.md), [Enterprise Governance](./guide/security/enterprise-governance.md), then [Observability](./guide/ops/observability.md) | | Product manager or designer | [Product Manager Guide](./docs/for-product-managers.md) or [Design-to-Code Workflow](./guide/workflows/design-to-code.md) | | Non-developer knowledge worker | [Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) | For a personalized route, use the repository onboarding prompt: ```bash 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](./guide/core/agent-harness.md) | Identify the controls required around an agent loop | | [Loop & Graph Engineering](./guide/core/loop-graph-engineering.md) | Choose bounded feedback loops or explicit workflow graphs | | [Agent Harness Map](./guide/ecosystem/agent-harness-landscape.md) | Distinguish runtimes, orchestrators, frameworks, control planes, and support tools | | [Agentic Tools](./guide/ecosystem/agentic-tools.md) | Compare selected coding agents and orchestration products | | [Agent Evaluation](./guide/roles/agent-evaluation.md) | Test behavior, regressions, and task-level outcomes | | [Harness Glossary](./guide/core/glossary.md) | 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](./guide/core/context-engineering.md) | Context budget, modular instructions, assembly, and measurement | | [Memory Systems](./guide/core/memory-systems.md) | Native memory, cross-session systems, team sharing, and retention risks | | [Context Engineering Tools](./guide/ecosystem/context-engineering-tools.md) | Output compression, retrieval, gateways, and context inspection | | [Context Audit](./tools/context-audit-prompt.md) | Measure a project's context architecture | | [Team AI Instructions](./guide/workflows/team-ai-instructions.md) | Maintain shared instructions across a development team | ### Workflows | Goal | Workflow | |---|---| | Implement with tests first | [TDD with Claude](./guide/workflows/tdd-with-claude.md) | | Define behavior before implementation | [Spec-First Development](./guide/workflows/spec-first.md) | | Separate planning from execution | [Plan-Driven Development](./guide/workflows/plan-driven.md) | | Compare independent candidates | [Best-of-N](./guide/workflows/best-of-n.md) | | Coordinate several agents | [Agent Teams](./guide/workflows/agent-teams.md) | | Build bounded autonomous loops | [Agentic Software Factories](./guide/workflows/agentic-software-factories.md) | | Review code systematically | [Code Review](./guide/workflows/code-review.md) | | Prepare a contribution another team can review | [AI-Assisted Open Source Contributions](./guide/workflows/ai-assisted-open-source-contributions.md) | | Diagnose unfamiliar repositories | [Exploration Workflow](./guide/workflows/exploration-workflow.md) | [Browse every workflow](./guide/workflows/) 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](./guide/ecosystem/