Coding Agent Context Rot: How to Fix It With a Handoff File

What is context rot in a coding agent?

Context rot is the drop in an AI coding agent's quality as a conversation gets longer. Every message, file it reads, and command output piles into the model's working memory (its "context window"). As that pile grows, the agent gets worse at following instructions, forgets earlier decisions, and repeats mistakes. Some developers call the late stage of a long session the "dumb zone." The practical fix is to stop pushing one chat forever, write a short handoff file, and start a fresh session from it.

Why do coding agents get worse in long conversations?

A language model does not have memory the way you do. Each time it responds, it re-reads the whole conversation: your first request, every file it opened, every error message, every dead end. The model has a fixed limit on how much it can hold, and well before it hits that limit, quality tends to slip. Researchers have written about this under names like "context rot" and "lost in the middle." The details vary by model, and I won't give you a magic number, because none holds across tools.

The effect in daily work is easy to recognize. Early in a session the agent follows your conventions. Two hours later it forgets them, reintroduces a bug you already fixed, or builds something you explicitly ruled out. Old failed attempts sit in the context right next to the working solution, and the model can pick up the wrong one.

There is a second problem that gets confused with this one: agents declaring work finished when it isn't. A creator who works extensively with coding agents lists this as probably the most universal frustration, along with agents that never show proof their work runs. Both get worse when the session is bloated, because the agent has less room to hold what was actually asked for.

How can you tell context rot has started?

You don't need a token counter. Watch behavior.

One sign is not proof. Two or three together, in a long session, is your cue to hand off.

What is a handoff.md and how do you use it?

A handoff file is a short written summary of where the work stands, saved in your project folder. You ask the current agent to write it, you read and correct it, then you open a new session and point the new agent at the file. The new session starts with a clean context and only the facts that matter.

Keep it short. A handoff that runs several pages recreates the problem you are escaping.

Here is a template you can copy:

# Handoff

## Goal
One or two sentences on what we are building and why.

## Decisions made (do not revisit without asking me)
- Decision, and the reason for it
- Decision, and the reason for it

## What is done
- Completed items, with the files they touched

## What is in progress
- The exact next step, and where we stopped

## What was tried and failed
- Approach, and why it did not work

## Open questions for me
- Anything the agent needs me to decide

## How to verify
- The commands or user steps that prove it works

The "tried and failed" section matters most and gets skipped most. Without it, the fresh agent will happily walk down the same dead end.

The prompt to generate it

We're going to continue this work in a new session. Write a handoff.md
in the project root using this structure: goal, decisions made, what is
done, what is in progress, what was tried and failed, open questions for
me, and how to verify. Keep it under one page. Only include facts you
are sure of. Mark anything uncertain as "unverified."

Then read it. This is your control point. If the summary got a decision wrong, fix it now. A wrong line in a handoff gets treated as truth by the next session.

Starting the new session

Open a fresh chat and say: "Read handoff.md, then tell me in your own words what you understand the goal, decisions, and next step to be. Do not start building yet." Reading the restatement catches misunderstandings before they cost you an hour.

When should you hand off instead of pushing on?

Hand off at natural breaks, not in a crisis. Good moments:

1. A feature is finished and tested, before you start the next one.
2. You have switched topics (from building a feature to debugging an unrelated problem).
3. The agent has failed at the same fix twice.
4. You have been in one session through many file reads and long outputs.

A cleaner chat with a one-page summary usually beats a long chat with perfect "memory" that is actually buried in noise.

How do you keep key decisions in your hands?

The handoff protects what you decided. The harder part is making sure you decide things in the first place, rather than discovering that the agent quietly chose for you.

Coding agents tend to fill gaps with assumptions. Ask for "a settings page" and it picks the layout, the fields, what happens on error, and who can see it. Each choice might be reasonable, but they are still choices you didn't make.

The fix is to tune your planning step. Many coding tools let you define a reusable "skill," which is a saved set of instructions the agent follows for a type of task. If you have a planning skill, edit it so the agent must ask questions before writing code. Creators who build with agents regularly describe the method for changing these: tell the agent the problem you are having, suggest a fix, and work with it to decide where the change belongs (your skills, rules, or hooks). The point is that the setup should fit your work, because everyone builds different things.

Here is a prompt in that spirit:

I keep finding that you make decisions about scope and behavior without
asking me. I want our planning skill to change. Before any
implementation, the plan must:

1. List what is in scope and what is explicitly out of scope.
2. Describe the user-visible behavior, including error cases.
3. Ask me any question where there is more than one reasonable answer.
4. List the evidence you will collect to prove it works.
5. Wait for my approval.

Propose the edit to the planning skill and show me the diff before
changing anything.

Item 4 comes from a practice the same creator uses: have the agent state, before it implements, which test artifacts it will produce, such as real command output or screenshots of the feature working. You then know what proof to expect.

What should go in rules, hooks, and skills?

Context rot gets worse when you stuff everything into one giant instructions file. A useful split:

• Rules: facts, constraints, and conventions the agent should know.
• Hooks: anything that is a "must never," "must always," or "if this, then that." A hook is a bit of code that runs on an event, like every time the agent is about to use a tool.
• Skills: larger workflows you want the agent to walk through, like planning or review.

The reason to use hooks is reliability. Rules and skills are natural-language instructions, so following them is probabilistic. A hook is code, so it is a guarantee. The example from the source is blocking the agent from ever reading your secrets file. Writing "don't read the .env file" in your rules can fail, especially in a long, noisy session. A hook blocks the action even if the agent tries.

A quick audit you can run: ask your agent to go through your instructions file and flag every line shaped like "never do X" or "when doing Y, always do Z," then convert those to hooks.

Should a different agent review the work?

Yes, when the stakes justify it. After a long build, the builder has the same blind spots as its context. A separate reviewer started with fresh context can ask: "What would make this not actually work? What are the gaps between what was requested and what was built?" Agents are good at finding gaps when asked directly. Expect a long list, since they want to please you. Skim it for the two or three items that obviously matter.

You can do a lighter version in the same chat, but a separate reviewer session avoids the contaminated context. Pair it with testing that acts like a user: opening the real app and clicking through it, not only running unit tests.

Where does Remy fit if you want to stop relying on chat history?

The deeper lesson of a handoff file is that important information should live in a written document, not in a conversation. That is how Remy works for business apps: you describe what you want in plain English, and the spec it writes is the source of truth, with the code derived from it. If you are building an internal tool, like a request form or a tracker for your team's decisions, you can keep revising the spec instead of rescuing a long chat. It does not replace good habits with coding agents, but it moves the memory into a document you own.