Core Claude Code Workflows

# Simple task: collapsed loop (one prompt does it all)
> Fix the typo in the footer component. It says "Copyrigth" instead of "Copyright".

# Complex task: explicit plan-execute-review
> /plan
> I need to add user authentication to this Next.js app. We should use
  NextAuth.js with GitHub and Google providers. Plan the implementation
  including all files that need to change.

# Claude creates a detailed plan. You review it.
# Then you say:

> This plan looks good. Go ahead and implement it.

# Claude executes. You review each file change.

# Effective bug fix prompt
> The checkout page crashes when a user has an empty cart.
  Error: "TypeError: Cannot read properties of undefined (reading 'map')"
  Stack trace points to app/checkout/page.tsx line 42.
  The cart items come from the useCart() hook.
  Expected: show an empty cart message. Actual: white screen crash.
  Fix this bug and add a guard for empty/undefined cart state.

# Claude will:
# 1. Read app/checkout/page.tsx
# 2. Read the useCart hook
# 3. Identify the missing null check
# 4. Add proper empty state handling
# 5. May also check other pages for the same pattern

# Bad prompt (too prescriptive)
> Create a function called filterUsers that takes an array of User objects
  and a string query. Loop through the array with a for loop, check if
  the user.name includes the query using toLowerCase(), and push matching
  items to a results array. Return the results array.

# Good prompt (describes behavior, not implementation)
> Add search functionality to the Users page. Users should be able to
  type in a search box and see the user list filter in real-time by name
  or email. Follow the existing patterns in this codebase for form inputs
  and list filtering. Make sure it handles empty states and is debounced
  to avoid excessive re-renders.

# Great prompt (adds context and constraints)
> Add search functionality to the Users page (app/users/page.tsx).
  Requirements:
  - Real-time filtering by name or email as the user types
  - Debounced input (300ms) to avoid excessive re-renders
  - Show "No users found" empty state
  - Preserve existing URL params when searching
  - Follow the same pattern used in app/products/page.tsx which
    already has search implemented
  - Add tests for the search functionality

# Extract a shared component
> I notice that app/dashboard/page.tsx and app/analytics/page.tsx both
  have very similar chart card components with titles, descriptions, and
  chart containers. Extract a shared ChartCard component into
  app/components/ChartCard.tsx and refactor both pages to use it.

# Rename across codebase
> Rename the "subscription" concept to "membership" across the entire
  codebase. This includes file names, component names, variable names,
  database field references, and user-facing text. Show me the plan
  before executing.

# Migration pattern
> Migrate all class components in the app/legacy/ directory to functional
  components with hooks. Preserve all existing behavior and prop types.
  Convert class state to useState, lifecycle methods to useEffect,
  and class methods to regular functions.

# Review a PR
> /review-pr

# Or review specific files
> Review the changes I made today. Look for:
  - Potential bugs or edge cases
  - Security issues (SQL injection, XSS, etc.)
  - Performance problems
  - Deviations from our coding conventions
  - Missing error handling
  - Missing tests

# Review before committing
> Look at my staged changes (git diff --staged) and review them
  for any issues before I commit.

# Generate tests for a specific file
> Write comprehensive tests for app/lib/pricing.ts. Include:
  - Unit tests for each exported function
  - Edge cases: zero values, negative numbers, currency rounding
  - Test the discount calculation logic thoroughly
  - Use our existing test patterns (Vitest + testing conventions from
    other test files in this project)

# Generate tests and run them
> Write tests for the UserProfile component, then run them and fix
  any failures. I want passing tests when you are done.

# Test coverage improvement
> Check which files in app/lib/ have no test coverage. Write tests
  for the 3 most critical uncovered files. Focus on the business
  logic functions, not simple utility helpers.

# Generate API documentation
> Generate JSDoc comments for all exported functions in app/lib/api.ts.
  Include parameter descriptions, return types, and usage examples.

# Explain complex code
> Explain what the reconciliation algorithm in app/lib/reconciler.ts does.
  Walk me through it step by step. I need to understand this before
  making changes.

# Create architecture docs
> Create an ARCHITECTURE.md that documents:
  - High-level system architecture
  - Data flow between components
  - Key design decisions and rationale
  - Directory structure explanation
  Base it on the actual code, not assumptions.

# Ask Claude to break down and track a complex task
> I need to add internationalization (i18n) to this app. Break this into
  subtasks, track your progress, and implement each one:
  1. Install and configure next-intl
  2. Extract all hardcoded strings from components
  3. Create English and Spanish translation files
  4. Update the layout to support locale routing
  5. Add a language switcher component

# Claude will create internal todos and work through them systematically

# 1. Start session and orient (2 min)
> I need to add a notifications system. Users should see a bell icon
  in the header with unread count, and a dropdown showing recent
  notifications. We use Supabase for the backend.

# 2. Review the plan Claude creates (3 min)
# Claude proposes: DB table, API route, hook, components, real-time sub
# You review and adjust: "Skip real-time for now, just polling every 30s"

# 3. Let Claude implement (5 min)
# Claude creates 6-8 files, you approve each change

# 4. Review the diff (10 min)
> Show me a summary of all files you changed

# 5. Test it (5 min)
> Run the tests. If any fail, fix them.

# 6. Polish (5 min)
> The dropdown looks good but add an "empty state" when there are
  no notifications. Also add aria-labels for accessibility.

# Total: 30 minutes for a feature that would take 3-4 hours manually