Context engineering for long agent runs: CLAUDE.md, AGENTS.md and a current-state file

Transcript

3 engineers at OpenAI shipped an internal product in about a 10th of the time it would’ve taken by hand. Roughly 1,500 pull requests. It was a codebase over a million lines by the time they were done. Not a line of it was typed by humans. A few days ago, I made a video arguing that you should effectively keep your agent’s desk neat and tidy if you wanted it to do useful work. I’m gonna continue that in this video, but I’m gonna talk about the biggest, boldest things we do with agents today.

The long-running work we do, maybe over multiple agent sessions, over 6 hours, 8 hours, 10 hours more. And I’m gonna tell you the secret of how good engineers and good builders manage those sessions and how you can too. And hint, it’s not just by keeping your metaphorical desk clean. The set of files that you want to get all of this to work for you is over on the Substack. I’ll tell you all about it at the end of the video. But before, I wanna give you why it works and I wanna give you the principles so that you understand regardless of how you use agents or whether you work with Codex or Claude, how to actually do the work of shaping agent runs and accomplishing ambitious projects.

3 engineers at OpenAI shipped an internal product in about a 10th of the time it would have taken by hand. Now, that sounds great, but that’s not the real story. Yes, it was a big project, roughly 1,500 pull requests. It was a codebase over a million lines by the time they were done. And yes, of course, not a line of it was typed by humans. Now, individual Codex run that that team pursued ran for more than 6 hours, if not longer at a stretch.

And as it was running, the team hit a context problem that anyone who’s running agents is going to recognize. A giant instruction file that you give an agent for a run like that will crowd out the task, and a huge manual for the project as a whole will turn into, in their words, a graveyard of stale rules. In other words, how do you give the agent direction so you can accomplish a giant, giant project without causing that project in its own rules to overwhelm the agent. By the end of this video, you’re going to know how to start one of these long projects before you know every step, how to change the direction without restarting, and how to make that correction reach the work the agent hasn’t done yet, how to steer it as it goes. More capable agents increase the reach of your judgment. They also increase the cost of leaving an outdated judgment in charge.

So this method works across Claude, across Codex, and across ordinary long conversations you have with AI because the current state can live beyond any single session. I think this matters more than the headline context window number because it changes what you can safely put into motion.

OpenAI replaced that giant manual I told you about with a very short map. The map pointed Codex toward active execution plans, toward decision logs, toward design documents, toward an architecture map, and quality grades for every part of the codebase it was touching. As the product evolved, those materials changed along the way, so they formed an accurate map of the current state of execution as the giant codebase rebuild progressed. So the agent didn’t need every old instruction competing for attention. It needed a reliable way to find the best current information for the next piece of work.

Anthropic has arrived at a similar practice with Claude. In its work on long-running scientific computing, Claude Code uses a progress file as portable memory between sessions. That file records the current state. It records completed work. It records known limitations and failed approaches with the reason they failed, so a new Claude session can read it, pick up the next task, and avoid walking into the same dead end on a giant project. Anthropic uses the same basic pattern in its long-running agentic coding harness: a progress file, structured handoffs, and version history that let fresh sessions continue that job.

These are different companies; they’re different systems, but they’re responding to the same change. AI is moving from producing an answer to carrying work that develops over hours and days and many, many separate runs. Once that happens, context can’t remain sort of like a frozen packet from the beginning of the job that you send out in a rocket. It doesn’t work that way. It has to change as the work teaches you what the job actually is. The stakes are very high, right?

A long-running agent can take a useful direction much, much farther than a chatbot would. It can also take a slightly wrong direction through 6 hours of research and code and analysis and drafts before you realize how far off base you are.

So I call this practice progressive context shaping. You begin with a clear brief, sure, but then you change the small set of instructions and decisions that should govern what happens next as the work continues to produce evidence along the way. That small current state receives priority over everything that happened along the way.

Good prompt engineering absolutely still matters. A strong opening prompt should define the result that you want. It should identify the materials the agent can use. It should set the boundaries on what it may do and may not do and give it a very sensible first move to try. If you know what quality looks like, you should say so in the instruction set. If publication or spending or deletion or contact with another person requires approval, that’s another thing you should write down and say.

The opening prompt gives the agent enough direction to begin useful work and puts those basic guardrails in place. But the opening prompt is written before the work begins. It can only express what you know at that moment. A serious project produces information along the way. The research may weaken your original thesis. The first implementation may expose a dependency that changes how the architecture works, right?

The customer evidence points toward a different use case, potentially. The first 50 results that you get could reveal that your original request will produce a lot of volume and very little value. So maybe this whole thing is not what you wanted it to be. So at this point, the job is not to defend your original prompt or to sort of push through in a bullheaded way. The job is to change what the agent treats as the current version of the assignment. That is where prompting becomes less like placing an order and more like directing work.

I found myself doing this across a wide range of tools. Sometimes I interrupt Claude Code while it is steering. I steer Codex after reviewing a result or let a project develop through several turns in Claude or ChatGPT. I’ve kept the changing state in a current.markdown file, in a plan, in a JSON, in an issue tracker, and in a carefully updated conversation. So I’ve tried a bunch of different approaches, right? The specific container here matters much, much less than whether the next action gets an updated state on the run.

One of the clearest public examples we have of this comes from Arize. Its agent Alex was asked to summarize multiple traces. During one memorable run, the agent made 27 model calls. Almost all of them went into reorganizing its own to-do list. It kept moving information around without completing the assignment. Sometimes that does sound like AI, right?

The original request had been buried under tool output and under intermediate results and the agent’s own activity. And Arize didn’t solve that by adding a more forceful sentence at the top of the prompt. The team decided to solve that by moving the current plan entirely outside the conversation window and storing it on disk. On every model call, the system rebuilt a short plan message from the latest state and placed it in front of the noisy history. The agent could see what was done, what was in progress, what came next. Doesn’t that sound nice if you’re the agent?

Arize’s example separates transcript, the transcript of the work so far, from current context. That’s really important. It’s like putting the road safety signs up front. The transcript still held real information, but the maintained plan received much more authority than the pile of events that happened along the way. Arize gave the agent an updated answer to a very practical question. Given everything that has happened, what should I be doing next?

What should I be doing now?

That is close to how I use current.markdown in a personal workflow. It, it’s an ordinary file, right? It’s not a Claude or Codex feature. Anybody can use it. And you and the agent just need to agree to keep it current. In Claude Code, claude.markdown can tell Claude to read it at the start of the job and update it after every consequential decision.

In Codex, agents.markdown or the task itself can give the same instruction. In a normal chat, you can attach or paste the current state when you begin a new conversation. In an ordinary Claude or ChatGPT conversation, the same practice takes on a couple of different forms. While the thread is still useful, you can steer it directly. And when a decision needs to survive, when it needs to transcend the current chat you’re in, you just ask for a replacement project brief that reflects the new state. And you read it and you correct it and you carry that brief into your next conversation with— the old thread becomes history and the brief says what’s true today, what’s true now.

You don’t need to preserve every correction this way. You want to save the change only when it affects what you’re going for, your target for this run, your goal, the definition of done. If you would be annoyed when a fresh agent misses the decision that you would want to make, then you should put it in the project state, or you should have the agent put it in the project state. On the other hand, if it only helps explain how you got there, it probably doesn’t belong in that file. It probably is in just the history and you cannot mess with it a lot. Other coding agents expose project rules or instruction files that can point to the same kind of state, while a multi-agent system might use a ticket or a JSON record or a database.

OpenAI’s Symphony system uses a project board to define and track real work. Whether the mechanism is markdown or an issue in Linear, the next agent action has to read the updated decision.

I learned the value of this in a long Codex project of my own. I was building a benchmark across a really large set of my own work. So the run discovered 339 different sources, and it generated over 1,000 questions, and it produced 250 verified answers. And that was real progress. And then the delegated agent began repeatedly continuing itself during package synchronization. In other words, it was still active, but it stopped adding useful value.

The original objective had encouraged continuous stress testing, and early in the run, that instruction helped the agent to kind of keep going. But at some point, it became the wrong instruction. The useful next move was no longer to generate more questions or keep the continuation loop alive. It was actually to deepen the evidence behind the most valuable answers we discovered to questions along the way, and then to stop. So I stopped the run and I changed the state. The saved record said the project was checkpointed after a retry loop and prohibited resuming the unbounded run.

And the next pass would select the 50 highest value answers to those questions, replace generic evidence with evidence specific to each question, validate the package, and stop. All completed work remained available under a new direction. That is progressive context shaping in a real project. Because what I found was I was getting stuck because the old instruction was essentially pushing the agent too far in a direction that was unhelpful for ultimately getting my goal accomplished. The next run needed to do different work, so I changed the agent state it would inherit and turned an open-ended generation job into a very bounded job that was supposed to finish up. So then I got 1,000 questions, 250 answers and a source map that remained useful.

So at the end of it, I actually got the questions and answers that mattered the most to me, and I got real value. Anthropic’s scientific computing example shows the same move at a smaller scale. In one solver project, the progress notes record that an attempted method was too stiff and name the method that replaced it. A new Claude session doesn’t need to relive the entire failed attempt. It can see the failure and move on. It just needs the consequence, right?

This approach failed for this reason. Use this replacement. Continue from the current state. This is what helpful forgetting can look like for agents. The system doesn’t erase the evidence of the old attempt. The history can remain in changelog somewhere, but the failed method doesn’t have the same position as the active plan.

The agent carries the lesson forward without carrying every single token that produced the lesson and kind of getting confused along the way.

Now, there are 4 kinds of context worth separating here, and I’m going to go through all 4. The first is stable instruction. How to work, where to find things, what actions require approval, and what standards should remain in force. Claude might read that from claude.markdown. Codex might read it from an agents.markdown file. It’s a markdown file, right?

Another tool might call it project rules. You get the idea.

The second is current project state. What the goal means now, which decisions are active, what remains unresolved, what should happen next, and when the agent really needs to stop. This is often changing material, and it may live in, again, a markdown file, a ticket, a structured data, but it’s different. It’s different from the actions that require approval. It’s different from the guardrail stuff. It’s really about the condition of the goal.

The third is the map. What material exists and where it lives. How does the agent get resources? Research files, design documents, transcripts, prior drafts. The agent doesn’t need all of it in front of it right now. It needs a reliable way to find the bit that matters for the next decision.

Most people will skip this layer, and skipping it is why they end up just kind of pasting everything in. Have you ever done that?

The 4th is history. What happened before, what changed, why a decision was made, and how to recover an earlier version. So Git or a changelog or a decision log, transcripts, they’re all useful history. And history matters, but we want history to not masquerade as current instructions. So we keep it as a separate set of data that the agent can access instead. OpenAI used exactly this separation in that million-line project I talked about at the beginning of this video.

A short agents.markdown mapped the repository, active execution plans carried progress and decision logs, and design and architecture documents held deeper knowledge. The team even ran recurring work to find stale documentation and update it along the way. And so instead of squeezing a million-line project into a single prompt, they gave the agent a way to locate current knowledge as the product evolved. It’s also what Anthropic did for fresh Claude sessions. An initializer set up the working environment and the progress file. Later sessions read the progress and inspected the version history and selected unfinished work and made incremental change and left an updated state for whoever comes next.

That’s just good agent hygiene. 4 months later, Anthropic rebuilt that harness. They dropped the sprint scaffolding entirely because the newer model no longer needed the work broken into chunks, and they kept the structured handoff between sessions because that still needed to happen. So the scaffolding ended up being disposable as agents evolve, but the current state was not. The handoff is part of the work because a long project, no matter how— what sort of big agents evolve to be, can’t depend on one conversation staying alive forever.

Now, Anthropic’s research across roughly 400,000 Claude Code sessions makes the human role in all of this much clearer. In a typical session, the prompter, the person in charge, made about 70% of the planning decisions, while Claude made about 80% of the execution decisions. That result is specific to Claude Code, but I think the division is a useful rule of thumb. The person doesn’t have to narrate every file change or command these days, and anyone who uses agents will tell you they, they generally don’t. Otherwise, why would you do that? The person decides what ought to be built, what the new evidence means, what counts as done.

They steer the agent, and the agent handles much of the path between those decisions. Progressive context shaping is how those planning decisions survive between check-ins. If you correct only the draft in front of you, the correction may just stop there. If you change the current project state, the correction can alter the remaining research and the next implementation and the work given to another agent and the task resumed tomorrow.

Keeping current agent state becomes more important as people run several agents at once. OpenAI learned this when it discovered its engineers could comfortably manage only 3 to 5 Codex sessions at once before context switching became painful. People forgot which session was doing what and spent their time moving between terminals. Symphony moved the work into a project board where agents pulled tickets, and I’ve talked about that before. On some teams, landed pull requests rose 500% during the first 3 weeks after Symphony.

The operating change is something that we have to kind of wrap our heads around because essentially what it did was instead of holding every session in their head, people use the ticket to carry the deliverable, the status, the latest direction. Does this sound familiar? They’re basically carrying current state for the agent much more easily in a ticket board, and they can manage many more agents at once, and they could change the work where the next agent would find it by just changing the ticket. You can use the same idea without committing to Symphony. You can start with one project whose path is uncertain but whose outcome matters. You can ask the agent for an early result that can teach you something like a research map, or maybe a first MVP implementation or something, a diagnosis of the problem, something like that.

Don’t ask for the entire project in one blind run if the early work is likely to change your judgment. Ask for that checkpoint first.

At the start, give the agent 4 things: the outcome, the relevant source material, the action boundaries, and the first useful checkpoint along the way. That checkpoint should contain work that you can have an opinion about, right? Think about the problem and report back is a very weak thing to ask, right? Instead, say something like, compare the sources, identify where they disagree, and propose the first version of the plan that you think would actually satisfy my requirements. That gives you something that you can wrestle with, right? Get your teeth into.

And then create a very small current state record along the way. It doesn’t need to be elaborate. It should say, what the project is trying to accomplish, which decisions currently govern the work, which questions remain open, and what the agent ought to do next, and what conditions should make it stop or return to you. You, of course, also want to add what can the agent do and what can the agent not do without your approval. Now, I call mine current.markdown. It’s an ordinary file.

It’s short enough that I will actually read it, and it sits where the agent will look and can read and write to it. And when I do a run like this and I reach that checkpoint, I can review the work, and I can locate where I need to change that current markdown file to adjust the next run of the agent so that I keep the agent on track. The evidence may fail to support the claim I’m making. Users might care about a different problem. You can imagine all sorts of progressive discovery along the way. Ultimately, this puts our human decisions above the loop as appropriately in charge of agents when they are doing these big runs, we need to be able to make corrections along the way.

So here’s an example of a useful instruction, right? Update the current project state so that this evidence replaces our earlier assumption about the buyer. Apply the new decision to the research still open in the implementation plan, and then keep going. And then preserve this other old assumption in the decision history rather than using it as current guidance. So I’m actually giving you specific language here, but you get the idea. You don’t actually have to go in and manually type into this file.

You can talk to your AI and basically say, we’re working on current.markdown together, uh, I am reading what you’re doing here in this checkpoint. I think it’s incorrect in these ways. Update current.markdown in these ways so you don’t make this mistake again, and then keep going on our larger project. That’s the idea.

This is the capability I think people miss when they look only at context window size for agents. A larger context window may retain more events technically, but compaction may continue to work after the window fills, and memory may end up retrieving something weird from earlier in the session. So those mechanisms can’t decide which new facts should change your project. They’re not a substitute for your judgment. You, you still supply that judgment. There’s actually an experiment you can run to see this for yourself.

You can run the same agent task multiple times. You run it once just the way you normally would. You run it once with a very focused packet. It has a current.markdown file. It has the evidence rules I talked about, et cetera. And you run it once with everything you have, like max out the context window.

Now, a lot of people might think the third one wins, or else they might think that the third one at least allows the agent to have a more complete answer. No. When, when, when you see what comes out of those runs, in almost every case, a focused package of context that allows you to update state as you go. Well, it wins because it allows you to put your judgment into place properly over the course of the run. Dumping a bunch of context is not a substitute for your judgment. Prompting is still there.

Reviewing work is still there. But the whole project no longer depends on one perfect prompt at the beginning or one conversation, and everyone remembers that conversation equally. Instead, you give the agent enough direction to begin. You learn from what it produces. And you change the state that governs what comes next. So maybe take a project that you’ve put on ice because you can’t see every step and you feel like you need to sort of define it in advance to give it to AI and be more bold, right?

Look for where you’re going. Look for the source material. Look for the boundaries or guardrails for AI, and then give the agent a little place to keep the current state. When the work changes your judgment, rewrite that state before the agent keeps going.

Now, if you want a starter kit on all of this, I’ve got you. I made 4 ordinary files and a set of prompts. I made a README.md that explains this method to your agent. I made a current.md that holds the state. I made a context_map.md that says what exists and where it lives that your agent can help fill out. And I made a decisions.md that holds what you’ve already decided on and why over the course of your agent run.

None of it is a feature for any particular tool. It works in Claude, it works in Codex, it works in ordinary chat. The link is on my Substack. This is how you get the benefit of a 6-hour agent without asking a 6-hour-old prompt to keep running your project.