TODO.md-Driven Development (Maintaining Task Continuity)

When working across multiple sessions, it's easy for Claude to lose context about what has been done.
By explicitly managing task progress with TODO.md, you can maintain continuity even after running /clear.

---

Built-in Todo System vs TODO.md File

It's important to distinguish between the two first.

	Built-in Todo (TodoWrite)	TODO.md File
Method	Auto-generated by Claude within a session	A file you create manually
Persistence	Disappears when the session ends	Persists permanently in Git
Purpose	Shows progress in the current session	Passes context to the next session

💡 The built-in Todo is automatically created by Claude when performing complex tasks (3+ steps) to display progress. No separate setup is needed.
If your goal is continuity between sessions, you need a TODO.md file.

---

Practical Workflow

1. Initial TODO.md Structure

# Project Name TODO

## 🔥 In Progress
- [ ] Write authentication API endpoints

## ✅ Completed
- [x] Design Supabase schema
- [x] Initial project setup

## 📋 Up Next
- [ ] Connect frontend login UI
- [ ] Configure RLS policies

## 📝 Notes (Rationale for Decisions)
- 2025-03-25: Decided to use Supabase Auth instead of JWT — no need to manage separate tokens

---

2. At the Start of a Session

"Read TODO.md, understand what work to do today, and create a Plan."

3. During Work

"Check off the authentication API I just completed in TODO.md."

4. Before Ending a Session

"Update TODO.md with today's completed work, what to continue next time,
 and any important decisions made, then commit to Git."

---

Compound Effect (Gets Stronger as Sessions Accumulate)

The TODO.md file becomes a living execution log. In the next session, Claude doesn't just see what needs to be done — it also sees what has already been completed and how it was done.

Session 1: Understand project structure + design schema
Session 2: Sees Session 1's completions, understands patterns → writes API
Session 3: With full context from Sessions 1+2 → works faster with fewer questions

---

Adding a TODO Reading Rule to CLAUDE.md

If you find it tedious to say this every time, add it to CLAUDE.md.

## Work Rules
- Always read TODO.md at the start of a session to understand the current state
- Update TODO.md every time a feature is completed
- Record important technical decisions in the TODO.md notes section with a date

---

Caveats

• If TODO.md gets too long, the same problem as CLAUDE.md arises. Periodically clean up completed items or split them into a separate file (DONE.md).
• Writing down the reason (Why) behind a decision means you won't have to ask Claude the same question again later.