When the chat gets too long

What it is and why it matters

You've probably had this happen: you've been working in the same Claude Code chat for hours and at some point things start slipping. It redoes a choice you'd already ruled out, forgets a rule you gave it at the start, brings back an attempt that didn't work.

The reason is the context window, Claude's working memory. Everything goes in there: your messages, the answers, the files it read, the command output, CLAUDE.md. When it gets close to the limit, Claude Code makes room on its own: first it drops old command results, then it summarizes the conversation. Your requests and the important code stay. Detailed instructions you gave at the start can disappear.

And there's the usage too: with every message, Claude Code sends the whole conversation to the model again. The longer the chat, the more every question costs you, even a one-line one.

What I do: when I finish a piece, I have Claude summarize where we are, have it write the decisions in a file in the project, and start again from a clean chat. The important things live in the file, not in the conversation.

1. The summary prompt

When you finish a piece of work (a screen, a connection, a fix) and before you move on to the next one, write this:

Summarize where we are in five points: what we decided, what's done, what's missing, the problems still open, the files we touched. Then update DECISIONS.md with the new decisions. No code in the summary.

The five points give you a full picture of the work, not just of the last thing done. “The files we touched” helps if something breaks later: you know where to look. “No code in the summary” because the code is already in the files: here you need to understand where you are, not reread a hundred lines.

Read that summary yourself. If there's a decision you don't remember making, or an open problem you'd missed, ask now, while the chat is still there.

2. The decisions file

In the project folder, create a file called DECISIONS.md. Short, one line per decision, with the reason. Mine looks like this:

# Decisions
## Login
- Email only, no social login (fewer things to maintain)
## Profile
- One photo only, name visible to everyone
## Don't touch
- The real database: testing happens only on the test one
## Open questions
- Notifications, yes or no?

The sections are the parts of the app, plus two I always use. “Don't touch” is the list of what Claude mustn't change without asking: the real database, payments, whatever is delicate for you. “Open questions” holds what hasn't been decided yet, so Claude doesn't choose for you and you find those questions in front of you when the time comes.

The reason is the part that matters. A week from now, a choice with no reason looks like a mistake, and Claude may well “fix” it. With the reason written next to it, it knows why it's that way.

And keep it short. In a moment we'll have it loaded in every session, and everything in it takes up memory every time. No meeting minutes: one line per decision. When an open question gets settled, move it to the right section. When a decision changes, rewrite the line instead of adding another one.

3. Starting again clean

With the summary done and the file updated, Claude Code gives you two ways forward.

/clear: a new chat

/clear opens a new, empty conversation. It doesn't touch the project files, and the previous chat doesn't vanish: if you need it, you reopen it with /resume. In the new chat, write:

Read DECISIONS.md and pick up from there: the next piece is [what's missing].

In place of the square brackets, put the next piece in one sentence, like “the profile page, just the photo part.” If you have the summary from before, its “what's missing” point already tells you. That way the new chat starts with only what it needs.

/compact: same chat, lighter

/compact summarizes the conversation and frees up space without closing it. You can give it instructions for the summary, written after the command. I tell it what to keep and what to throw away:

/compact keep the decisions, what's done and what's missing; skip the failed attempts

The automatic summary, the one Claude Code does on its own when the memory is almost full, works the same way. The difference is who chooses: there, Claude Code decides what's important; with instructions, you do.

Which of the two

I use /clear when I've finished a piece or I'm moving to unrelated work: it starts again from the file, I know what's in it, and it costs nothing. I use /compact when I'm halfway through a piece and still need the thread of the conversation. Remember that /compact isn't free: to summarize, it has to re-read the whole chat, so on a huge chat it's a big request.

/context: how full it is

If you want to see how full the memory is, /context shows you: a colored grid of what's taking up space, from CLAUDE.md to the files it read. I look at it when Claude starts losing pieces, before deciding whether to start again.

4. Having it read every time

CLAUDE.md is the project's instructions file, the one Claude Code loads at the start of every session. If you don't have one, create it in the project's main folder, or have /init set one up. Then add this line:

@DECISIONS.md

With the @ in front, the file is loaded together with CLAUDE.md, even after a /clear. And after a compaction Claude Code re-reads the project's main CLAUDE.md from disk, so the decisions come back there too. The path starts from CLAUDE.md's folder: if the two files sit side by side, the name is enough.

Underneath it, add:

When we make an important decision, write it in DECISIONS.md.

That way the file grows while you work, not only when you remember. The summary prompt at the end of a piece stays as the check: that's where you see if something is missing. And the “Read DECISIONS.md” after a /clear becomes almost redundant, but I write it anyway: it tells Claude where to pick up from.

Worth knowing: with the @, DECISIONS.md goes into every session, even when it isn't needed. That's why it has to stay short. The same goes for CLAUDE.md: the docs recommend keeping it under 200 lines.

Extra: instructions for the automatic summary

If you want the automatic summary to keep the right things too, you can write a section in CLAUDE.md with instructions for compaction. Claude Code takes it into account when it summarizes:

# Compact instructions
When you summarize the conversation, keep the decisions, what's done and what's missing; skip the failed attempts.

The rule: short chats, long files. You throw the chat away, the file stays.

Common mistakes

• Waiting for the chat to fill up on its own: the automatic summary picks what to keep by itself. At the end of a piece, do the summary yourself and start again.
• Running /clear without updating DECISIONS.md first: what you decided stays only in the old chat. First the summary prompt, then /clear.
• Writing decisions without the reason: a week later they look like mistakes and Claude may “correct” them. Add the reason in parentheses.
• Letting DECISIONS.md grow like a diary: with the @ it goes into every session and takes up memory. One line per decision, and when one changes, rewrite that line.
• Using /compact to switch to a different job: you drag along a summary you don't need and pay for the re-read. When you change topic, /clear.

Checklist

• DECISIONS.md is in the project folder
• Every decision has its reason
• CLAUDE.md contains the line @DECISIONS.md
• At the end of a piece I use the summary prompt
• Before /clear the file is up to date
• /clear when I switch jobs, /compact only halfway through a piece

Frequently asked questions