# 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.

- URL: https://shotmatic.app/blog/stop-re-explaining-your-project-to-ai
- Category: Agent Context
- Published: 2026-10-04
- Author: Tu Nguyen

## Key takeaways

- 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.

*"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](https://shotmatic.app/blog/working-for-your-ai-agent) showed how you end up as your
agent's assistant. This part fixes the most common chore: retelling the project every session.

## 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:

```markdown
# 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](https://shotmatic.app/blog/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](https://shotmatic.app/blog/no-process-just-prompts): 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.

## Where ShotMatic fits

ShotMatic reads the phase, next step and notes your agent keeps in `progress.json` and shows them as one line
per task. When you press ✦ on a task with no saved session, it starts a new Claude session with that context
already written into the first prompt — no retelling.

## FAQ

**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.