Claude Code Workflow Guide: 4 Proven Patterns for Daily AI Coding in 2026

# One-shot mode — fastest path to a fix
claude -p "Fix the type error in src/api/users.ts line 42 — the return type should be Promise<User[]> not Promise<User>"

# Review the changes Claude made
git diff

# One-shot with multi-step
claude -p "1. Add input validation to the POST /users endpoint using Zod. 2. Add a unit test for empty name input. 3. Run npm test to verify."

## Session Brief: Payment Webhook Handler

**Goal**: Implement Stripe webhook handler for subscription events
**Files involved**: src/api/webhooks/stripe.ts (NEW), src/services/billing.ts (MODIFY), src/types/stripe.ts (NEW)
**Constraints**:
- Must verify Stripe signature before processing
- Handle 3 events: checkout.session.completed, customer.subscription.deleted, invoice.payment_failed
- Return 200 within 5 seconds (async processing for heavy work)
- Add integration test with Stripe test mode
**Out of scope**: Email notifications, admin dashboard updates

# 1. Start with the session brief loaded
claude

# 2. Load the brief as context
"Read @session-brief.md and plan the implementation order"

# 3. Work through task list step by step
"Start with the Stripe signature verification — implement the middleware first, then I'll review before we move to event handlers"

You: "Implement the Stripe signature verification middleware"
Claude Code: [writes ~50 lines]
You: "Looks good. Now add a test for invalid signatures."
Claude Code: [writes test]
You: "Test passes. Now implement the checkout.session.completed handler."

# Ask Claude Code to document the current architecture
claude -p "Analyze the codebase and output a structured summary: directory structure, key modules, data flow, and pain points. Save to ARCHITECTURE.md"

## Architecture Decisions

### AD-001: Database Migration Strategy
**Context**: Migrating from raw SQL to Prisma ORM
**Decision**: Incremental migration — one module at a time, dual-write during transition
**Rationale**: Avoids downtime, allows rollback per module
**Date**: 2026-07-04

"First, explain the current data flow from the API route to the database for the user registration path. Do NOT make any changes yet."

## Claude Code explains
"Now, propose a refactored version that separates validation, business logic, and persistence into three layers. Show the file structure and key interfaces."

## Claude Code proposes
"I like the separation. Start with extracting the validation layer. Implement the signup validator in src/validators/auth.ts."

name: Claude Code PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: AI Code Review
        env:
          ANTHROPIC_API_KEY: ***
        run: |
          git diff origin/main...HEAD > /tmp/pr.diff
          claude -p "Review this PR diff. Focus on: (1) security vulnerabilities, (2) logic errors, (3) missing edge cases, (4) performance issues. Output a structured review with severity levels and line references." \
            --input-file /tmp/pr.diff \
            --output-format stream-json \
            --permission-mode bypassPermissions \
            --max-turns 15 > /tmp/review.json

import json, sys

review = []
with open('/tmp/review.json') as f:
    for line in f:
        msg = json.loads(line)
        if msg.get('type') == 'assistant':
            for block in msg.get('message', {}).get('content', []):
                if block.get('type') == 'text':
                    review.append(block['text'])

print(''.join(review))

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:diff)",
      "Bash(git:status)",
      "Bash(git:log)",
      "Bash(ls:*)",
      "Bash(python:*)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Bash(git:push)",
      "Bash(git:commit)",
      "Bash(docker:*)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(npx:*)"
    ]
  }
}

# CLAUDE.md

## Stack
- Next.js 14 (App Router), TypeScript strict, Tailwind CSS v4
- Prisma ORM + PostgreSQL, NextAuth.js v5
- Vitest for unit tests, Playwright for E2E

## Commands
- `npm run dev` — Start dev server (port 3000)
- `npm test` — Run unit tests
- `npm run test:e2e` — Run Playwright tests (requires dev server running)
- `npm run lint` — ESLint + Prettier
- `npx prisma generate` — Regenerate Prisma client after schema changes
- `npx prisma migrate dev` — Apply database migrations

## Conventions
- Server Components by default; `'use client'` only when needed
- API routes under `src/app/api/`, use Route Handlers
- Zod schemas in `src/lib/validators/`
- Database queries in `src/lib/db/` (never inline Prisma calls in components)
- All API responses use `ApiResponse<T>` wrapper from `src/lib/api-response.ts`

## Constraints
- No `any` types — use `unknown` and narrow
- All form inputs must be validated with Zod on both client and server
- Database queries must include `select` to avoid over-fetching
- Tailwind classes only — no inline styles or CSS modules

# CLAUDE.md

## Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0 (async)
- PostgreSQL, Redis (aioredis)
- Pytest + pytest-asyncio for testing
- Docker Compose for local dev

## Commands
- `docker compose up -d` — Start PostgreSQL + Redis
- `uvicorn src.main:app --reload` — Dev server (port 8000)
- `pytest -n auto` — Run all tests in parallel
- `black . && ruff check .` — Format and lint
- `alembic upgrade head` — Apply migrations

## Conventions
- Repository pattern: all DB access through `src/repositories/`
- Pydantic v2 models in `src/schemas/`
- Dependency injection via FastAPI `Depends()`
- All async handlers must have timeout wrappers

## Constraints
- Type hints required on all function signatures
- All external API calls must have retry logic (tenacity)
- Database sessions must use `async with` context managers