Until recently, when someone asked me, “How do you make an agent maintain the documentation?”, my answer was: “You don't.” That was an honest answer based on my experience, but I left out a qualification. Models change. Newer, stronger models follow project rules much better, lose track of updates less often and, in my experience, use fewer tokens to get the work done, especially when they can make sense of a thousand lines of documentation instead of ten thousand lines of code. The picture of an agent inevitably forgetting to update the docs after every task is already out of date.
That still isn't a guarantee. And even perfect discipline within a single task doesn't solve a second problem: over time, documents begin to contradict each other, old pointers stay in view and an important decision ends up somewhere the next agent won't look. So I separate maintaining documents during the work from reviewing the documentation system as a whole. They call for different checks.
What to record after a task
When I started Mango, I needed a file for handing work from one session or agent to another: op-exchange.md. It isn't meant to recount the entire working day. It holds unfinished business: where we stopped, what has already been checked, which attempts failed and what to do next. Back then, agents filled it in when I told them to. Now they keep it up to date themselves, but the file's purpose hasn't changed.
The question before writing anything is: what does the next agent need to know so it doesn't mistake the state of the task? The answer also tells us where the record belongs:
- Changed behaviour or a completed fix goes in the change history, with a link to the result and what was checked.
- A current decision or rule belongs in the relevant subject document, next to the thing it governs. If it replaces an earlier decision, record why and where the new one applies.
- Unfinished work belongs in the handover: current state, attempts already made, the next step and the condition for closing it.
- A fact about a live server, version or published page belongs in a dated record with the source of the check. Yesterday's report does not establish today's state.
These aren't universal filenames. Another project may use a different set. What matters is that each document has a job: one holds the current rule, another the history of a change, a third the open task. Put everything into one running log and the answer is hard to find. Copy the same decision into three places and the copies will eventually disagree.
A useful record distinguishes what was done from what was checked. Claude once replied to me after changing an interface: compilation and automated checks had passed, but it hadn't looked at the screen on a phone and asked me to judge the layout. That is more honest than “the interface is done”. For the next session, I would leave something like this:
The elements on the screen have been rearranged. The build and automated checks passed. The screen has not been checked on a device. Next, inspect the layout and any overlap on a phone. Close the task after that check and any further fix it calls for.
This shows the format; it isn't a report that the device check happened. A real entry also needs a link to the change and a person responsible for the next step. The point is to keep the boundaries clear: a build, a device check and acceptance of the result are three different states. The next agent shouldn't have to infer them from the word “done”.
If a bug remains, the handover should include the negative result too. “Tried again; didn't help” tells us almost nothing. “Checked the suspected cause; the bug still reproduces in the same way; next, inspect another part of the flow” prevents the next agent from repeating yesterday's loop. There is no need to copy the whole session transcript. The reason, the result of the check and the next action are enough.
Check at the transitions
I don't intend to approve every time an agent opens a file. With that approach, even a weak agent would turn the project owner into a “Continue” button. A record needs checking where the cost of missing it rises: when handing work to another agent, ending a long session, declaring a task complete or releasing a change.
At those points, I don't look for the phrase “docs updated”. I look at the route. Which file now answers the question? Will a new agent reach it from the project instructions? Does the entry distinguish confirmed facts from hypotheses? Does the open task have a next step and a closure condition? Sometimes opening one section is enough to see that the handover happened. Sometimes there is a polished report in chat and nothing in the project.
That doesn't automatically call for another rule in capital letters. First, find the cause: was there no rule, did the agent fail to reach it, choose the wrong document or misunderstand the status? Only the first and last cases might need an instruction changed. If the model simply skipped a step it already knew, it is more useful to send it back to the record and check the result. Another page of rules won't, by itself, make an older model more attentive.
The model is part of the process
Here is a correction to my earlier experience. With today's stronger models, following the route through the documentation has become noticeably easier. They hold on to instructions better, forget to record the result less often and can carry longer tasks without constant reminders. So the quality of the documentation depends not only on the wording of the rules, but also on who does the work.
My impression is that when a new flagship arrives, models that were at the top two generations ago sometimes perform worse than I remember. I have seen similar impressions from other users. I have even wondered whether older models are given less compute. But I have no evidence for that: I haven't compared them on identical tasks with identical settings and context.
My practical choice is simpler. For substantial day-to-day work, I use at least the model that was the flagship in the previous generation. For difficult architecture, conflicting rules or a decision where mistakes are costly, I use the current top model. That doesn't mean sending the most expensive option to search for every word in a file.
If a strong model brings in subagents, the rules should say this explicitly: choose and specify the model for each subtask. The weakest available model may be enough to compare a few numbers or extract matches from files; where a script can check the result precisely, use that check too. Resolving contradictory documents or making a risky project decision calls for a stronger agent. The main model then brings the results together and is responsible for the outcome. Otherwise, you can end up with ten flagship models doing mechanical work, and the bill grows faster than the quality of the documentation.
It helps to give each subagent a narrow assignment: which files and question to examine, what result to return and what counts as evidence. Then the model can be chosen for a reason. “Look through all the docs and tell me if everything is fine” is a poor brief even for a flagship: it sets no boundary for the check, so an answer of “everything is fine” is almost impossible to verify.
A review is a separate task
Even if every agent carefully updates its own area, the system as a whole ages. A new document takes over an old one's role; an instruction still points to the previous section; two files start answering the same question. An agent doing its immediate job can faithfully record the result along the route it was given and miss the fact that the route itself needs changing.
That is why I periodically commission separate reviews. An agent goes through the documents and related code, looks for missing records, outdated pointers and contradictions, then proposes changes with reasons. The report is usually good enough for me to approve it. But I still decide when to start that work and what to do about disputed changes. Every completed task is not a reason to reorganise the entire project.
The review can be broken into concrete steps:
- Define the scope: for example, one workflow, its code, the current documents and links from the project index.
- For each claim that affects the work, establish its status: current, retained as history or still awaiting a check. Compare facts that can change with the present state, not just the date of an old note.
- List discrepancies with their source locations and propose the change: which document becomes authoritative, which links need redirecting and what to keep as the explanation of an earlier decision.
- Once the changes are accepted, update the reading route and make sure the next agent reaches the corrected section and that unresolved questions have not disappeared from the handover.
Without the last step, a review can make the text more accurate while leaving the same mistake at the entrance: the agent will keep opening the old file and never see the new one.
Formal checks help here, but they don't replace a review of the content. A script can find a broken link, check required fields or show that a file has grown too large. From a filename alone, it cannot decide whether a task is really closed, which of two rules applies or whether an old document should go. That takes the content, the history of the decision and sometimes a comparison with what the code actually does.
Once, I thought TODO and backlog in Mango were in conflict. I asked Claude to investigate. They had become a mix of a completed phase, a fix still waiting for a backend release and an idea nobody had assessed. The filenames no longer described what was in them. We ended up combining the files and sorting the entries into sections. A formatting linter could not have explained what to do with those three different statuses.
An agent shouldn't silently delete the old document just because the work has moved to a new one, either. The old one may explain why a decision was made. First, identify the current source, correct the route and preserve the useful history. What to keep close at hand and what to archive is a subject for another conversation.
Today's models already remove a good deal of the need for manual reminders. The owner's remaining job is to give records clear homes, choose an agent suited to the difficulty of the work and check the important transitions, while revisiting the structure itself from time to time. Then documentation actually helps the work move forward instead of simply growing alongside the project.