The Cold Start Problem

Every AI session starts the same way: with nothing.

No memory of yesterday's breakthroughs. No recollection of the architecture decisions we made last week. No awareness that we've already tried three approaches that didn't work.

This is the cold start problem. And how we handle those first five minutes determines whether the session is productive or frustrating.

---

The Temptation

When we open a new session, the instinct is to dive in. We have momentum from yesterday. We know exactly what needs to happen next. So we type something like:

"Continue working on the data pipeline"

And then we wait. And the AI asks clarifying questions. And we explain. And it asks more questions. And twenty minutes later, we've burned through context just getting back to where we were yesterday.

Here's the thing: the AI isn't being difficult. It genuinely doesn't know. Every session is a blank slate.

---

What the AI Needs to Know

Before any AI assistant can help effectively, it needs context in three categories:

1. Project structure - What files exist? What's the architecture? Where does code live versus documentation?

2. Conventions - How do we name things? What patterns do we follow? What have we explicitly decided against?

3. Current state - What are we working on right now? What's blocked? What's the immediate next step?

Without this context, the AI will make reasonable guesses that happen to be wrong for our specific project. It might suggest a file structure we've already rejected. It might use naming conventions that clash with existing code. It might re-solve a problem we handled yesterday.

---

The CLAUDE.md Solution

The most effective pattern we've found is a project-level context file. We call it CLAUDE.md, but the name matters less than the practice.

The idea: maintain a single file that contains everything an AI needs to know to be immediately productive on this project.

Here's what goes in it:

# Project Name

## What This Is
One paragraph explaining the project's purpose.

## Directory Structure
Where things live. What each folder contains.

## Conventions
- Naming patterns
- Code style decisions
- Patterns we use
- Patterns we've rejected (and why)

## Current State
- What we're working on now
- Recent decisions
- Known issues
- Immediate next steps

When a session starts, the AI reads this file first. Instead of twenty minutes of catch-up, we get immediate productivity.

---

The First Five Minutes

With a CLAUDE.md in place, the session opening changes:

Before:

"Continue working on the data pipeline"

[20 minutes of context-building questions]

After:

"I need to add error handling to the API collector. The current implementation is in src/collectors/api.py. We discussed retry logic yesterday but haven't implemented it yet."

The difference goes beyond efficiency. It's accuracy. When we provide specific context upfront, the AI doesn't have to guess. It doesn't waste tokens exploring wrong paths. It doesn't suggest solutions we've already rejected.

---

What to Front-Load vs. Defer

Some context belongs in those first five minutes, but not everything. Context has a cost: every token of background is a token not available for actual work.

Front-load:

• File paths we'll be working with
• Relevant conventions and patterns
• Recent decisions that affect today's work
• Specific error messages or blockers

Defer:

• Historical context that's not immediately relevant
• Detailed explanations of code we're not touching
• Future plans that don't affect current work

The goal is minimum viable context: enough for the AI to be effective, not so much that we've exhausted the context window before doing any work.

---

Keeping CLAUDE.md Current

A stale context file is almost worse than no context file. If the AI trusts outdated information, it will confidently make wrong decisions.

The practice that works: update CLAUDE.md at the end of each session, not the beginning of the next one. When we're finishing up, we know exactly what changed. When we're starting fresh, we've already forgotten half of it.

What to update:

• Current state section (always)
• Conventions section (when we make new decisions)
• Directory structure (when we add major components)

What to prune:

• Completed tasks that no longer matter
• Rejected approaches that we've documented elsewhere
• Context that's now embedded in code comments

---

The Compound Effect

Here's what we've noticed after six months of this practice: the context file becomes a project history.

The git history tells us what changed. The CLAUDE.md tells us why. It captures decisions that don't fit in code comments. It preserves context that would otherwise exist only in our heads.

When we return to a project after a month away, the CLAUDE.md is often more useful than the code itself. It tells us where we were, what we were thinking, and what we planned to do next.

The cold start problem never fully goes away. But with good context hygiene, those first five minutes become a warm-up rather than a rebuild.

---

Practical Recommendations

1. Create CLAUDE.md before writing any code. Even a stub with project purpose and directory structure helps.
2. Update at session end, not session start. Capture context while it's fresh.
3. Keep the current state section ruthlessly current. This is what changes most and matters most.
4. Prune aggressively. Old context is noise. If it's not relevant to the next few sessions, archive it elsewhere.
5. Include what we've rejected. "We tried X and it didn't work because Y" saves future sessions from repeating mistakes.

The first five minutes set the trajectory for the entire session. Invest in them.

---

This is part of our series on AI-assisted research workflows. Next: End-of-Session Hygiene, covering what to capture before context resets.