Managing Context in Long-Running AI Agent Sessions
How progressive context shaping and current-state files help AI coding agents stay on track across multi-hour, multi-session runs.
Drafted with Claude from source material, checked by automated verification, and reviewed before release. How we make these.
What is progressive context shaping?
Progressive context shaping is a method for steering an AI agent across a long run, hours or days, by continually updating a small set of current-state instructions instead of relying on one giant upfront prompt. Instead of writing everything you know at the start and hoping it holds up, you keep a compact record of what’s true now: the active goal, the decisions made, the dead ends found, and what to do next. The agent reads that record before acting, so new information changes future work without requiring a restart.
This matters because agents now run far longer than a single chat exchange. Coding agents can work for six, eight, ten hours at a stretch, sometimes across multiple sessions on the same project. A prompt written before any of that work started can’t account for what the work itself reveals. The fix isn’t a better initial prompt. It’s a living one.
TL;DR
- Progressive context shaping means updating a small, current-state file as an agent run progresses, rather than trusting a single static prompt to hold up over hours of work.
- Stale instruction files become a liability, not a safety net. A giant manual of rules can turn into what one engineering team called “a graveyard of stale rules” that crowds out the actual task.
- Separating stable rules from current state matters. How-to-work guidance (approval requirements, coding standards) should live apart from what-to-do-now guidance (current goal, open decisions, next step).
- A simple markdown file often does the job. Tools like Claude Code and Codex support project files (claude.md, agents.md) that agents read at the start of a session and can update as work continues.
- Failed approaches should be recorded as consequences, not relived. A note saying a method failed and naming the replacement lets a new session skip the dead end instead of repeating it.
- You don’t need to log everything. Only decisions that change the goal or the definition of done belong in the current-state file. Explanatory detail belongs in history, not in active instructions.
- The same pattern shows up across different systems, including OpenAI’s internal coding work, Anthropic’s long-running scientific computing agents, and multi-agent frameworks that store plans outside the conversation window.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
Why does long-running agent work break down?
The failure mode is consistent across tools and teams: an agent given a large project and a big instruction file starts strong, then drifts. Either the original instructions become outdated as the work reveals new facts, or the sheer volume of accumulated conversation and tool output buries the actual task.
One documented example involved an agent asked to summarize multiple traces. During a single run, it made a large number of model calls, and nearly all of them went toward reorganizing its own to-do list rather than completing the assignment. The original request had been buried under tool output, intermediate results, and the agent’s own activity. Adding a stronger instruction at the top of the prompt didn’t fix it. The problem wasn’t the wording. It was that the current plan had no distinct place to live, separate from the noise of everything that had already happened.
This is the core tension in long-running agent work: a static packet of instructions sent at the start of a job doesn’t survive contact with a job that teaches you things as it goes. Research can weaken your original thesis. An early implementation can expose a dependency you didn’t know about. The first batch of results can show that the direction you chose produces a lot of output and very little value. At that point, defending the original prompt is the wrong move. The right move is changing what the agent treats as the current version of the assignment.
How do teams structure context for multi-hour agent runs?
A pattern shows up repeatedly, regardless of which company or tool is involved: replace one big static file with a small set of documents that stay current.
In one large-scale internal engineering project (a codebase that grew past a million lines, built entirely through agent-generated pull requests), a short map file pointed the agent toward active execution plans, decision logs, design documents, an architecture map, and quality assessments for different parts of the codebase. As the project evolved, those documents were updated. The agent didn’t need every historical instruction competing for its attention. It needed a reliable way to find the best current information for whatever it was about to do next.
A similar approach appears in long-running scientific computing agent work, where a progress file acts as portable memory between sessions. That file records the current state, what’s been completed, known limitations, and failed approaches along with the reason they failed. A new session reads the file, picks up the next task, and avoids repeating a dead end that already burned time in an earlier session.
In multi-agent systems, the same idea gets implemented by moving the current plan outside the conversation entirely and storing it on disk. Before each model call, the system rebuilds a short plan message from the latest state and places it ahead of the noisy conversation history. The agent sees what’s done, what’s in progress, and what’s next, without wading through everything that happened to get there.
Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
What should actually go in a current-state file?
Four distinct kinds of context tend to get mixed together in agent instructions, and separating them is most of the value of this method.
Stable instructions cover how to work: where files live, what actions require approval, and what quality standards apply. This is the kind of thing that belongs in a project rules file (claude.md in Claude Code, agents.md in Codex, or an equivalent in other tools) and doesn’t change often.
Current project state covers what the goal means right now: which decisions are active, what’s unresolved, what should happen next, and when the agent should stop. This changes as the work progresses and deserves its own space, distinct from stable rules.
The map covers what materials exist and where to find them: research files, design documents, prior drafts, transcripts. The agent doesn’t need all of this loaded at once. It needs a dependable way to locate the right resource for the decision in front of it. Skipping this layer is often why people end up pasting entire documents into a prompt out of habit.
History covers what happened before: why a decision was made, what was tried and abandoned, how to recover an earlier version. Git history, change logs, and decision logs belong here. History matters, but it shouldn’t be treated as current instruction. An agent needs the consequence of a failed attempt (this approach didn’t work, use this instead), not a replay of the entire failed attempt.
When should you update the current-state file?
Not every observation deserves a permanent update. A useful test: if a fresh agent picking up the work later would miss something you’d be annoyed about, it belongs in the current-state file. If a detail only explains how you got to a decision without changing the decision itself, it belongs in history instead.
In practice, this means updating the file after decisions that change the target, not after every step. A method that turned out to be unstable, a scope that narrowed after early results came back thin, an approval that opened up a previously blocked action: these all shift what “current” means and deserve to be written down. Routine progress, intermediate output, and exploratory dead ends that didn’t change direction can stay in the transcript or history log without cluttering the active plan.
One real-world case involved a benchmark-building project that discovered hundreds of sources, generated over a thousand questions, and produced a couple hundred verified answers before the agent got stuck in a loop, continuing itself during a synchronization step without adding value. The original instruction had encouraged continuous testing, which was useful early on but became counterproductive later. The fix wasn’t a new prompt from scratch. It was checkpointing the run, updating the state to prohibit resuming the open-ended loop, and redirecting the next pass toward a narrower, boundable task: select the highest-value answers, strengthen the evidence behind them, validate, and stop. All prior work stayed usable. Only the active direction changed.
- ✕a coding agent
- ✕no-code
- ✕vibe coding
- ✕a faster Cursor
The one that tells the coding agents what to build.
Is this different from just writing a better prompt?
Yes. A strong opening prompt still matters: it should define the desired result, name the materials the agent can use, set boundaries on what it can and can’t do, and specify what requires human approval. But an opening prompt is written before the work starts, so it can only reflect what you know at that moment. Progressive context shaping picks up where the opening prompt runs out, treating the assignment as something that gets revised as evidence comes in, rather than something to be defended as originally written.
Frequently Asked Questions
What is a current-state file in AI agent workflows?
It’s a document (often markdown) that records the active goal, current decisions, unresolved questions, and next steps for an ongoing agent project. The agent reads it before continuing work, so it always acts on the latest understanding of the task rather than outdated instructions from the start of the run.
Does this only work with specific tools like Claude Code or Codex?
No. The pattern has been implemented with claude.md and agents.md files, but also with plain markdown files, JSON records, ticketing systems, and issue trackers. The specific container matters far less than making sure the next action reads an updated version of the state.
How is this different from just having a longer context window?
A bigger context window lets an agent hold more information at once, but it doesn’t solve the problem of outdated or conflicting instructions competing for attention. Progressive context shaping is about keeping a small set of current, authoritative information ahead of everything else, regardless of how large the context window is.
How often should the current-state file be updated?
Only when something changes the goal, an active decision, or the definition of done. Routine progress or exploratory work that didn’t change direction can stay in a history log instead of cluttering the active state.
What happens to failed approaches or abandoned ideas?
They don’t need to be erased, but they shouldn’t sit at the same level as current instructions. Recording the failure and the reason it didn’t work, along with what replaced it, lets a new session skip the dead end without needing to relive the entire failed attempt.