Claude Code Guide: Complete Tutorial & Best Practices

The comprehensive guide to Claude Code — Anthropic's AI coding assistant CLI. From installation to advanced MCP servers, agents, skills, hooks, and CI/CD integration.

Author: Florian BRUNIAUX | Founding Engineer @Méthode Aristote

Contact: LinkedIn

Written with: Claude (Anthropic)

If you find this guide useful, please consider giving it a star! It helps others discover this resource and motivates continued updates.

---

What's Inside

File	Description	Reading Time
english-ultimate-claude-code-guide.md	Complete guide (8500+ lines, 32K+ words)	~3 hours
cheatsheet-en.md	1-page printable daily reference	5 minutes
claude-setup-audit-prompt.md	Self-audit prompt for your setup	~10 minutes
examples/	Production-ready commands, hooks, agents	Browse as needed
claude-code-ultimate-guide_notebooklm.pdf	NotebookLM slides export	~20 minutes
claude-code-ultimate-guide_kimi.pdf	PDF version (Kimi export)	~3 hours

🔍 Explore Interactively

DeepWiki: Interactive Documentation

Transform this repository into an interactive AI-powered documentation explorer:

• Ask questions in natural language about the guide
• Navigate contextually through interconnected concepts
• Search semantically beyond keyword matching
• Get summaries of specific sections on demand

Perfect for quick lookups when you don't want to read the full 8500+ lines.

---

About This Guide

Our Pedagogical Approach

Unlike reference manuals that simply list features, this guide follows a learning journey designed to take you from beginner to power user. We focus on:

• Understanding why before diving into how
• Real-world patterns you can use immediately
• Progressive complexity — start simple, master advanced techniques at your pace
• Practical workflows over theoretical concepts

Think of this as your mentor for mastering Claude Code — not just documentation.

Origins & Philosophy

This guide is the result of several months of daily practice and research with Claude Code, Anthropic's AI coding assistant CLI. Whether you're exploring agentic development, LLM-powered coding workflows, or AI pair programming, this resource covers everything from basic setup to advanced MCP server orchestration.

I don't claim to be an "expert" — I'm simply sharing what I've learned along the way, humbly hoping to help my peers and evangelize good practices in AI-assisted development.

Key inspirations for this work:

• Claudelog.com — Excellent tips, patterns & tutorials (highly recommended)
• zebbern/claude-code-guide — Comprehensive reference & troubleshooting guide with cybersecurity focus
• ykdojo/claude-code-tips — Practical tips & productivity techniques from Y.K. Dojo

Important note: This guide was largely generated with the help of AI. As such, it likely contains errors, inaccuracies, or outdated information. I would be delighted to receive any feedback, corrections, or — even better — pull requests to improve it. Don't hesitate to open an issue or submit a PR!

⚠️ WINDOWS USERS - IMPORTANT DISCLAIMER

I work on macOS and have not personally tested Windows-specific commands (PowerShell, batch files, path syntax).

What this means for you:

• PowerShell scripts are AI-generated and may need adjustment
• Path separators (\ vs /) may be incorrect in some examples
• Batch file hooks may require debugging
• Git Bash commands should work as-is (they use Unix syntax)

How you can help:

1. Open an issue if you find Windows-specific problems
2. Submit a PR with corrections (Windows testers highly appreciated!)
3. Join our community discussions to share Windows-specific tips

Status: We are actively seeking Windows contributors to improve platform support.

Language: I wrote this guide in English by default to reach a wider audience, but French is my native language. I could easily translate it to French myself, or leverage AI and community contributions for other languages. Let me know if translations would be useful!

If you find value in this guide, have questions, or want to discuss Claude Code practices, feel free to reach out on LinkedIn.

---

Ready-to-Use Examples

The examples/ directory contains production-ready templates you can copy directly into your projects:

🎯 Commands (Slash Commands)

Command	Purpose	Highlights
/pr	Create PRs with scope analysis	Complexity scoring, auto-detect scope issues, split suggestions
/release-notes	Generate release notes (3 formats)	CHANGELOG + PR body + Slack announcement, migration detection
/sonarqube	Analyze SonarCloud quality issues	Executive summary, top violators, action plan
/commit	Conventional commit messages	Follows team conventions, auto-formats
/review-pr	PR review workflow	Structured feedback, security checks
/git-worktree	Isolated git worktree setup	Safe parallel development

🛡️ Hooks (Event Automation)

Hook	Event	Purpose
dangerous-actions-blocker.sh	PreToolUse	Block rm -rf /, force push, secrets, dangerous edits
notification.sh	Notification	macOS sound alerts (success, error, warning)
security-check.sh	PreToolUse	Detect secrets in commands
auto-format.sh	PostToolUse	Auto-format with Prettier

📖 See examples/README.md for complete catalog including agents, skills, and config templates

---

Table of Contents

Jump directly to any section in the full guide:

#	Section	Description
1	Quick Start	Installation, first workflow, essential commands
2	Core Concepts	Context management, Plan Mode, Rewind, Mental Model
3	Memory & Settings	CLAUDE.md files, .claude/ folder, precedence rules
4	Agents	Custom AI personas, Tool SEO, orchestration patterns
5	Skills	Reusable knowledge modules (Security, TDD...)
6	Commands	Custom slash commands, variable interpolation
7	Hooks	Event-driven automation (security, formatting, logging)
8	MCP Servers	Serena, Context7, Sequential, Playwright, Postgres
9	Advanced Patterns	Trinity, CI/CD, feedback loops, vibe coding
10	Reference	Commands, shortcuts, troubleshooting, checklists
A	Appendix	Ready-to-use templates

Quick Links by Topic

Getting Started

• Installation · First Workflow · Essential Commands

Critical Concepts

• Context Management · Plan Mode · Memory Files

Customization

• Creating Agents · Creating Skills · Creating Commands · Creating Hooks

Advanced

• The Trinity Pattern · CI/CD Integration · MCP Configuration

---

Quick Start

# Install Claude Code (all platforms)
npm install -g @anthropic-ai/claude-code

# Or on macOS/Linux only:
curl -fsSL https://claude.ai/install.sh | sh

# Start in your project
cd your-project
claude

Windows Users: Use %USERPROFILE%\.claude\ instead of ~/.claude/ for all paths in this guide.

The 7 Commands You Need

Command	Action
/help	Show all commands
/status	Check context usage
/compact	Compress context (>70%)
/clear	Fresh start
/plan	Safe read-only mode
/rewind	Undo changes
Ctrl+C	Cancel operation

Context Management (Critical!)

Context %	Action
0-50%	Work freely
50-70%	Be selective
70-90%	/compact now
90%+	/clear required

---

The Golden Rules

1. Always review diffs before accepting changes
2. Use /compact before context gets critical (>70%)
3. Be specific in requests (WHAT, WHERE, HOW, VERIFY)
4. Start with Plan Mode for complex/risky tasks
5. Create CLAUDE.md for every project

---

Who Is This For?

• Beginners: Start with Quick Start (15 min) → be productive immediately
• Intermediate: Deep dive into Configuration, Agents, Skills
• Power Users: Advanced Patterns, MCP orchestration, CI/CD integration

---

Learning Paths

Choose your path based on experience and goals:

Junior Developer (45 min to productivity)

1. Quick Start - Installation & first workflow
2. Essential Commands - The 7 commands you need
3. Context Management - Critical concept
4. Memory Files - Create your first CLAUDE.md
5. Cheatsheet - Print and keep nearby

Senior Developer (40 min to mastery)

1. Core Concepts - Mental model & context zones
2. Plan Mode - Safe exploration
3. Agents - Custom AI personas
4. Hooks - Event-driven automation
5. CI/CD Integration - Pipeline automation

Power User (2 hours for full mastery)

1. Read the complete guide end-to-end
2. MCP Servers - Extended capabilities
3. The Trinity Pattern - Advanced workflows
4. Audit your setup - Optimize your configuration
5. Explore examples/ - Ready-to-use templates

Non-Technical / Product Manager (20 min overview)

1. What's Inside - Understand the scope
2. The Golden Rules - Key principles
3. Core Concepts - High-level overview
4. Context Management - Why it matters

---

Contributing

Found an error? Have a suggestion? See CONTRIBUTING.md for guidelines.

---

Audit Your Setup

Want to know if your Claude Code setup follows best practices?

Option 1: Quick Bash Scan (2 seconds)

Script: examples/scripts/audit-scan.sh

# Human-readable output
./examples/scripts/audit-scan.sh

# JSON output for processing
./examples/scripts/audit-scan.sh --json

# Or download and run directly
curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash

What it checks (instantly):

• ✅ Global and project config files existence
• 📦 Tech stack detection (Node.js, Python, Go, Rust, etc.)
• 🔧 Extensions count (agents, commands, skills, hooks)
• 🔒 Security hooks presence (PreToolUse patterns)
• 📖 MCP servers configured
• 📏 CLAUDE.md quality metrics (size, @references)

Option 2: Full Audit with Claude (~3 minutes)

File: claude-setup-audit-prompt.md

How it works:

1. Copy the prompt from the file
2. Run claude --ultrathink in your project
3. Paste the prompt and get a comprehensive audit report

What it checks:

• Everything from Option 1, plus:
• Context management practices
• Single Source of Truth patterns
• CI/CD integration patterns
• Best practices against the full guide

Output: A prioritized report with health score, quick wins, and ready-to-use templates tailored to your tech stack.

Performance: The audit now uses bash/grep for ~80% faster scanning and 90% fewer tokens!

---

Resources

Official

• Claude Code Documentation — Official Anthropic docs

Related Guides

• zebbern/claude-code-guide — Comprehensive reference & troubleshooting guide with cybersecurity focus (excellent for security practitioners)
• Claudelog.com — Tips, patterns & tutorials (highly recommended for all users)
• ykdojo/claude-code-tips — Practical tips & productivity techniques (voice workflows, context management, terminal efficiency)
  • Additional topics worth exploring: voice transcription (superwhisper/MacWhisper), tmux autonomous testing, cc-safe tool, cascade method, container experimentation, half-clone technique
• DeepTo Claude Code Guide — Comprehensive best practices covering XML-structured prompts, session continuation, image processing, Unix piping workflows, and cost tracking (ccusage tool)
• Shipyard: Claude Code Cheat Sheet — Quick reference covering CLI flags, MCP configuration patterns, and command examples

Community Curated Lists

• awesome-claude-code — Extensive reference library (19.9k stars) covering commands, workflows, hooks, IDE integrations, and monitoring tools. Note: This is a curated collection for discovering solutions, not an architectural guide—it lists tools without guidance on how to combine them intelligently or which to choose based on specific needs
• awesome-claude-skills — Custom skills collection
• awesome-claude-code-subagents — Full-stack & DevOps subagents
• awesome-claude — General Claude resources (SDKs, tools)
• awesome-claude-prompts — Prompt templates

Frameworks & Tools

• SuperClaude — Advanced configuration framework with 30+ commands

Further Reading

• Nick Tune: Coding Agent Development Workflows — Advanced autonomous workflow patterns
• Neon Branching Documentation — Database branching for development workflows
• PlanetScale Branching Documentation — MySQL branching and deployment patterns

---

License

This work is licensed under CC BY-SA 4.0.

You are free to share and adapt this material, provided you give appropriate credit and distribute your contributions under the same license.

---

Last updated: January 2026 | Version 2.8