Development Workflows

End-to-end workflows using Claude Code's Plan Mode, checkpointing, and native git integration.

Feature Development

The recommended flow for building features with Claude Code.

Phase 1: Explore (Plan Mode)

Start in Plan Mode (Shift + Tab × 2) to understand the codebase without changing anything:

I need to add OAuth login with Google. Explore:
- current auth system in @src/auth/
- database schema in @prisma/schema.prisma
- existing middleware patterns

Propose an implementation plan with file changes.

Phase 2: Implement (Normal Mode)

Switch back to Normal mode and implement step by step. Claude will ask before writing files:

implement the OAuth plan from above.
start with the database migration, then the API routes,
then the frontend. write tests for each layer.
commit after each working step.

Phase 3: Review & Ship

review all changes since main. check for:
- missing error handling
- security issues in the OAuth flow
- test coverage gaps
then create a pr with a clear description.

Bug Fix Workflow

1. Diagnose in Plan Mode

Bug: checkout fails for guest users with TypeError

Explore @src/pages/Checkout.tsx and trace the call chain.
Don't change anything yet, just find the root cause.

2. Write Failing Test

Switch to Normal mode:

write a test that reproduces the guest checkout bug.
put it in @src/__tests__/checkout.test.ts.
do NOT implement the fix yet.

3. Fix & Verify

now fix the code to make the failing test pass.
run the full test suite after. if anything else breaks,
fix that too. commit when all tests pass.

4. Sweep for Similar Bugs

scan the codebase for the same pattern —
accessing user properties without null checks.
list every instance found.

TDD Workflow

Claude Code is well-suited for test-driven development:

1. Describe the feature in natural language
2. Ask Claude to write failing tests first
3. Ask Claude to implement code to pass the tests
4. Ask Claude to refactor while keeping tests green

TDD this feature: rate limiting for the /api/auth/login endpoint.
Max 5 attempts per IP per minute, return 429 after.

Step 1: write comprehensive tests first.
Step 2: implement to pass all tests.
Step 3: refactor for clarity.

Run tests between each step. Do not modify tests in steps 2-3.

Checkpointing Workflow

Use Claude Code's built-in checkpointing for safe experimentation:

1. Start a task — Claude automatically creates checkpoints
2. If the approach isn't working, press Esc Esc to rewind
3. Choose: revert code only, conversation only, or both
4. Try a different approach with your context intact

This is especially useful for exploratory refactoring where you want to try multiple approaches.

PR Creation Workflow

Claude Code has native git integration:

create a pr for the current changes.

include:
- summary of what changed and why
- testing instructions
- screenshots if UI changed
link to issue #42.

For reviewing PRs from others:

git diff main...feature-branch | claude -p "review this PR.
focus on correctness, security, and test coverage.
be specific with line numbers."

Next Steps

• Prompts — Copy-paste prompts for each workflow step
• Hooks — Automate parts of these workflows with hooks
• Skills & Subagents — Delegate workflow steps to subagents