In this guide
Every AI coding tool has a finite context window. On projects that span many sessions, agents can silently lose track of earlier decisions — leading to inconsistent architecture, duplicated work, or 'fixes' that undo previous ones. This guide covers practical techniques to keep an agent oriented across a long build.
The underlying principle is simple: never rely on the conversation alone to hold state that matters. Externalise it.
Why context loss happens
As a conversation grows, older messages fall outside the model's effective context, and details from early in the build stop influencing its decisions. The agent is not 'forgetting' in a human sense — the information is simply no longer in front of it. The fix is to keep the important state somewhere durable that the agent re-reads.
Keep a living checkpoint file
Maintain a single markdown file in your repo — CHECKPOINT.md or PROGRESS.md — that captures the project's durable state: architecture decisions, completed features, file locations, and open TODOs. Instruct the agent to read it at the start of each session and update it at the end.
# Project checkpoint
## Architecture
- Frontend: React + Vite + Tailwind
- Backend: Supabase (auth, Postgres, storage)
- Payments: Stripe (subscriptions)
## Done
- Auth + RLS on all user tables
- Task CRUD with per-user isolation
## In progress
- Stripe checkout (webhook handler not done yet)
## Decisions
- Dates stored as UTC ISO strings
- No server state in components; data fetched per pageTip
Start new sessions with: 'Read CHECKPOINT.md before doing anything, and update it when you finish.' This single habit prevents most cross-session drift.
Split large features into independent increments
Instead of one enormous prompt for an entire feature, break it into steps that each reach a working, testable state. Smaller increments keep each individual context window focused, make verification easy, and give you natural commit points. This is the same discipline that makes agentic editing reliable — it just matters even more on long builds.
Use scope-lock prompts
Scope creep is one of the biggest silent context-window killers. When an agent 'improves' unrelated code, it spends context and risks breaking working features. Counter this explicitly by telling the agent to change only what the task requires.
Note
A ready-to-use Scope Lock prompt lives in our Prompt Vault. The core instruction: 'Only modify what is strictly necessary. Do not refactor, rename, or improve unrelated code. If a broader change seems needed, explain why before touching anything outside the immediate scope.'
Key takeaways
- Never rely on the conversation alone for state that matters — externalise it.
- Keep a CHECKPOINT.md the agent reads at the start and updates at the end of each session.
- Break large features into small, independently working increments.
- Use scope-lock prompts to stop the agent expanding tasks and burning context.
Frequently asked questions
As a conversation grows, earlier messages fall outside the model's effective context window and no longer influence its output. The information is not deleted — it is simply out of view. Keeping durable state in a file the agent re-reads solves this.