Todo Workflows

Update (Jan 2025): A more capable task system now ships with Claude Code, including dependencies, blockers, and multi-session handoff. The fundamentals on this page still hold. See the new guide for advanced patterns.

Problem: Steps land out of order, or a whole step goes missing, and you're left second-guessing whether the brief was clear at all.

Quick Win: Bolt this onto the end of any involved task:

claude "add user authentication - create a todo list first, then implement each step"

Claude writes the plan as a checklist inside the terminal. Any misread surfaces before a single line of code ships.

Bugs aren't the pain point in AI coding. The pain is not knowing whether Claude actually understood the request. Claude Code ships with a built-in TodoWrite tool that turns every task into a checklist in the terminal UI.

Treat a todo list as Claude's version of repeating back what it heard. The checklist refreshes live while work happens, flagging done items, the current focus, and what's still queued. Alignment means the instructions were clear. Divergence means a communication gap, caught early.

Common Todo Divergence Patterns

Out of Order: You ask for A then B, the list comes back with B then A. Missing Steps: Tests were in the brief, the todos forgot them.

Wrong Detail: The ask was a high-level "update docs," and Claude breaks it into file-by-file entries. Misinterpretation: You say "review changes," Claude plans "commit changes."

The list also redraws live when you give feedback. That turns it into a real steering wheel during involved work. Say "actually make the button green instead of blue" mid-run, and the pending todo gets updated while every completed item stays exactly as it was.

Get Specific Todos

A todo that says "style navbar" is the whole problem in one line. Ask for concrete detail instead.

Bad approach:

- [ ] Style the navigation bar

Good approach:

- [ ] Change navbar height from 60px to 80px
- [ ] Reduce padding from 16px to 12px
- [ ] Update background to rgba(255,255,255,0.95)

Phase-Based Dependencies

Group related work into phases and spell out what each one waits on:

Phase 1: Setup database schema, create user model
Phase 2: Build registration and login (needs Phase 1)
Phase 3: Add validation and styling (needs Phase 2)

Quality Checkpoints

Walk every todo list through four quick checks:

1. Order: Logical sequence?
2. Complete: All steps included?
3. Right Detail: Appropriate granularity?
4. Clear: Another dev could follow?

When Things Go Wrong

Claude skips todos: Drop "Check todo list before starting each step" into your CLAUDE.md.

Todos too generic: After giving instructions, say "Break this down into specific, measurable steps".

Wrong priorities: Reach for numbered lists, not bullets, whenever order is load-bearing:

1. First, backup the database
2. Then run migrations
3. Finally, restart services

Make It a Habit

The best todo workflows run on autopilot. Bake this five-step loop into your day:

1. Give Claude your task instructions
2. Ask "Create a detailed todo list"
3. Review for alignment with your intentions
4. Refine instructions if todos diverge
5. Proceed with confidence

When Claude's checklist matches the one in your head, the instructions were clear. That's the whole bar. Ask for the todos first, read them carefully, and the rest of the session runs on rails.

Next Steps:

• Git integration for todo-driven commits
• Feedback loops to iterate on todo quality
• Permission management for secure execution
• Planning modes for structured todo creation
• Context management to keep todo history