My coding agent kept making the same mistake, and a 12-line file finally taught it not to

Published Sep 2, 2026, 4:00 PM EDT Anurag is an experienced journalist and author who’s been covering tech for the past 5 years, with a focus on Windows, Android, and Apple. He’s written for sites like Android Police, Neowin, Dexerto, and MakeTechEasier. Anurag’s always pumped about tech and loves getting his hands on the latest gadgets. When he's not procrastinating, you’ll probably find him catching the newest movies in theaters or scrolling through Twitter from his bed. Sign in to your XDA account I’ve tried just about everything to stop my coding agent from making the same mistakes repeatedly. I tried pointing out the mistake in my prompt, explaining exactly what went wrong, and adding another instruction to AGENTS.md. The agent would follow it for that session. The next time I gave it a similar task, it would make the same mistake again. I eventually added a MISTAKES.md file to the project. Whenever the model made a mistake, the file recorded what happened and how to prevent it. I then made the model read the file before it started working. So my coding agent now has a record of its previous failures, and it actually uses that record when approaching the same kind of task again. Coding agents don’t learn from your corrections Corrections disappear when you restart the session Correcting a coding agent doesn’t modify the underlying model. The agent is using the model at inference time, so your correction becomes additional context rather than new training. The model can follow the correction while it remains in the conversation, but a new session starts without that context unless the information has been saved and retrieved. AGENTS.md makes instructions persistent, though it still cannot enforce them. For example, Codex loads the file into the model’s context as a user-role message. The model reads those instructions alongside your prompt and everything it collects while working. A rule in AGENTS.md therefore influences the next action without making the prohibited action impossible. The problem becomes worse as the context grows. Models use relevant information less reliably when it appears in the middle of a long input. A coding agent keeps adding source code and command output to its context, which can bury an important project rule. Adding every correction to AGENTS.md eventually creates the same problem. The file becomes another long collection of instructions that the model has to process. If you use Claude code, you can use hooks to send the agent back to review its output. However, the review remains part of that session. It doesn’t preserve why the failure happened. If you want to prevent the same mistake later, you need to put that lesson back into the model's context before it chooses its approach, which is where MISTAKES.md fits in. MISTAKES.md records what the agent should do differently It's a project-specific record of failures MISTAKES.md is a project-specific record of confirmed failures. Each entry explains what the agent did wrong and identifies the decision that caused it. It then gives the agent a specific rule to apply when it encounters the same situation again. I started with this 12-line template: # MISTAKES.md Review relevant entries before planning or editing code. Add an entry after a confirmed mistake or user correction. Keep entries short, specific, and project-related. Merge repeated mistakes instead of creating duplicates. Do not record transient tool failures or unverified guesses. ## Entry format ### [YYYY-MM-DD] [Short title] **Mistake:** [What the agent did wrong] **Root cause:** [Why the decision failed] **Prevention:** [The rule to apply next time] **Verification:** [How to confirm the mistake was avoided] The root cause and prevention fields are the most important parts of an entry. Recording that the agent “broke authentication” doesn’t give the next session enough information. The file needs to explain which decision broke it. The prevention rule should then describe the correct approach in terms the agent can apply directly. I would suggest not adding routine tool failures to this file. For example, a command failing because the network dropped doesn't teach the model anything. The same applies to typos that were fixed immediately. You should also avoid adding generic instructions such as "write clean code" because it's just more text and doesn't change a specific decision. Make the agent read MISTAKES.md Before it starts working MISTAKES.md will only be useful when the agent reads it before making any decisions. I added an instruction to AGENTS.md telling the agent to review the file before planning or editing code. Since I use Claude Code, I import AGENTS.md through CLAUDE.md. I also use a SessionStart hook to load the file automatically. The hook runs a small script whenever Claude starts a new session or resumes an existing one. That script checks whether MISTAKES.md exists and reads its contents. Claude Code then adds the output to the model’s context before the first prompt. The same hook runs again after the context is compacted, so the entries don’t disappear during a longer task. For the unaware, hooks are small scripts that run automatically when a coding agent reaches a specific point in its workflow. The trigger could be the start of a session or an attempted tool call. Unlike a prompt instruction, the agent doesn’t decide whether to run a hook. The agent harness executes it whenever the configured event occurs. You will often encounter the term “hooks” in Claude Code, but the feature isn’t exclusive to it. Lifecycle hooks are common across coding-agent harnesses, although their names, triggers, and configuration differ between agents.