I opened a new Claude Code session and asked it to add a feature to a tool I'd been building for three weeks. It asked me what language the project was in.
Three weeks. Dozens of sessions. Hundreds of decisions. And the AI started from zero — as if we'd never met.
That's not a bug. That's how every AI coding agent works. Claude Code, Cursor, Windsurf, Copilot — every session is a blank slate. The agent can write complex systems in minutes, but it can't remember what you named the database table yesterday.
Most people solve this by re-explaining. They paste context into the first message. They describe the project. They remind the AI about conventions. Every single session.
Then they wonder why they're burning through their Max plan 5x allowance in two hours.
Every re-explanation is tokens. Every clarifying question the AI asks because it doesn't know your stack — tokens. Every time it suggests a migration you already rejected — tokens, plus the tokens you spend correcting it. You're not paying for work. You're paying for the AI to catch up to where it was yesterday.
There's a file that fixes this. And most people either don't have one, or they have one that makes things worse.
The Three Ways It Goes Wrong
After 60+ sessions building production tools, I've seen the same three mistakes — in my own projects and in every public repo I've checked.
1. The Empty File
No context file at all. Or something like:
# My Project
A web app built with Flask.
The AI knows nothing. It asks what framework you're using — again. It suggests PostgreSQL when you already chose SQLite — again. Every clarifying question eats into the context window you need for actual work.
2. The Kitchen Sink
The opposite extreme: 400 lines. Full README. Changelog. API docs. Dependency lists. Three paragraphs of project philosophy. Installation instructions the AI will never use.
This costs money directly. That file loads into the context window at session start. On API pricing, 400 lines is roughly 8,000 tokens — loaded before you've typed a word. Across 50 sessions, that's 400,000 tokens of instructions the AI re-reads every time. Most of it noise.
The AI doesn't need your API documentation. It can read the code. It needs your operating context — the decisions, patterns, and gotchas that aren't in the code.
3. The Stale Snapshot
A context file written two months ago that still references the database you migrated away from and the deployment target you abandoned.
This is the sneakiest failure mode. The AI generates code that looks correct but targets the wrong architecture. You don't catch it until the tests fail — or worse, until production breaks.
Stale context is worse than no context. No context makes the AI ask questions. Stale context makes it confident and wrong.
What Actually Works
The fix isn't "write a better prompt." It's context engineering — giving the AI the right operating context, compressed, current, and curated.
A working context file has seven sections:
- Project Summary — 2-3 lines. Stack, purpose, deployment target. Not what it could be. What it is right now.
- Architecture — One bullet per component. File name, what it does, what it connects to.
- Key Decisions — Things you've already decided. The AI should not relitigate these.
- Patterns & Conventions — How things work here. Not rules — descriptions of existing patterns.
- Gotchas & Pitfalls — Every gotcha entry is an hour of debugging you'll never repeat.
- Current Progress — Where you are right now. Not where you were two months ago.
- Context — Hardware, environment, constraints the AI can't infer from code.
Each section is compressed bullets with tags. The whole file stays under 100 lines. Everything loads fast, everything earns its place.
The difference between a project with this file and one without it is the difference between onboarding a new hire every morning and working with someone who was there yesterday.
The Playbook
I wrote the full system into a playbook — 8 chapters covering structure, cost discipline, security patterns, production gotchas, advanced features, and before/after transformations. Plus 6 copy-paste starter templates for different stacks (Python/Flask, Next.js, Rust, monorepo, Docker, solo dev).
It's built from 60+ real sessions shipping real tools, not theory.
If you're tired of re-explaining your project to your AI every session, this is the file that fixes it.
The CLAUDE.md Playbook — $12 on LemonSqueezy
Built by WebsationFlow. Zero-cost AI tools from consumer hardware.
Top comments (0)