Task Management & Tracking

For complex work involving multiple steps, Claude can track progress using task lists. This helps you see what’s done, what’s in progress, and what’s left to do.

The TodoWrite Tool

When you ask Claude to do something complex, it often breaks the work into tasks and creates a task list:

> add user authentication with JWT, including tests and documentation

I'll break this down into tasks:

✓ Create User model with password hashing
⚙ Add JWT token generation utilities
○ Create login endpoint
○ Create registration endpoint
○ Add authentication middleware
○ Write unit tests
○ Write integration tests
○ Update API documentation

Let me start with the JWT utilities...

Task States

Symbol	State	Meaning
○	Pending	Not started yet
⚙	In Progress	Currently working on this
✓	Completed	Done

When Claude Uses Task Tracking

Claude automatically creates task lists for:

1. Multi-Step Features

> add a complete user profile feature: avatar upload, bio, social links

✓ Add database migration for profile fields
⚙ Create profile update endpoint
○ Add avatar upload with S3 integration
○ Add input validation
○ Create tests
○ Update frontend models

2. Sequential Changes

> refactor the authentication system to use dependency injection

✓ Update AuthService to accept dependencies
⚙ Refactor route handlers to use new AuthService
○ Update tests to use DI
○ Update documentation

3. Fixes with Multiple Components

> fix the memory leak in the background job processor

✓ Profile memory usage to identify leak
⚙ Fix EventEmitter listener accumulation
○ Add cleanup in job completion handler
○ Add monitoring/alerting
○ Add regression test

How Task Tracking Helps You

1. Progress Visibility

You always know where Claude is in a complex task:

✓ Database migration
✓ Model updates
⚙ API endpoint implementation (currently working)
○ Tests (next up)
○ Documentation (after tests)

2. Interruption Recovery

If you need to stop Claude, you can see exactly what’s done:

> stop

[Claude stops]

> what's the status?

We've completed:
✓ Database changes
✓ User model updates

Still remaining:
○ API endpoints
○ Tests
○ Documentation

Ready to continue?

3. Context Management

Task lists help Claude remember the big picture:

# After implementing several tasks
✓ Login endpoint
✓ Registration endpoint
⚙ Password reset endpoint

# Claude knows: We're building an auth system, currently on password reset

Requesting Task Breakdown

You can explicitly ask Claude to break down work:

> create a task breakdown for adding search functionality
> don't implement yet, just plan the tasks

I'll break this into tasks:

1. Add search index configuration
2. Create search service
3. Add search API endpoint
4. Add pagination for results
5. Add filtering options
6. Write tests
7. Update documentation

Shall I proceed with implementation?

Task Management Patterns

Pattern 1: Review Before Starting

> plan the tasks for migrating from REST to GraphQL
> show me the breakdown before implementing

Here's the task breakdown:

Phase 1: Setup
○ Install GraphQL dependencies
○ Configure GraphQL server
○ Set up schema

Phase 2: Implementation
○ Convert user endpoints
○ Convert product endpoints
○ Convert order endpoints

Phase 3: Testing & Cutover
○ Write tests
○ Update client
○ Deploy

Look good? Shall I start?

Pattern 2: Approve Each Task

> add notifications feature
> wait for my approval after each task

✓ Database migration
Completed! Next task: Create NotificationService

Continue? (yes/no)

Pattern 3: Partial Implementation

> implement tasks 1-3 from the plan
> I'll review before you do tasks 4-6

✓ Task 1: Add database fields
✓ Task 2: Create service class
⚙ Task 3: Add API endpoint
○ Task 4: Tests (paused for review)
○ Task 5: Documentation (paused)

The Task Tool (Subagents)

For some work, Claude can spawn subagents using the Task tool. This is different from TodoWrite:

Feature	TodoWrite	Task Tool (Subagent)
Purpose	Track main session work	Delegate isolated work
Context	Same session	Separate session
Use case	Complex multi-step tasks	Parallel or isolated work

Example: TodoWrite

> add authentication

✓ Create User model
⚙ Add login endpoint
○ Add tests

# All work happens in your session

Example: Task Tool

> use a subagent to write tests for the auth module
> while it works, I'll continue with the API implementation

# Claude spawns a separate agent:
# - Subagent: Writes tests in isolation
# - Main agent: You continue working
# - Subagent reports back when done

When Tasks Aren’t Needed

Claude doesn’t create task lists for:

Simple Single-Step Work

> add a comment explaining this function

# No task breakdown needed
# Claude just adds the comment

Questions

> what does this code do?

# No tasks - just analysis and explanation

Quick Fixes

> fix the typo in line 42

# Too simple for task tracking

Advanced: Task Persistence

Tasks exist within a conversation session. If you need to save progress:

> save the current task status to status.md

# Claude writes:
## Auth Feature Implementation

### Completed
- Database migration
- User model with password hashing
- JWT utilities

### In Progress
- Login endpoint (80% done)

### Remaining
- Registration endpoint
- Tests
- Documentation

---

# Later, new session:
claude
> continue the auth feature from status.md

Best Practices

1. Let Claude Decide

Don’t force task breakdowns for simple work:

# Good: Let Claude assess
> add input validation to the form

# Overkill: Forcing task tracking
> create detailed tasks for adding one line of validation

2. Review Complex Breakdowns

For large features, review the task plan before starting:

> show me the task breakdown first
> [review]
> looks good, proceed

3. Break Mega-Tasks Into Sessions

If you see 20+ tasks, consider splitting:

# Instead of:
> implement entire user management system (25 tasks)

# Better:
> implement user CRUD operations (tasks 1-8)
# [complete]
> implement user roles and permissions (tasks 9-15)
# [complete]
> implement user settings (tasks 16-20)

4. Acknowledge Completions

When Claude completes significant tasks, acknowledge:

> ✓ all tests pass, great work
> move to the documentation task

This helps Claude maintain context about what’s validated vs what still needs review.

Task Completion Requirements

Claude should only mark a task as completed when:

✓ The work is actually done ✓ No errors occurred ✓ Tests pass (if applicable)

If Claude encounters errors:

⚙ Run test suite

Error: 3 tests failing in test_auth.py

# Task stays in-progress, NOT marked complete
# Claude should fix the failures before moving on

Troubleshooting Task Tracking

Claude Marks Tasks Complete Too Early

> wait - that task isn't done, there are still errors
> fix the errors before marking it complete

Claude Loses Track of Tasks

Sign of context overload:

> /compact
# or
> what tasks are remaining?

Too Many Tasks

Break into smaller chunks:

> let's focus just on tasks 1-5 for now
> we'll tackle 6-10 in the next session

Example: Full Task Flow

You: Implement a password reset feature

Claude:
I'll break this into tasks:

○ Add password_reset_token field to User model
○ Create token generation utility
○ Add POST /auth/reset-request endpoint
○ Add POST /auth/reset-confirm endpoint
○ Add email template for reset link
○ Write tests for reset flow
○ Update API documentation

Starting with the User model...

---

[Later in session]

✓ Add password_reset_token field to User model
✓ Create token generation utility
✓ Add POST /auth/reset-request endpoint
⚙ Add POST /auth/reset-confirm endpoint
○ Add email template for reset link
○ Write tests for reset flow
○ Update API documentation

Currently implementing the confirmation endpoint...

---

[Even later]

✓ Add password_reset_token field to User model
✓ Create token generation utility
✓ Add POST /auth/reset-request endpoint
✓ Add POST /auth/reset-confirm endpoint
✓ Add email template for reset link
✓ Write tests for reset flow
✓ Update API documentation

Password reset feature complete! All tests passing.

Summary

TodoWrite tracks multi-step work in your current session
Task Tool (subagents) delegates isolated work to separate sessions
One task “in progress” at a time
Tasks help with progress visibility and interruption recovery
Not needed for simple single-step work
Complex tasks (20+) should be split across sessions