Claude Code Practical Workflow Guide

Are you using Claude Code simply as a tool to ask questions when you get stuck? In reality, Claude Code shows its true power when integrated into your entire work process.

This article introduces practical workflows that work for everyone from developers to non-engineers. Each workflow is presented in a consistent format with "when to use it," "specific steps," and "copy-pasteable command examples."

Workflow Philosophy

There are two keys to mastering Claude Code.

"Integration into the whole flow" over one-off questions

Most people start with one-off questions like "fix this bug" or "explain this code." This is already useful, but Claude Code's real value emerges when integrated into the overall flow of your work.

Consider a code review workflow as an example.

One-off approach (less efficient):

# Manually specifying files one at a time
> Please review src/components/Button.tsx
> Now please review src/hooks/useAuth.ts as well

Integrated into the whole flow (more efficient):

# Review the entire PR diff at once
git diff main | claude -p "Review these changes and summarize any issues in a list"

Setting context with CLAUDE.md

Claude Code starts without knowing your project context. Having to explain "this project is written in TypeScript, uses Vitest for tests..." every time is inefficient.

Placing a CLAUDE.md file at your project root makes Claude Code automatically load it on every startup. Write it once and you never have to explain it again in future conversations.

# Create CLAUDE.md at your project root
touch CLAUDE.md

What to include in CLAUDE.md:

# Project Overview
This project is a web application for [purpose].

## Tech Stack
- Language: TypeScript
- Framework: Next.js 15 (App Router)
- Testing: Vitest + Testing Library
- Package Manager: pnpm

## Coding Conventions
- Components are written as functions
- Types are defined explicitly (avoid `any`)
- Test files go in the __tests__ directory

## Common Commands
- `pnpm dev` — development server
- `pnpm test` — run tests
- `pnpm build` — production build

Tips: Think of CLAUDE.md as something you grow over time. While you work, whenever you notice you're giving the same explanation repeatedly, add it to CLAUDE.md. After a few weeks it becomes a remarkably smart instruction document.

When to use interactive mode vs. one-shot mode

Mode	Command	Best for
Interactive mode	`claude`	Multi-step tasks where you want to review results as you go
One-shot mode	`claude -p "..."`	Tasks that complete in a single pass, scripting
Pipe mode	`command \| claude -p "..."`	Parsing or transforming output from another command

Code Review

Difficulty: Beginner

When to use it

When you want to self-review before submitting a PR
When you can't reach a reviewer but want to check quality early
When you want a comprehensive list of issues in your code

Steps

Pattern 1: One-shot review with git diff (recommended)

# Review all changes against the main branch
git diff main | claude -p "Review these code changes. Point out potential bugs, performance concerns, and readability issues in a list"

# Review only staged changes
git diff --staged | claude -p "Review these code changes and list any problems"

Pattern 2: Review a specific file

# In-depth review of a specific file in interactive mode
claude
> @src/lib/auth.ts Please review this file. In particular, check for any security issues.

Pattern 3: Generate review comments based on commit history

# Include recent commit messages in the review
git log --oneline -10 | claude -p "Based on these commits, what points should a reviewer pay attention to?"

Tips

Common stumbling block: If git diff main produces a massive diff, it helps to narrow the scope. Use git diff main -- src/components/ to limit to a directory, or review important files one by one in interactive mode.

Generate a commit message with one shot:

# Generate a commit message from the staged diff
git diff --staged | claude -p "Summarize these changes as a Conventional Commits format commit message (single line)"

Bug Fixing

Difficulty: Beginner

When to use it

When you don't understand what an error message means
When you don't know how to read a stack trace
When you've identified the cause but aren't sure how to fix it

Steps

Pattern 1: Paste the error log directly (simplest)

# Pass error log through a pipe
cat error.log | claude -p "Identify the cause of this error and explain how to fix it"

# Pass the command output and error together
pnpm build 2>&1 | claude -p "Analyze this build error and tell me which file and line to fix"

Pattern 2: Debug interactively

claude
> I'm getting this error: TypeError: Cannot read properties of undefined (reading 'map')
> Here is the stack trace: [paste the stack trace]
> @src/components/UserList.tsx Please look at this file and identify the cause

Pattern 3: Reproduce and fix the bug using tests

claude
> Running pnpm test produced these failing tests
> [paste the test failure log]
> Please fix the code so the tests pass

Tips

Common stumbling block: Saying "I'm getting an error" alone gives Claude too little information. Providing the full error message along with what action triggered it dramatically improves accuracy. The ideal format is: "I get the following error when I click the login button."

An example prompt with explicit reproduction steps:

> The error occurs in the following situation:
> 1. Navigate to http://localhost:3000/dashboard
> 2. Enter username and password and click the login button
> 3. The following error occurs:
>    [paste the error message]
>
> @src/app/api/auth/route.ts and @src/lib/session.ts — please look at these files, identify the cause, and apply a fix

Refactoring

Difficulty: Intermediate

When to use it

When your code is getting complex and needs to be cleaned up
When a function or component has grown too large
When you want to gradually pay down technical debt
When you want to safely carry out a large-scale refactor

Steps

Pattern 1: Clean up a single file (small scale)

claude
> @src/utils/data-transform.ts Please refactor this file.
> Goals:
> - Split so each function does exactly one thing
> - Make variable names clearer
> - Consolidate duplicate logic
> Please verify that the tests still pass as you go.

Pattern 2: Strategy for splitting a large-scale refactor

Trying to do a large-scale refactor all at once leads to many unexpected problems. Proceeding incrementally is essential.

First, have Claude create a refactoring plan:

claude
> I want to clean up the code in the entire src/services/ directory.
> Start by analyzing the current problems and create a plan for the order in which to refactor.
> Each step should be small enough to be independently merged.

Once the plan is set, proceed one step at a time:

claude
> Please implement Step 1 from the plan we just created (splitting UserService).
> After making changes, run the tests and confirm all existing tests still pass.

Pattern 3: Performance improvement

# When a specific operation is slow
cat src/lib/heavy-computation.ts | claude -p "Identify the performance bottlenecks in this code and suggest improvements"

Tips

Common stumbling block: During refactoring, expanding the scope with "I also want to fix this" and "that also looks off" leads to chaos. Explicitly stating "the scope for this session is this file only" is important. Claude can make the same mistake, so instruct it: "Only modify this file. Do not touch any other files."

Verification flow before and after refactoring:

# 1. Check tests before refactoring
pnpm test

# 2. Run the refactoring
claude
> @src/components/Form.tsx Please refactor this file.

# 3. Re-run tests to verify after refactoring
pnpm test

Test Generation

Difficulty: Intermediate

When to use it

When you have code that's been waiting for tests
When you want to add tests after implementing a new feature
When you want to increase test coverage
When you're not sure what tests to write

Steps

Pattern 1: Generate unit tests for existing functions

claude
> @src/lib/format.ts Generate unit tests for all functions in this file.
> - Test framework: Vitest
> - Save the test file to: src/lib/__tests__/format.test.ts
> - Include edge cases (empty strings, null, undefined, boundary values)

Pattern 2: Generate tests for a React component

claude
> @src/components/SearchInput.tsx Generate tests for this component.
> - Use Testing Library
> - Include tests for user interactions (typing, clearing)
> - Also test accessibility (aria attributes, etc.)

Pattern 3: Generate tests for an API endpoint

claude
> @src/app/api/users/route.ts Generate tests for this API endpoint.
> - Include happy-path (200 response) and error cases (400, 401, 500)
> - Properly mock any database calls that need mocking

Pattern 4: Check coverage and fill in the gaps

# Generate a coverage report
pnpm test --coverage 2>&1 | claude -p "Looking at this coverage report, identify the important areas with insufficient tests and tell me what test cases to add"

Tips

Common stumbling block: Using generated tests as-is can result in "tests for the sake of tests" — tests that don't actually verify the real behavior. Always review the generated tests and make sure you understand "what is this test checking?" before using them. Asking Claude "explain the most complex test case you generated" helps deepen your understanding.

Verification steps after test generation:

# Run the generated tests to confirm they pass
pnpm test src/lib/__tests__/format.test.ts

# Ask for an explanation of the tests
claude
> Please explain the most complex test case among the ones you just generated.

Documentation Generation

Difficulty: Beginner

When to use it

When code lacks explanations and is hard for team members to understand
When you need to write a spec doc to publish an API
When your README is out of date
When you want to add JSDoc comments in bulk

Steps

Pattern 1: Auto-generate a README

claude -p "Generate a README.md for this project. Include: overview, installation, usage, configuration options, and license."

Or to update an existing README:

claude
> @README.md Read this file and assess its current state.
> Then check the actual project structure (directory layout, package.json) and identify any outdated content.
> Update it to reflect the current state.

Pattern 2: Add JSDoc comments to functions and classes

claude
> @src/lib/api-client.ts Add JSDoc comments to all functions and classes in this file.
> Include:
> - Parameter types and descriptions
> - Return type and description
> - Usage examples (@example)

Pattern 3: Generate API documentation

claude
> Look through the src/app/api/ directory and compile a list of all API endpoints with their specs in Markdown format.
> For each endpoint include: method, path, request body, response format, and whether authentication is required.

Pattern 4: Generate a CHANGELOG

# Generate a changelog from git log
git log --oneline v1.0.0..HEAD | claude -p "Generate a CHANGELOG from this list of commits. Categorize as Bug Fixes, New Features, and Breaking Changes in Markdown format."

Tips

Common stumbling block: Documentation always needs a review after generation. Claude infers the intent of code when writing documentation, so descriptions that differ from actual behavior can slip in. Pay particular attention to "side effects" and "error handling" descriptions.

For quick one-shot documentation generation:

cat src/utils/validation.ts | claude -p "Write documentation for this code embedded directly in the code. Output the complete code with JSDoc comments added."

Starting a New Project

Difficulty: Intermediate

When to use it

When starting a new project from scratch
When adding a new feature module to an existing project
When you want to speed up boilerplate setup

Steps

Phase 1: Design the CLAUDE.md

The very first thing to do in a new project is create the CLAUDE.md. Giving Claude the full picture of the project dramatically improves the quality of all subsequent work.

mkdir my-new-project && cd my-new-project
claude
> I'm building a new web application. Please create a CLAUDE.md with the following requirements:
> - Overview: An internal employee time-tracking system
> - Tech stack: Next.js 15, TypeScript, Prisma, PostgreSQL, Tailwind CSS
> - Development conventions: Conventional Commits, tests with Vitest
> - Deployment target: Vercel

Phase 2: Scaffolding

claude
> Based on the requirements in the CLAUDE.md we just created, set up the project scaffold.
> Please configure the following:
> 1. Initialize the Next.js project
> 2. TypeScript and ESLint configuration
> 3. Tailwind CSS setup
> 4. Prisma setup and initial schema
> 5. Vitest setup
> 6. Create the basic directory structure

Phase 3: Implementing features

claude
> Implement user authentication.
> - Sign-up and login with email/password
> - Session management using JWT
> - Redirect based on login state
> Please implement it using the existing tech stack (Next.js App Router, Prisma).

Tips

Common stumbling block: Trying to implement all features at once causes Claude to run out of context (the amount of information it can hold). Split features into small units and implement one at a time. Adopt a pattern like "once user auth is done, start a new conversation session to add the product management feature."

Managing context in a large project:

# When the session gets long, compress the context
> /compact

# When resuming work in a new session, start by understanding the current state
claude
> @CLAUDE.md Read this file and understand the structure of this project.
> Then check the src/ directory structure and tell me the current state of implementation.

Workflows for Non-Engineers

Even without programming knowledge, there are many everyday tasks you can automate with Claude Code. Here are three particularly practical workflows.

File Organization and Bulk Renaming

Difficulty: Beginner

When to use it: When your folders are a mess; when you want to organize photos or documents with a consistent naming rule.

claude
> Rename all jpg files in the "2025 Photos" folder on my Desktop
> to the format "YYYYMMDD_NNN.jpg" (e.g., 20250615_001.jpg)
> Use the file's creation date as the date.
> Show me a list of what changes will be made before executing.

claude
> Please organize the files in the "Project Materials" folder:
> - PDF files → move to "PDF" subfolder
> - Excel/CSV files → move to "Data" subfolder
> - Word files → move to "Documents" subfolder
> - Image files (jpg/png) → move to "Images" subfolder

Data Transformation and Summary Reports

Difficulty: Beginner

When to use it: When you need to aggregate CSV data, merge data from multiple files, or do data processing that's difficult in Excel.

# Aggregate a CSV file
claude
> Open "SalesData2025.csv" on my Desktop and perform the following aggregations:
> 1. Monthly sales totals by product category
> 2. Ranking of the top 10 products by sales
> 3. Month-over-month change (percentage change vs. previous month)
> Save the results as "SalesSummaryReport.csv"

# Merge multiple CSV files into one
claude
> Read all the CSV files in the "Monthly Data" folder
> and combine them into a single file.
> Add a "Month" column to each row so it's clear which month the data is from.

Common stumbling block: When you tell Claude Code to work with "a file on my Desktop," Claude Code looks for files relative to its current directory. Make sure the directory you launched Claude Code from matches where the target file is. The safest approach is to cd ~/Desktop before launching Claude Code.

Text Conversion, Translation, and Summarization

Difficulty: Beginner

When to use it: When you want to batch-process many text files; when you want to read materials written in another language.

# Summarize all text files in a folder
claude
> Read all the .txt files in the "Meeting Notes" folder
> and extract the 3 key points from each,
> then compile them into "MeetingSummary.md".
> Sort them by filename and date.

# Translate a PDF to English
claude
> Translate the "report_ja.pdf" on my Desktop into English.
> Save the translation as "report_en.txt".
> Use standard business English for technical terms.

# Convert a text file to a specific format
claude
> Convert "customer-list.txt" (names and email addresses separated by tabs)
> to "customer-list.csv" (comma-separated, with a header row).

Automating Recurring Tasks with One-Shot Mode

Routine tasks can be automated by combining one-shot mode (-p) with shell scripts:

#!/bin/bash
# Example daily report generation script
# (Run this with cron or similar each morning)

claude -p "Aggregate yesterday's sales data ($(date -d yesterday +%Y%m%d)_sales.csv) and save a daily report to daily_report_$(date +%Y%m%d).txt"

Tips: When wrapping the prompt for claude -p in single quotes, special characters like $ won't be expanded. Use double quotes when you want variable substitution.

Next Steps

Once you've tried these workflows, explore features that can make you even more efficient.

If you want to use Claude Code inside your editor:

IDE Integration — How to connect Claude Code with VS Code or JetBrains. Use AI power without leaving your editor.

If you want to learn terminal basics from scratch:

Claude Code Guide for Non-Engineers — A clear explanation of terminal fundamentals for beginners.

If you haven't installed Claude Code yet:

Getting Started with Claude Code — From installation to running your first command.

If you want to check pricing and plans:

Claude Pricing Plan Comparison — Which plans include Claude Code and estimated usage.