How many times today has someone on your team typed something like “I told you not to touch that file” or “that's not what I asked for”? Each of those lines explains what the agent was missing to get it right. In most teams it stays in the history of a session nobody opens again.
What your team corrects in the agent every day is the list of what your way of working with it is missing, and hardly anyone keeps it.
What they analysed in 20,574 real sessions
Ningzhi Tang, Toby Jia-Jun Li and six other researchers published in May 2026, with a revision in August, an analysis of 20,574 real sessions with coding agents, from 1,639 repositories, both in the editor and in the terminal. They come from two public sources: 14,789 chat histories that developers committed to their GitHub repositories, and 5,785 terminal sessions from people who agreed to log them openly.
The authors call misalignment every moment in which the developer pushes back on or corrects the agent. They validated 16,118 episodes and recorded, for each one, what form it took, why it happened, what it cost and how it was resolved.
What people correct
Code that does not work is only the fourth most common form of failure. These are the most frequent; a single episode can have several:
- Ignoring a constraint the developer had stated: 38.33% of episodes.
- Misreading the request: 26.95%.
- Misreporting its own work: 22.58%.
- Writing faulty code: 17.82%.
As for the causes, the first is that the agent did not follow an instruction it did have (36.49%). Next come an underspecified instruction (15.36%) and acting before knowing the project (11.11%). In 26.85% of episodes, the authors could not determine the cause.
Why the same correction comes back
The correction lives in the chat. When the session ends, the next one starts without it, unless someone has moved it somewhere the agent reads or into a check that runs by itself. The study measures that failures carry over from one session to the next in the same repository, and it is reasonable to think that much of that repetition comes from nobody moving the correction to a fixed place; that reading is ours and the study does not prove it.
Failures also change over time. The overall misalignment rate per turn is going down, but among those that remain, ignored constraints and inaccurate reports weigh more and more. Both are better fixed outside the chat: a constraint you have to repeat in every session needs a fixed place, and a report you cannot trust needs something that checks it.
How to keep what your team corrects
One way to do it in a week, with no new tools:
- Every time someone stops the agent, they note it in one line: what happened and what type it was, using the study's forms as a list (ignored constraint, misread request, inaccurate report, faulty code).
- At the end of the week, the team looks at which lines repeat. A correction that appears only once stays where it is.
- Whatever repeats is moved where it belongs: to the instruction file if it is something about the repository the agent cannot work out from the code, to the specification if it belongs to a type of task, and to a permission or an automated check if it can never be skipped.
- It is reviewed in a short session without looking for culprits, as in a blameless postmortem: the analysis that SRE teams (site reliability engineering, as Google practises it) carry out after an incident to find its contributing causes without blaming any person or team.
- The following week, the team checks whether that correction has come back. If it has, the place chosen was not the right one.
This is what a week's log could look like (a made-up example):
Mon · ignored constraint · touched the migrations; it had been told not to
Mon · inaccurate report · said the tests passed; they had not been run
Tue · ignored constraint · touched the migrations again
Wed · misread request · rewrote the whole module; one method was asked for
Thu · ignored constraint · migrations, once moreThe migrations come up three times in four days. A rule the agent skips that often goes into a permission that stops it touching them (where each rule goes in Claude Code). The inaccurate report calls for the tests to run on their own before anything is marked as done. And if the misread request kept coming back, a convention may be missing from the agent file (what to keep in that file).
Limit The sessions come from developers who published their histories; company teams, with their own rules, may fail in other ways. Only 9.33% of episodes show how they were resolved, and the 91.49% is calculated on that part. The authors themselves warn that continuous review by the developer, on which almost every visible resolution depends today, is unlikely to scale once agents work alone for longer.
A one-week trial
Ask your team to note every correction to the agent this week in one line, in a shared document. By Friday you will have the first list of what your way of working with agents is missing, which is exactly the part that does not come with the tool.
As Manel Marcos, our CTO, puts it: “The continuous improvement of agents and skills is part of our day-to-day work, and that is how we build a workflow that keeps working better. We routinely audit the drift of the documentation and of the Spec-Driven Development (SDD, development guided by specifications) process, and we use the SDD orchestrator agent for it. We do not edit those files by hand: we ask it to help us improve them.”
If you want to review that list with someone from outside, the diagnostic is free. How we work with development teams: AI-Accelerated Development.
Frequently asked questions
Why do coding agents fail?
In an analysis of 20,574 real sessions, the most frequent failure was ignoring a constraint the developer had stated (38.33% of episodes), ahead of misreading the request (26.95%), misreporting its own work (22.58%) and writing faulty code (17.82%).
Why doesn't the coding agent follow instructions?
In the study, the most frequent cause was the agent not following an instruction it did have (36.49% of episodes). An underspecified instruction accounts for another 15.36%. Anything that must never be skipped is best moved into permissions or automated checks.
Does the coding agent correct itself?
Rarely. Of the episodes where the resolution is visible, 91.49% were fixed after the person corrected the agent, and only 2.99% were corrected by the agent on its own.
Do agent failures repeat from one session to the next?
In the same repository, when a session had a misalignment, the next one also had one in 51.9% of cases, compared with 33.6% when the previous one did not.
How does a team improve its work with a coding agent?
By logging each correction with its type and reviewing every week which ones repeat, so each one can be moved where it belongs: the instruction file, the task specification, or a permission or automated check.
What is a blameless postmortem?
It is the analysis a team carries out after a failure to find its contributing causes without blaming any person or team. Google's SRE book describes it, and it also works for reviewing corrections to the agent.
Sources
- Ningzhi Tang, Chaoran Chen, Gelei Xu, Yiyu Shi, Yu Huang, Collin McMillan, Tao Dong and Toby Jia-Jun Li, “How Coding Agents Fail Their Users: A Large-Scale Analysis of Developer-Agent Misalignment in 20,574 Real-World Sessions”, arXiv:2605.29442, v2 of 31 August 2026 (v1 of 28 May 2026).
- John Lunney and Sue Lueder, “Postmortem Culture: Learning from Failure”, chapter 15 of Site Reliability Engineering, Google and O'Reilly, 2017.
Bernat López is founder and CEO of onext, an AI boutique. He helps development and product teams work with AI with method —specification before building, a person who decides where there is risk and Spec-Driven Development— and applies to his own company what he proposes: onext runs on its own agentic system.
LinkedIn →