salverius-tech/claude-code-workflow

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Claude Code Workflow

Guidelines for effective AI-assisted development with Claude Code.

Task Value Matrix

| Value | Task Type | Example | |-------|-----------|---------| | High | Boilerplate generation | CRUD endpoints, test scaffolding | | High | Refactoring | Extract function, rename across files | | High | Documentation | Docstrings, README updates | | Medium | Bug investigation | Error analysis, log interpretation | | Medium | Code review | Pattern suggestions, security review | | Low | Novel architecture | Requires deep domain knowledge | | Low | Ambiguous requirements | Needs human clarification |

---

Workflow Patterns

Explore-Plan-Code-Commit (EPCC)

The RECOMMENDED workflow for most development tasks:

1. Explore: Use Glob, Grep, Read to understand existing code

   • MUST understand context before making changes
   • SHOULD identify related files and dependencies
   • MAY use subagents for parallel exploration

2. Plan: Outline changes before implementation

   • SHOULD create TodoWrite items for multi-step tasks
   • MUST validate plan covers edge cases

3. Code: Implement changes incrementally

   • MUST run tests after each significant change
   • SHOULD use Edit over Write for existing files
   • SHALL NOT introduce breaking changes without tests

4. Commit: Create logical, atomic commits

   • MUST follow semantic commit conventions
   • SHALL NOT commit secrets or credentials

Test-Driven Development with AI

1. Write failing test → 2. Implement minimum to pass → 3. Refactor → 4. Repeat

• MUST run tests between each step
• SHOULD use targeted test execution during development

Spike-Then-Implement

For uncertain implementations: Create throwaway spike, validate, delete, implement properly with tests.

---

Context Management

Efficient Prompting

MUST: Provide specific file paths, include error messages verbatim, state expected vs actual behavior

SHOULD: Reference previous context, specify output format, include constraints upfront

SHOULD NOT: Repeat information in context, include unnecessary background, ask multiple unrelated questions

Conversation Structure

[Initial Context] → [Specific Task] → [Iterative Refinement]

• SHOULD front-load critical information
• MUST NOT bury important constraints at end of message

Context Window Optimization

• SHOULD use subagents for isolated subtasks
• MUST NOT paste entire files when snippets suffice

---

Subagent vs Direct Tool Usage

Use Subagents (Task tool) When:

• Parallel independent operations (multiple searches, test runs)
• Isolated subtasks not needing main conversation context
• Complex multi-step work (refactoring across many files)
• Risk isolation (exploratory changes that might fail)

Use Direct Tools When:

• Sequential dependencies (each step depends on previous)
• Context continuity needed (building on recent conversation)
• Simple operations (single file read/edit)
• Immediate feedback required (interactive debugging)

| Scenario | Recommendation | |----------|----------------| | Search 5+ files for pattern | Subagent | | Edit single file | Direct | | Run tests + fix failures | Subagent | | Explore unfamiliar codebase | Subagent | | Implement planned changes | Direct |

---

Model Selection

Opus (Complex Reasoning)

SHOULD use for: Architecture decisions, complex debugging, multi-file refactoring, novel problem solving, security-sensitive code review

Sonnet (Standard Tasks)

RECOMMENDED for: Routine code changes, test writing, documentation, code review, bug fixes with clear scope

Haiku (Quick Operations)

MAY use for: Simple queries, syntax checking, format conversions, quick lookups, commit message generation

IF deep reasoning OR high-stakes: USE Opus
ELSE IF routine development: USE Sonnet
ELSE IF simple/quick: USE Haiku

---

Quality Assurance

Automated Validation

MUST: Test execution after changes, linting/formatting, type checking, security scanning

SHOULD: Coverage thresholds, performance benchmarks, integration tests

Human Review Checkpoints

REQUIRED: Security-sensitive changes, production deployments, architecture modifications, public API changes

RECOMMENDED: Complex business logic, performance-critical code, external integrations

---

Prompt Engineering for Code Tasks

Specificity Patterns

Effective: "Refactor UserService in src/services/user.py to use dependency injection for database connection"

Ineffective: "Clean up the user code"

Constraint Specification

MUST specify: Language/framework versions, performance requirements, backward compatibility, error handling

Prompt Templates

Bug Fix:

File: [path] | Error: [exact message]
Expected: [behavior] | Actual: [behavior]
Relevant code: [snippet]

Feature:

Goal: [one sentence]
Criteria: [list] | Location: [file] | Constraints: [limits]

---

Session Context Management

Integration with Context Files

CURRENT.md - Active task state (SHOULD update when switching tasks, MUST reflect current focus)

STATUS.md - Project progress (SHOULD update at session end, MUST include blockers/next steps)

Session Lifecycle

[Start] → [Load CURRENT.md] → [Work + TodoWrite] → [End] → [Update STATUS.md]

Context Preservation

• MUST save context before long breaks
• SHOULD use /snapshot for complex multi-session work
• MAY use /pickup to resume efficiently

---

Skill Activation Optimization

Triggering Skills Efficiently

• MUST use specific keywords in descriptions
• SHOULD include file patterns for automatic activation
• MAY use manual invocation for specialized skills

Skill Composition

Skills SHOULD be: Single-purpose, composable, self-contained

Skills MUST NOT: Conflict with others, duplicate core rules, exceed context budget

| Pattern | Trigger | |---------|---------| | File-based | *.py, Dockerfile, package.json | | Directory-based | .claude/, tests/, src/ | | Content-based | Keywords in conversation | | Command-based | /skill-name invocation |

---

Anti-Patterns to Avoid

Conversation Anti-Patterns

| Anti-Pattern | Better Approach | |--------------|-----------------| | Context dumping | Provide focused, relevant context | | Vague requests | Specific, measurable goals | | Premature optimization | MVP first, optimize with data | | Ignoring errors | Address errors immediately |

Tool Usage Anti-Patterns

| Anti-Pattern | Better Approach | |--------------|-----------------| | Bash for file ops | Use Read/Edit/Write tools | | Write over Edit | Prefer Edit for existing files | | Single-threaded search | Parallel subagent searches | | Skipping Read | Always Read before Edit |

Workflow Anti-Patterns

| Anti-Pattern | Better Approach | |--------------|-----------------| | Coding without tests | TDD or test-after minimum | | Giant commits | Atomic, logical commits | | Ignoring TodoWrite | Update status in real-time |

Prompting Anti-Patterns

| Anti-Pattern | Better Approach | |--------------|-----------------| | "Make it better" | Define specific improvements | | Assuming knowledge | Provide relevant background | | Ignoring constraints | State constraints upfront |

---

Quick Reference

Effective Session

1. Start with clear goal
2. Load context (CURRENT.md)
3. Use EPCC workflow
4. Update TodoWrite in real-time
5. Run tests frequently
6. Save context before ending

Model Selection

• Opus: Architecture, security, complex bugs
• Sonnet: Daily development, tests, docs
• Haiku: Quick queries, formatting

Tool Selection

• Read: View file content
• Edit: Modify existing files
• Write: Create new files (rare)
• Glob: Find files by pattern
• Grep: Search file contents
• Task: Parallel/isolated work
• Bash: System operations only