I wrote recently about context hygiene, the idea that managing what an LLM knows matters more than how cleverly you prompt it. That post covered the theory. This post covers the implementation.

I've been using Claude Code as my primary development environment for a few months, and it is genuinely good. But I kept hitting the same wall: by session three of any project, Claude would start suggesting things that contradicted decisions we had made on day one. The cause was not a lack of capability. Those decisions were buried under hundreds of messages about CSS bugs and Docker volumes.

So I rebuilt my starter prompt around one principle: the AI should not carry project state in its head, it should carry it in files.

Conversational memory limits

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

What it did not do was address what happens after hour four, or session two, or the point where you have exchanged 200 messages and the initial architecture decisions are competing for attention with a debug session about why your SVGs are not 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, and what happened last session that needs to carry forward.

External memory files

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, and communication protocols. It is written once after discovery and rarely changes. It answers "who are we and what are we building."

PROGRESS.md is a living build log: what is done, in progress, next, and blocked. I update it after every completed task rather than batching at the end of a session. It answers "where are we right now?" without reconstructing from conversation history.

DECISIONS.md is an architecture decision record. Every significant technical choice is logged with its rationale and the alternatives considered. It prevents a common 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, and infrastructure. It is the engineering handoff document. Stakeholders do not need it, but it keeps the technical work coherent across sessions.

HANDOVER.md is the session transition document. I write it at the end of every session and overwrite it each time. It records the current state of the active task, decisions made this session, constraints that must carry forward, and concrete next steps. It is what makes starting a fresh session work instead of starting over.

Read/write protocol

Having the files is not enough. The original prompt already had CLAUDE.md and 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. This is enforced as a hard requirement. It takes 30 seconds and keeps the first hour of a new session from being wasted on re-establishing context.

During work: PROGRESS.md is updated after every completed task rather than at the end. Decisions are logged to DECISIONS.md as they are made. This sounds tedious but is faster in practice: appending a line takes five seconds and 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, the same way running tests frequently catches regressions before the end of a task.

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 every time. This is the hardest habit to build because it feels like overhead when you are in the middle of something, but it is the practice that pays off most. A clean context window with a good handover consistently outperforms a bloated 4-hour conversation.

Retained 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 affect 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.

Practical results

The biggest change is that projects feel continuous now instead of episodic. Before, each session was partly a reconstruction project: the first 20 minutes went to 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, both for preventing re-litigation and 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 would not 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 prefer shorter sessions with clean handovers. Four focused 90-minute sessions beat one 6-hour session where the last two hours go to fighting drift.

The prompt file

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

It is 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, meaning five .md files, a checkpoint cadence, and a handover format, is what I have found works after iterating across several projects.

Use it as-is or adapt it. The file structure matters less than the principle behind it: your AI collaborator's memory should live in files you control, not in a conversation that degrades over time.