The Memory Problem Everyone Hits
It usually shows up around week two or three of a serious AI-assisted project. You've been building good things. Sessions have been productive. But now, when you open a new session, you spend the first 20 minutes re-explaining. What's the project? What's already built? What are the webhook URLs? What's the Airtable schema? What conventions did we decide on last time?
Every answer to those questions is context that Claude needs before it can do useful work. And every session, it's gone. Not degraded — completely gone. Claude starts fresh every time you open it.
The naive fix is to paste in a summary at the start of each session. That works, sort of, but it means you're maintaining a summary in your head and manually rehydrating the AI every time. It's the kind of friction that compounds invisibly — each session starts a little slower, you skip a few context details because it feels tedious, the output quality drifts because Claude is working with incomplete information.
The real fix is a reference document. A single file that contains the full state of your project — architecture, URLs, conventions, schemas, what's been built, what's in progress — versioned alongside your code and loaded at the start of every session.
What Goes In the Reference Document
My reference doc is a markdown file called lance-site-reference.md, living at the root of my repo. It's not a README — it's not for public consumption. It's a technical state document for Claude. Here's what it covers:
Site Architecture
The directory structure, what each folder contains, naming conventions for blog post files, where the apps live, how the staging folder works, what's gitignored and why. Claude Code can read the actual files, but the reference doc gives it the architecture at a glance — saving the time it would take to infer structure from exploration.
All Webhook URLs and API Keys
The exact Make.com webhook URLs for each app. The newsletter subscription webhook. The GA4 tag ID. The affiliate link with the correct referral code. Claude doesn't need to guess or ask — it reads the doc and knows. This also prevents the wrong values from making it into generated files, which was a real failure mode before the doc existed.
Make.com Scenario Map
A field-level breakdown of every active Make.com scenario: what triggers it, what modules it contains, what Airtable table it writes to, what the output is. When I'm building a new scenario or debugging an existing one, Claude has the full map. No re-explaining the automation architecture every session.
Airtable Schema
Every table, every field, every field type. When Claude writes a Make.com module that saves to Airtable, it knows exactly what the table looks like. Field names match. Types match. No guessing.
Blog and Content State
A list of all published posts, what's in staging, what topics are in progress. The voice guidelines summary. The blog-post skill configuration. When I start a content session, Claude knows what's already been written and doesn't suggest duplicates.
Design System Reference
The CSS custom property names, the color palette, the font choices, which components exist and what they're called. When Claude generates a new page or component, it uses the actual design system rather than inventing its own conventions.
How I Actually Use It — Session by Session
In Claude Code (VS Code), the reference doc is in the repo, so Claude can read it directly. When I start a session focused on a specific area of the site, I'll often point Claude at the reference doc explicitly: "Read the site reference first, then let's work on X." It reads the file, confirms it has the context it needs, and we're building within the first exchange.
In Claude Cowork sessions, I paste the relevant sections as context at the start. The doc is structured so I can pull just the section I need — the Make.com scenario map for an automation session, the Airtable schema for a data structure session — without overwhelming the context window with everything at once.
The key habit that makes the system work: update the doc whenever the project state changes. New app deployed? Add it to the apps list and webhook URL table. New Make.com scenario built? Add the module map. New blog post published? Update the content state. At the end of every productive session, I ask Claude to update the reference doc to reflect what we built. Takes 2 minutes. Saves 20 minutes the next time.
The CLAUDE.md Layer
Claude Code specifically supports a file called CLAUDE.md at the root of your project — a special context file that Claude Code reads automatically when it starts. Think of it as the Claude-Code-native version of the same idea.
My CLAUDE.md contains the things that apply to every session — the project overview, the deployment model, the code conventions, the webhook security requirement. It's the standing instructions layer. The site reference doc is the state layer — it reflects where the project is right now. Together, they give Claude everything it needs to work at full effectiveness from the first message.
If you're using Claude Code and haven't set up a CLAUDE.md, start there. It's the lowest-effort version of this system — 30 minutes to write, pays off immediately, and Claude Code reads it without you having to ask.
What This Makes Possible
The reference doc isn't glamorous. It doesn't ship a feature. It doesn't produce an artifact you can show someone. But it's the thing that makes everything else in this system work, because it's the thing that makes sessions coherent across time.
Without it, every session is a fresh start. With it, every session picks up where the last one ended. The distinction compounds: over dozens of sessions, the sessions-with-reference-doc version of your project is dramatically more advanced than the sessions-without version, simply because you didn't burn 20% of every session re-establishing ground truth.
It's also the thing that enables the blog-post factory to work reliably — the factory reads the voice guidelines and correct URLs from the reference doc, which is why the generated posts have the right values. And it's the reason the 16-module Make.com automation could be iterated on across multiple sessions without re-explaining the Airtable schema every time.
If you're going to invest in one thing before starting a serious AI-assisted build, invest in this. The reference doc is the foundation. Everything else is built on top of it.
How to Start Yours in Under an Hour
You don't need a perfect reference doc to start. You need a good enough one that gets better over time. Here's a starting structure:
- Project overview. One paragraph: what you're building, what it runs on, how it deploys.
- Key URLs and credentials. All webhook URLs, API keys, external service links that appear in your code.
- Directory structure. What's in each folder. What's gitignored. Where new files should go.
- Active integrations. Every external service connected: what it does, how it connects, what data flows through it.
- Current state. What's built and live. What's in progress. What's planned next.
Write that in a markdown file. Put it in your repo root. Point Claude at it at the start of your next session. Then update it at the end of the session. That's the entire system. It sounds too simple to make a significant difference — it isn't.
Once you have this running, explore what Claude Code inside VS Code makes possible when Claude has this context in its own environment. The combination of a good reference doc and Claude operating directly in your files is where the real leverage is.