Workflows Intermediate

This lesson covers the most common real-world workflows developers use with Claude Code. Each workflow includes step-by-step instructions and example prompts you can adapt to your own projects.

1. Bug Fixing Workflow

Bug fixing is one of Claude Code's strongest use cases. It can analyze error messages, trace through code paths, identify root causes, and implement fixes.

1. Describe the bug clearly
   Claude Code Session Copy

   Claude > There's a bug: when a user submits the contact form with
            an empty phone number, the app crashes with "Cannot read
            property 'trim' of undefined". The form is in
            src/components/ContactForm.tsx

2. Let Claude investigate

   Claude will read the file, trace the error, and identify the root cause. It may read related files (form validation, API handlers) to understand the full picture.

3. Review the proposed fix

   Claude will suggest a fix — typically adding a null check, default value, or optional chaining. Review the change to ensure it is correct.

4. Verify the fix
   Claude Code Session Copy

   Claude > Now run the tests to make sure the fix doesn't break anything

2. Feature Development Workflow

Claude Code can help build entire features from scratch, from planning the implementation to writing the code and tests.

1. Describe the feature requirements
   Claude Code Session Copy

   Claude > I need to add a "dark mode" toggle to the app. Requirements:
            - A toggle button in the header (use the existing Header component)
            - Save the preference in localStorage
            - Apply a "dark" class to the document body
            - The toggle should persist across page reloads
            - Follow the existing design patterns in the project

2. Let Claude plan and implement

   Claude will examine your existing code, understand the patterns, and implement the feature step by step — editing the header component, adding CSS, creating a hook for theme persistence, etc.

3. Iterate on the implementation
   Claude Code Session Copy

   Claude > Looks good, but can you also add a smooth CSS transition
            when toggling between light and dark modes?

4. Add tests
   Claude Code Session Copy

   Claude > Write tests for the dark mode feature. Test the toggle
            behavior, localStorage persistence, and CSS class application.

3. Code Review Workflow

Claude Code can review code changes, identify potential issues, and suggest improvements. Use the /review slash command or describe what you want reviewed.

Reviewing Your Own Changes

# Review current unstaged changes
Claude > Review my current git diff and point out any issues,
         potential bugs, or improvements

# Or use the slash command
Claude > /review

Reviewing a Pull Request

# Review a specific PR by number
Claude > Review PR #42 and give me a summary of the changes,
         any concerns, and whether it's ready to merge

# Review a diff between branches
Claude > Compare the feature/auth branch against main and review
         the changes

Claude Code looks for:

• Logic errors and edge cases
• Security vulnerabilities
• Performance issues
• Missing error handling
• Code style inconsistencies
• Missing tests

4. Test Writing Workflow

Claude Code can generate comprehensive test suites by analyzing your existing code and test patterns.

# Generate tests for a specific file
Claude > Write unit tests for src/services/UserService.ts.
         Cover all public methods, edge cases, and error scenarios.
         Use the same testing framework and patterns as existing tests.

# Generate tests for a specific function
Claude > Write tests for the validateEmail function. Include
         tests for valid emails, invalid formats, edge cases like
         plus signs and dots, and empty/null inputs.

# Generate integration tests
Claude > Write integration tests for the POST /api/users endpoint.
         Test successful creation, validation errors, duplicate email
         handling, and database errors.

5. Git Commit Workflow

The /commit slash command is one of Claude Code's most-loved features. It analyzes your staged and unstaged changes and creates a well-formatted commit message.

1. Make your changes (either manually or with Claude Code's help)
2. Use /commit to create the commit
   Claude Code Session Copy

   Claude > /commit

3. Claude analyzes the diff and generates a commit message that accurately describes the changes
4. Review and confirm the commit message before it is applied

Claude analyzed 3 changed files:
  src/components/LoginForm.tsx  (+12, -3)
  src/utils/validation.ts      (+25, -0)
  src/tests/validation.test.ts (+45, -0)

Proposed commit message:
fix: add email validation for addresses with special characters

Add proper email validation that handles plus signs, dots, and other
special characters in the local part of email addresses. Add validation
utility function and corresponding unit tests.

Fixes #127

Accept this commit? [y/n/e]

6. PR Creation Workflow

Claude Code can create pull requests with AI-generated titles and descriptions using the /pr slash command or the gh CLI.

# Create a PR with auto-generated description
Claude > /pr

# Or be more specific
Claude > Create a pull request for this branch. Summarize all the
         changes, include a testing checklist, and mention that this
         fixes issue #42.

Claude Code will:

1. Analyze all commits on the current branch (compared to main/master)
2. Generate a descriptive title and body
3. Include a summary of changes, testing instructions, and any relevant context
4. Create the PR using the GitHub CLI (gh)

7. Refactoring Large Codebases

For large-scale refactoring across many files, break the work into smaller, manageable pieces:

1. Plan the refactoring
   Claude Code Session Copy

   Claude > I want to migrate all class components to functional components
            with hooks. List all files that have class components and suggest
            an order to refactor them (least dependencies first).

2. Refactor in batches
   Claude Code Session Copy

   Claude > Convert src/components/Button.tsx from a class component
            to a functional component with hooks. Keep the same props API.
   
   # After reviewing and accepting...
   Claude > Now convert src/components/Modal.tsx the same way

3. Test after each batch
   Claude Code Session Copy

   Claude > Run the tests for the components we just refactored

4. Commit incrementally
   Claude Code Session Copy

   Claude > /commit

8. Working with CLAUDE.md Files

CLAUDE.md is a special file that provides persistent context to Claude Code. When Claude Code starts a session, it automatically reads CLAUDE.md files from your project root, parent directories, and home directory.

What to Put in CLAUDE.md

# Project: My Web App

## Architecture
- Next.js 14 with App Router
- TypeScript strict mode
- Prisma ORM with PostgreSQL
- Tailwind CSS for styling
- Jest + React Testing Library for tests

## Coding Conventions
- Use functional components with hooks (no class components)
- Use named exports (not default exports)
- File naming: kebab-case for files, PascalCase for components
- All API routes should include input validation with Zod
- Error messages should be user-friendly (no stack traces in responses)

## Important Files
- src/lib/db.ts - Database connection singleton
- src/lib/auth.ts - Authentication utilities
- src/middleware.ts - Next.js middleware for auth checks

## Common Commands
- `npm run dev` - Start dev server
- `npm test` - Run tests
- `npm run db:migrate` - Run database migrations
- `npm run lint` - Run ESLint