STATUS, TODO & DECISIONS

The memory system at a glance

your-project/
├── CLAUDE.md            ← auto-loaded EVERY session — the project's brain
└── docs/
    ├── STATUS.md        ← "where we left off" — written at the END of each session
    ├── TODO.md          ← the task queue — checkboxes, worked top to bottom
    └── DECISIONS.md     ← why we chose X over Y — append-only

CLAUDE.md holds what's permanently true. These three hold what's currently true — and together they're the difference between "Claude, read everything again" and a twenty-second briefing.

STATUS.md — the handoff note

A short note from the last session to the next one: the date, what was accomplished, the exact current state (what works, what's half-done), the precise next step, and any open questions. It's what makes coming back after weeks painless — for you and for Claude.

The trick: you never write it by hand. The End-of-Session prompt makes Claude write it as the last act of each session, and the Re-Entry prompt makes Claude read it first thing when you return. Two prompts, one file, full continuity.

TODO.md — the queue

The project's task list as plain checkboxes, roughly in order. Every work session starts by picking the top unchecked item and ends by checking it off. Simple on purpose: when both you and Claude read tasks from the same file, "what should we do next?" always has an answer. 

- [x] Set up project + memory system
- [x] Recipe page template
- [ ] Search across recipes        ← next session starts here
- [ ] About page

DECISIONS.md — the why log

One line per notable technical choice: what you chose and why. "Vanilla CSS over Tailwind — learning goal", "SQLite over Postgres — single-server app, simpler ops". Append-only, rarely read — until the day you (or Claude) wonder "wait, why did we do it this way?" and the answer is one grep away instead of lost forever.

You don't maintain any of this by hand

This system sounds like homework. It isn't — that's the point of the paired session prompts coming in chapter 12: the End-of-Session prompt updates STATUS, TODO and DECISIONS in about two minutes, and the Re-Entry prompt reads them back. Your only job is to actually run them.

Real-world example — this website. Siazly's task queue is a file called docs/FIXES.md — a checkbox list where each item states its "done when" criteria, and CLAUDE.md's standing rule says to read it before any task and check items off after. Same system, different filename: the roles matter, not the names.

Up next: put it all together from zero — one prompt that scaffolds a brand-new project with the whole memory system born in.

FAQ

Frequently Asked Questions

What files make up the Claude Code memory system?
Four: CLAUDE.md (permanent project facts, auto-loaded) plus three in docs/ — STATUS.md (where we left off), TODO.md (the task queue) and DECISIONS.md (why choices were made, append-only).
What goes in STATUS.md?
The handoff note from one session to the next: date, what was accomplished, the exact current state (what works, what's half-done), the precise next step, and any open questions. About forty lines that replace re-reading the whole project.
Do I write STATUS.md myself?
No — the End-of-Session prompt makes Claude write it as the last act of each session, and the Re-Entry prompt makes Claude read it when you return. Your only job is to run those two prompts.
What is DECISIONS.md for?
An append-only log of notable technical choices — one line each: the choice and the why. Months later, "why did we do it this way?" has a findable answer instead of a shrug.