Here's the problem nobody talks about until it bites them.
You start a project. Claude is locked in. Responses are tight, relevant, actually useful. You're moving fast.
Then you hit session three. Or five. Or you come back after a weekend. And suddenly Claude is giving you generic answers. It's lost the thread. You're re-explaining decisions you already made two weeks ago. The momentum dies.
This isn't a Claude problem. It's an information architecture problem. And it's fixable.
Why This Happens
Claude doesn't remember between sessions. You know this. But the deeper issue is that most builders don't have a system for what to hand it when they start a new conversation. They just dump the last few messages or paste in some code and hope for the best.
That approach works on day one. It falls apart by week two.
The project grows. There are decisions made, patterns established, edge cases discovered, tech debt acknowledged. None of that lives in the current chat window. So Claude operates blind, and you get answers that technically make sense but don't fit your actual project.
What Actually Works: The Handoff Doc
Think of it like a briefing document you'd give a contractor who's joining mid-project. Not a full spec. Not a README. Something in between.
I keep one file per project. It lives in the repo root. I call it CONTEXT.md. It's not the same as a CLAUDE.md with coding rules. This one tracks the state of the project, not just the standards.
Four sections. That's it.
1. What This Is
Two to three sentences. What are we building, who is it for, what does it need to do. Not marketing copy. Just the facts.
"This is a client portal for a small law firm. Users log in, view their case documents, and message their attorney. It needs to feel simple because the client base is not technical."
2. Decisions Already Made
This is the section most people skip. It's the most important one.
Every project has forks in the road. You chose Next.js over Remix. You went with Supabase over PlanetScale. You decided to skip auth and use magic links. You said the MVP won't have notifications.
These decisions live in your head. Not in the codebase. When Claude doesn't know them, it'll suggest alternatives or build things that conflict with the choices you already made.
Write them down. One line each. No need to explain every tradeoff unless it's important.
3. Current State
Where is the project right now? What's done, what's in progress, what's blocked.
This is the section I update most often. Even a quick two-sentence update at the end of a session saves real time next time I open a chat.
"Auth is done. Document upload works but needs error handling. Haven't started the messaging feature. Stripe is blocked waiting on client's account details."
Claude can now orient itself without you narrating the whole timeline.
4. Known Issues and Accepted Debt
This one saves me from Claude "fixing" things that are intentionally broken or intentionally deferred.
If you know the search is slow and you're not dealing with it until post-launch, write it down. If there's a hacky workaround in the auth flow that you're aware of, note it. Claude will stop trying to refactor things you've already consciously decided to leave alone.
How to Use It in Practice
Every new session, paste the CONTEXT.md at the top before anything else. That's it. Not the whole codebase. Not the whole chat history. Just this file.
I usually open with something like:
"Here's where we are on this project. Read this first, then I'll tell you what I need today."
Takes ten seconds. Saves thirty minutes of Claude being half-lost while I try to re-establish context organically.
Keeping It Updated Without Hating Your Life
The system breaks if updating the doc feels like a chore. So I keep it minimal.
I don't update it mid-session. I update it at the end, when I'm about to close the tab. Two minutes max. What changed today, what's the current state, anything new to the decisions or debt section.
Sometimes I just ask Claude to do it:
"Based on what we built today, update the Current State section of this CONTEXT.md."
It does a decent job. I skim it and adjust if needed. Done.
When Projects Get Complex
For bigger builds, one CONTEXT.md isn't always enough. If you've got multiple agents, multiple services, or multiple workstreams running, you need context scoped to each area, not one massive doc that's overwhelming to parse.
The solution is nested context files. A root-level doc for the project as a whole, and sub-docs for specific modules or agents. Each one follows the same four-section format.
When you're working in a specific area, you hand Claude the root doc plus the relevant sub-doc. Not everything. Just what's needed for the task at hand.
The full prompt system, the sub-doc pattern, and the exact language I use to keep Claude from going off-script are behind the gate above. That's the kind of detail we get into inside Inner Circle, where the actual workflows live.
