Claude Code Loses Context: Keep the Plan Outside the Chat

Two hours into a good session, Claude Code prints “Conversation compacted” and carries on. Ten minutes later it suggests the approach you ruled out before lunch. Then it writes the next file in the old style, the one you agreed to move away from.

Nothing crashed. The code is all there. What went missing is the part of the session that only ever existed as conversation.

What compaction keeps, and what it drops

When the context window fills, Claude Code replaces the conversation with a structured summary and keeps working. Anthropic's docs are specific about what comes back afterwards. The project-root CLAUDE.md is re-read from disk, along with auto memory, the plan from plan mode, and up to five of the files it most recently read or edited. CLAUDE.md files in subfolders and path-scoped rules only return when Claude touches a matching file again.

Everything else becomes the summary. It holds on to your requests, the files changed, the errors fixed and the pending tasks. What it tends to flatten is reasoning. “We tried a queue, it sent every email twice, so we switched to a scheduled job” can come back as “set up scheduled email sending”. The decision survives. The option it ruled out often does not, and that is exactly what Claude suggests again ten minutes later.

Running /clear goes further: the whole conversation is gone and only the files on disk remain. A brand-new session starts the same way. The general version of this problem is in Why Your AI Forgets Your Project. This post is about the Claude Code specifics.

The usual fixes, and where they stop

The advice on this is consistent, and most of it is good. 1. Run /context to see what is filling the window. 2. Compact yourself at a natural checkpoint, with a focus such as “/compact focus on the auth fix”, instead of waiting for the automatic pass to guess what matters. 3. Run /clear when you switch to unrelated work. 4. Send big research jobs to a subagent so only its summary lands in your window. 5. Move anything important out of the chat and into CLAUDE.md.

The first four keep the window healthy. The fifth is where it gets harder. Rajiv Pant wrote up a migration from callbacks to async/await in which, after compaction, Claude added the new convention to CLAUDE.md and then wrote the final batch of files with .then() chains anyway. The rule was in the file. Nothing checked the work against it.

Anthropic says as much in its own docs: Claude treats CLAUDE.md “as context, not enforced configuration”, and each file should stay under about 200 lines. That is a good size for rules about how to build. It is a cramped place to also keep what you are building, what comes next, and every call you made on the way. Files describe. They don't decide.

Keep the plan where compaction cannot reach it

Compaction can only summarise what is in the chat. So keep the plan out of the chat.

Split what you would normally say in conversation into two homes. CLAUDE.md keeps the rules: stack, conventions, commands, things never to touch. It is short and rarely changes. The plan lives somewhere else and changes every day: the task in flight, what done looks like for it, what you decided and why, what you ruled out, and what is next.

Two habits make it work. Start every session by having Claude read the plan before it opens any code. End every task by checking the diff against that task's definition of done, then writing what changed back into the plan before you clear. The second habit is the one people skip, and it is the one that would have caught those .then() chains.

You can run this with a markdown file and some discipline. It holds up until a busy week, when the file quietly goes stale and the next session trusts it anyway.

Running it with PAPI

This is the job PAPI does inside Claude Code. The plan sits outside the session: work runs in cycles of a few tasks, decisions keep their reasoning, and every build files a report that the next plan reads. Each task gets a build handoff with the goal, what is out of scope, and how to check it is done, written so a session with no history on the project can pick it up.

That makes /clear cheap. The fresh session reads the handoff instead of your recap, and when the work comes back you give the verdict: accept, request changes or reject. How it connects is on the PAPI for Claude Code page.

The honest version

PAPI does not stop compaction, and it does not write code. Claude Code still does the building, and you still want a lean CLAUDE.md and the habit of compacting and clearing on purpose.

If your sessions are short, one task each, and nothing you decided last week matters this week, that is enough. Stay there. A plan outside the chat earns its place once the project has outgrown a single session and you catch yourself explaining it again every morning. Walk through a demo project to see what that plan looks like, no signup needed.