Real-World Workflows

Workflow Overview (Visual)

This diagram shows the seven core workflows and when to use each one. Every workflow follows a similar rhythm: understand first, act second, verify last.

Workflow 1: Explore → Plan → Code → Verify

This is the default workflow for building new features. It is the most commonly used pattern and the one you should reach for first when you are unsure which workflow fits.

Step 1: Explore

Start by asking Claude to understand the relevant parts of your codebase. Do not tell it what to build yet. Let it read and learn.

# Start in plan mode to prevent premature coding
claude --plan

# Then ask Claude to explore
> Read the auth module in src/auth/ and explain how login currently works.
> What middleware runs before protected routes?

Step 2: Plan

Once Claude understands the codebase, ask it to create a plan. Review the plan before any code is written. This is your checkpoint.

> Now plan how to add OAuth2 support. List every file you'd change and why.
> Don't write code yet — just the plan.

Step 3: Code

After you approve the plan, let Claude implement it. Be specific about which part to start with.

> Good plan. Start with step 1: create the OAuth2 provider config file.

Step 4: Verify

After implementation, have Claude verify its own work. This catches mistakes before you commit.

> Run the existing auth tests. Do they still pass?
> Write a new test for the OAuth2 login flow.

Workflow 2: Test-Driven Development

Write the test first, then let Claude make it pass. This is the fastest way to get correct, well-tested code. Claude excels at implementing code to satisfy a spec.

The TDD Loop

# Step 1: You write the test (or ask Claude to write it from a spec)
> Write a test for a function that validates email addresses.
> It should accept "[email protected]" and reject "not-an-email".

# Step 2: Run the test — it should fail (red)
> Run the test. It should fail since we haven't implemented the function yet.

# Step 3: Let Claude implement until green
> Now implement validateEmail() to make the test pass.

# Step 4: Refactor if needed
> Clean up the implementation. Keep the tests passing.

The beauty of TDD with Claude is that the test acts as an unambiguous specification. Claude cannot misinterpret what you want when a failing test tells it exactly what "correct" means.

Workflow 3: PR Review

Use Claude to review pull requests before merging. It catches bugs, suggests improvements, and checks for consistency with the rest of the codebase.

One-shot review

# Pipe the diff directly to Claude
gh pr diff 123 | claude -p "Review this PR for bugs, security issues,
  and style problems. Be specific about line numbers."

Interactive review

# Inside a Claude session
> Review the changes in this PR branch compared to main.
> Focus on: security issues, error handling, test coverage gaps.

# Follow up on specific findings
> Explain the race condition you found in more detail.
> How would you fix it?

Workflow 4: Debugging

When you hit a bug, Claude can read logs, trace execution paths, and propose targeted fixes. The key is giving Claude the right context upfront.

The Debugging Flow

# Step 1: Describe the bug with evidence
> I'm getting this error when I submit the login form:
> "TypeError: Cannot read property 'token' of undefined"
> at src/auth/login.ts:42

# Step 2: Let Claude investigate
> Read src/auth/login.ts and trace where the token should come from.
> Check the API response handling.

# Step 3: Apply the fix
> Fix the null check and add proper error handling for missing token.

# Step 4: Verify
> Write a test that reproduces this bug and confirm the fix resolves it.

Workflow 5: Codebase Exploration

When you join a new project or need to understand unfamiliar code, Claude can read, trace, and explain entire subsystems for you.

# Broad exploration
> How is this project structured? What are the main modules?
> How does a request flow from the API endpoint to the database?

# Targeted deep-dive
> Explain the caching layer in src/cache/. When does it invalidate?
> What happens if Redis is down — is there a fallback?

# Architecture questions
> Draw the dependency graph between these modules.
> Which parts of the codebase would I need to change to add a new API endpoint?

This workflow turns Claude into a senior engineer who has read the entire codebase. The answers are grounded in actual code, not generic advice.

Workflow 6: Multi-Agent Orchestration

For large tasks, you can launch multiple Claude agents working in parallel. Each agent handles an independent piece of work, and you merge the results.

Setting up parallel agents

# Create worktrees for each agent
git worktree add ../feature-auth feature-auth
git worktree add ../feature-dashboard feature-dashboard

# Launch agents in separate terminals
cd ../feature-auth && claude "Implement OAuth2 login flow"
cd ../feature-dashboard && claude "Build the analytics dashboard"

Headless mode for background tasks

# Launch a background agent using the SDK
claude -p "Refactor the logging module to use structured logs" \
  --output-format stream-json

Multi-agent works best when the tasks are truly independent. If agent B depends on agent A's output, run them sequentially instead.

Workflow 7: Refactoring

Refactoring with Claude follows a disciplined cycle: identify the scope, plan the changes, execute across files, and verify nothing broke.

The Refactoring Cycle

# Step 1: Identify scope
> Which files use the old Logger class? List all imports and usages.

# Step 2: Plan changes
> Plan the migration from Logger to StructuredLogger.
> Show me every file that needs to change and what the change looks like.

# Step 3: Execute
> Start with src/utils/logger.ts — update the class definition first.
> Then update all import sites one module at a time.

# Step 4: Verify after each batch
> Run the full test suite. Are there any failures?
> Check for any remaining references to the old Logger class.

The key is to refactor in small, verifiable steps rather than changing everything at once. Claude can track which files are done and which remain.

Anti-patterns: What NOT to Do

These patterns lead to poor results. Recognizing them will save you time and frustration.