Mastering Claude Code: Essential Workflows for Modern Development

Claude Code is Anthropic's official CLI that transforms how developers interact with codebases. This comprehensive guide covers the essential workflows that will make you more productive when working with Claude Code.

What is Claude Code?

Claude Code is an interactive CLI tool that helps you with software engineering tasks. It can understand your codebase, fix bugs, refactor code, write tests, create documentation, and much more. Think of it as having an expert developer partner who can instantly analyze your entire codebase and help you solve complex problems.

Getting Started

Launch Claude Code

Simply navigate to your project and start Claude:

cd /path/to/your/project
claude

Claude Code will automatically:

• Read your project structure
• Analyze your codebase
• Provide contextual assistance based on your project type

Understand Permission Modes

Claude Code operates in different permission modes for safety:

Normal Mode (default)

• Prompts before making changes
• Safe for exploration and analysis
• Best for first-time use

Auto-Accept Mode

• Automatically applies safe changes
• Indicated by ⏵⏵ accept edits on
• Useful for trusted operations

Plan Mode

• Read-only analysis
• Creates detailed plans without executing
• Perfect for exploring and planning complex changes
• Activated with Shift+Tab or --permission-mode plan

Essential Workflows

1. Understanding New Codebases

When joining a new project or exploring an unfamiliar codebase, Claude Code excels at providing quick insights.

Get a High-Level Overview

> give me an overview of this codebase

Claude will analyze your project structure and provide:

• Project type and framework
• Main components and their purposes
• Key dependencies
• Architecture patterns used

Dive Deeper into Specific Areas

> explain the main architecture patterns used here

> what are the key data models?

> how is authentication handled?

> show me the API endpoints and their purposes

Find Relevant Code

> find the files that handle user authentication

> where is the payment processing logic?

> show me how the email notifications work

Understand Component Interactions

> trace the login process from front-end to database

Pro Tips:

• Start with broad questions, then narrow down
• Ask about coding conventions and patterns
• Request a glossary of project-specific terms
• Use domain language from your project

2. Fixing Bugs Efficiently

When you encounter errors, Claude Code can help you diagnose and fix issues quickly.

Share Errors and Get Recommendations

> I'm seeing an error when I run npm test

> here's the error message: [paste error]

> suggest a few ways to fix the @ts-ignore in user.ts

Apply Fixes

> update user.ts to add the null check you suggested

> fix the SQL injection vulnerability in the login function

> resolve the race condition in the payment processor

Reproduce and Verify

> help me create a test case to reproduce this bug

> run the tests after applying the fix to verify it works

Pro Tips:

• Tell Claude the exact command to reproduce the issue
• Provide the full stack trace
• Mention if the error is intermittent or consistent
• Ask Claude to explain the root cause

3. Refactoring Code

Modernize your codebase with confidence using Claude Code's refactoring capabilities.

Identify Refactoring Opportunities

> find deprecated API usage in our codebase

> identify functions that could benefit from modern JavaScript features

> find code that violates DRY principles

Get Refactoring Recommendations

> suggest how to refactor utils.js to use modern JavaScript features

> how can we improve the performance of the image loader?

> what patterns should we use for state management?

Apply Refactoring Safely

> refactor utils.js to use ES2024 features while maintaining the same behavior

> convert the callback-based API to async/await

> extract reusable components from the authentication module

Verify Changes

> check if the refactoring maintains backward compatibility

Pro Tips:

• Ask Claude to explain benefits of the modern approach
• Request backward compatibility when needed
• Refactor in small, testable increments
• Use Plan Mode for large refactoring projects

4. Working with Tests

Improve your code quality with comprehensive test coverage.

Identify Untested Code

> find functions in NotificationsService.swift that are not covered by tests

> show me which components lack integration tests

Generate Test Scaffolding

> add tests for the notification service

> create unit tests for the user authentication module

> generate test cases for the payment processor

Add Meaningful Test Cases

> add test cases for edge conditions in the notification service

> create tests for error handling scenarios

> add performance tests for the data processor

Run and Verify Tests

> run the new tests and fix any failures

> show me test coverage for the refactored code

Pro Tips:

• Ask for edge cases and error condition coverage
• Request both unit and integration tests
• Have Claude explain the testing strategy
• Use tests to verify refactoring doesn't break functionality

5. Creating Pull Requests

Streamline your PR workflow with Claude Code.

Summarize Changes

> summarize the changes I've made to the authentication module

> what files were modified in this feature branch?

Generate PR Documentation

> create a pull request with a clear description

> add information about how these changes were tested

> enhance the PR description with more context about the security improvements

Review and Refine

> check if there are any potential issues with this PR

> highlight any breaking changes

Pro Tips:

• Ask Claude directly to make a PR for you
• Review the generated PR before submitting
• Ask Claude to highlight potential risks
• Include testing details and migration notes

6. Handling Documentation

Keep your codebase well-documented with Claude Code's help.

Identify Documentation Needs

> find functions without proper JSDoc comments in the auth module

> identify undocumented public APIs

> show me which files need README updates

Generate Documentation

> add JSDoc comments to the undocumented functions in auth.js

> create README documentation for the payment module

> add inline comments explaining the complex algorithm

Review and Enhance

> improve the generated documentation with more context and examples

> add code examples to the API documentation

Verify Documentation

> check if the documentation follows our project standards

> validate that all public methods are documented

Pro Tips:

• Specify the documentation style (JSDoc, docstrings, etc.)
• Ask for examples in documentation
• Request documentation for public APIs and complex logic
• Use consistent formatting across the codebase

7. Using Extended Thinking

For complex problems, leverage Claude's extended thinking capabilities.

Enable Extended Thinking

Extended thinking is disabled by default. Toggle it on using:

• Tab key to toggle Thinking on/off
• Prompts like "think" or "think hard"
• Environment variable: MAX_THINKING_TOKENS

Apply Deep Reasoning

> I need to implement a new authentication system using OAuth2. Think deeply about the best approach for implementing this in our codebase.

> think about potential security vulnerabilities in this approach

> think hard about edge cases we should handle

Prompt Intensity Examples

• "think" → Basic extended thinking
• "think hard" → Deeper thinking
• "keep thinking" → Extended reasoning
• "think more" → Intensified analysis
• "think a lot" → Maximum depth

Pro Tips:

• Use for complex architectural decisions
• Apply to challenging bugs
• Leverage for multi-step implementations
• Enable via Tab toggle during a session

8. Using Plan Mode for Safe Analysis

Plan Mode provides read-only access for safe exploration and planning.

Start in Plan Mode

# New session in Plan Mode
claude --permission-mode plan

# Direct query (headless mode)
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Switch to Plan Mode During Session

Use Shift+Tab to cycle through modes:

1. Normal Mode → ⏵ accept edits on (Auto-Accept Mode)
2. Auto-Accept Mode → ⏸ plan mode on (Plan Mode)

Configure as Default

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

When to Use Plan Mode:

• Multi-step implementations requiring planning
• Exploring unfamiliar codebases
• Iterative development with feedback
• Safe analysis before making changes

9. Working with Images

Claude Code can analyze images to provide visual context.

Add Images to Conversation

1. Drag and drop image into Claude Code window
2. Copy image and paste with Ctrl+V (not Cmd+V)
3. Provide image path: Analyze this image: /path/to/image.png

Analyze Visual Content

> What does this image show?

> Describe the UI elements in this screenshot

> Are there any problematic elements in this diagram?

> Here's a screenshot of the error. What's causing it?

Get Code from Visual Content

> Generate CSS to match this design mockup

> What HTML structure would recreate this component?

> Create React components from this design

Pro Tips:

• Use images when text descriptions are unclear
• Include screenshots of errors and UI designs
• Work with multiple images in one conversation
• Great for diagrams, mockups, and screenshots

10. Using File References

Quickly reference files and directories without waiting for Claude to read them.

Reference a Single File

> Explain the logic in @src/utils/auth.js

This includes the full file content in the conversation.

Reference a Directory

> What's the structure of @src/components?

This provides a directory listing with file information.

Reference Multiple Files

> Compare @file1.js and @file2.js

> Explain @src/services/auth.ts and @src/services/permissions.ts

Reference MCP Resources

> Show me data from @github:repos/owner/repo/issues

Format: @server:resource for connected MCP servers.

Pro Tips:

• File paths can be relative or absolute
• @ references add CLAUDE.md to context automatically
• Directory references show listings, not contents
• Use multiple file references for comparison

Advanced Workflows

Using Specialized Subagents

Claude Code can delegate tasks to specialized subagents for better results.

View Available Subagents

> /agents

This shows all available subagents and lets you create new ones.

Automatic Delegation

Claude automatically delegates appropriate tasks:

> review my recent code changes for security issues

> run all tests and fix any failures

Explicit Subagent Requests

> use the code-reviewer subagent to check the auth module

> have the debugger subagent investigate why users can't log in

Create Custom Subagents

> /agents
# Then select "Create New subagent" and define:
# - Subagent type (e.g., api-designer, performance-optimizer)
# - When to use it
# - Which tools it can access
# - Its specialized system prompt

Pro Tips:

• Create project-specific subagents in .claude/agents/
• Use descriptive description fields for automatic delegation
• Limit tool access to what each subagent needs
• Check subagents documentation for detailed examples

Resume Previous Conversations

Continue where you left off in later sessions.

Continue Most Recent Conversation

claude --continue

This immediately resumes your most recent conversation.

Continue in Non-Interactive Mode

claude --continue --print "Continue with my task"

Perfect for scripts and automation.

Show Conversation Picker

claude --resume

Displays interactive selector with:

• Session summary or initial prompt
• Metadata: time elapsed, message count, git branch
• Use arrow keys to navigate, Enter to select

How It Works:

1. Storage: All conversations saved locally with full history
2. Deserialization: Message history restored to maintain context
3. Tool State: Previous tool usage and results preserved
4. Context: Conversation resumes with all context intact

Parallel Sessions with Git Worktrees

Work on multiple tasks simultaneously with complete isolation.

Create Worktrees

# Create worktree with new branch
git worktree add ../project-feature-a -b feature-a

# Create worktree with existing branch
git worktree add ../project-bugfix bugfix-123

Run Claude in Each Worktree

cd ../project-feature-a
claude

# In another terminal
cd ../project-bugfix
claude

Manage Worktrees

# List all worktrees
git worktree list

# Remove worktree when done
git worktree remove ../project-feature-a

Benefits:

• Each worktree has independent file state
• No interference between Claude instances
• Share same Git history
• Perfect for parallel development

Using Claude as a Unix-Style Utility

Integrate Claude into your existing workflows.

Add to Build Scripts

// package.json
{
  "scripts": {
    "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
  }
}

Pipe Data Through Claude

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Control Output Format

# Text format (default)
cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

# JSON format
cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

# Streaming JSON format
cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

Creating Custom Slash Commands

Automate your common tasks with custom slash commands.

Create Project-Specific Commands

mkdir -p .claude/commands

echo "Analyze the performance of this code and suggest three specific optimizations:" > .claude/commands/optimize.md

Use it in Claude:

> /optimize

Add Command Arguments

echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1. Understand the issue 2. Locate the code 3. Implement solution 4. Add tests 5. Prepare PR description' > .claude/commands/fix-issue.md

Use with arguments:

> /fix-issue 123

Create Personal Commands

mkdir -p ~/.claude/commands

echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security-review.md

Personal commands show "(user)" in description and work across all projects.

Best Practices for Effective Use

1. Be Specific in Your Requests

Instead of:

> fix this code

Use:

> refactor the authentication function to use OAuth2 while maintaining backward compatibility

2. Provide Context

Include relevant information:

• What you're trying to achieve
• What you've already tried
• Any constraints or requirements
• Expected vs. actual behavior

3. Use Iterative Approach

Start broad, then refine:

> overview of our codebase
> focus on the API layer
> explain how rate limiting is implemented
> suggest improvements to the rate limiter

4. Leverage Different Modes

• Normal: Exploration and small changes
• Plan: Complex planning and analysis
• Auto-Accept: Trusted, automated changes

5. Combine with Other Tools

# Run tests, then get help with failures
npm test 2>&1 | claude -p 'help me fix these test failures'

# Check git diff, then refactor
git diff | claude -p 'suggest refactoring for these changes'

Troubleshooting Common Issues

Claude Doesn't Make Changes

Solution: Switch to Auto-Accept Mode with Shift+Tab

Too Much Context

Solution: Use Plan Mode to explore before making changes

Slow Responses

Solutions:

• Be more specific in requests
• Reference files directly with @
• Use headless mode for simple queries

Permission Errors

Solution: Check that you're in the correct directory with proper file permissions

Conclusion

Claude Code is a powerful tool that can transform your development workflow. Start with the basics—exploring codebases and fixing bugs—then gradually adopt advanced features like Plan Mode, subagents, and custom commands.

Next Steps:

1. Install Claude Code and try the workflows in this guide
2. Experiment with Plan Mode for safe exploration
3. Create custom slash commands for your common tasks
4. Explore specialized subagents for your domain
5. Integrate Claude into your existing scripts and tools

Key Takeaways:

• Use the right permission mode for your task
• Be specific and provide context
• Iterate and refine your requests
• Leverage Plan Mode for complex operations
• Combine Claude with your existing workflow

Happy coding with Claude Code! For more advanced features and examples, explore the official documentation and experiment with different workflows.