Claude Code Workflow Guide

Claude Code is most powerful when you build deliberate workflow habits around it — not just asking ad-hoc questions, but structuring every feature, bug fix, and refactor as a repeatable loop. This guide covers the patterns that work best in practice: from daily routines to TDD, git branching, PR review, and CI/CD integration.

Starting a Claude Code Session

How you open a session determines how effective the whole session will be. Don't just run claude and start typing — prime it first.

1. Navigate to your project root: cd ~/projects/my-app. Claude reads CLAUDE.md, .git/, and the directory structure automatically.
2. Check git state before asking anything: git status and git log --oneline -5. Mention the current branch and your intent in your first message.
3. Give Claude the context it needs upfront: "I'm on branch feat/auth-v2. The goal today is to add OAuth2 login. CLAUDE.md has the DB schema. Don't touch the legacy /auth/v1 routes."
4. For any task touching more than 2-3 files, start with /plan to see Claude's proposed approach before any file is written.

Opening prompt template

I'm working on [branch name].
Goal for this session: [one sentence].
Constraints:
- Don't modify [protected files/directories]
- Tests are in [test directory], run with [test command]
- [Any other context from CLAUDE.md]

First task: [specific task]

Test-Driven Development (TDD) Workflow

TDD with Claude Code is one of the highest-leverage patterns. You write the spec (the test), Claude writes the implementation, and you never merge code that doesn't have a corresponding test.

Phase 1 — Write failing tests

Write failing tests for a function called parseInvoiceDate(str).
Requirements:
- Parses strings in ISO 8601, US (MM/DD/YYYY), and EU (DD.MM.YYYY) formats
- Returns a Date object
- Throws InvalidDateError for invalid inputs
- Edge cases: empty string, null, Feb 29 on non-leap years

Use Jest. Do NOT write the implementation yet.

Phase 2 — Implement to pass tests

Now implement parseInvoiceDate() in src/utils/dates.ts to pass all the tests you just wrote.
Minimum code to pass — no extra features.
Run the tests and iterate until all pass.

Phase 3 — Refactor without breaking

The tests are green. Now refactor parseInvoiceDate() for readability:
- Extract the format detection into a private detectFormat() helper
- Replace the nested if-else with a format lookup table
Tests must stay green throughout.

Git Workflow

Claude Code works best when you treat git as a first-class part of the workflow — not an afterthought at the end of the session.

Feature branch workflow

# Before starting any task
git checkout -b feat/my-feature

# After Claude builds, review the diff
git diff

# Ask Claude for a conventional commit message
Write a conventional commit message for these staged changes.
Use the format: type(scope): description
Types: feat, fix, refactor, test, docs, chore

Atomic commits

Commit frequently — after each logical unit completes, not at end of day. Ask Claude to identify commit boundaries:

We've made several changes. Group them into logical commits:
1. List each commit with: which files, what type (feat/fix/refactor), suggested message
2. Stage and commit each group in order

PR description generation

/pr
# or manually:
Write a PR description for this branch vs main.
Include: summary of changes, motivation, testing approach, and any breaking changes.
Format as markdown with sections.

Bug Fix Workflow

Effective bug fixing with Claude Code follows a strict sequence: reproduce → isolate → fix → verify → document.

Bug fix prompt template

# Step 1 — Reproduce
This error appears in production:
[paste error message and stack trace]

Write a minimal failing test in [test file] that reproduces this exact error.
Do NOT fix anything yet.

# Step 2 — Diagnose
Now identify the root cause. Which line(s) cause this and why?

# Step 3 — Fix
Fix the root cause. The test you wrote must now pass.
Run the full test suite and confirm there are no regressions.

# Step 4 — Commit
Write a fix commit message following conventional commits.

Refactoring Workflow

Refactoring with Claude Code requires discipline: never mix refactoring with feature additions, always have tests before you start, and work in small steps.

Safe refactoring loop

1. Characterize the current behavior. Ask Claude to describe what the code does and what its public API is. This becomes your baseline.
2. Add coverage if missing. Before refactoring, ask: "Are there tests that cover the public API of [module]? If not, write them first."
3. Plan the refactor. Use /plan Refactor [module] to [goal] — do NOT change the public API. Review the plan before approving.
4. Execute one step at a time. After each significant change, run tests. Stop and fix if tests go red — don't accumulate debt.
5. Verify public API unchanged. Ask Claude: "Compare the public API before and after — confirm nothing changed for callers."

Common refactoring prompts

# Extract a module
Move all the payment processing logic from orders.ts into a new payments/ module.
Public API must remain identical — callers import from the same path.
Tests must stay green throughout.

# Simplify complex function
The function processOrder() in src/orders.ts is 200 lines.
Break it into smaller functions where each does one thing.
Do NOT change behavior. Tests must stay green.

# Replace pattern
Replace all uses of the old callback pattern in src/api/ with async/await.
Update all call sites. Run tests after each file to catch regressions early.

# Dependency injection
Refactor DatabaseService in src/db/ to accept dependencies as constructor arguments
instead of importing them directly. Update all instantiation sites.
Add a type-safe mock for tests.

Code Review Workflow

Use Claude Code as a pre-PR reviewer to catch issues before human reviewers see them.

Self-review before pushing

Review the staged changes as a senior engineer would in a PR review.
Focus on:
1. Correctness — any logic errors, edge cases missed?
2. Security — any injection risks, auth gaps, secrets in code?
3. Performance — any N+1 queries, missing indexes, unnecessary loops?
4. Readability — any confusing names, missing error handling?
5. Tests — adequate coverage for the new code?

For each issue found: quote the line, describe the problem, suggest a fix.

Review a specific file or PR

/review
# or:
Review src/api/auth.ts for security issues.
Assume an attacker can control all query parameters and request bodies.
List each vulnerability with severity (critical / high / medium / low) and a fix.

CI/CD Integration

Claude Code can run headlessly in GitHub Actions for automated code review, test generation, and PR summarization. See the GitHub Actions guide for full YAML examples.

Common automated workflows

Workflow	Trigger	What Claude does
PR Review Bot	pull_request opened	Reviews diff, posts comments via gh CLI
Auto-fix Lint	push to any branch	Runs linter, asks Claude to fix violations, commits
Test Generation	New file added	Writes tests for new functions, opens a follow-up PR
Release Notes	Tag pushed	Summarizes commits since last tag into release notes
Dependency Audit	Weekly schedule	Reviews new vulnerabilities, opens fix PRs

Headless invocation pattern

# In GitHub Actions
- name: Claude Code review
  run: |
    claude --headless \
      --print "Review the diff in this PR and comment on any bugs, security issues, or readability problems. Output as GitHub markdown." \
      --allowedTools "Bash,Read,Grep,Glob" \
      > review.md
    gh pr comment $PR_NUMBER --body-file review.md
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    PR_NUMBER: ${{ github.event.number }}

Sample Daily Development Routine

Here's a concrete morning-to-commit routine that most teams find effective:

Workflow Anti-Patterns to Avoid

• Context dumping. Pasting 2,000 lines into a single message without structure. Instead, reference files by path and let Claude read them.
• One mega-session. Running all-day without committing. If Claude makes a wrong turn at hour 3, you lose hours of work. Commit every green state.
• No plan for big changes. Asking Claude to "refactor the entire auth system" without /plan. The first file it writes may invalidate the approach.
• Ignoring test failures. Telling Claude to "just skip that test for now." Disabled tests compound into untestable code.
• Over-permissive settings. Running with --dangerously-skip-permissions in your main working directory. Use it only in throwaway containers or fully sandboxed repos.
• Feature + refactor in one PR. Ask Claude to separate them: refactor first (no behavior change), then the feature. Reviewers can't see what changed if both happen together.

FAQ

Related Guides

• Plan Mode — review the full implementation proposal before any file is changed
• Best Practices — CLAUDE.md, permissions, TDD, context, and cost tips
• GitHub Actions & CI/CD — headless Claude Code for automated PR review and test generation
• Sub-Agents & Orchestration — parallel agents for complex multi-step workflows
• Prompt Library — 60+ ready-to-use prompts for every workflow pattern
• Troubleshooting — fix common Claude Code session problems
• All Claude Code Skills — full directory

More Claude Code Tools

• Claude Code Cost Calculator →Paste a session log, see exact $ cost.
• AI Diff Summarizer →Git diff → plain-English PR description.
• Prompt Improver →Paste a prompt, get a refined version back instantly.
• Claude API Cookbook →Long-tail guides for Claude API usage.