Concept: Progressive Context Shaping
Progressive Context Shaping is an operational framework for managing long-running AI agent sessions (6, 8, 10+ hours) across single or multiple agent runs. Rather than relying on a static opening prompt or a massive static instruction manual, progressive context shaping dynamically updates a small, external, prioritized state file (e.g., current.md or a ticket board) as execution uncovers new information and refines human judgment.
The Core Problem: Context Inflation & Static Instruction Degradation
When AI models transition from answering simple questions to carrying out long-horizon work, static prompt engineering encounters severe failure modes:
- The Frozen Packet Fallacy: Initial prompts written before execution begins express only what the user knew at that moment. Multi-hour runs generate new evidence (dependency blocks, invalidated assumptions, unexpected edge cases) that make original instructions obsolete.
- Graveyard of Stale Rules: Squeezing comprehensive manuals or historical corrections into an initial system prompt crowds out the active task window, leading to rule collisions, performance averaging, or agents getting stuck in repetitive self-referential loops (see harness-design).
- Context Switching Limits: Human operators managing multiple long-running agents in terminal windows (such as codex or claude-code) experience severe cognitive overload when tracking session state purely in memory.
The Four Context Layers Framework
To maintain context hygiene across long multi-hour runs, progressive context shaping separates context into four distinct operational layers:
| Layer | Container Example | Purpose & Operational Rule |
|---|---|---|
| 1. Stable Instructions | claude.md, agents.md, project rules | Persistent rules, coding standards, required human approvals, and guardrails. Loaded consistently across runs. |
| 2. Current Project State | current.md, ticket board, JSON state | The Active Governer. Short, dynamically updated file stating current goal definition, active decisions, open questions, next action, and stop conditions. Overrides history. |
| 3. Context Map | contextmap.md, architecture map | Index pointing to available resources (design docs, research files, transcripts) so agents can load material on demand without loading everything upfront. |
| 4. History | decisions.md, git commit log, transcript | Chronological record of completed steps, failed attempts, and prior reasoning. Accessible when explicitly needed, but isolated from active instructions. |
Key Industry Implementations
1. OpenAI (1M-Line Codebase & OpenAI Symphony)
- 1,500 Pull Requests: Three OpenAI engineers shipped an internal product codebase exceeding 1,000,000 lines with zero human-typed code in ~1/10th traditional development time. They replaced a static instruction manual with a short map pointing to active execution plans, decision logs, architecture maps, and quality grades (see three-openai-engineers-shipped-a-million-lines).
- OpenAI Symphony: To solve the human cognitive limit of managing 3–5 simultaneous Codex sessions, OpenAI developed openai-symphony—a project board interface where agents pull tickets. Moving state into tickets increased landed PRs by 500% in 3 weeks.
2. Anthropic (Claude Code Progress Files)
- In long-running scientific computing, Anthropic uses portable progress files between fresh claude-code sessions. The file logs completed work, current state, and failed approaches with reasons (“helpful forgetting”). Fresh sessions inspect the progress file to pick up unfinished tasks without repeating failed attempts.
- Human vs. Agent Division: Anthropic’s study of ~400,000 Claude Code sessions revealed that human operators make ~70% of planning decisions (goal setting, evaluating new evidence), while Claude makes ~80% of execution decisions.
3. ARISE (Off-Transcript Plan Maintenance)
- In a multi-trace summary task, ARISE’s agent Alex executed 27 model calls, spending most iterations reorganizing its own to-do list because prompt rules were buried under tool outputs. arise solved this by moving the plan entirely outside the conversation window onto disk (
current.md) and rebuilding a concise plan message in front of history on every model call.
4. Bounded Execution Re-Steering (Nate B Jones Benchmark)
- During a 339-source benchmark run generating 1,000 questions, nate-b-jones observed Codex looping indefinitely in package synchronization. Rather than discarding the run, he updated
current.mdto prohibit unbounded generation and bounded the next run to process the 50 highest-value answers, successfully salvaging the run.
The Progressive Context Shaping Starter Kit
A standard workspace implementation utilizes four core markdown files:
readme.md: Explains the progressive context shaping workflow to the agent.current.md: Active execution state, active choices, open questions, and finish line criteria.contextmap.md: Map of all project assets, design documents, and source paths.decisions.md: Historical log of choices made and rationale behind them.