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