The 3 Files That Make Claude Code Actually Remember
2026-03-11 · Jazz Lien
You're 40 minutes into a Claude Code session. You've explained the architecture, corrected the framework choice twice, and just realized it's trying to rebuild the auth you finished yesterday. Sound familiar?
The fix isn't better prompting. It's three files.
A bit about me
I've built 10+ projects with Claude Code over the past couple of months: web apps, mobile apps, data pipelines, AI tools. Some deployed to production with real users. Along the way, I kept running into the same friction: Claude forgetting context, making wrong assumptions, redoing finished work. These three files are what I landed on after enough pain to stop ignoring the problem.
The lifecycle
SPEC.md → CLAUDE.md → HANDOVER.md
before during between
coding every sessions
session
- CLAUDE.md -- "Here's how we work here." The rulebook Claude reads every session.
- SPEC.md -- "Build THIS, not that." The blueprint before you touch code.
- HANDOVER.md -- "Here's where I left off." The relay baton between sessions.
That's it. Three files, three problems solved. Let me show you what each one actually looks like in practice.
File 1: CLAUDE.md -- the rulebook that stops you from repeating yourself
Think of it as a README.md for Claude Code. Except it gets smarter over time.
This is the one you should set up first. If you already have a running project, start here.
The before/after
Without CLAUDE.md -- session 1 on a new project:
Me: "Add a loading skeleton to the gallery page"
Claude: *uses inline CSS*
Me: "No -- we use Tailwind here."
Claude: *adds an emoji icon to the button*
Me: "We use Lucide icons, never emojis in UI."
Claude: *puts the component in /pages*
Me: "It's /components. And it's App Router, not Pages."
Three corrections. Ten minutes wasted. Tomorrow it'll happen again.
With CLAUDE.md -- session 47 on that same project:
Me: "Add a loading skeleton to the gallery page"
Claude: *reads CLAUDE.md → knows Tailwind, Lucide icons, App Router,
component folder structure, even the learned rule about no emojis*
Claude: *gets it right first try*
The difference isn't Claude getting smarter. It's Claude having context.
What goes in it
Project overview, key commands, architecture, conventions. But the most powerful section is Learned Rules. Every time Claude makes a mistake, you add a rule:
### Rule 1: Icons over emojis in UI
- **Trigger**: Generated HTML with emojis for UI elements
- **Correct behavior**: Use Lucide/Heroicons SVGs. Emojis only in content text.
- **Date**: 2026-02-12
Every correction becomes permanent. No mistake happens twice.
When to write it
After initial project setup. Update it as rules accumulate. Claude reads it automatically at the start of every session. You never paste it.
The prompt
Read through this project's codebase and generate a CLAUDE.md that covers:
1. Project overview (what it does, tech stack)
2. Key commands (dev, build, test, deploy)
3. Architecture and folder structure
4. Coding conventions and patterns used
5. Error handling approach
6. Testing requirements
7. A "Learned Rules" section (empty for now -- we'll add to it)
Be specific to THIS project. Include actual file paths and real commands.
File 2: SPEC.md -- the conversation you have before writing code
What happens without one
I learned this the hard way. I sat down to build a podcast transcription pipeline -- audio in, transcripts and summaries out, published to a static site. Simple enough, right? I told Claude "build me a podcast pipeline" and started coding.
First session: Claude picked Flask. I wanted FastAPI. It set up a relational database. I needed Firestore. It structured the output as a single JSON blob. I needed per-episode markdown files with frontmatter. It generated a REST API. I needed a CLI that runs on a cron job.
They were wrong for my project. And I didn't realize how many assumptions Claude was making until I was three files deep, undoing scaffolding that looked professional but solved the wrong problem.
That first session? I spent more time correcting architecture than building features. The second session, Claude forgot the corrections and made half the same choices again.
What a good spec looks like
I later found a well-written spec from another project. A structured decision record:
- A tech stack table with why each choice was made
- A folder structure tree showing where everything lives
- ASCII wireframes for each page layout
- API endpoint specs with input/output shapes
- A priority list (P0 = must ship, P3 = nice to have)
That spec was handed to Claude Code and the first session just... worked. No corrections. No "actually, I meant..." because the decisions were already made.
When to write it
Before any code. Have Claude help you draft it. It's great at asking the right scoping questions. Once building starts, SPEC.md is read-only: a snapshot of intent, not a living doc.
The prompt
I'm about to build a new project: [describe the idea in 2-3 sentences].
Before we write any code, help me create a SPEC.md that covers:
1. Tech stack selection (with reasoning)
2. Data sources and APIs
3. Project folder structure
4. Page/screen designs (ASCII wireframes)
5. Key component and API specs
6. UI/UX design system (colors, typography, component style)
7. Environment variables needed
8. Deployment plan
9. Development phases with priorities (P0/P1/P2/P3)
10. Constraints and known limitations
Be opinionated. Challenge my choices if there are better options.
File 3: HANDOVER.md -- the relay baton
The pain
You're deep into a refactor, halfway through migrating an auth system from one library to another. The old JWT validation is ripped out, the new one is half-wired, and three files are in a state that would break if you stopped now. Then the context window compacts. Or you need to close your laptop and pick this up tomorrow.
The new session has no idea what just happened. It re-reads the codebase, sees the half-migrated auth, and tries to "fix" it by reverting to the old library. Or it re-does work the previous session already finished. Or it makes a different architectural choice that contradicts what you decided an hour ago.
I hit this wall during a cleanup sprint across multiple projects. I was refactoring dead code, consolidating duplicates, rewriting docs. The kind of work that spans dozens of files and can't be understood from a cold read of the codebase. Without handovers, every new session would open with "what needs cleaning up?" and re-investigate from scratch. With handovers, each session picked up exactly where the last one stopped: "Phase 1 (folder cleanup) is done, Phase 2 (dead code removal) is in progress, here are the 4 files left to touch."
The relay protocol
Think of it as a relay race, not a diary:
Agent A: *approaching context limit*
→ writes HANDOVER.md (what's done, what's next, gotchas)
Agent B: *new session*
→ reads HANDOVER.md
→ deletes HANDOVER.md ← THIS IS CRITICAL
→ continues the work
→ approaching limit? writes a fresh HANDOVER.md for Agent C
Why delete? Because a stale handover from two sessions ago will poison the current one. The baton is ephemeral. Pick it up, throw it away, keep running.
The prompts
When hitting context limit (tell the current session):
We're approaching the context limit. Write a HANDOVER.md for the next session:
1. What we accomplished this session
2. Current state (what works, what's broken, what's half-done)
3. Exact next steps with file paths
4. Decisions made and why
5. Gotchas or context the next agent absolutely needs
Be specific -- the next agent has zero context about our conversation.
Starting a new session:
Read HANDOVER.md, then delete or clear the file.
Continue the work from where the previous session left off.
The setup checklist
For your next project:
- Write SPEC.md before any code (or have Claude draft it with you)
- Generate CLAUDE.md after initial setup
- Use the HANDOVER.md relay whenever sessions get long
Claude Code is as smart as the context you give it. These three files are that context.
What's next
These three files handle the project level: what to build, how to build it, and how to hand off between sessions. But there's a deeper layer: teaching Claude Code who you are.
Part 2 covers three more files:
- soul.md -- Your background, communication style, and values. The file that stops Claude from being a yes-machine.
- Hooks -- Branch protection, auto-linting, auto-testing. The automation layer that catches mistakes before they land.
- MEMORY.md -- Cross-project memory that accumulates over time. The long-term brain.
If the three files in this article make Claude remember your project, the next three make Claude remember you.