Stop Re-Explaining Your Project to the AI Every Session
Every new Claude session starts blank, so you retell the project from the top. A short state file ends the ritual. Here's what to put in it and how to use it.
On this page · 8 sections
"OK, so, quick context: this is a tip-splitting app, it's in React Native, we're on the store listing now, and we decided yesterday not to do dark mode screenshots because…"
If you've typed some version of that paragraph more than twice this week, this post is for you.
It's part 2 of Working for the AI. Part 1 showed how you end up as your agent's assistant. This part fixes the most common chore: retelling the project every session.
The short answer#
- A new AI session knows nothing about yesterday, so without a written handoff you retell the project every time.
- A state file in the repo — goal, phase, next step, decisions, things not to do — replaces the retelling.
- Start each session with 'read the state file and continue the next step', end it with 'update the state file'.
- Decisions and dead ends are the most valuable lines, because they stop the agent from repeating yesterday's mistakes.
Why the retelling happens#
An AI session has no memory of the last one. Everything it knows comes from what's in front of it right now: your prompt, the files it reads, the tools it runs.
So the project history has to come from somewhere. If it isn't written down, it comes from you — every session, from the top, slightly differently each time. And "slightly differently" is how the agent ends up re-trying the approach you rejected on Tuesday.
Write the handoff once, in the repo#
Replace the retelling with a small file the agent reads itself. It doesn't need a special format; it needs the right lines:
# Tip Split — state
Goal: simple bill splitter, iOS + Android, free with one IAP.
Phase: 5/6 — store listing
Next: write captions for the 3 screenshots
Decided: no dark-mode screenshots in v1 · price tier 1 for the IAP
Tried and failed: auto-generating screenshots with the simulator script (fonts break)
Won't do: tipping presets per country (v2)
Six lines. Your agent can read them in a second, and they carry everything you were about to type.
The two lines people skip are the most valuable ones: Decided and Tried and failed. They are what stop the agent from walking back into yesterday's dead end. The broader idea is in memory lives in files.
Two prompts, every session#
The whole ritual shrinks to two prompts:
- Start: "Read
state.md, then continue with the next step." - End: "Update
state.md: new phase if it changed, new next step, anything we decided or ruled out."
The end prompt is the one people forget, and it's the one that makes tomorrow easy. Make it a habit before you close the terminal.
Keep it short or it stops working#
A state file that grows into a diary stops being read — by you and by the agent. A few rules:
- One screen maximum. Move history to a changelog; keep only what matters for the next step.
- Overwrite, don't append. "Next" is one line that changes, not a list that grows.
- One file per task or project, not one giant file for everything.
This is also the smallest possible version of a process: phase, next step, decisions — kept where the work is.
What changes when you stop retelling#
The first session of the day starts in seconds instead of minutes. The agent stops proposing things you already rejected. And you can hand the project to a new session — or a new machine — without losing anything, because nothing important lives only in a chat.
Keep reading#
Frequently asked questions
Why does Claude forget my project between sessions?
Each session only sees its own context. Unless the project state is written somewhere the agent reads, a new session starts with no knowledge of previous work.
What should a project state file contain?
The goal in one line, the current phase, the single next step, decisions already made, approaches that failed, and what is out of scope. Keep it short enough to read in a minute.
Isn't CLAUDE.md enough?
CLAUDE.md is good for rules that rarely change. Task progress changes every session, so it belongs in a separate state file the agent updates as it works.
Sources
Related reading
AI Tools & Models
Can't Find the Claude Session That Had the Fix?
You know the fix was in a chat last week, but which one? Why AI sessions get lost across projects, and a simple habit that makes the right one a click away.
AI Tools & Models
Memory Lives in Files, Not Chats: Managing AI Agent Context
Why AI coding agents lose the thread between sessions, and how a small state file in the repo lets any new Claude session resume exactly where work stopped.
AI Tools & Models
Your Claude Session Is on the Other Mac. Now What?
You started the work on your desktop and now you're on the laptop, where the AI session doesn't exist. How to move between machines without losing context.