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:
-
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
-
Plan: Outline changes before implementation
- SHOULD create TodoWrite items for multi-step tasks
- MUST validate plan covers edge cases
-
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
-
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
- Start with clear goal
- Load context (CURRENT.md)
- Use EPCC workflow
- Update TodoWrite in real-time
- Run tests frequently
- 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