Workflow Patterns

These are battle-tested patterns for common development scenarios.

Pattern 1: Feature Development

# 1. Start with spec (new session)
claude
> I want to add [feature]. Interview me about requirements.
[Answer questions, get spec]
> save spec to docs/specs/feature-name.md

# 2. Implement (new session)
exit
claude
> implement docs/specs/feature-name.md
> start with the data models

# 3. Test (same session or new)
> write tests for what we just implemented
> run them

# 4. Review (new session for clean context)
exit
claude
> review the changes in the last 3 commits
> check for bugs, security issues, and style

Pattern 2: Bug Investigation

# 1. Describe the bug
> users report [symptom]
> error message: [paste error]
> started happening [when]

# 2. Let Claude investigate
> investigate and find the root cause
> don't fix yet, just report findings

# 3. Review findings
> [Claude reports what it found]
> yes, that's the issue / no, dig deeper

# 4. Fix with test
> fix it and add a regression test

Pattern 3: Code Review Workflow

# Before committing
> /review
> [Custom slash command reviews staged changes]

# Or manually
> review my staged changes
> focus on: security, performance, edge cases
> be critical

Pattern 4: Documentation Sprint

# 1. Audit existing docs
> what modules lack documentation?
> list files with no docstrings

# 2. Generate in batches (use subagent)
> use a subagent to add docstrings to app/models/
> Google style, include types and examples

# 3. Review
> show me the changes to models/user.py

Pattern 5: Refactoring

# 1. Plan the refactor
> I want to refactor [module] to [new pattern]
> what's the safest approach?

# 2. Create tests first
> before we change anything, ensure test coverage
> write tests for current behavior

# 3. Incremental changes
> make the first change: [specific change]
> run tests after each step

# 4. Verify
> run all tests
> anything broken?

Pattern 6: Learning a Codebase

# Day 1: High level
> explain this codebase at a high level
> what are the main components?
> draw a diagram of data flow

# Day 2: Deep dives
> walk me through the auth flow
> explain how [specific feature] works

# Day 3: Make a change
> I want to add [small feature]
> guide me through where to make changes

Anti-Patterns to Avoid

❌ The Marathon Session

# Bad: 50+ message conversation
> [task 1]
> [task 2]
> ...
> [task 50 - Claude is confused]

❌ Context Dumping

# Bad: Pasting everything upfront
> Here's all my code: [10,000 lines]
> Now help me with this small thing

❌ Vague Iterations

# Bad: Unclear feedback loop
> make it better
> no, better than that
> still not right