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

What Is Claude Code?

Claude Code turns your terminal into an AI-powered development environment. Instead of writing every line yourself, you describe what you want and Claude generates, edits, and tests the code for you. It integrates with your development environment. It reads your project files, understands dependencies, makes multi-file edits, runs shell commands, and submits pull requests.

Getting Started

Installation

Install Claude Code using npm (requires Node.js 18+):

npm install -g @anthropic-ai/claude-code

Alternative installation methods:

# macOS with Homebrew
brew install claude-code

# Windows with WinGet
winget install Anthropic.ClaudeCode

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, Max, or API subscriptions.

Quick Authentication Check

# Verify your setup
claude --version

# Start with a specific model
claude --model claude-sonnet-4-20250514

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.

The CLAUDE.md File: Your Most Powerful Tool

Create a CLAUDE.md file in your project root. This file is automatically loaded when Claude Code starts and provides persistent context about your project.

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

Hierarchical CLAUDE.md Files

Claude Code loads CLAUDE.md files hierarchically:

• 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.

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

You can also activate plan mode by pressing Shift+Tab twice. In plan mode, Claude analyzes and plans but cannot modify files until you approve.

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 complex features, ask Claude to create a plan first:

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

2. Incremental Development

Break large tasks into smaller chunks:

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

Claude Code performs better with focused context. Clear frequently:

# After completing a task
/clear

# Before starting new work
/clear
"Now let's work on the payment integration..."

# Compact when you need to preserve some context
/compact Focus on preserving the database schema decisions

4. Testing-Driven Development

Use Claude Code to write tests alongside implementation:

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 Refactoring

Claude excels at analyzing existing code:

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.

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

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.

Solutions:

# Clear and restart
/clear

# Or compact with specific instructions
/compact Keep the database schema and API contract details

Stuck in a Loop

Symptoms: Claude keeps trying the same failing approach.

Solutions:

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

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

Using Claude Code effectively is less about clever prompts and more about adopting the right development mindset. The following principles help ensure that AI accelerates your workflow without compromising code quality or maintainability.

1. Plan Before You Build Before asking Claude Code to implement anything, clarify the goal and the structure of the solution.

AI agents perform best when the task is well defined. Outline the architecture, identify the components involved, and break the problem into smaller tasks. A clear plan reduces ambiguity and leads to more reliable code generation.

In practice, this means thinking through the design first rather than asking the agent to “build everything at once.”

2. Work Incrementally Large requests often lead to complex and fragile implementations. Instead, approach development in small, manageable steps.

Break features into smaller tasks or phases such as:

• Create the data model

• Implement the core logic

• Add API endpoints or UI components

• Write tests and validation

Incremental development helps the AI maintain context and makes it easier to review and verify each change.

3. Verify Everything AI-generated code should always be treated as a first draft.

Before marking a task as complete:

• run tests

• review the generated code

• check logs and runtime behavior

• confirm that the implementation meets the original requirement

Claude Code can accelerate development, but validation remains the responsibility of the developer.

4. Control the Context AI agents rely heavily on context. Too much irrelevant information can reduce accuracy and lead to incorrect changes.

Provide focused and structured context by:

• maintaining a CLAUDE.md file for project guidance

• keeping task files organized

• writing precise prompts

Clear context leads to better reasoning and more accurate code generation.

5. Treat AI as a Collaborator Claude Code is most powerful when used as a development partner rather than a replacement for engineering judgment.

Use the agent to:

• explore implementation options

• analyze existing code

• automate repetitive tasks

• accelerate feature development

But always maintain ownership of the design decisions and the final code.

AI can dramatically increase productivity, but strong engineering practices remain essential.

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