Learning path map
Detailed content
⚙️ Installing Claude Code
Requirements, installation via npm/bun, verification, updates, and troubleshooting the most common errors on any OS.
Node.js v18+ (or Bun), a terminal with color support, and internet access for initial authentication.
Without the right environment, installation fails silently. Checking beforehand saves 30 min of debugging.
Node.js LTS, verify with node -v, npm v9+ or Bun v1+, macOS/Linux/WSL2 support.
A single command installs Claude Code globally: npm install -g @anthropic-ai/claude-code.
Global installation makes the command claude available in any directory on the system.
Flag -g (global), npm folder permissions, Bun alternative: bun install -g.
Run claude --version e claude --help to confirm the binary is on the PATH.
Detects PATH errors before you waste time on authentication. "command not found" has a simple fix.
System PATH, which claude, expected output with version number.
Claude Code releases frequent updates with new models and features. The same installation command with npm update -g updates.
Older versions don't support new models. Updating takes 30 seconds and brings significant improvements.
npm update -g @anthropic-ai/claude-code, check the changelog on GitHub; breaking changes are rare.
Claude Code runs natively on macOS and Linux. On Windows, use WSL2 (Windows Subsystem for Linux) for better compatibility.
Each OS has different permission and PATH gotchas. Knowing the differences saves hours of frustration.
WSL2 on Windows, Homebrew on macOS for Node.js, recommended Linux distros (Ubuntu 22+).
The 5 most common errors: EACCES (npm permissions), command not found (PATH), ENOENT (outdated Node version), network timeout, and version conflict.
Installation errors block 30% of beginners. Keeping the diagnosis in mind solves them in minutes.
sudo npm install -g (EACCES fix), nvm for multiple Node versions, check the npm cache with npm cache clean --force.
🔑 Authentication and First Use
Login, API key vs. subscription, the interactive prompt, first real commands, and how to exit/resume a session.
Type claude in the terminal opens the interactive REPL. On the first run, redirects you to authentication.
Understanding the first-boot flow prevents confusion with login prompts and the interactive terminal.
REPL (Read-Eval-Print Loop), interactive terminal, automatic onboarding flow.
Claude Code authenticates through browser OAuth with your Anthropic account or with an API key. Credentials are stored in ~/.claude/.
Choosing between an account and an API key determines billing, limits, and available models.
OAuth2 browser flow, folder ~/.claude/, session token, reauthentication when it expires.
API key = pay per use (tokens). Claude Max = monthly subscription with a generous limit. For heavy use, the subscription is usually a better deal.
The wrong choice can lead to surprise costs or limit projects that need many daily calls.
Token pricing, rate limits, Claude Pro vs Max, environment variable ANTHROPIC_API_KEY.
The prompt > accepts natural language, slash commands (/help, /clear) and references to files with @.
Mastering REPL shortcuts multiplies productivity — without having to rewrite context with every message.
Commands /help, /clear, /status, references to files with @, multiline input with Enter vs Shift+Enter.
Ask Claude to create a file, read a project, or explain existing code — the first hands-on tasks.
Getting hands-on right away reinforces learning and demystifies using the tool.
Task prompt, action confirmation, difference between reading (safe) and writing (requires permission).
Exit with Ctrl+C or /exit. Resume the previous context with claude --resume or by opening the same directory.
Long sessions are normal in real projects. Knowing how to resume without losing context is essential.
Context persisted in the directory, .claude/ local, claude --resume, conversation history.
🛠️ Configuration: settings.json and Permissions
User vs. project settings.json file, allow/ask/deny permission system, what to safely allow, and a basic CLAUDE.md.
JSON file that controls Claude Code permissions, tools, hooks, and behaviors. Located at ~/.claude/settings.json (global) or .claude/settings.json (project).
Without knowing settings.json, you accept all the defaults — and get permission prompts for every trivial action.
User > project hierarchy, key permissions, tools, merge vs override.
Each tool can be configured with allow (run without asking), ask (ask for confirmation) or deny (block).
Incorrect permissions can block your workflow or expose destructive operations. The right balance is productive and safe.
Key allow lists glob patterns, scope by tool (Bash, Read, Write, Edit), and project-level overrides.
General rules: reading is safe (allow), writing within the project is okay, external system commands require attention, delete/drop requires ask.
Allowing everything (allow *) is dangerous on production machines. Allowing too little makes the tool useless.
Principle of least privilege, glob src/** to limit scope, deny for destructive commands.
Predefined modes: default (asks for confirmation for everything), --dangerously-skip-permissions (without confirmation — local dev only), headless mode for CI/CD.
Automated pipelines require non-interactive mode. In production, never use dangerously-skip.
Flag --print for non-interactive output, environment variables for CI, claude --no-tty.
Markdown file that Claude reads automatically at every session. It's the project "briefing" — context, conventions, special commands.
Without CLAUDE.md, you repeat the context every session. With it, Claude already knows the stack, style, and project rules.
Position ./CLAUDE.md or ~/.claude/CLAUDE.md, recommended sections, context token limit.
Global settings (~/.claude/settings.json) apply to all projects. Project settings (.claude/settings.json) override them for that repo.
Configuring the hierarchy correctly prevents conflicts between personal and professional projects.
Merge JSON objects, project > user precedence, version control .claude/settings.json in the project's git.
🔌 MCP and your first project
Model Context Protocol: connect MCP servers and external tools, create and open a real project from start to finish.
Model Context Protocol (MCP) is an open standard for connecting Claude to external tools: databases, APIs, filesystems, and cloud services.
With MCP, Claude stops being a chatbot and becomes an agent that accesses real data in your environment.
MCP server, Claude Code client, JSON-RPC, tools exposed via MCP, official server repository.
Add an MCP server to settings.json in the key mcpServers. Claude initializes and exposes the tools automatically.
Connecting an MCP takes 2 minutes. Without this knowledge, you only use Claude’s built-in tools.
Key mcpServers in JSON, command e args, check with /mcp in the REPL.
Available MCP servers: filesystem, GitHub, PostgreSQL, Slack, Google Drive, Puppeteer (browser), SQLite, and dozens more.
Each MCP dramatically expands what Claude can do. GitHub MCP + Claude = automated code review.
Repository modelcontextprotocol/servers, official vs community MCPs, security of third-party servers.
Open Claude Code in an existing directory or create a project from scratch with a file structure, CLAUDE.md, and initial settings.
Starting a project correctly (with CLAUDE.md and settings) ensures consistency throughout development.
cd meu-projeto && claude, recommended directory structure, /init to generate CLAUDE.md automatically.
Create a project, write CLAUDE.md, do a real task (e.g., create a REST API), review changes, commit — all with Claude guiding you.
Seeing the complete cycle (intent → code → review → commit) solidifies your mental model of how to use Claude Code.
Development loop, visual diff, confirmation of changes, git integration, output from complex tasks.
With installation, auth, settings, and MCP configured, you're ready to explore Skills (T3), Automation (T4), and real-world projects (T5).
Setup is the foundation. Everything that follows depends on having the environment configured properly.
Custom skills, automation hooks, worktrees, multi-file projects, CI/CD with Claude.