Progressive Context Shaping for Long-Running AI Agents

The Failure of Static Context

Long-running agent tasks often fail because the initial prompt becomes a "graveyard of stale rules." As an agent progresses through hours of work, the original instructions—written before the agent discovered dependencies or hit dead ends—begin to conflict with the actual state of the project. Simply increasing context window size does not solve this, as the agent struggles to distinguish between outdated instructions and current execution priorities.

Progressive Context Shaping

To maintain control over multi-hour or multi-session agent runs, developers should implement "progressive context shaping." This technique separates the agent's memory into four distinct categories:

• Stable Instructions: High-level rules, standards, and approval boundaries that rarely change (e.g., agents.markdown).
• Current Project State: The active plan, unresolved questions, and the definition of done. This is the most critical file and must be updated after every consequential decision.
• The Map: A directory of resources, research files, and design documents. The agent should be able to index these rather than having them all loaded into the active prompt.
• History: Transcripts, logs, and version history. This provides context on why a decision was made, but it should not be treated as the current instruction set.

Implementation Strategy

Instead of forcing an agent to navigate a noisy history of tool outputs and intermediate results, move the "current plan" to a dedicated file on disk. Instruct the agent to read this file at the start of every session and update it after every significant milestone.

• Use a checkpoint-based workflow: Do not ask for the entire project in one run. Define an early, verifiable checkpoint (e.g., "compare sources and propose a plan") to force the agent to produce evidence you can review.
• Maintain a 'Current' file: Use a simple file like current.markdown. When the agent reaches a checkpoint, review the output and explicitly instruct the agent to update the file: "Update the current project state so that this evidence replaces our earlier assumption, then continue."
• Delegate planning: Aim for a split where the human defines the goal and the new evidence, while the agent handles the execution path. If the agent's original objective (e.g., "keep generating questions") becomes unhelpful, stop the run, update the state file to reflect a new, bounded goal, and restart.