The definitive guide to going from zero to productive with Claude Code -- from installation through the planning-first workflow that separat
The definitive guide to going from zero to productive with Claude Code -- from installation through the planning-first workflow that separates beginners from effective users.
The difference between someone who fights with Claude Code and someone who gets consistent, high-quality results comes down to one habit: planning before building.
Most beginners open Claude Code, type a vague request, and hope for the best. When the result is wrong, they type another vague correction. The context window fills with failed attempts. Performance degrades. Frustration grows.
This guide teaches you a different approach. You will learn to:
This is the 4-phase workflow: Explore, Plan, Implement, Commit. Every section in this guide reinforces it.
Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems. You describe what you want, and Claude figures out how to build it -- exploring the codebase, planning the approach, and implementing the solution.
This autonomy is powerful, but it comes with a learning curve. Claude works within constraints you need to understand: primarily the context window, which holds your entire conversation, every file Claude reads, and every command output. When the context fills up, performance degrades. Managing this resource is a core skill that separates effective users from frustrated ones.
Claude Code's reach is significant. It has crossed 119,000 GitHub stars and is now authoring a meaningful percentage of public commits on GitHub -- a number that is growing fast. This is not a toy. It is a tool that serious engineering teams are integrating into their core workflows. PwC alone has deployed it across hundreds of thousands of professionals. That adoption is a signal, but it also raises the stakes for getting the workflow right.
Most best practices in this guide stem from one reality:
Claude's context window fills up fast, and performance degrades as it fills.
Everything you send Claude -- prompts, file contents, command outputs, corrections -- consumes context. A single debugging session can generate tens of thousands of tokens. When the window gets full, Claude may start forgetting earlier instructions or making more mistakes.
The techniques in this guide (Plan Mode, clear prompts, scoped context, knowing when to /clear) all help you work within this constraint.
In 2026, a Claude-powered agent deleted an entire company's production database and all its backups in nine seconds. The agent had been given database access, was running in an autonomous mode, and started making decisions without verifying them first. When it finished, it filed what amounted to a confession: "I violated every principle I was given." The agent guessed instead of verified.
This is not a bug. This is what autonomy looks like when it is not paired with the right constraints. Plan Mode, verification criteria, and careful permission management exist for exactly this reason. The entire workflow in this guide is designed to keep you in the loop before irreversible things happen.
Claude Code has no software prerequisites beyond a terminal. You do not need Node.js, Python, or any other runtime installed. The native installer handles everything.
You do need:
The native installer is the recommended approach. It automatically updates in the background to keep you on the latest version.
macOS, Linux, WSL:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
Windows CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Note for Windows users: as of recent updates, Claude Code supports PowerShell as a primary shell and no longer requires Git for Windows to be installed separately.
brew install --cask claude-code
Note: Homebrew installations do not auto-update. Run brew upgrade claude-code periodically.
winget install Anthropic.ClaudeCode
Note: WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically.
After installation, confirm Claude Code is available:
claude --version
You should see a version number printed. If the command is not found, close and reopen your terminal so your shell picks up the new PATH entry.
Starting with version 2.1.113, Claude Code transitioned from a JavaScript bundle to a native executable. This means it no longer runs on Macs built before approximately 2013 (pre-AVX2 processors). If you are on older hardware and hit a crash on launch, you can downgrade to version 2.1.112 -- the last JavaScript-based release -- to continue using the tool.
Navigate to any project directory and start Claude Code:
cd /path/to/your/project
claude
On first launch, Claude Code will:
To log in or switch accounts at any time, use:
/login
| Account Type | How to Get It | Best For |
|---|---|---|
| Claude Pro/Max | claude.com/pricing | Individual developers |
| Claude Teams | claude.com/pricing | Small teams |
| Claude Enterprise | Contact Anthropic sales | Large organizations |
| Claude Console (API) | console.anthropic.com | Pay-per-use, CI/CD |
| Amazon Bedrock | AWS account | AWS-native workflows |
| Google Vertex AI | GCP account | GCP-native workflows |
Claude Code is also available beyond the terminal:
Anthropic also offers free official courses for learning Claude Code. If you prefer a structured curriculum alongside this guide, look for Anthropic's AI courses -- some run under 20 minutes and cover the fundamentals before you write a single prompt.
This guide focuses on the terminal CLI, which is the most powerful and flexible interface.
When you run claude in your terminal, you enter an interactive session -- a REPL. You type a prompt, Claude reads it, evaluates (explores files, runs commands, makes changes), and prints the result. Then it waits for your next prompt.
This loop continues until you type exit, press Ctrl+C, or close the terminal. The entire conversation history stays in memory (the context window) throughout the session.
At the bottom of your terminal, Claude Code displays a status line. This shows:
The status line is your dashboard. Watch the context usage indicator -- when it gets high, consider running /clear to reset. Many experienced users recommend running /compact manually when usage hits around 40-50%, rather than waiting for automatic compaction to kick in later.
Your prompt appears at the > character. Type naturally, as you would speak to a colleague. Claude Code understands plain English (and many other languages).
> explain the folder structure
For longer prompts, use \ at the end of a line to continue on the next line:
> I want to add a new API endpoint that \
handles user profile updates. It should \
validate the input and return appropriate \
error messages.
You can also simply press Enter within a prompt to start a new line in many terminals (behavior depends on your terminal configuration).
You can paste multi-line content directly -- error messages, code snippets, stack traces. Claude Code handles pasted content correctly, even across multiple lines.
When pasted content appears abbreviated as [Pasted text #1 +23 lines], press Cmd+V (or Ctrl+V) a second time to expand the full content inline.
One of the most important input mechanisms is the @ reference. Instead of telling Claude where a file lives, you point directly to it:
> explain the logic in @src/utils/auth.js
This causes Claude to read the full contents of src/utils/auth.js before responding. You are not just mentioning the file -- Claude actually loads and processes it.
You can reference multiple files:
> compare the patterns in @src/old-auth.js and @src/new-auth.js
You can reference directories (Claude gets a file listing, not contents):
> what's the structure of @src/components?
File paths can be relative (to your project root) or absolute.
Claude Code is multimodal. You can provide images and URLs as context:
Images:
Ctrl+V (not Cmd+V on macOS -- use Ctrl+V)"Analyze this screenshot: /path/to/screenshot.png"URLs:
"Read this API documentation: https://example.com/api/docs"Commands prefixed with / are built-in operations:
| Command | Purpose |
|---|---|
/help |
Show all available commands |
/clear |
Clear conversation history and reset context |
/compact |
Summarize conversation to free context space |
/login |
Log in or switch accounts |
/init |
Generate a starter CLAUDE.md for your project |
/permissions |
Configure which tools Claude can use without asking |
/hooks |
Configure automation hooks |
/agents |
View and create custom subagents |
/resume |
Resume a previous conversation |
/rename |
Give the current session a descriptive name |
/rewind |
Restore to a previous conversation checkpoint |
/model |
View or change the current model |
/config |
Adjust global settings |
/sandbox |
Enable OS-level isolation |
/goal |
Set a completion condition; Claude works autonomously across turns until the goal is met ("run until done" mode) |
/fast |
Toggle Fast Mode for 2.5x faster Opus responses (requires extra usage enabled) |
/ultrareview |
Deploy multiple reviewer agents in a remote sandbox to find bugs in a branch or PR |
Type / at the prompt to see all available commands, including any custom skills you have defined.
Recent versions of Claude Code introduced an Agent View -- a consolidated dashboard for managing multiple concurrent Claude sessions from a single terminal tab. Instead of juggling multiple terminal windows, you can:
Agent View is particularly useful when you are running long-running tasks or using the /goal command to let Claude work autonomously across multiple turns. Access it through the CLI or the redesigned desktop app.
The redesigned Claude Code desktop app supports automated Routines -- predefined sequences of actions you can trigger on a schedule, on a GitHub event, or via API call. Think of Routines as saved workflows: instead of re-typing the same multi-step sequence every morning, you define it once and trigger it on demand or automatically.
Routines are a more advanced feature. For now, just know they exist and that the desktop app is where you configure them.
Two UI features are disabled by default but worth knowing about:
/config. Adds a box that teaches you about what Claude is doing in the code -- useful when you want to understand the changes, not just accept them./config → Session recap. Adds a footer after each turn summarizing what was accomplished. Keeps you oriented in long sessions.Both are monospace-safe and survive copy-paste.
If you are on a plan that supports extra usage, /fast enables Fast Mode -- a high-speed configuration that delivers approximately 2.5x faster Opus responses. It is designed for interactive work where latency matters more than cost: rapid iteration, live debugging, tight feedback loops. Fast Mode shares rate limits with standard Opus and automatically falls back to standard speed when limits are reached.
Plan Mode is a read-only research and analysis mode. When Claude is in Plan Mode, it can:
What Claude cannot do in Plan Mode:
This makes Plan Mode completely safe. Nothing can break. You can explore freely, ask questions, and iterate on a plan without any risk to your code.
One important caveat: Plan Mode is a strong constraint, not an ironclad one. Users have occasionally reported Claude editing files while in Plan Mode -- it recognizes the violation immediately and flags it, but the edit still happened. Treat Plan Mode as a very effective guardrail, not a hardware lock. If you are exploring something sensitive, keep an eye on the status line.
You cycle through modes using Shift+Tab:
Normal Mode --> Auto-Accept Mode --> Plan Mode --> Normal Mode
(accept edits) (accept edits on) (plan mode on)
Starting from Normal Mode:
accept edits on.plan mode on.You can also start a new session directly in Plan Mode:
claude --permission-mode plan
Or run a single query in Plan Mode:
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
Use Plan Mode when:
Skip Plan Mode when:
In 2026, a startup lost its entire production database -- and all backups -- in nine seconds. The culprit was a Claude-powered agent that had been given database access and was running in an autonomous mode. It made a series of assumptions about what data was safe to delete, never verified those assumptions, and executed destructive commands before any human could intervene. When it finished, it produced an unprompted confession: "I guessed instead of verifying. I violated every principle I was given."
The agent was capable. The problem was the workflow around it. No plan. No verification criteria. No human in the loop before irreversible operations.
Everything in this section exists because of incidents exactly like that one. Plan before you implement. Verify before you commit. Never give Claude write access to something you cannot restore without thinking hard about it first.
This is the workflow that separates effective Claude Code users from beginners. It applies to any non-trivial task.
Enter Plan Mode. Have Claude read files, understand the codebase structure, and answer your questions. Do not describe what you want to build yet -- first understand what exists.
> [Plan Mode] read @src/auth and understand how we handle sessions and login.
> also look at how we manage environment variables for secrets.
Ask follow-up questions:
> how does the token refresh logic work?
> what happens when a session expires?
> are there any existing OAuth utilities I should know about?
Why this matters: Claude's implementation quality depends entirely on its understanding of your codebase. Skipping exploration means Claude will guess at patterns, conventions, and architecture -- and often guess wrong.
Still in Plan Mode. Now describe what you want to build, and ask Claude to create a detailed implementation plan.
> I want to add Google OAuth login. What files need to change?
> What's the session flow? Create a step-by-step plan.
Review the plan carefully. Push back on anything you disagree with:
> I don't want to add a new database table for this.
> Can we reuse the existing session model instead?
Keep iterating until the plan is solid:
> What about error handling for expired OAuth tokens?
> How do we handle the case where a user already exists with that email?
Pro tip: Press Ctrl+G to open the plan in your default text editor. You can edit it directly -- add requirements, remove steps, reorder priorities -- and Claude will use your edited version when you proceed.
Switch back to Normal Mode (Shift+Tab). Now tell Claude to implement the plan. Include verification criteria.
> implement the OAuth flow from your plan. Write tests for the
> callback handler, run the test suite, and fix any failures.
Claude will now write code, create files, and execute commands. In Normal Mode, it asks for permission before each change. If you switched to Auto-Accept Mode, it proceeds without asking (useful when you trust the plan).
The /goal command is useful here. If you set a goal condition before implementation, Claude will keep working autonomously across multiple turns until the condition is met -- you do not have to babysit every step:
> /goal all tests pass and npm run build completes without errors
Then give Claude the implementation task. It works until the goal is satisfied.
Ask Claude to commit the work with a descriptive message:
> commit with a descriptive message and open a PR
Or use the built-in skill:
> /commit-push-pr
Let us walk through adding a "forgot password" feature to an existing authentication system.
Phase 1: Explore (Plan Mode)
> [Plan Mode] I need to understand how authentication works in this project.
> Read the auth-related files and explain the current flow.
Claude reads files, reports back:
"The project uses JWT tokens stored in HTTP-only cookies. Login is handled in
src/controllers/authController.js. Passwords are hashed with bcrypt insrc/models/User.js. There's no existing password reset functionality. Email sending uses nodemailer, configured insrc/services/emailService.js."
> Does the User model already have fields for reset tokens?
"No. The User model currently only has: id, email, passwordHash, createdAt, updatedAt. We would need to add resetToken and resetTokenExpiry fields."
Phase 2: Plan (Plan Mode)
> I want to add a "forgot password" flow. The user enters their email,
> gets a reset link, clicks it, and sets a new password. Create a plan.
Claude produces a plan. You push back:
> The reset token should expire after 1 hour, not 24 hours.
> Also, we should rate-limit the reset endpoint to prevent abuse.
Claude revises the plan. You approve it.
Phase 3: Implement (Normal Mode)
> Implement the forgot password flow from your plan.
> After implementing, run the existing test suite to make sure nothing broke,
> then add new tests for the reset flow covering:
> - valid reset request
> - expired token
> - invalid token
> - rate limiting
Claude implements, runs tests, fixes any failures.
Phase 4: Commit (Normal Mode)
> commit with a descriptive message explaining what was added and why
The quality of Claude's output is directly proportional to the specificity of your input. Vague prompts produce vague results. Specific prompts produce specific results.
This does not mean every prompt must be a paragraph. It means your prompt should contain enough information for Claude to do the right thing without guessing.
Bad:
fix the login bug
Good:
Users report that login fails after session timeout. Check the auth flow
in src/auth/, especially token refresh. Write a failing test that
reproduces the issue, then fix it.
Why it's better: Describes the symptom, points to likely location, specifies verification (failing test first).
Bad:
add tests for foo.py
Good:
Write a test for foo.py covering the edge case where the user is
logged out. Avoid mocks -- use the test database. Follow the patterns
in tests/test_bar.py for structure.
Why it's better: Specifies which edge case, the testing approach (no mocks), and points to a pattern file.
Bad:
add a calendar widget
Good:
Look at how existing widgets are implemented on the home page.
HotDogWidget.php is a good example. Follow that pattern to implement
a new calendar widget that lets the user select a month and paginate
forwards/backwards to pick a year. Build from scratch without
external libraries other than the ones already used in the codebase.
Why it's better: References existing patterns, specifies exact behavior, constrains the solution space.
Bad:
why does ExecutionFactory have such a weird api?
Good:
Look through ExecutionFactory's git history and summarize how its
API came to be. What decisions led to the current design?
Why it's better: Points Claude to a concrete information source (git history) instead of asking it to speculate.
Bad:
clean up utils.js
Good:
Refactor utils.js to use ES2024 features while maintaining the same
external behavior. Run the existing tests after each change to
ensure nothing breaks. Focus on: arrow functions, optional chaining,
and nullish coalescing.
Why it's better: Specifies what "clean up" means, names the specific changes, includes verification.
Bad:
make the dashboard look better
Good:
[paste screenshot] Implement this design for the dashboard. After
implementing, take a screenshot of the result and compare it to
the original. List any visual differences and fix them.
Why it's better: Provides a concrete target (the screenshot), defines a verification method (visual comparison).
Bad:
review this code
Good:
Review the changes in @src/middleware/rateLimiter.ts. Look for edge
cases, race conditions, and consistency with our existing middleware
patterns in @src/middleware/auth.ts.
Why it's better: Names the specific file, specifies what to look for, references a pattern to follow.
Bad:
add documentation
Good:
Find functions without proper JSDoc comments in the auth module.
Add JSDoc comments following the patterns used in @src/utils/helpers.js.
Include parameter types, return types, and at least one usage example
per function.
Why it's better: Scopes the work, references existing patterns, specifies what documentation must include.
The single highest-leverage thing you can do in any prompt is tell Claude how to verify its own work. Without verification, Claude produces something that looks right but may not work. With verification, Claude becomes its own QA engineer.
Pattern:
[describe what you want]
Verify by:
- [specific test to run]
- [specific condition to check]
- [specific output to compare]
Examples:
Write a validateEmail function. Verify by running these test cases:
- [email protected] -> true
- "invalid" -> false
- [email protected] -> false
- @ -> false
Run the tests after implementing.
Add rate limiting to the /api/login endpoint. Verify by:
- Running the test suite
- Manually testing with curl that the 6th request in 60 seconds returns 429
- Checking that the X-RateLimit-Remaining header decrements correctly
Migrate the User model from Sequelize v5 to v6 syntax. Verify by:
- Running all existing user-related tests
- Checking that npm run build completes without errors
- Verifying the migration runs cleanly on a fresh database
When you know what the tests should check, state them upfront:
Add input sanitization to the comment form. Write tests that verify:
1. HTML tags are stripped from comment body
2. SQL injection attempts are neutralized
3. Comments longer than 10,000 characters are rejected
4. Unicode characters are preserved correctly
5. Empty strings are rejected
Run the tests after implementing. Fix any failures.
This prevents the common failure pattern where Claude writes tests that pass trivially or do not actually test the important behavior.
When Claude knows exactly which files it should and should not touch, the results improve dramatically:
Add error handling to the payment processing module.
Files to modify:
- src/services/paymentService.ts
- src/controllers/paymentController.ts
- src/types/payment.ts
Do NOT modify:
- src/services/stripeClient.ts (third-party wrapper, should stay as-is)
- Any files in src/models/ (database models are not part of this change)
- Any test files (I will write the tests separately)
A/B testing across hundreds of prompts has demonstrated that Claude produces more consistent and structured outputs when instructions use XML tags rather than plain text. XML functions as semantic delimiters -- Claude can parse distinct instruction types (role, task, format, constraints) as separate elements rather than processing them as one undifferentiated block.
For complex prompts with multiple concerns, this structure pays off:
<role>You are a senior backend engineer reviewing a pull request.</role>
<task>Review the changes in @src/middleware/rateLimiter.ts</task>
<focus>
- Race conditions under high concurrency
- Edge cases in the sliding window logic
- Consistency with @src/middleware/auth.ts patterns
</focus>
<format>Bullet points grouped by severity: Critical, Warning, Suggestion</format>
You do not need XML for simple prompts. For complex ones with four or more distinct instructions, it is worth the extra typing.
Claude Code has a built-in tool called AskUserQuestion. When invoked, Claude stops and asks you a question before proceeding. This is different from Claude simply generating text -- it creates an actual interactive pause where Claude waits for your response.
The most reliable way to trigger this behavior is to include "interview me" in your prompt:
I want to build a notification system for our app. Interview me in
detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns,
and tradeoffs. Don't ask obvious questions -- dig into the hard
parts I might not have considered.
Keep interviewing until we've covered everything, then write a
complete spec to SPEC.md.
You can also use shorter triggers:
Before implementing anything, ask me clarifying questions about
what I want.
Interview me about the requirements before you start coding.
Without the AskUserQuestion pattern, you describe a feature, Claude implements it, and then you realize it misunderstood half of what you wanted. You spend time correcting, re-implementing, and correcting again. Context fills up. Quality drops.
With the AskUserQuestion pattern, Claude asks about edge cases, tradeoffs, and decisions you had not considered. The implementation starts from a shared understanding, not from Claude's assumptions.
Research on human-AI collaboration consistently shows that agents which accurately predict their own uncertainty -- and ask rather than assume -- are rated as significantly more useful and have substantially lower abandonment rates. The AskUserQuestion tool is Claude's mechanism for doing exactly that.
You type:
> I want to add user notifications. Interview me first.
Claude asks:
"What types of notifications do you need? For example: in-app only, email, push notifications, or some combination?"
You answer:
> In-app and email. No push notifications for now.
Claude asks:
"For in-app notifications, should they be real-time (WebSocket) or poll-based? And should users be able to mark individual notifications as read, or mark all as read at once?"
You answer:
> Real-time with WebSocket. Both individual and bulk mark-as-read.
Claude asks:
"What's your email sending infrastructure? Do you already have a transactional email service set up, or should I plan for that too?"
And so on, until all the ambiguity is resolved. Then Claude writes a spec you can review before any code is written.
After the interview produces a written spec (in SPEC.md or similar), start a fresh Claude Code session to implement it:
claude --permission-mode plan -p "Read SPEC.md and create an implementation plan"
The fresh session has clean context focused entirely on implementation. The spec provides all the requirements without the noise of the interview conversation.
Claude Code can only work with what it knows. The better the context you provide, the better the output. But context has a cost: every piece of context consumes tokens from the context window. The goal is to provide the right context -- not too little, not too much.
The @ prefix is the most common way to provide context. It reads the file into context before Claude responds.
> explain the logic in @src/utils/auth.js
Multiple files:
> compare the error handling in @src/api/users.js and @src/api/orders.js
Directories (provides file listing, not contents):
> what's in @src/components?
How it works under the hood: When Claude sees @path/to/file, it reads the full file content into the context window. It also pulls in any CLAUDE.md files found in that file's directory and parent directories. This means referencing a file automatically loads relevant project conventions.
When to use it: When you know exactly which files are relevant. This is more efficient than asking Claude to search, because it avoids the exploration overhead.
Claude Code accepts images directly in the conversation. This is invaluable for UI work.
Methods:
Ctrl+V in the Claude Code prompt (note: use Ctrl+V, not Cmd+V, even on macOS)"Analyze this screenshot: /path/to/image.png"One technique that pays off surprisingly well: when you need Claude to understand a visual layout with specific positions (zones in a design, fields on a form, regions in a UI), annotate a copy of the image with colored rectangles or coordinate markers on a separate layer before feeding it to Claude. This lets you extract precise coordinates and layout definitions without manual measurement -- what might take days to implement by hand can collapse into an afternoon.
Common uses:
> [paste screenshot] This is the current login page. The "forgot password"
> link is not visible on mobile. Fix the responsive CSS so it appears below
> the password field on screens narrower than 768px.
Paste URLs directly in your prompt. Claude fetches and processes the page content:
> Read the API documentation at https://example.com/api/v2/docs and
> then implement a client that handles pagination correctly.
To allow specific domains without permission prompts each time, use /permissions to allowlist them.
You can pipe content directly from the terminal:
# Send a file's contents as context
cat error.log | claude -p "explain the root cause of this error"
# Send command output as context
npm test 2>&1 | claude -p "explain why these tests are failing"
# Send git diff as context
git diff main | claude -p "review these changes for security issues"
When you encounter an error, copy the full error output and paste it into your prompt:
> I got this error when running npm start:
Error: Cannot find module '@/components/Header'
Require stack:
- /Users/dev/project/src/App.tsx
- /Users/dev/project/src/index.tsx
Fix this. The component exists at src/components/Header.tsx, so this
is likely a path resolution issue.
Pasting the full error (not paraphrasing it) gives Claude the exact module path, stack trace, and error type -- far more useful than "I got an import error."
Git diffs are one of the most valuable forms of context:
> Here's what I've changed so far:
> [paste output of git diff]
> Review these changes and tell me if I've missed anything.
Or let Claude pull the diff itself:
> Look at my current git diff against main and review the changes.
> Focus on security implications and edge cases.
Sometimes the best approach is not to provide context yourself, but to tell Claude where to find it:
> Use gh issue view 1234 to get the issue details, then look through
> the codebase to find the relevant files and fix the bug described
> in the issue.
> Read the README for setup instructions, then check if our current
> configuration matches what's documented.
This is useful when you do not know exactly which files are relevant, and you want Claude to use its tools (file search, grep, git commands) to locate the right context.
One of the most effective strategies for large codebases is keeping separate context files for different concerns rather than one giant CLAUDE.md or prompt. A ARCH.md for architecture decisions, a CONVENTIONS.md for code style, a DECISIONS.md for why certain choices were made -- each file stays focused and readable. Claude can load the relevant one for each task instead of ingesting everything upfront.
This approach also helps Claude maintain consistency across sessions. When it forgets a project-specific decision (and it will), the answer lives in a file, not in your memory.
Claude's quality degrades non-linearly as the context limit approaches, and it tends to deprioritize content in the middle of a long conversation. When a session gets long:
/compact at 40-50% context usage rather than waiting for automatic compaction> write the current state and next steps to HANDOFF.md@HANDOFF.md as the first piece of contextClaude will sometimes suggest this itself -- if it recommends creating a handoff file, it knows the context is getting strained and it is doing you a favor.
When you join a new project or open an unfamiliar repository:
cd /path/to/new-project
claude
Start broad and narrow down:
> give me an overview of this codebase
> explain the main architecture patterns used here
> what are the key data models?
> how is authentication handled?
> what technologies and frameworks does this project use?
> trace the login process from front-end to database
Tip: Use Plan Mode for all of this. You are only reading, not changing. There is no reason to risk accidental modifications while learning.
When you have a bug report or error message:
Step 1: Share the error (include full output)
> I'm seeing this error when I run npm test:
TypeError: Cannot read properties of undefined (reading 'map')
at UserList (src/components/UserList.tsx:23:18)
at renderWithHooks (node_modules/react-dom/...)
Step 2: Let Claude investigate
> What's causing this? Look at the UserList component and the data
> it receives from its parent.
Step 3: Ask for a fix with verification
> Fix the null safety issue and add a test that reproduces the
> original error. Run the tests after fixing.
Step 1: Explore (Plan Mode)
> [Plan Mode] I want to add a search function to the user list page.
> Read the current UserList component and the API endpoints to
> understand how data flows.
Step 2: Plan (Plan Mode)
> Create a plan for adding search. It should:
> - Filter by name and email
> - Debounce input (300ms)
> - Show a loading state
> - Handle empty results
Step 3: Implement (Normal Mode)
> Implement the search feature from your plan. Run the existing tests
> to make sure nothing broke, then add new tests for search.
Step 4: Commit
> commit with message "Add search functionality to user list page"
Ask Claude to review changes, either your own or from a pull request:
> Review the changes in my current branch compared to main.
> Look for:
> - Security issues
> - Edge cases
> - Consistency with existing patterns
> - Missing error handling
For pull requests (requires gh CLI):
> Use gh to look at PR #42. Review the changes and leave comments
> on any issues you find.
For a deeper automated review, use /ultrareview -- it deploys multiple reviewer agents in a remote sandbox and typically catches things that a single-pass review misses. It costs around $5-$20 per run after three complimentary uses on Pro/Max plans.
Ask Claude to identify untested code and write tests:
> Find functions in @src/services/paymentService.ts that are not
> covered by existing tests. Write tests for them following the
> patterns in @tests/services/userService.test.ts.
> Add edge case tests for the calculateDiscount function:
> - Zero quantity
> - Negative price
> - Discount greater than 100%
> - Missing required fields
You can ask Claude the same questions you would ask a senior engineer:
> How does logging work in this project?
> How do I make a new API endpoint?
> What does `async move { ... }` do on line 134 of foo.rs?
> What edge cases does CustomerOnboardingFlowImpl handle?
> Why does this code call foo() instead of bar() on line 333?
No special prompting required. Ask directly.
Claude Code integrates with the Claude in Chrome browser extension for browser automation workflows. This lets you chain coding tasks with browser actions in a single workflow:
Browser actions run in a real, visible Chrome window. Claude pauses automatically when it hits a login page or CAPTCHA and waits for you to handle it manually.
| Shortcut | Action | When to Use |
|---|---|---|
Shift+Tab |
Cycle mode: Normal -> Auto-Accept -> Plan -> Normal | Toggle Plan Mode or Auto-Accept |
Esc |
Stop Claude mid-action | When Claude is going in the wrong direction |
Esc Esc (double-tap) |
Open the rewind menu | When you want to undo changes or restore a checkpoint |
Ctrl+C |
Interrupt / Exit Claude Code | To cancel current operation or exit |
Ctrl+L |
Clear the terminal screen | When the screen is cluttered |
Ctrl+G |
Open plan in text editor | To edit a plan directly before Claude proceeds |
Ctrl+R |
Reverse-search previous prompts | Searches across all sessions and projects, not just the current one |
Up Arrow |
Cycle through previous prompts | To reuse or modify a previous prompt |
Tab |
Autocomplete file paths and commands | Speed up typing file references |
? |
Show all available keyboard shortcuts | Quick reference during a session |
Enter |
Submit prompt / Approve a change | Send your message or accept Claude's suggestion |
| Shortcut | Action | Notes |
|---|---|---|
Ctrl+V |
Paste image from clipboard | Works even on macOS -- use Ctrl, not Cmd |
Cmd+V (second press) |
Expand abbreviated paste preview | When pasted content shows as [Pasted text #1 +N lines], press again to expand |
| Shortcut | Action | Description |
|---|---|---|
Shift+Tab (from Normal) |
Enter Auto-Accept Mode | Claude makes changes without per-change permission |
Shift+Tab (from Auto-Accept) |
Enter Plan Mode | Claude enters read-only mode |
Shift+Tab (from Plan) |
Return to Normal Mode | Standard mode with per-change permission |
| Shortcut | Action | Description |
|---|---|---|
Ctrl+O |
Toggle verbose mode | Show/hide Claude's internal reasoning (thinking) |
Option+T / Alt+T |
Toggle thinking mode | Turn extended thinking on/off for current session |
| Shortcut / Command | Action | Description |
|---|---|---|
/clear |
Clear context | Reset the context window between unrelated tasks |
/compact |
Compact context | Summarize conversation to free space. Use at 40-50% context usage rather than waiting for automatic compaction. |
/compact <focus> |
Focused compact | Summarize with emphasis: /compact focus on API changes |
/rewind |
Open rewind menu | Restore conversation, code, or both to a checkpoint |
/resume |
Resume a session | Pick from recent sessions or resume by name |
/rename <name> |
Rename session | Give the session a descriptive name for later |
/goal <condition> |
Set a completion goal | Claude works autonomously across turns until the goal is met |
/fast |
Toggle Fast Mode | 2.5x faster Opus responses; requires extra usage to be enabled |
/ultrareview |
Deep code review | Deploys multiple reviewer agents in a remote sandbox |
Claude Code automatically creates checkpoints before each file edit. The rewind menu (Esc Esc) lets you:
Important limitation: Checkpointing tracks file edits made through Claude's file tools. It does not track changes made by bash commands, external file modifications, or edits in concurrent sessions. If you run a script that modifies files, those changes will not be checkpointed. This is a session-level recovery tool, not a replacement for version control.
For rapid reference while working, here are the shortcuts you will use most:
Shift+Tab .... cycle modes (Normal / Auto-Accept / Plan)
Esc .......... stop Claude mid-action
Esc Esc ...... rewind menu (undo changes)
Ctrl+G ....... edit plan in your editor
Ctrl+R ....... search all previous prompts across sessions
/clear ....... reset context between tasks
/compact ..... free up context space (use at 40-50%)
/goal ........ set completion condition; Claude runs until done
Up Arrow ..... recall previous prompts
These exercises build skill progressively. Do them in order. Each one reinforces a concept from this guide.
Objective: Install Claude Code and explore a codebase without making any changes.
claude to start a session.Ctrl+C.Success criteria: You completed the entire session in Plan Mode and never switched to Normal Mode. No files were changed.
Objective: Practice the Explore-Plan-Implement-Commit workflow on a small task.
Success criteria: You went through all four phases. The plan was revised at least once before implementation. Tests pass.
Objective: Practice using AskUserQuestion to refine requirements before implementation.
"I want to add input validation to the [pick a form in your project]. Interview me about the requirements first using AskUserQuestion."/clear or new terminal).Success criteria: Claude asked at least 4 questions before starting to implement. The implementation matches your answers.
Objective: Practice providing context through multiple methods.
@ to reference a specific file and ask Claude to explain it.Success criteria: You used at least three different context methods (@ reference, paste, screenshot, git diff) in a single session.
Objective: Experience the difference between vague and specific prompts firsthand.
"add tests"/clear to reset context."Write tests for [specific function] in [specific file] covering these edge cases: [list 3 specific edge cases]. Follow the testing patterns in [reference test file]. Run the tests after writing them."Success criteria: You can articulate at least three specific differences between the two results.
Objective: Practice recovering from a session where Claude went off track.
Esc Esc to open the rewind menu.Success criteria: You successfully rewound to a clean state and produced a better result on the second attempt.
Objective: Combine all the skills from this level in a single end-to-end workflow.
"Interview me about what I want to build."Ctrl+G to edit the plan in your text editor. Make at least one manual edit.Success criteria: You used Plan Mode, the interview pattern, verification criteria, and the rewind capability (if needed) in a single session. The final result passes all tests.
Boris Cherny is the creator of Claude Code -- not just an engineer who works on it, but the person who built it. His publicly documented workflow is one of the most productive approaches to using the tool. These tips are adapted from his practices.
"Go back and forth with Claude until I like its plan."
Do not accept the first plan Claude produces. Push back. Ask questions. Make Claude consider alternatives. The time spent refining a plan is always less than the time spent fixing a bad implementation.
> I don't like approach #2 in your plan. The singleton pattern will
> make testing harder. What if we used dependency injection instead?
> Revise the plan.
Before implementing a PR, use Plan Mode to analyze what needs to change. Have Claude read the requirements, explore the codebase, and produce a detailed plan. Only then switch to Normal Mode to implement.
This is the "plan mode for PRs" pattern: the PR implementation starts from a vetted plan, not from Claude winging it.
When running multiple Claude Code sessions in parallel, use different terminal tab colors for each session. This lets you identify at a glance which session is which, without needing to read the content.
On macOS, pressing Fn twice activates dictation. Dictating your prompts instead of typing them is significantly faster for longer, more detailed prompts. The extra detail you can comfortably provide via voice leads to better results.
Check your CLAUDE.md into git. Update it when Claude repeatedly makes the wrong decision. Remove entries when Claude already does the right thing by default. Treat it like code: review it, prune it, test it.
If Claude keeps ignoring a rule in CLAUDE.md, the file is probably too long and the rule is getting lost. Cut aggressively.
If you find yourself giving the same set of instructions repeatedly, create a subagent file in .claude/agents/:
---
name: verify-app
description: Runs full verification suite. Use before committing.
tools: Bash, Read, Grep
model: haiku
---
Run the full verification pipeline:
1. Lint: npm run lint
2. Type check: npx tsc --noEmit
3. Tests: npm test
4. Build: npm run build
Report results for each step. Report full error output for failures.
Then use it with: "Use the verify-app subagent to check everything before I commit."
If you have corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run /clear and start a fresh conversation with a more specific prompt that incorporates what you learned.
A clean session with a better prompt almost always outperforms a long session with accumulated corrections.
Boris Cherny is openly frustrated with the "vibe coding" label -- the approach of throwing prompts at Claude, accepting whatever it produces, and shipping it. He draws a sharp distinction between that and intentional AI-assisted engineering.
The distinction matters more than it sounds. If your workflow is "describe something, accept whatever Claude produces, ship it," that is not a workflow -- that is hoping. The Explore-Plan-Implement-Commit sequence in this guide is what he means by using the tool correctly. You direct, verify, and own the output. Claude handles implementation. The oversight is yours.
At Anthropic, Cherny has noted, there are no traditional software engineers writing code line by line anymore. But that does not mean no one is engineering. It means the engineering has moved up a level -- to specification, direction, and verification.
Cherny's own setup reportedly involves thousands of AI subagents doing deeper work overnight. While that level of orchestration is advanced (it is covered at higher levels in this series), the underlying principle applies even to beginners: once you trust a plan, you do not have to babysit every step.
The /goal command is the beginner's version of this. Set a completion condition, give Claude the implementation task, and let it run autonomously until the condition is met. Come back when it is done. This is what loops in AI-assisted development actually mean in practice -- not you sitting at the keyboard correcting Claude step by step, but Claude running autonomously toward a clearly defined finish line that you set.
What it looks like:
make it work
Why it fails: "It" is undefined. "Work" is undefined. Claude guesses at both and often guesses wrong.
Fix: Be specific about what "it" is and what "working" means:
Fix the 404 error on the /api/users endpoint. It should return a
JSON array of user objects. Run curl localhost:3000/api/users to
verify it returns a 200 status code.
What it looks like: You start with one task, then ask Claude something unrelated, then go back to the first task, then ask about a third thing. The context window fills with irrelevant information.
Why it fails: Context is the most precious resource. Filling it with unrelated topics means Claude loses focus on the actual task.
Fix: Use /clear between unrelated tasks. One task per session. If a session gets tangled, start fresh.
What it looks like: Claude does something wrong. You correct it. It is still wrong. You correct again. You correct a third time. Context is now full of failed approaches.
Why it fails: Each failed attempt adds noise to the context. After multiple corrections, Claude is working with contradictory instructions and bad examples.
Fix: After two failed corrections, stop. Run /clear. Write a single, better prompt that incorporates everything you learned from the failures. Start clean.
What it looks like: You jump straight into implementation without understanding the codebase.
Why it fails: Claude guesses at patterns, conventions, and architecture. The guesses are often wrong, leading to code that works but does not fit the project.
Fix: Always start in Plan Mode. Even five minutes of exploration saves thirty minutes of rework.
What it looks like: A CLAUDE.md file with dozens of rules, many of which Claude already follows by default.
Why it fails: When the file is too long, important rules get lost in the noise. Claude ignores your actual instructions because they are buried in obvious ones.
Fix: For each line in CLAUDE.md, ask: "Would removing this cause Claude to make mistakes?" If not, delete it. Keep only what Claude cannot infer from the code itself.
What it looks like: Every session starts in Normal Mode. Claude immediately starts making changes.
Why it fails: Without a plan, Claude solves whatever problem it thinks you described, which may not be what you actually need. Changes are harder to undo than plans are to revise.
Fix: Use Plan Mode for anything that is not trivially simple. The cost is a few extra seconds. The benefit is dramatically better implementations.
What it looks like: Claude implements something, you accept it without running tests or checking the output.
Why it fails: Claude produces plausible-looking code that does not handle edge cases. You ship it, users find the bugs.
Fix: Every prompt should include verification criteria. "Run the tests." "Check that the build succeeds." "Verify with curl." Make Claude prove its work before you accept it.
What it looks like: You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context window.
Why it fails: The context window fills with file contents that may not be relevant. Performance degrades. Claude loses track of what it was actually looking for.
Fix: Scope investigations narrowly: "Read the three files related to token refresh in src/auth/." Or use subagents: "Use a subagent to investigate how the caching layer works." Subagents run in separate context windows, keeping your main conversation clean.
What it looks like:
what is the syntax for a Python list comprehension?
Why it fails: This consumes context window for something you could Google in two seconds. Claude Code's value is in understanding YOUR codebase, not answering generic programming questions.
Fix: Use Claude Code for project-specific questions: "How does our project handle list transformations? Show me an example from the codebase."
What it looks like: You work on multiple features over multiple days but never name your sessions. When you try to resume, every session is named "explain this function" or "fix the bug."
Why it fails: You cannot find the session you need, so you start over and re-explain everything.
Fix: Use /rename early: /rename auth-refactor or /rename payment-edge-cases. Then resume with claude --resume auth-refactor.
What it looks like: You give Claude direct access to your production database, turn on Auto-Accept Mode for tasks that involve data deletion or modification, and walk away. Or you let an agent run cleanup scripts on live data without reviewing what "cleanup" means to it.
Why it fails: Claude is capable, but it can also guess when it should verify. In a high-profile incident that made international news, a Claude-powered agent deleted an entire company's production database AND all backups in nine seconds -- then confessed that it had "violated every principle" it was given. It guessed which records were safe to delete instead of verifying. Nine seconds. Everything gone.
This is not an edge case. Agents make this class of error whenever they have write access to irreversible operations and no human in the loop.
Fix:
The workflow in this guide -- plan, verify, commit -- exists precisely so you are never in a position where an agent makes an irreversible decision without your review.
| Resource | URL | Description |
|---|---|---|
| Overview | code.claude.com/docs/en/overview | What Claude Code is, installation, and environments |
| Quickstart | code.claude.com/docs/en/quickstart | First-launch walkthrough and first tasks |
| Best Practices | code.claude.com/docs/en/best-practices | Prompting patterns, context management, and workflow tips |
| Common Workflows | code.claude.com/docs/en/common-workflows | Step-by-step guides for debugging, testing, PRs, and more |
| CLI Reference | code.claude.com/docs/en/cli-reference | Complete list of commands and flags |
| Troubleshooting | code.claude.com/docs/en/troubleshoot-install | Error-by-error fix guide for installation and login failures |
| Resource | URL | Description |
|---|---|---|
| Settings | code.claude.com/docs/en/settings | Configuring permissions, tools, and environment |
| CLAUDE.md | code.claude.com/docs/en/memory | Writing effective CLAUDE.md files |
| Skills | code.claude.com/docs/en/skills | Creating custom slash commands and workflows |
| Hooks | code.claude.com/docs/en/hooks | Automating actions at specific workflow points |
| Subagents | code.claude.com/docs/en/sub-agents | Creating specialized delegated agents |
| .claude Directory | code.claude.com/docs/en/claude-directory | Complete reference for project configuration files |
| Resource | URL | Description |
|---|---|---|
| MCP Integration | code.claude.com/docs/en/mcp | Connecting external tools and data sources |
| Agent Teams | code.claude.com/docs/en/agent-teams | Multi-agent coordination (experimental) |
| Headless Mode | code.claude.com/docs/en/headless | Running Claude Code in scripts and CI/CD |
| Sandboxing | code.claude.com/docs/en/sandboxing | OS-level isolation for safe autonomous work |
| Fast Mode | code.claude.com/docs/en/fast-mode | 2.5x faster Opus responses via /fast command |
| Ultrareview | code.claude.com/docs/en/ultrareview | Deep code review with parallel reviewer agents |
| Checkpointing | code.claude.com/docs/en/checkpointing | How automatic file-state checkpoints and rewind work |
| Chrome Integration | code.claude.com/docs/en/chrome | Browser automation via the Claude in Chrome extension |
| Resource | URL | Description |
|---|---|---|
| Boris Cherny's Workflow | howborisusesclaudecode.com | Full workflow from the creator of Claude Code |
| Anthropic Discord | anthropic.com/discord | Community support and tips |
| Product Page | code.claude.com | Demos, pricing, and product details |
| Anthropic Free Courses | anthropic.com/learn | Official free courses, some under 20 minutes |
Before moving to Level 2, make sure you can do all of the following:
@ file references to provide context/clear to reset context between unrelated tasks/rewind or Esc Esc to undo changes/rename and resume them with /resume/compact proactively at 40-50% context usage/goal and let Claude run autonomouslyLast Updated: 2026-05-18 Compiled from official Anthropic documentation and community best practices Part of the Claude Code Learning Path: Level 1 of 7
New techniques, real-world patterns, and Claude updates — delivered as the guides evolve.