Claude Code is not just another AI coding assistant — it is an agentic development environment that reads your entire codebase, edits files, runs commands, manages git workflows, and integrates with your existing tools. Whether you are a solo developer or part of a large team, understanding how to use Claude Code effectively can transform your productivity by 10x or more.
This guide covers everything — from basic setup to advanced patterns that most developers never discover. By the end, you will understand not just what Claude Code can do, but how to unlock its full potential.
What Is Claude Code?
Claude Code is an agentic coding tool built by Anthropic that operates through an autonomous loop: it gathers context about your project, takes actions (reading files, writing code, running commands), verifies its work, and repeats until the task is complete. Unlike traditional chatbots that just respond to prompts, Claude Code actively works on your codebase.
The Agentic Loop
Every interaction with Claude Code follows this pattern:
- Gather Context — Read files, search code, understand project structure
- Take Action — Edit files, run commands, create branches
- Verify Results — Run tests, check builds, validate output
- Repeat — Continue until the task is complete or you intervene
You can interrupt at any point to steer Claude in a different direction. Press Esc to stop generation while preserving context, or Ctrl+C to cancel entirely.
Where Claude Code Runs
- Terminal CLI — Full-featured, recommended for power users
- VS Code Extension — Inline diffs, file mentions, visual review
- JetBrains Plugin — Interactive diff viewing, IDE context sharing
- Desktop App — Visual diff review, schedule tasks, multiple sessions
- Web Interface — claude.ai/code, runs in browser on Anthropic infrastructure
- Slack Integration — Collaborative coding in team channels
- CI/CD Pipelines — GitHub Actions, GitLab CI automation
Getting Started: Your First 10 Minutes
Installation
Install Claude Code globally via npm:
npm install -g @anthropic-ai/claude-codeThen navigate to any project directory and start a session:
cd your-project
claudeClaude will automatically scan your project structure, read key configuration files, and build an understanding of your codebase.
Essential First Commands
Once inside a session, try these:
/help— See all available commands/context— View what is consuming your context window/config— Open the settings interface/memory— View and edit persistent instructions/cost— Check token usage for the current session
Your First Real Task
Instead of starting with something trivial, give Claude Code a real task:
"Read the src/auth/ directory and explain how authentication works in this project. Then write a test for the token refresh flow."This single prompt demonstrates Claude Code's power: it will explore files, understand architecture, and produce working code — all autonomously.
CLAUDE.md: Your Project's Brain
The single most important file for Claude Code effectiveness is CLAUDE.md. This file gives Claude persistent instructions that load at the start of every session — think of it as your project's institutional knowledge.
Where to Place CLAUDE.md
- Project root:
./CLAUDE.mdor./.claude/CLAUDE.md— Shared with your team via git - User home:
~/.claude/CLAUDE.md— Personal preferences across all projects - Subdirectories: Loaded on demand when Claude works in that directory
- Managed policy: System-wide defaults for organization enforcement
What to Include (The Sweet Spot)
- Build commands Claude cannot guess:
npm run build:prod,dotnet test --filter "Unit" - Code style rules specific to your project: "Use 2-space indentation", "Prefer named exports"
- Testing instructions: "Always run jest --coverage after changes to src/"
- Repository etiquette: Branch naming, PR conventions, commit message format
- Architectural decisions: "We use CQRS pattern", "All API calls go through the gateway"
- Common gotchas: "The database schema uses schema-qualified table names (blog.posts, not posts)"
What NOT to Include
- Standard language conventions Claude already knows (PEP 8, ESLint defaults)
- Detailed API documentation — link to it instead with
@docs/api.md - Information that changes frequently
- Long explanations or tutorials
The Golden Rule: Keep It Under 200 Lines
This is where most developers go wrong. A bloated CLAUDE.md degrades performance because it consumes context on every single request. Be ruthless — if an instruction is not actively saving Claude from mistakes, remove it.
Advanced: File Imports and Path-Specific Rules
You can reference other files from CLAUDE.md:
See @README.md for project overview
Git workflow: @docs/git-instructions.md
API conventions: @docs/api-conventions.mdFor rules that only apply to certain directories, use .claude/rules/. These rules are lazy-loaded — they only consume context when Claude is working on matching files.
Keyboard Shortcuts Every User Must Know
Speed is everything in a development workflow. Memorize these shortcuts to work with Claude Code at maximum velocity:
Navigation and Control
| Shortcut | Action |
|---|---|
Ctrl+C | Cancel current generation |
Esc | Stop generation (preserves context) |
Ctrl+L | Clear terminal screen |
Ctrl+D | Exit Claude Code |
Ctrl+R | Reverse search command history |
Ctrl+G | Open prompt in your text editor |
Ctrl+B | Background a running task |
Ctrl+T | Toggle task list |
Shift+Tab | Cycle permission modes |
Esc + Esc | Rewind conversation |
Alt+P | Switch AI model |
Alt+T | Toggle extended thinking |
Alt+O | Toggle fast mode |
Text Editing in the Prompt
| Shortcut | Action |
|---|---|
Ctrl+K | Delete to end of line |
Ctrl+U | Delete entire line |
Ctrl+Y | Paste deleted text |
Alt+B / Alt+F | Move cursor by word |
Ctrl+J | New line (multiline input) |
Shift+Enter | New line (alternative) |
Permission Modes: Finding the Right Balance
One of the most powerful but misunderstood features. Cycle through modes with Shift+Tab:
- Default Mode — Prompts for every file edit and shell command. Safe but slow.
- Accept Edits — Auto-accepts file changes, still prompts for commands. Good middle ground.
- Plan Mode — Read-only exploration. Claude presents a plan but makes no changes. Perfect for understanding code before modifying it.
- Auto Mode — A classifier evaluates risk and auto-blocks dangerous actions. Best for experienced users.
- Bypass Permissions — Skips all prompts. Use with caution, ideal for trusted automated workflows.
Pro Tip: Start in Plan Mode when tackling unfamiliar code. Let Claude explore and explain before switching to a more permissive mode for implementation.
The Art of Prompting Claude Code
This is where most users leave 80% of Claude Code's power on the table. The quality of your prompts directly determines the quality of output.
The Perfect Prompt Structure
Follow this pattern: Context - Task - Verification - Constraints
Bad prompt:
"Fix the login bug"Good prompt:
"Users report login fails after session timeout. Check src/auth/, especially the token refresh logic. Write a failing test first, then fix it. Run the full test suite after to verify nothing else broke."The difference is dramatic. The good prompt gives Claude: specific context (what is broken), location hints (where to look), methodology (test-first), and verification (run tests).
Six Prompting Strategies That Unlock Full Power
1. Always Give Claude a Way to Verify
- Include test cases or expected output
- Paste UI screenshots for visual changes (
Ctrl+Vto paste images) - Define clear success criteria upfront
- Ask Claude to run tests after making changes
2. Use the Explore, Plan, Code, Commit Workflow
- Start in Plan Mode: "Read the payment module and explain the architecture"
- Review Claude's understanding and correct any misunderstandings
- Switch to a permissive mode: "Now implement the refactor we discussed"
- Verify: "Run all payment tests and fix any failures"
- Commit: "Commit these changes with a descriptive message"
3. Reference Existing Patterns
"Look at SearchBar.tsx to understand our component patterns. Follow the same structure, naming conventions, and test patterns for the new FilterBar component."4. Ask Claude to Interview You
"I want to build a notification system. Interview me about the requirements — ask about delivery channels, priority levels, user preferences, and edge cases. Then write a technical spec."5. Delegate, Do Not Dictate
"The checkout flow is broken for expired credit cards. The relevant code is in src/payments/. Investigate and fix it."Let Claude figure out which files to read and commands to run. Over-specifying steps limits Claude's ability to find the best solution.
6. Provide Rich Context
- Use
@filenameto reference specific files - Paste error logs directly into the prompt
- Pipe data:
cat error.log | claude -p "analyze this error" - Share documentation URLs
Subagents: Claude Code's Secret Weapon
Subagents are specialized, isolated Claude instances that run in parallel with your main session. They are the single most underused feature of Claude Code.
Built-in Subagents
- Explore Agent — Fast, read-only (uses Haiku model). Perfect for file discovery and codebase analysis without consuming your main context.
- Plan Agent — Read-only research agent used in Plan Mode.
- General-purpose Agent — Full capabilities, can read and write files.
Why Subagents Matter
Every file Claude reads, every command output, every conversation turn — it all consumes your context window. When context fills up, performance degrades significantly. Subagents run in isolated context, meaning their exploration does not pollute your main session.
Creating Custom Subagents
Create a file at .claude/agents/code-reviewer.md with a YAML frontmatter defining the agent's name, description, tools, model, and maxTurns, followed by your system prompt instructions. Then invoke it naturally: "Use the code-reviewer agent to review the changes in src/auth/"
Running Agents in Background
Press Ctrl+B to background a running task, or ask Claude to run agents in the background. This lets you continue working while the agent completes its task. You will be notified when it finishes.
Skills: Reusable Workflows
Skills are custom commands that Claude can invoke automatically or that you trigger manually with /skill-name.
Creating a Skill
Create a file at .claude/skills/deploy/SKILL.md with YAML frontmatter (name, description, allowed-tools) followed by your workflow steps. Now type /deploy and Claude executes the entire workflow.
Skill Best Practices
- Use
disable-model-invocation: truefor workflows with side effects (only you can trigger them) - Use
user-invocable: falsefor reference material Claude should auto-load - Keep SKILL.md focused — move detailed content to supporting files alongside it
- Use string substitution:
$ARGUMENTSpasses your input to the skill
Bundled Skills You Should Know
/batch— Decompose large changes across parallel git worktrees (5-30 parallel PRs)/simplify— Review your changed code for quality, reuse, and efficiency/debug— Troubleshoot issues in the current session/loop 5m /your-command— Run a command repeatedly on an interval
MCP: Connecting Claude to External Tools
The Model Context Protocol (MCP) is an open standard that lets Claude Code connect to databases, APIs, browsers, and any external tool.
Popular MCP Servers
- Databases — PostgreSQL, MySQL, MongoDB, SQLite
- Development — GitHub, GitLab, Sentry, Linear
- Communication — Slack, Discord, email
- Productivity — Notion, Google Drive, Figma
- Browser — Chrome automation, web scraping
Warning: Each MCP server consumes context on every request (tool definitions are loaded). Only connect servers you actively need, and check context cost with /mcp.
Hooks: Automating Without AI
Hooks are deterministic shell commands that run at specific lifecycle points. Unlike skills and agents, hooks do not use AI — they execute instantly with zero token cost.
Hook Events
PreToolUse— Before Claude executes a tool (can block it)PostToolUse— After a tool succeedsSessionStart— When a session beginsStop— When Claude finishes respondingUserPromptSubmit— When you submit a prompt
For example, you can configure a PostToolUse hook that auto-formats every file Claude edits using Prettier — no AI tokens spent, instant execution.
Context Management: The Hidden Skill
Understanding context is the difference between a productive session and a frustrating one. Every piece of data Claude processes consumes your context window, and performance degrades as it fills up.
What Consumes Context
| Source | When Loaded | Cost |
|---|---|---|
| CLAUDE.md | Every request | High (keep small!) |
| Conversation history | Every request | Grows with each turn |
| MCP tool definitions | Every request | High per server |
| File reads | When read | Proportional to size |
| Command output | When run | Variable |
| Subagent results | When complete | Only summary returned |
Context Optimization Strategies
- Use
/clearbetween unrelated tasks — Do not let a debugging session's context bleed into feature development - Use
/compact "focus on X"— Compress conversation history with focus instructions - Delegate exploration to subagents — They use their own context, keeping yours clean
- Move reference docs to skills — They only load when needed
- Use
.claude/rules/— Path-specific rules are lazy-loaded - Disconnect unused MCP servers — Each one adds overhead to every request
- Use
/btw "quick question"— Ephemeral answer that does not get stored in history
The 10 Biggest Mistakes Claude Code Users Make
Mistake 1: Kitchen Sink Sessions
Problem: Mixing unrelated tasks in one session until context is exhausted.
Fix: Use /clear between unrelated tasks. Start fresh sessions for new work.
Mistake 2: Over-Correcting Instead of Restarting
Problem: Spending 10 turns correcting Claude when the initial prompt was unclear.
Fix: After 2-3 failed corrections, use /clear and write a better prompt from scratch.
Mistake 3: Bloated CLAUDE.md
Problem: A 500-line CLAUDE.md that Claude partially ignores.
Fix: Ruthlessly prune to under 200 lines. Move details to .claude/rules/ or skills.
Mistake 4: Not Providing Verification
Problem: Asking Claude to "implement feature X" without any way to check if it works.
Fix: Always include tests, expected output, or screenshots.
Mistake 5: Infinite Exploration Without Scope
Problem: "Investigate why the app is slow" — too broad, Claude reads everything.
Fix: Scope narrowly: "Profile the /api/checkout endpoint and identify the slowest query."
Mistake 6: Ignoring Plan Mode
Problem: Jumping straight into code changes without understanding existing architecture.
Fix: Start with Plan Mode. Let Claude explore and explain before modifying anything.
Mistake 7: Not Using Subagents
Problem: Having Claude read 50 files in the main session, consuming all context.
Fix: "Use a subagent to explore the authentication module and summarize the architecture."
Mistake 8: Manual Repetition Instead of Skills
Problem: Typing the same deployment steps every session.
Fix: Create skills for repeated workflows. /deploy beats typing 5 steps every time.
Mistake 9: Dictating Steps Instead of Delegating Goals
Problem: Micromanaging Claude with step-by-step instructions.
Fix: "The email validation rejects valid addresses with plus signs. Fix it and add test cases."
Mistake 10: Never Checking Context Usage
Problem: Sessions getting slower without understanding why.
Fix: Run /context regularly. Use /compact when above 60%.
Advanced Patterns for Power Users
Git Worktrees for Parallel Development
claude --worktree feature-auth # Isolated branch for auth work
claude --worktree feature-ui # Separate branch for UI workEach worktree is a full copy of your repo on a separate branch. Claude can work on multiple features simultaneously without conflicts.
Batch Operations
The /batch command decomposes large changes across parallel worktrees. Claude creates 5-30 parallel worktrees, each handling a subset of the work, and opens individual PRs for review.
Non-Interactive Mode for Automation
# Single prompt, get response
claude -p "explain the auth flow in this project"
# JSON output for scripting
claude -p "list all TODO comments" --output-format jsonCI/CD Integration
Claude Code works in GitHub Actions and GitLab CI for auto-reviewing PRs, triaging issues, generating release notes, fixing lint errors, and updating dependencies.
Chrome Integration for Web Testing
claude --chromeClaude can launch a browser, navigate to your local dev server, interact with UI elements, check console logs, and capture screenshots — all through natural language commands.
Built-in Commands Reference
| Command | Purpose |
|---|---|
/clear | Clear context, start fresh |
/compact [focus] | Compress conversation with optional focus |
/config | Settings interface |
/context | View context usage breakdown |
/cost | Token usage statistics |
/model [name] | Change the AI model |
/effort [level] | Set effort (low/medium/high/max) |
/memory | View/edit persistent memory |
/skills | List available skills |
/agents | Manage subagents |
/mcp | Manage MCP servers |
/hooks | Browse hooks |
/diff | View uncommitted changes |
/rewind | Go to a previous state |
/resume | Pick a previous session |
/export | Export conversation as text |
/security-review | Security analysis of changes |
/doctor | Diagnose installation issues |
CLI Flags Reference
| Flag | Purpose |
|---|---|
claude -p "prompt" | Non-interactive print mode |
claude -c | Continue most recent session |
claude -r "name" | Resume a named session |
--model opus | Use a specific model |
--effort high | Set thinking effort |
--permission-mode plan | Start in Plan Mode |
--agent reviewer | Run as a specific subagent |
--worktree feature | Isolated git worktree |
--chrome | Enable browser automation |
--max-turns 20 | Limit agentic turns |
--max-budget-usd 5 | Set spending limit |
--output-format json | JSON output for scripting |
--debug | Enable debug logging |
Security Best Practices
- Review CLAUDE.md before checking into git — Ensure no secrets are exposed
- Keep secrets in environment variables — Never hardcode API keys
- Use permission allowlists for trusted commands
- Enable sandboxing with
/sandboxfor OS-level isolation - Use subagents with restricted tools for untrusted operations
- Run security reviews:
/security-reviewbefore committing
The Complete Workflow: From Zero to Production
Here is how an experienced Claude Code user approaches a real task — building a new API endpoint:
- Start in Plan Mode (
Shift+Tabtwice): "Read the existing API endpoints and explain the patterns." - Review — Correct any misunderstandings about your architecture.
- Create a plan: "Plan a new /api/notifications endpoint. Follow existing patterns."
- Switch to Accept Edits mode: "Implement the plan. Write tests first."
- Verify: "Run all tests, check for type errors, run the linter."
- Code review: "Use the code-reviewer agent to check for issues."
- Commit: "Commit with a descriptive message and create a PR."
Total time: 10-15 minutes for what would typically take 2-3 hours manually.
Final Thoughts: The Mindset Shift
The developers who get the most out of Claude Code share a common mindset: they treat it as a capable junior developer who is incredibly fast, has perfect recall, never gets tired, but needs clear direction and verification.
Do not micromanage — delegate goals. Do not write one giant prompt — iterate in steps. Do not ignore context limits — manage them actively. Do not skip verification — always run tests.
Claude Code is the most powerful AI coding tool available in 2026. The difference between average and exceptional usage comes down to understanding these principles and applying them consistently. Start with the basics, add skills and hooks as you identify patterns, and let Claude Code amplify your existing expertise rather than replace your judgment.
Happy coding.
