AI 原生开放教材

外观

Claude Code Ultimate Guide工程手册·英文原文 ↗原件 ↓仓库 ↗

The Ultimate Claude Code Guide ​

A comprehensive, self-contained guide to mastering Claude Code - from zero to power user.

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

Written with: Claude (Anthropic)

Reading time: ~30-40 hours (full) | ~15 minutes (Quick Start only)

Last updated: January 2026

Version: 3.43.0

Before You Start ​

This guide is not official Anthropic documentation. It's a community resource based on my exploration of Claude Code over several months.

What you'll find:

  • Patterns that have worked for me
  • Observations that may not generalize to your workflow
  • Time estimates and percentages that are rough approximations, not measurements

What you won't find:

  • Definitive answers (the tool is too new)
  • Benchmarked performance claims
  • Guarantees that any technique will work for you

Use critically. Experiment. Share what works for you.

⚠️ Note (Jan 2026): If you've heard about ClawdBot recently, that's a different tool. ClawdBot is a self-hosted chatbot assistant accessible via messaging apps (Telegram, WhatsApp, etc.), designed for personal automation and smart home use cases. Claude Code is a CLI tool for developers (terminal/IDE integration) focused on software development workflows. Both use Claude models but serve distinct audiences and use cases. More details in Appendix B: FAQ.

TL;DR - The 5-Minute Summary ​

If you only have 5 minutes, here's what you need to know:

Essential Commands ​

bash
claude                    # Start Claude Code
/help                     # Show all commands
/powerup                  # Interactive lessons: CLAUDE.md, /rewind, memory, effort modes
/status                   # Check context usage
/compact                  # Compress context when >70%
/clear                    # Fresh start
/plan                     # Safe read-only mode
Ctrl+C                    # Cancel operation

The Workflow ​

Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify

Context Management (Critical!) ​

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

These thresholds are based on my experience. Your optimal workflow may differ depending on task complexity and working style.

Memory Hierarchy ​

~/.claude/CLAUDE.md       → Global (all projects)
/project/CLAUDE.md        → Project (committed)
/project/.claude/         → Personal (not committed)

Power Features ​

FeatureWhat It Does
AgentsSpecialized AI personas for specific tasks
SkillsReusable knowledge modules
HooksAutomation scripts triggered by events
MCP ServersExternal tools (Serena, Context7, Playwright...)
PluginsCommunity-created extension packages

The Golden Rules ​

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

Quick Decision Tree ​

Simple task → Just ask Claude
Complex task → Use TodoWrite to plan
Risky change → Enter Plan Mode first
Repeating task → Create an agent or command
Context full → /compact or /clear

Now read Section 1 for the full Quick Start, or jump to any section you need.

Choose Your Path ​

The guide has 11 chapters and 22,000+ lines. You don't need to read everything: here's what matters for your situation.

I am...Read thisSkip thisTime
Developer, getting startedCh.1 → Ch.2 → Ch.3Ch.9, Ch.11, Appendix3h
Developer, intermediateCh.2.6 → Ch.4 → Ch.5 → Ch.7Ch.1, Ch.10 ref only4h
Power user / seniorCh.9 (Advanced) → Ch.4-8Ch.1 Quick Start2h
Tech Lead / EMCh.3.5 → Ch.9.17 → Ch.9.20 → Ch.11Ch.5-6 detail1h30
Just need a referenceCh.10.5 CheatsheetEverything else5 min

Top 5 sections by ROI ​

If you only have time for 5 sections:

  1. 2.6 Mental Model: Understand how Claude Code thinks (20 min)
  2. 3.1 CLAUDE.md: Persistent memory that survives sessions (30 min)
  3. 9.1 The Trinity: The core pattern for agentic work (20 min)
  4. 7.4 Security Hooks: Automate guardrails you won't forget (30 min)
  5. 10.5 Cheatsheet: Daily reference, bookmark it (5 min)

Table of Contents ​

1. Quick Start (Day 1) ​

Quick jump: Installation · First Workflow · Essential Commands · Permission Modes · Productivity Checklist · Migrating from Other Tools · Beginner Mistakes

Reading time: 15 minutes

Skill level: Beginner

Goal: Go from zero to productive

Already using Claude Code? Skip to 1.6 Migration guide or go directly to Ch.2 Core Concepts.

1.1 Installation ​

Choose your preferred installation method based on your operating system:

C
/*──────────────────────────────────────────────────────────────*/
/* Universal Method       */ npm install -g @anthropic-ai/claude-code
/*──────────────────────────────────────────────────────────────*/
/* Windows (CMD)          */ npm install -g @anthropic-ai/claude-code
/* Windows (PowerShell)   */ irm https://claude.ai/install.ps1 | iex
/*──────────────────────────────────────────────────────────────*/
/* macOS (npm)            */ npm install -g @anthropic-ai/claude-code
/* macOS (Homebrew)       */ brew install claude-code
/* macOS (Shell Script)   */ curl -fsSL https://claude.ai/install.sh | sh
/*──────────────────────────────────────────────────────────────*/
/* Linux (npm)            */ npm install -g @anthropic-ai/claude-code
/* Linux (Shell Script)   */ curl -fsSL https://claude.ai/install.sh | sh

Verify Installation ​

bash
claude --version

Updating Claude Code ​

Keep Claude Code up to date for the latest features, bug fixes, and model improvements:

bash
# Check for available updates
claude update

# Alternative: Update via npm
npm update -g @anthropic-ai/claude-code

# Verify the update
claude --version

# Check system health after update
claude doctor

Available maintenance commands:

CommandPurposeWhen to Use
claude updateCheck and install updatesWeekly or when encountering issues
claude doctorVerify auto-updater healthAfter system changes or if updates fail
claude --versionDisplay current versionBefore reporting bugs
claude auth loginAuthenticate from the command lineCI/CD, devcontainers, scripted setups
claude auth statusCheck current authentication stateVerify which account/method is active
claude auth logoutClear stored credentialsShared machines, security cleanup

Update frequency recommendations:

  • Weekly: Check for updates during normal development
  • Before major work: Ensure latest features and fixes
  • After system changes: Run claude doctor to verify health
  • On unexpected behavior: Update first, then troubleshoot

Desktop App: Claude Code Without the Terminal ​

Claude Code is available in two forms: the CLI (what this guide focuses on) and the Code tab in the Claude Desktop app. Same underlying engine, graphical interface instead of terminal. Available on macOS and Windows, with no Node.js installation required.

What the desktop adds on top of standard Claude Code:

FeatureDetails
Visual diff reviewReview file changes inline with comments before accepting
Live app previewClaude starts your dev server, opens an embedded browser, auto-verifies changes
GitHub PR monitoringAuto-fix CI failures, auto-merge once checks pass
Parallel sessionsMultiple sessions in the sidebar, each with automatic Git worktree isolation
ConnectorsGitHub, Slack, Linear, Notion: GUI setup, no manual MCP config
File attachmentsAttach images and PDFs directly to prompts
Remote sessionsRun long tasks on Anthropic's cloud, continue after closing the app
SSH sessionsConnect to remote machines, cloud VMs, dev containers

When to choose Desktop vs CLI:

Use Desktop when...Use CLI when...
You want visual diff reviewYou need scripting or automation (--print, output piping)
You're onboarding colleaguesYou use third-party providers (Bedrock, Vertex, Foundry)
You want session management in a sidebarYou need dontAsk permission mode
You're doing a live demo or pair reviewYou need agent teams / multi-agent orchestration
You want file attachments (images, PDFs)You're on Linux (Desktop is macOS + Windows only)

What's NOT available in Desktop (CLI only): third-party API providers, scripting flags (--print, --output-format), --allowedTools/--disallowedTools, agent teams, --verbose, Linux.

Shared configuration: Desktop and CLI read the same files: CLAUDE.md, MCP servers (via ~/.claude.json or .mcp.json), hooks, skills, and settings. Your CLI setup carries over automatically.

Migration tip: run /desktop in the terminal to move an active CLI session into the Desktop app. On macOS and Windows only.

Note on MCP servers: MCP servers configured in claude_desktop_config.json (the Chat tab) are separate from Claude Code. To use MCP servers in the Code tab, configure them in ~/.claude.json or your project's .mcp.json. See Section 8.1: MCP.

Full reference: code.claude.com/docs/en/desktop

Platform-Specific Paths ​

PlatformGlobal Config PathShell Config
macOS/Linux~/.claude/~/.zshrc or ~/.bashrc
Windows%USERPROFILE%\.claude\PowerShell profile

Windows Users: Throughout this guide, when you see ~/.claude/, use %USERPROFILE%\.claude\ or C:\Users\YourName\.claude\ instead.

First Launch ​

bash
cd your-project
claude

On first launch:

  1. You'll be prompted to authenticate with your Anthropic account
  2. Accept the terms of service
  3. Claude Code will index your project (may take a few seconds for large codebases)

Note: Claude Code requires an active Anthropic subscription. See claude.com/pricing for current plans and token limits.

1.2 First Workflow ​

Let's fix a bug together. This demonstrates the core interaction loop.

Step 1: Describe the Problem ​

You: There's a bug in the login function - users can't log in with email addresses containing a plus sign

Step 2: Claude Analyzes ​

Claude will:

  • Search your codebase for relevant files
  • Read the login-related code
  • Identify the issue
  • Propose a fix

Step 3: Review the Diff ​

diff
- const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+ const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

💡 Critical: Always read the diff before accepting. This is your safety net.

Step 4: Accept or Reject ​

  • Press y to accept the change
  • Press n to reject and ask for alternatives
  • Press e to edit the change manually

Step 5: Verify ​

You: Run the tests to make sure this works

Claude will run your test suite and report results.

Step 6: Commit (Optional) ​

You: Commit this fix

Claude will create a commit with an appropriate message.

1.3 Essential Commands ​

These 7 commands are the ones I use most frequently:

CommandActionWhen to Use
/helpShow all commandsWhen you're lost
/clearClear conversationStart fresh
/compactSummarize contextRunning low on context
/statusShow session infoCheck context usage
/exit or Ctrl+DExit Claude CodeDone working
/planEnter Plan ModeSafe exploration
/rewindUndo changesMade a mistake
/voiceToggle voice inputSpeak instead of type

Quick Actions & Shortcuts ​

ShortcutActionExample
!commandRun shell command directly!git status, !npm test
@file.tsReference a specific file@src/app.tsx, @README.md
Ctrl+CCancel current operationStop long-running analysis
Ctrl+RSearch command historyFind previous prompts
EscStop Claude mid-actionInterrupt current operation

本篇目录 ​