Giving a coding agent context that survives the session

This post is deliberately practical. No new tooling, nothing to adopt, six things a team can do this week to stop losing what its agents work out, ranked by return on effort.

Then, honestly, the two problems none of them solve, because a list like this is only useful if it says where it stops.

1. Keep the instruction file short and about conventions

Highest return, lowest effort, most commonly done badly.

CLAUDE.md or AGENTS.md should contain what is true for every task and cannot be falsified by a merge: the package manager, the test command, the module boundaries, the prohibitions. It should not contain findings about current system behaviour, because those go stale silently and are read on every unrelated task at full cost. The boundary and a way to audit an existing file are in what instruction files can and cannot hold.

If your file is over about a hundred lines, the trim is the highest value hour available to you.

2. Put findings next to the code they are about

A comment above the function is the most durable place a finding can go, for one structural reason: it moves with the code. Rename the file, the comment goes with it. Delete the function, the comment goes too, which is exactly right, because a claim about a deleted function should not survive it.

Both people and agents read it in the course of the work, with no retrieval step and nothing to search.

The limit is scope. A comment can hold a claim about the thing it sits next to. It cannot hold a claim about the relationship between two repositories, and that is where the expensive findings tend to be.

Write comments that say why, not what. The what is the code.

3. Write decision records, short ones

An architecture decision record is a small file that states a decision, the context that forced it, the alternatives considered and the consequences. Numbered, in the repository, never edited after the fact. If a decision is reversed, a new record supersedes the old one.

The value for agents is specific: it is the only common practice that preserves rejected alternatives. "We considered X and rejected it because Y" is the sentence that stops the next person, or the next agent, from proposing X in a design discussion six months later.

Keep them to a page. The reason most teams' decision records die is that the template was too long.

4. Write pull request descriptions for a future reader

Most descriptions are written for the reviewer, who has the context already, and are therefore useless three months later when someone is trying to work out why. A description that states what was wrong, what was tried, what was rejected and why the chosen approach was chosen becomes a permanent, searchable, evidence linked record, attached forever to the exact diff it describes.

This is free. The work is being done anyway. It is only a question of who the writing is aimed at.

Agents are good at drafting these from the diff and the conversation, which removes the usual objection.

5. Give the agent a task scoped brief, not the whole codebase

Rather than pointing an agent at everything and hoping retrieval sorts it out, spend two minutes writing what you already know: the files that matter, the constraint that is not obvious, the thing you already ruled out.

This is the least durable item on the list, since the brief is thrown away with the session, and it has the highest immediate return, because it directly removes the most expensive part of the work. It also tells you something useful: the briefs you find yourself writing repeatedly are precisely the findings that need one of the durable homes above.

6. Keep one shared findings file per team

A single append only file, in a repository the whole team can reach, one entry per finding: what was found, the evidence, the date, the repository it concerns.

It is crude. It is also the only item on this list that spans repositories, which is why it is worth the awkwardness. Keep entries short and always include the evidence, the file paths and the pull request numbers, because the evidence is what lets the next reader check the claim in a minute instead of re-deriving it in an hour.

Expect it to decay. Its purpose is not to be authoritative; it is to be a pointer that saves the search.

What none of this solves

Two problems survive all six, and they are the reason this is still an open area rather than a solved one.

Nothing checks whether a claim is still true. Every item above is a written statement that stops being verified the moment it is written. The code moves; the sentence does not. A stale claim reads exactly like a fresh one and is acted on with the same confidence, which is worse than having no claim at all. Age is not a good proxy for staleness either, which is why review dates do not fix it. That argument is in context rot.

Nothing retrieves by relevance. Instruction files are read whole, on every task, relevant or not. Comments are found only if you are already in the file. Decision records and findings files require search, which requires knowing what to search for, which is exactly what the person who needs the finding does not have.

Between those two, the ceiling on writing things down by hand is low, and every team that has tried it seriously has found the ceiling.

Where that leaves it

Do the six anyway. They are cheap, they compound, and the first two in particular are worth an afternoon.

Then notice which of your findings none of them can hold: the ones about the seams between repositories, the ones that need to be checked before they are trusted, the ones that are needed by someone who does not know they exist. That set is the actual problem, and it is what REM is being built for: claims linked to evidence, versioned, reconciled against git, tests and history, scoped to the team. It is in private beta and there is a form on the front page.