I tested how Claude Code remembers decisions. A plain TODO.md beat its own Tasks list.

Claude Code has its own task list now. I saved 18 tasks to it, opened a new session and asked "what's next?". It never looked at the tasks themselves. A TODO.md sitting in the repo did better.

I'm building Frostbyte, a product plan that you and your coding agent both work from. So I wanted to know something pretty basic: if my agent makes a decision today, can tomorrow's session tell me what it decided and why? I didn't actually know, so I tested it.

What I tested

The repo is Pantry, a little throway Node command line tool that tracks when your food expires. It has a plan of 18 tasks: 10 in a v0.2 release, 8 in a backlog. Each setup got the same plan, a fresh copy of the repo and the same script:

1. Session 1: What's next?
2. Same session: Go ahead and do it. Where there's a real choice to make, make it yourself and tell me what you chose and why.
3. Session 2, fresh, same folder: What did we decide on "<the task's title>", and why? What's next now?

I scored three things:

• Next: did it answer from the plan, pick one task and give a reason?
• Write-back: without being asked, did it update the task and write down the choice and the reason on it?
• Recovery: could session 2 give the same choice and reason, read from the plan?

Each setup ran twice and had to pass on both runs. Everything ran on 31 October 2026, Claude Code 2.1.312 with Sonnet 5.5, with none of my own settings or CLAUDE.md loaded. Auto memory was on, because that's how most people run it.

The results

Basically, the agent only carried a decision into the next session when two things were true. It knew where the plan was, and something asked it to keep the reason.

Claude Code never opened its own list

This one surprised me the most. Tasks needed two environment variables to work in my setup (CLAUDE_CODE_ENABLE_TODO_TOOLS=1, because Sonnet 5.5 isn't in its default list, and CLAUDE_CODE_TASK_LIST_ID so a new session finds the same list). All 18 tasks were saved in ~/.claude/tasks. The agent ignored them, read the repo and made up its own plan.

I ran it once more and asked straight out, "What's next on your task list?" It said:

I don't have a task list. This conversation is new, and nothing has been assigned or queued.

Linear and Notion did the same thing when nothing told the agent they were there. It read the repo and made up tasks that weren't in the plan.

A TODO.md gets read, but the reason gets lost

With no instructions at all, a TODO.md got read every time. It's in the repo, so the agent just finds it. It did the work and ticked the box.

The reason never made it into the file, though. The second session still gave a decent answer, but it rebuilt it from the commit message and code comments, and one run said the why was inferred. So the answer was there, just not where the plan is.

Backlog.md went further than a plain file. Its setup gives the agent instructions, so it moved the task and wrote down the choice in all four runs. The reason made it onto the task once.

What got me is that the agent explained its reasoning out loud most of the time. It just said it in the chat, and the next session can't see the chat.

The lines that fixed it

These are the exact lines I used for the TODO.md version. Put them in CLAUDE.md and change the release name to yours:

This project's plan is in TODO.md. When asked what's next, read the open tasks under v0.2 and rank them by priority. Before working on a task, mark it in progress in the file. When you make a non-obvious choice, write the choice and the reason under the task. When you finish, add a short summary under the task and tick it.

With those lines, TODO.md passed everything. The same kind of lines fixed Linear and Notion too. In a Linear run, session 2 went straight to the right place: "The decision is probably in the comments on PAN-5, so I'll read those."

Without them, a Linear session 2 said: "I can't tell you why anything was decided, and I won't guess at the reasoning." At least it's honest.

One catch is that you have to keep the lines current. The release name in them goes out of date as soon as you ship.

My own tool failed too

To be fair, I ran Frostbyte through the same test, and in the first round one run failed because of a bug in my server. The agent sent its reason as a separate field. My tool only accepted the decision, so it threw the reason away and still said "Decision logged". Agents did that in 3 of 8 runs, so real users would've hit it often. I fixed it, re-ran it, and it passed.

It passed without any CLAUDE.md lines, but I should say the test leans my way. Its tool is literally called whats_next, the same words as the first prompt. It also has a tool that asks for the reason by name, which is exactly what the test scores.

What I didn't test

• One model, one version of Claude Code.
• A small plan. 18 tasks is nothing next to a real Linear workspace.
• Two runs per setup. That shows what can happen, not how often.
• Auto memory was on the whole time and stayed empty, so I can't tell you what it adds.

So take it as what I saw, not a benchmark.

If you take one thing from this, add those lines to your CLAUDE.md today, whatever you track your plan in. It's free and it took my TODO.md from failing to passing.

How do you keep your agent on the plan between sessions? I'm keen to hear what's actually working for people, especially if you've got something that keeps the reason without any lines at all.

P.S. I'm building Frostbyte for this: one plan you, your team and your agent all work from, with the reasons kept on the task. It's early, so if you try it I'd really love your feedback.