Plan Claude Code work with a ROADMAP.md file

Who does what

1. MeI write the work as numbered checkbox tasks in a gitignored ROADMAP.md.
2. MeI open a fresh session and say "let's do next on the roadmap".
3. ClaudeFinds the next open task, asks me about any choice that is mine, then plans it.
4. MeI answer and approve. Claude builds it and ticks the box.

1Keep the roadmap private

The file sits in the project root as ROADMAP.md, and one line in .gitignore keeps it out of git:

ROADMAP.md

It's my working notes: half-made decisions, review notes, ideas I may drop. None of that belongs in the repo. The public CLAUDE.md mentions it in one line, so Claude knows it exists:

`ROADMAP.md` (gitignored) is the working plan and to-do list.

2Write tasks as numbered checkboxes

Each section is one piece of work with a short Why, then numbered tasks. This is a real section from this site's roadmap:

## 2. New guide: planning with a roadmap file

Why: show how a `ROADMAP.md` lets me split work into sessions, decide where Claude stops, and save tokens.

- [ ] 1. Write the guide, ideally as the first new `.md` guide after task 1.
- [ ] 2. Cover scheduling (run a task later, e.g. `/schedule` or `/loop`) and stopping points.
- [ ] 3. Link it from the CLAUDE.md, save-tokens and Claude + Gemini MCP guides.

[ ] is open, [x] is done. The numbers matter: they let me say "do 2.1 to 2.3" instead of describing the work again. The Why line matters too. When a task is unclear, Claude can decide from the reason instead of asking me.

A task should be small enough to finish, build and test in one session. If it isn't, split it.

3Start every task in a fresh session

/clear

Then one short prompt. This is the exact one I typed for this guide:

let's do next on the roadmap

That's enough because the plan is in the file. Claude reads ROADMAP.md, finds the first open task, gathers what it needs and starts. The old session's files, logs and dead ends are gone, so I don't pay for them on every turn. It's the "one task, one session" habit from how to save tokens, with the file doing the remembering.

4Tell Claude where to stop

Without a stopping point, Claude keeps going: one task turns into three, and I review a pile of changes at once. So the prompt says how far to go:

do items 1–5, then decide

do one more

"Then decide" means: stop, show me what's done, and wait. I check the result, then choose the next step. Claude also ticks each finished task in the file, so the next session knows where things stand even if I forget.

5Note what happened, right in the task

When a task ends differently than planned, one line under it says so. From this site's roadmap:

Task 1 done 2026-10-28 (Gemini was down, so a one-off converter script did the conversions;
verified by HTML + computed-style diffs against the old build).

Later sessions see why the plan changed, and I don't have to explain it again.

6Archive the roadmap when a version ships

When a version is done, the file moves to roadmaps/ with the version in its name, and a fresh ROADMAP.md starts:

roadmaps/
  ROADMAP_v1.0.0.md
  ROADMAP_v1.1.0.md
  ROADMAP_v2.1.0.md

The new file starts with one line pointing back: "v2.1.0 ... is archived in roadmaps/ROADMAP_v2.1.0.md". Unfinished work moves forward as a new task ("moved from v2.1.0"). The current file stays short, so it's cheap to read every session, and the old ones are there when I need to look something up.

7Point Claude's memory at the current roadmap

Because the roadmap is gitignored, git log can't tell Claude where planning stands. Claude Code's memory can. My memory note for this project says:

- `ROADMAP.md` (root) = the current plan, v2.2.0. Task 1 (Guides as Markdown) done 2026-10-28.
  Next: task 2 (roadmap-planning guide) and task 3 ("How I work" animated maps, location undecided).
- When a version ships, archive the plan as `roadmaps/ROADMAP_v<x>.md` and start a fresh `ROADMAP.md`.

The memory index loads at the start of every session, so even a vague prompt lands on the right file. Keep it to pointers and rules; the plan itself stays in the roadmap. See CLAUDE.md best practices for what goes where.

Run a task later

Two built-in skills help when a task should run without me starting it:

• /schedule creates a cloud agent that runs on a schedule, or once at a set time ("run this once at 3pm").
• /loop runs a prompt again and again in the current session, at a fixed interval or at Claude's own pace, e.g. /loop 5m check the deploy.

With /loop the prompt can stay short ("do the next open task in ROADMAP.md, then stop"), because the file holds the details.