claude-code-workflow - Claude MCP Skill

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