I wrote recently about context hygiene — the idea that managing what an LLM knows is more important than how cleverly you prompt it. That post was theory. This one is the implementation.

I've been using Claude Code as my primary development environment for a few months now. It's genuinely good. But I kept hitting the same wall: by session three of any project, Claude would start suggesting things that contradicted decisions we'd made on day one. Not because it's dumb — because those decisions were buried under hundreds of messages about CSS bugs and Docker volumes.

So I rebuilt my starter prompt from scratch around one principle: the AI shouldn't carry project state in its head. It should carry it in files.

The problem with conversational memory

My original starter prompt was solid. It defined roles (Claude as tech lead, me as business stakeholder), laid out a discovery process, specified communication protocols. It produced a CLAUDE.md file as the project's governing document. Standard stuff.

What it didn't do was address what happens after hour four. Or session two. Or the point where you've exchanged 200 messages and the initial architecture decisions are now competing for attention with a debug session about why your SVGs aren't rendering in Docker.

The CLAUDE.md was a good start — it captured the what of the project. But there was no system for capturing the ongoing state: decisions made along the way, current progress, what happened last session that needs to carry forward.

Five files instead of one

The new prompt establishes five .md files as the project's external memory:

CLAUDE.md stays as the project constitution — stakeholder profile, business objectives, engineering standards, communication protocols. This gets written once after discovery and rarely changes. It's the "who are we and what are we building" document.

PROGRESS.md is a living build log. What's done, what's in progress, what's next, what's blocked. Updated after every completed task, not batched at the end of a session. This is the file that answers "where are we right now?" without having to reconstruct from conversation history.

DECISIONS.md is an architecture decision record. Every significant technical choice gets logged with rationale and alternatives considered. This is the file that prevents the single most annoying pattern in long AI projects: re-litigating settled decisions. When Claude suggests switching from PostgreSQL to MongoDB in session four, DECISIONS.md has the entry from session one explaining why we chose Postgres and what we considered.

TECHNICAL.md captures implementation details — stack, API contracts, data models, infrastructure. It's the engineering handoff document. Not for stakeholder consumption, but essential for maintaining technical coherence across sessions.

HANDOVER.md is the session transition document. Written at the end of every session, overwritten each time. Current state of the active task, decisions made this session, constraints that must carry forward, concrete next steps. This is the file that makes "start a fresh session" actually work instead of starting over from scratch.

The protocol matters more than the files

Having the files isn't enough. The original prompt already had CLAUDE.md and it still suffered from context rot. What changed is the protocol around them.

Session start: The prompt requires reading CLAUDE.md, PROGRESS.md, and HANDOVER.md before doing anything else. Not "consider reading" — it's a hard requirement. This takes 30 seconds and prevents the first hour of a new session from being wasted on re-establishing context.

During work: PROGRESS.md gets updated after every completed task, not at the end. Decisions get logged to DECISIONS.md as they're made. This sounds tedious but it's actually faster — it takes five seconds to append a line, and it saves the 20-minute "wait, didn't we decide to use JWT instead of sessions?" conversation later.

The 10-15 exchange checkpoint: Every 10-15 messages, the AI does a silent self-check against CLAUDE.md. This catches drift early. It's the context management equivalent of running your tests frequently instead of waiting until the end.

Before big tasks: Before implementing anything significant, the prompt requires re-reading the relevant decisions and constraints. This is the "re-anchoring" pattern from my context hygiene post, formalized into the workflow.

Session end: HANDOVER.md gets written. No exceptions. This is the hardest habit to build because it feels like overhead when you're in the middle of something. But it's the single highest-leverage practice. A clean context window with a good handover consistently outperforms a bloated 4-hour conversation.

What I kept from the original

The role definition still works well. Claude as tech lead, stakeholder as domain expert. The key rule: never ask the stakeholder for technical input. This prevents the "should I use React or Vue?" question that no business stakeholder should have to answer.

The discovery phase is unchanged — structured but conversational, 1-2 questions at a time, probing deeper where needed. The CLAUDE.md template is the same, with its sections on communication protocols, technical authority, engineering standards, and quality assurance.

The stakeholder decision framework is the same too: engage only when decisions impact business outcomes or user experience. "Mobile optimization adds three days — is cross-device access essential for launch?" is a stakeholder question. "Should we use Express or Fastify?" is not.

What's different in practice

The biggest change is that projects feel continuous now instead of episodic. Before, each session was partially a reconstruction project — spending the first 20 minutes getting Claude back up to speed. Now, a fresh session reads the files and is productive within the first exchange.

The decision log has been surprisingly valuable. Not just for preventing re-litigation, but as a reference for myself. Three weeks into a project, I sometimes forget why we chose a particular approach. DECISIONS.md has the answer with context I wouldn't have remembered.

The forced handover also changed how I think about session length. I used to push through long sessions, fighting context degradation. Now I actively prefer shorter sessions with clean handovers. Four focused 90-minute sessions beats one marathon 6-hour session where the last two hours are spent fighting drift.

Grab the prompt

I've published the full starter prompt as a downloadable file: STARTPROMPT.md

It's designed for Claude Code but the pattern works with any LLM that can read and write files. The core idea — external state files with explicit read/write protocols — is model-agnostic. The specific implementation (five .md files, checkpoint cadence, handover format) is what I've found works after iterating on it across several projects.

Use it as-is or adapt it. The important thing isn't the exact file structure — it's the principle that your AI collaborator's memory shouldn't live in a conversation that degrades over time. It should live in files you control.