> Building Productively with Claude Code: A Developer's Guide

What Is Claude Code?

Claude Code is an agentic AI coding tool from Anthropic that operates directly in your terminal. You describe what you want and Claude generates, edits, and tests the code for you.

It reads your project files, understands dependencies, makes multi-file edits, runs shell commands, and submits pull requests. Claude works within your existing development environment rather than requiring a separate interface.

As of June 2026, Claude Opus 4.8 (as of v2.1.154, released May 28, 2026) is now the default on Max, Team Premium, Enterprise pay-as-you-go, and the Anthropic API. Opus 4.8 defaults to high effort use /effort xhigh for harder tasks. Previous versions defaulted to Sonnet. You can still switch models with /model.

Claude Code is available across several environments: terminal CLI, VS Code extension, JetBrains IDEs (beta), desktop app, and the web interface at claude.ai/code. The terminal CLI is the flagship experience and where most developers start. Claude Code operates in a loop: it takes an action, observes the result, and adjusts. If a test fails after Claude makes a change, it reads the error, identifies the cause, and attempts a fix. This cycle continues until the task is complete or Claude needs input from you.

Claude Code runs on the Claude model family. The default model is Claude Sonnet, with Claude Opus available for complex reasoning tasks. You can switch models mid-session using /model or set a default in your configuration.

Getting Started

Installation

The npm install method (npm install -g @anthropic-ai/claude-code) was deprecated in v2.1.113 when the CLI moved to a platform-native binary. Use the native installers instead:

# macOS, Linux, and WSL (recommended — auto-updates)
curl -fsSL https://claude.ai/install.sh | bash
 
# Windows PowerShell (auto-updates)
irm https://claude.ai/install.ps1 | iex
 
# macOS with Homebrew (stable, ~1 week behind, no auto-update)
brew install --cask claude-code
 
# macOS with Homebrew (latest releases, no auto-update)
brew install --cask claude-code@latest
 
# Windows WinGet (no auto-update)
winget install Anthropic.ClaudeCode

If you installed via Homebrew or WinGet, run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode manually to stay current. The native curl/PowerShell installs update in the background and are the recommended path for most developers.

Requirement: Node.js 18+ is no longer required — the CLI is now a native binary.

First Run

Navigate to any project directory and start Claude Code:

cd your-project
claude

On first launch, you'll be prompted to authenticate. Claude Code works with Claude Pro at $20/month for casual use, Max 5x at $100/month for regular professional use, Max 20x at $200/month for heavy daily use, and API pay-per-use. Claude Code requires a paid plan. Most professional developers gravitate toward Max or API billing.

Quick Authentication Check

# Verify your setup
claude --version

# Start with a specific model
claude --model claude-opus-4-8

VS Code Extension

Install the Claude Code extension for VS Code or Cursor. It provides a launcher that makes opening Claude Code simple. You can run multiple instances in parallel in different panes as long as they're working on different parts of your codebase.

Skip Permission Prompts

Claude Code asks permission for every file edit and command. For faster workflows, bypass these prompts:

claude --dangerously-skip-permissions

This is similar to "yolo mode" in other tools. Claude can execute without confirmation. Use at your own discretion. Even though it feel annoying that Claude code be asking asking permission all the time. i would recommend you to still be control.

The CLAUDE.md File: Your Most Powerful Tool

The single most important file in your codebase for using Claude Code effectively is the root CLAUDE.md. This file is automatically loaded when Claude Code starts and provides persistent context about your project. We can create CLAUDE.md file in the root directory using the /init command.

What to Include

# Project: MyApp
 
## Tech Stack
- Frontend: React 18 with TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL with Prisma ORM
- Testing: Jest + React Testing Library
 
## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Use ES modules, not CommonJS
- Follow the Airbnb style guide
 
## Common Commands
- `npm run dev` — Start development server
- `npm run test` — Run test suite
- `npm run build` — Production build
- `npm run lint` — Run ESLint
 
## Project Structure
- `src/components/` — React components
- `src/hooks/` — Custom hooks
- `src/services/` — API service layer
- `src/stores/` — Zustand state management
 
## Important Patterns
- All API calls go through `src/services/api.ts`
- Authentication state is managed in `src/stores/authStore.ts`
- Use the `useQuery` hook for data fetching
 
## Testing Requirements
- New components require corresponding test files
- Minimum 80% coverage for new code
- Use `data-testid` attributes for test selectors
 
## Communication Style
- Be concise in explanations
- Show code first, explain only if asked
- No need to repeat back what I asked you to do

Hierarchical CLAUDE.md Files

Claude Code loads CLAUDE.md files hierarchically, from broadest to most specific:

• Global: ~/.claude/CLAUDE.md (applies to all projects)
• Project: ./CLAUDE.md (project-specific)
• Directory: ./src/CLAUDE.md (subdirectory-specific)

This lets you define global preferences while overriding them per project.

CLI Flags Reference

A quick reference for launching Claude Code from the terminal:

Flag	What it does
claude	Start interactive mode
claude "task description"	Run a one time task and return to shell
claude -p "query"	Non-interactive, run query and exit (for pipes/scripts)
claude -c or --continue	Resume most recent conversation in this directory
claude -r or --resume	Open conversation picker to resume a previous session
claude --permission-mode plan	Plan mode: Claude reads and proposes, no edits until approval
claude --worktree <branch>	Start session in a new git worktree on its own branch
claude --bg "task"	Launch a background agent session
claude agents	View all running, blocked, and completed sessions
claude -p "query" --output-format json	JSON output for scripting
claude mcp list	List all configured MCP servers
claude mcp add --transport http <name> <url>	Add a remote MCP server
claude project purge	Delete all Claude Code state for a project
claude --dangerously-skip-permissions	Bypass all permission prompts (use deliberately)

Essential Commands and Workflows

Slash Commands

Claude Code includes built-in slash commands for common operations:

# Context management
/clear          # Clear conversation history (use often!)
/compact        # Compress context while preserving key info
/resume <name>  # Resume a previous session
/rename         # Name your current session

# Planning
/plan           # Enter plan mode for complex tasks

# Navigation
/help           # Show all available commands
/stats          # View usage statistics

# Tools
/install-github-app  # Set up automated PR reviews

Planning and effort

/plan           # Enter plan mode for complex tasks
/effort         # Open interactive slider (arrow keys, no need to remember level names)
/effort high    # Set effort level explicitly: low, medium, high, xhigh, max
/goal fix the failing checkout test and stop after tests pass  # Work until condition is met

Plan mode can also be activated with Shift+Tab (cycles through permission modes). In plan mode, Claude analyzes and plans but cannot modify files until you approve.

Review and code quality

/review                  # Review current session's changes
/security-review         # Security-focused code review
/code-review high        # Correctness bug review at a chosen effort level
/code-review --comment   # Post findings as inline GitHub PR comments
/simplify                # Cleanup-only review (separate from /code-review)
/diff                    # Show a diff of all changes in this session

Agents and background work

/workflows      # Manage dynamic workflow runs
/loop           # Repeat a prompt on a recurring interval
/proactive      # Alias for /loop

Diagnostics and usage

/usage          # Per-category breakdown of what's driving your plan limits
/usage-credits  # Show extra usage / credit balance (formerly /extra-usage)
/mcp            # Check MCP server status, tool counts, and authenticate
/status         # Environment check and loaded context summary
/stats          # View usage statistics
/skills         # Browse and manage available skills
/plugin         # Browse, install, enable, and manage plugins
/config         # Session configuration (workflow trigger keyword, model defaults, etc.)
/fewer-permission-prompts  # Scan transcripts and propose an allowlist for settings.json

Navigation

/help           # Show all available commands
/install-github-app  # Set up automated PR reviews
/undo           # Alias for /rewind — revert to a previous checkpoint
/rewind         # Revert to a previous checkpoint
/checkpoints    # View available checkpoints

Keyboard shortcuts

Shortcut	Action
Shift+Tab	Toggle plan mode / cycle permission modes
Ctrl+T (in claude agents)	Pin a session to keep it alive when idle
Tab	Autocomplete commands
↑	Command history
Ctrl+D or exit	Exit Claude Code

File References

Reference files directly in your prompts using @:

# Reference specific files
"Update @src/components/Header.tsx to include a dark mode toggle"

# Reference directories
"Refactor all components in @src/components/ to use the new design system"

Shell Command Passthrough

Execute shell commands without Claude processing them:

# Prefix with ! for direct execution
!npm install axios
!git status

Productive Workflows

1. Plan Before You Build

For any task with 3+ steps or architectural implications, activate plan mode:

I need to add user authentication to this app. Before writing any code:
1. Analyze the current codebase
2. Propose an implementation plan
3. List files that need to be created or modified
4. Identify potential challenges
 
Save the plan to docs/auth-implementation-plan.md

Or use the flag directly:

claude --permission-mode plan

2. Incremental Development

Break large tasks into steps with explicit checkpoints.

Let's implement authentication step by step.
 
Step 1: Create the user model and database schema.
When done, show me what you created and wait for my approval before continuing.

3. Context Management

Clear context frequently. A focused context window produces more accurate output.

/clear              # After completing a task
/clear              # Before starting new work
/compact Focus on preserving the database schema decisions  # When you need continuity
/recap              # Summarize where you are before a break

4. Testing-Driven Development

Write tests alongside implementation, not after.

Create a new UserService class with these methods:
- createUser(email, password)
- authenticateUser(email, password)
- resetPassword(email)
 
Write the implementation and comprehensive tests together.
Run the tests and fix any failures.

5. Code Review and Security

Review @src/services/paymentService.ts for:
1. Security vulnerabilities
2. Error handling gaps
3. Performance issues
4. Code style violations
 
Propose fixes for each issue found.

Or use the built-in commands:

/security-review         # Security-focused pass
/code-review high        # Correctness and quality at high effort
/code-review --comment   # Post findings directly to GitHub PR

6. Autonomous Bug Fixing

When you have logs and a failing test, just hand it off:

The CI is failing. Look at the error logs, identify the issue, fix it, and push.
Don't ask me questions unless you're truly stuck.

Advanced Features

MCP (Model Context Protocol) Integration

MCP lets Claude Code connect to external tools and data sources:

# Add web search capability
claude mcp add brave-search -s project -- npx @modelcontextprotocol/server-brave-search

# Connect to your database
claude mcp add supabase -s project -- npx @supabase/mcp-server

With MCP configured, Claude can search the web for best practices and implement them:

Search for current best practices for securing JWT tokens
and implement them in our authentication service.

Git Workflow Automation

Claude Code integrates with Git:

# Create a feature branch, implement changes, and commit
Create a feature branch called 'add-dark-mode'.
Implement dark mode support in the Header and Sidebar components.
Commit each component change separately with descriptive messages.

Custom Slash Commands

Create project-specific commands in .claude/commands/:

# .claude/commands/test-component.md
---
name: test-component
description: Generate tests for a React component
---

Write comprehensive tests for the specified component:
1. Test all props and their variations
2. Test user interactions
3. Test edge cases and error states
4. Use React Testing Library best practices
5. Aim for >90% coverage

Then use it:

/test-component @src/components/UserProfile.tsx

Hooks for Automation

Configure hooks in your project's .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black $file"
          }
        ]
      },
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          }
        ]
      }
    ]
  }
}

This automatically formats files after Claude writes them.

Checkpoints and Rollback

Claude Code automatically creates checkpoints as you work. If something goes wrong, you can instantly revert:

# View available checkpoints
/checkpoints

# Revert to a previous state
/revert

This lets you experiment freely. If Claude makes a change you don't like, roll it back in seconds.

Skills

Skills are markdown-based guides that teach Claude Code how to handle specific tasks. Unlike slash commands, skills are invoked via natural language.

Create a skill in .claude/skills/:

# .claude/skills/api-endpoint.md
---
name: api-endpoint
description: Create REST API endpoints following project conventions
---

When creating API endpoints:
1. Use the controller pattern in src/controllers/
2. Add input validation with zod
3. Include error handling middleware
4. Write integration tests
5. Update the OpenAPI spec

Claude will reference the skill's instructions automatically when relevant.

GitHub Actions

The Claude Code GitHub Action runs Claude in your CI/CD pipeline. Trigger it from PRs, issues, or other events:

# .github/workflows/claude-code.yml
name: Claude Code
on:
  issue_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

With this setup, mentioning @claude in a PR comment triggers Claude to analyze code, suggest fixes, or implement changes.

Workflow Orchestration

These workflow patterns help you get consistent, high-quality results from Claude Code.

1. Plan Mode Default

Enter plan mode for any non-trivial task (3+ steps or architectural decisions). If something goes sideways, stop and re-plan immediately. Don't keep pushing forward. Use plan mode for verification steps as well as building. Write detailed specs upfront to reduce ambiguity.

2. Subagent Strategy

Use subagents liberally to keep your main context window clean. Offload research, exploration, and parallel analysis to subagents. For complex problems, throw more compute at it via subagents. Assign one task per subagent for focused execution.

Use a subagent to research the best pagination libraries for React.
Report back with pros and cons of each option.

3. Self-Improvement Loop

After any correction from the user, update tasks/lessons.md with the pattern. Write rules for yourself that prevent the same mistake. Iterate on these lessons until the mistake rate drops. Review lessons at session start for each project.

Example tasks/lessons.md:

## Lessons Learned

### Database
- Always add indexes for foreign keys
- Use transactions for multi-table updates

### React
- Check for null before accessing nested properties
- Use useCallback for functions passed to child components

### Testing
- Mock external APIs in unit tests
- Test error states and happy paths

4. Verification Before Done

Never mark a task complete without proving it works. Diff behavior between main and your changes when relevant. Ask yourself: "Would a staff engineer approve this?" Run tests, check logs, demonstrate correctness.

Before marking this complete:
1. Run the full test suite
2. Show me a diff of the changes
3. Demonstrate the feature works with a curl command

Or use the built-in commands:

/review      # Review what changed
/diff        # Show the full diff

Goal-Oriented Sessions

Use /goal when the task has a clear completion condition and you want Claude to keep working across turns without interruption:

/goal fix the failing checkout test and stop after tests pass

5. Demand Elegance (Balanced)

For non-trivial changes, pause and ask "is there a more elegant way?" If a fix feels hacky, prompt: "Knowing everything I know now, implement the elegant solution." Skip this for simple, obvious fixes. Don't over-engineer. Challenge your own work before presenting it.

6. Autonomous Bug Fixing

When given a bug report, just fix it. Don't ask for hand-holding. Point at logs, errors, and failing tests, then resolve them. Zero context switching required from the user. Go fix failing CI tests without being told how.

The CI is failing. Look at the error logs, identify the issue, 
fix it, and push. Don't ask me questions unless you're truly stuck.

Task Management

Structure your work sessions with these practices:

1. Plan First: Write plan to tasks/todo.md with checkable items
2. Verify Plan: Check in before starting implementation
3. Track Progress: Mark items complete as you go
4. Explain Changes: High-level summary at each step
5. Document Results: Add review section to tasks/todo.md
6. Capture Lessons: Update tasks/lessons.md after corrections

Example tasks/todo.md:

# Feature: User Notifications

## Plan
- [x] Create notification model and migrations
- [x] Build notification service
- [ ] Add API endpoints
- [ ] Create React components
- [ ] Write tests

## Progress Notes
Step 1 complete. Created Notification model with fields: 
id, user_id, type, message, read_at, created_at.

## Review
(To be filled after completion)

Best Practices for Maximum Productivity

1. Be Specific About Outcomes

Vague: "Make the login page better"

Specific: "Update the login page to include email validation, show inline errors, add a 'remember me' checkbox, and match our design system in @docs/design-tokens.md"

2. Provide Examples

Add a new API endpoint for fetching user orders.
Follow the same pattern as @src/routes/products.ts:
- Use the validation middleware
- Return paginated results
- Include proper error handling

3. Use Git as a Safety Net

Work in feature branches and commit frequently:

Before making changes:
1. Create a new branch called 'refactor-auth'
2. Make small, focused commits
3. Run tests after each significant change

4. Leverage Extended Thinking

For complex architectural decisions, ask Claude to think it through:

I need to decide between microservices and a monolith for our 
new application. Consider our team size (5 developers), expected 
traffic (10k users), and timeline (3 months to MVP).

Think through the tradeoffs carefully before making a recommendation.

5. Run Parallel Sessions

For large projects, run multiple Claude Code instances on different parts:

# Terminal 1: Frontend work
cd frontend && claude

# Terminal 2: Backend work
cd backend && claude

Use Git worktrees for better isolation:

git worktree add ../feature-auth -b feature/auth
cd ../feature-auth && claude

6. Review Changes Before Accepting

Review what Claude produces:

Show me a diff of all files you've modified in this session.
Explain the key changes and any potential risks.

Troubleshooting Common Issues

Context window exhaustion Symptoms: Claude starts forgetting earlier context or gives inconsistent responses.

/clear
# Or with continuity:
/compact Keep the database schema and API contract details

Stuck in a loop Symptoms: Same failing approach repeated.

Stop. The current approach isn't working. Let's step back and try
a different strategy. What other options do we have?

Too many permission prompts

/fewer-permission-prompts   # Scans transcripts, proposes an allowlist for settings.json

Or for trusted environments:

claude --dangerously-skip-permissions

Auto mode not appearing Cycle through modes with Shift+Tab. Auto mode appears once your account meets the requirements. Check /status to see what's enabled in your current session.

Overly Verbose Output

Symptoms: Claude writes long explanations.

Solutions: Add to your CLAUDE.md:

## Communication Style
- Be concise in explanations
- Show code first, explain only if asked
- No need to repeat back what I asked you to do

Real-World Example: Building a Feature

Here's a complete workflow for adding a new feature:

# 1. Start fresh
cd my-project
claude
/clear

# 2. Describe the feature
"I need to add a user notification system. Users should be able to:
- Receive in-app notifications
- Mark notifications as read
- Configure notification preferences
- Get email notifications for important events

Review @CLAUDE.md for project context. Create a plan before implementing."

# 3. Review and approve the plan
"The plan looks good. Implement step 1: the database schema and models."

# 4. Verify each step
"Run the migrations and show me the schema. Run the tests."

# 5. Continue incrementally
"Great, tests pass. Now implement step 2: the notification service."

# 6. Final verification
"Run the full test suite. Create a PR with a detailed description."

Principles for Working with Claude Code

Plan before you build. AI agents perform best when the task is well defined. Outline the architecture, identify components, break the problem into phases. This is more true than ever with dynamic workflows, where ambiguity at the top becomes coordination errors across dozens of subagents.

Work incrementally. Large requests produce complex and fragile implementations. Break features into: data model → core logic → API/UI layer → tests.

Verify everything. AI-generated code is a first draft. Run tests, review the output, check logs, confirm the implementation matches the requirement. The /review, /diff, and /code-review commands make this fast.

Control the context. Use CLAUDE.md for project guidance. Clear context between tasks. Use /compact when you need continuity but the window is filling up.

Use plugins for the policy layer. Instead of re-specifying the same rules in every prompt, put them in a plugin or skill once. Security rules, design system constraints, code style — these belong in structured configuration, not repeated prompts.

Treat Claude as a collaborator, not a replacement. Use it for exploration, analysis, automation, and acceleration. Keep ownership of design decisions and the final code.

AI can dramatically increase productivity. The practices that make it reliable are the same ones that made engineering reliable before AI: clear specs, small steps, verified outputs, and continuous improvement.

For the latest features and documentation, visit code.claude.com and the Anthropic documentation.