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 pageSplit 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.
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.
Common questions
Why do AI coding agents ‘forget’ earlier parts of a project?
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.
What should go in a checkpoint file?
Architecture decisions, completed features, key file locations, open TODOs, and any conventions the project follows. The goal is that an agent reading only this file could continue the project consistently without the prior conversation.
What is a scope-lock prompt?
An instruction that tells the agent to change only what the current task requires and not to refactor or ‘improve’ unrelated code. It prevents scope creep, which wastes context and risks breaking working features on long builds.
The Claude Code side of this, with commands, is in how to use Claude Code.