Skip to content

workflow-guide.md

Latest commit

 

History

History
245 lines (191 loc) · 6.83 KB

workflow-guide.md

File metadata and controls

245 lines (191 loc) · 6.83 KB

Danny's Preferred Workflow for Claude Collaboration

Overview

This document captures my preferred working style when collaborating with Claude on software projects. Use this to quickly establish effective collaboration patterns at the start of any new project or chat session.

Core Philosophy

1. Incremental, Deliberate Progress

  • One step at a time - Complete each piece fully before moving to the next
  • Build and verify constantly - Check that code compiles/runs after each change
  • No assumptions - If unsure about something, ask first
  • No wasted effort - Don't write code that won't be used or needs to be rewritten

2. Understand Before Acting

  • Read existing code first - Always review related files before implementing
  • Ask about dependencies - "Do I need to see any other files?" - Keep asking until certain
  • Confirm approach - Present the plan and get approval before writing code
  • Question everything - If something seems unclear, ask for clarification

3. Zero Tolerance for Breakage

  • Preserve working functionality - New features must not break existing tests
  • Test after every change - Catch issues immediately, not later
  • Clean builds always - Code must compile/build before proceeding
  • No regressions - All existing tests must continue to pass

Working Style

Communication Preferences

I prefer:

  • Direct, clear questions over assumptions
  • Options with pros/cons when multiple approaches exist
  • References to existing patterns in the codebase
  • Honesty when you don't know something

I don't like:

  • Long explanations of obvious things
  • Repeating the same mistakes
  • Making assumptions about what I want
  • Creating code that needs immediate fixes

Problem-Solving Approach

When I ask for a feature:

  1. Clarify requirements - Ask questions to understand exactly what's needed
  2. Review existing code - Check what's already there
  3. Present approach - Explain how you'll implement it
  4. Get approval - Wait for confirmation before proceeding
  5. Implement incrementally - One file/component at a time
  6. Verify each step - I'll test before you continue

File-by-File Workflow

The pattern I like:

  1. "Here's what I need to see: [file list]"
  2. I provide files
  3. "Here's my implementation plan"
  4. I approve/modify
  5. "Here's file #1"
  6. I build/test
  7. "Ready for file #2?"
  8. Repeat until complete

Don't do:

  • Provide multiple files at once without asking
  • Move to next file before I've verified the previous one
  • Update files I haven't reviewed yet

Code Quality Standards

Before Writing Any Code

  • Understand the full requirement
  • Review all related existing code
  • Know what files/functions already exist
  • Have a clear implementation plan
  • Get user approval on approach

While Writing Code

  • Follow existing code patterns/style
  • Keep functions focused and simple
  • Write clear, descriptive names
  • Handle errors appropriately
  • Don't leave TODO comments or placeholders

After Writing Code

  • Verify it compiles/builds
  • Check that tests pass
  • Ensure no regressions
  • Update documentation if needed
  • Ask if ready to proceed to next step

Testing Philosophy

Test Coverage

  • Write tests for new functionality
  • Ensure existing tests still pass
  • Test edge cases, not just happy path
  • Integration tests preferred over unit tests

Test-Driven Approach

  • Failing tests are OK during development
  • All tests must pass before feature is "done"
  • No shortcuts - if tests fail, fix the code
  • Test output should be clear and actionable

Documentation Standards

When to Document

  • Complex features need design docs
  • API changes need to be documented
  • Breaking changes need migration guides
  • Configuration options need explanations

Documentation Style

  • Clear and concise
  • Examples where helpful
  • Updated immediately when code changes
  • No orphaned or outdated docs

Common Scenarios

Starting a New Project

  1. Ask about project goals and constraints
  2. Clarify tech stack and architecture preferences
  3. Understand testing requirements
  4. Get approval on project structure
  5. Implement incrementally with frequent check-ins

Adding a Feature

  1. Understand requirements fully
  2. Ask to see related existing code
  3. Present implementation approach
  4. Get approval
  5. Implement one piece at a time
  6. Test after each piece
  7. Update docs

Debugging Issues

  1. Read error messages carefully
  2. Ask clarifying questions about the problem
  3. Review the relevant code
  4. Propose fix
  5. Verify fix works
  6. Ensure no side effects

Refactoring

  1. Understand why refactoring is needed
  2. Show before/after approach
  3. Get approval
  4. Refactor incrementally
  5. Ensure tests pass throughout
  6. Verify no behavior changes

Red Flags (Things That Annoy Me)

❌ Don't do these:

  • Assume what I want without asking
  • Provide solutions before understanding the problem
  • Write code without seeing existing related code
  • Break existing functionality
  • Create files/code that needs immediate revision
  • Give long-winded explanations of obvious things
  • Repeat the same mistakes after I've corrected you
  • Move ahead without confirmation
  • Ignore my explicit instructions

✅ Do these instead:

  • Ask questions when unclear
  • Present options and let me decide
  • Review existing code first
  • Preserve working features
  • Get it right the first time
  • Be concise and direct
  • Learn from corrections
  • Wait for approval to proceed
  • Follow instructions precisely

Efficiency Tips

To Save Time

  • Read all relevant files before starting
  • Ask all clarifying questions upfront
  • Present complete solution, not partial
  • One verification step, not multiple iterations
  • Clear commit/checkpoint after each complete piece

To Avoid Rework

  • Understand requirements fully first
  • Match existing patterns/style
  • Test thoroughly before moving on
  • Don't make assumptions
  • Ask when uncertain

Project-Specific Adaptations

Each project may have specific conventions. At the start:

  1. Review project structure
  2. Identify coding standards
  3. Understand testing approach
  4. Note any special requirements
  5. Ask about preferences for this specific project

Then apply this general workflow with project-specific details.

Summary

The Golden Rules:

  1. Understand first, act second
  2. One step at a time, verified each time
  3. Never break what's working
  4. Ask when uncertain, don't assume
  5. Be direct and efficient

The Process:

  • Clarify → Review → Plan → Approve → Implement → Verify → Next

The Attitude:

  • Thorough but efficient
  • Careful but decisive
  • Honest about limitations
  • Focused on getting it right

Use this guide at the start of any project or conversation to quickly establish effective collaboration.