# Your Agent Keeps Asking the Same Question It Already Answered Last Session

You finish a long session with Claude Code. You made three real decisions: which auth flow to keep, why the cache key must include the tenant id, and that the CSV exporter stays behind a feature flag.

You close the laptop. You come back tomorrow. You open a new session and ask the agent to keep going. The first thing it asks is whether to use JWT sessions or API keys.

You already settled that. Yesterday. Twice.

## The handoff problem nobody talks about

CLAUDE.md, AGENTS.md, project memory — all of it helps, but none of it is a real handoff. A project memory file answers *what is this codebase*. It does not answer *where we left off and what the next move is*.

So the agent does the only thing it can do: it re-derives the state from the codebase. And because code doesn't record the rejected alternatives, it re-litigates them. Every. Single. Session.

You lose 20 minutes per day explaining the same tradeoffs. Worse, the agent sometimes quietly picks the option you explicitly rejected yesterday, because the rejection lived in your head and in last night's scrollback, not in the repo.

## The file that actually works

We started keeping a short file at the repo root called `HANDOFF.md`. It is not a design doc. It is capped at about thirty lines and has exactly four sections:

1. **Last session ended on:** one line, the thing we just finished.
2. **Active decisions on the table:** bulleted, each one ending in *we chose X because Y*. No wishy-washy.
3. **Dead ends we already tried:** one line per wrong path, so the next agent doesn't walk down it again.
4. **Next command to run:** the exact shell command that picks up the thread.

That last section is the one that matters most. Without a concrete command, the next session starts by asking you what to do. With one, the agent runs it, reads the output, and continues.

## It has to be rewritten every session

The trap is treating HANDOFF.md like documentation. It isn't. It is a scratchpad that gets overwritten every time you close a long session. If you forget to update it, it rots fast — faster than CLAUDE.md, because it's supposed to be current.

The cheap discipline: spend the last minute of every session writing it. If the agent has been driving, ask it to write the handoff itself before it says goodbye. That forces it to actually summarize what it did, instead of just claiming it did it.

## Where this breaks down

Two failure modes we keep hitting:

One: the handoff becomes a diary. It rambles for two pages about what happened. Nobody — human or agent — reads two pages. Keep it under thirty lines. Cut anything that isn't a decision, a dead end, or a next command.

Two: the handoff doesn't survive a tool switch. If you write it for Claude Code and then open Cursor, Cursor ignores it by default. We ended up keeping it as a plain markdown file at the repo root so every agent tool can read it on demand. Tool-specific memory files don't cross tools; a plain file does.

That last part is also why we keep API contracts in a plain, spec-first format rather than inside any one tool's workspace. The contract is the one artifact that survives every session switch, every agent restart, and every tool we'll probably use next quarter. If you want to see what that looks like in practice, it's at [powerduck.com](https://www.powerduck.com/).

## Try it tomorrow

Before you close your next long agent session, spend sixty seconds writing four lines: where you stopped, what you decided, what you rejected, and the command that picks up. Watch how much faster the next session starts.

You'll spend less time re-explaining and more time actually moving.