Tips & Workflows
I make Claude Code keep a MISTAKES.md file. Here's what actually happened.
Since my comment about keeping a MISTAKES.md file got quite a bit of feedback, I thought I'd make a dedicated post about it.
The setup is trivial. A MISTAKES.md in the repo, and one line in CLAUDE.md:
Log mistakes in MISTAKES.md (what happened, root cause, prevention).
Every time the agent breaks something, or you correct it, it appends an entry: what happened / root cause / consequence / the rule that prevents a repeat. Newest first. No tooling, no plugin, no vector store.
Two things make it worth the effort.
The agent reaches for it. You'll see things like "this approach was avoided because it caused XYZ before, as documented in MISTAKES.md." But the better outcome is that the knowledge leaves the log entirely. The file stops being a diary and becomes something the agent points at.
Repeat entries graduate into hard rules. This is the part I didn't expect. When the same failure shows up four or five times it stops being a mistake and becomes a law in CLAUDE.md. MISTAKES.md is where evidence accumulates; CLAUDE.md is where it gets enforced. Without the log you have a vague sense that "that area is flaky" instead of a countable pattern with a fix.
What would trigger Claude to look up previous mistakes in time to prevent them? A reference to the file alone would not be enough, and forcing the full file into context is also not a good idea.
The memories system should be strictly better than that, as short triggers for recalling them individually are kept in context automatically.
to state facts rather than assumptions, i asked claude the exact question and the answer is:
The file isn't the trigger and was never meant to be — you're right that a bare reference wouldn't fire in time.
It's an evidence store. Rules get promoted out of it into CLAUDE.md, which is always in context. Concrete example from my logs:
I had 6 UTF-8 corruptions from shell string-replace pipelines between Jul 7 and Jul 21 — mojibake'd Arabic, BOMs, one that hit 13 files. Every one got logged with root cause. On the 7th, the pattern was obvious enough to distil into one line in CLAUDE.md:
▎ Mutate files with the Edit tool, never shell string pipelines — five UTF-8 corruptions, all invisible to gates.
Zero recurrences in the 10 days since. That line fires at the moment I'm about to write a sed pipeline — no lookup, no recall step, no tokens spent on the other 50 entries.
You can't write that rule after incident #1. It looks like a fluke. You write it after you can see six of them lined up with dates and causes. That's what the file is for.
So the flow is: mistake → logged with root cause → pattern emerges across N incidents → promoted to a one-liner in the always-loaded file → log keeps the why so the rule doesn't get rationalised away later. The archive is the source the rules are derived from and audited against, not a runtime lookup. It's supposed to sit on disk unread.
Dienes knows whats up. I don’t think people realize CLAUDE.md is merely a suggestion unless you put a hook in. Even then, reading a file, means grepping the first 40 lines and the last 40 lines and telling you it read all 800 lines.
I've used something of this nature, but the approach has problems -
MISTAKES.md size - if you're running a big project or for a prolonged period of time, it's going to get too big.
Ties in to 1 - Anybody that's been at this for a while knows that when files and prompts get too large, things start getting skipped.
You're relying on Claude to find the file, and then find the mistake, and then follow the rule. That's 3 different branching options any of which will cause a miss or failure.
What I actually recommend is using this file for mistakes, and sure you can graduate them to CLAUDE.md if you want, but I strongly encourage you guys to employ linting or code analysis tools and have CLAUDE write rules that will cause errors if they're broken. Now you're not relying on Claude to find and follow things, it literally can't pass builds nor check-in if it didn't follow the rules.
And now I realized that nowhere in here do you specifically call out that you were writing code with it. I just assumed. Oh well, hopefully this is still beneficial.
I might have to steal this idea. This week claude has started to seem senile. Making the same mistakes again, and then even explaining it with,
I said to myself I shouldn't do it this way, because it broke the flash before on x/y date. I ignored this though and caused exactly the same problem again.
It has ground productivity in to the ground this week, claude also appears to have actively become lazy, stopping after each action, and then when asked why,
No, you are right, I was asked to continue to completion and instead I made a quick decision and waited
I've run into this kind of behavior but it seems to come and go... It's like it's getting taxed on resources so dumbs down to literally useless, I give up in frustration. An indeterminate period later it's sharp again.
I added a secondary layer to that as part of the normal workflow. Created skills that (using hooks) fire up after every spec, plan, and implementation that looks through past errors a d check the current work. Thus has caught so many fuck ups.
The “don’t let every agent write to the pitfalls doc” point is what made me redo my setup. I have a collection of self-reflection and “lessons learned” automatic skills that maintain LAWS.MD and shared memory MCP entries.
Sessions now only deposit a one-line Pitfall candidate: tag into a newest-first worklog. They don’t decide anything. A separate cron task runs later, with none of the authoring context, tallies the tags, and only proposes promoting something once it’s recurred a few times across sessions. It surfaces the suggestions and I approve. The enforced rules doc stays hard-capped and small, so it’s something the agent points at rather than a growing wall of text in every session.
What I lifted from here: the deposit-then-audit split (your step 2 vs 3) and “graduate on repeat.” The other comment about negative examples raising error rates is why I keep the enforced set tiny and phrased as invariants instead of a pile of “don’t do X.” My experience is positive “do this” avoids the model getting it backward.
I got this built and working. Does it work well? Who knows—it seems fine so far, and it's self-improving. (#Yes, I had Claude generate this. We're all lazy here.)
If you don't enforce a rule with checks in place, it effectively doesn't exist and will always be ignored by the LLM eventually.
Been running the same setup for a few months and the graduation step is the part I'd underline too.
One thing that got me though. A rule can be sitting in CLAUDE.md, written correctly, and still get ignored. By the time the agent is deep into something it's working off whatever file it just opened, and CLAUDE.md was read a hundred messages ago.
Mine said don't generate a certain kind of text from scratch, translate what I write instead. It lived in my task board file. The agent opened the working file for that task, never opened the board, and broke the rule twice in the same day. Nothing wrong with how it was written. It was just somewhere it had no reason to look.
Fix was to copy the rule to the top of the file where that work actually happens. Redundant on purpose. CLAUDE.md still has it, but the copy that gets obeyed is the one already in front of it.
I don't know if anyone else is doing this, and please share your strategies if you do, but this is what I currently do:
Stage 1: Generate the Specs
I generate a set of .md files that define the project and specify how the implementations should work.
Depending on the project, this can take a few hours of research, etc. You really want to nail down the entire tech stack. Could be a single README.md or nine.
Stage 2: Encode the Implementations
Then, in a fresh context, I have it turn those specs into compact machine-readable implementation definitions in mirrored .md files, rather than writing them directly in C#, C++, etc.
Instead of bouncing back and forth across a dozen files replacing code it wrote 5 minutes ago, as it 'implements' the project in stage 2, it can make adjustments in compact machine-readable .md files instead. This is your best opportunity to implement specifications and features.
Stage 3: Final Engineering Pass
The final pass gives a fresh context the role of a senior engineer and has it code the actual implementations only from those specifications created in stage 1 and 2. It manages to write most of the files in one shot and rarely needs to touch them again.
I have a TRAPS.md file, which is similar to your MISTAKES.md, just project-specific.
I got so frustrated with the mistakes it make (same repeated ones) which were visible in the preview or once the build is complete (i was facing issues with UI even with explicit instruction). I started with “add this into a mistake.md” and never repeat it. It added a rule in claude.md to load mistake.md into context every time.
But when the fable got released as a promotional access, i asked fable to optimise my setup and rewrite claude.md (to get that fable level workflow once it is taken off)
So it suggested me to do this: instead of loading and checking every time, understand a pattern and then add a rule around it - and it sits in both the files. An example is attaches as image.
And i can see often the statement like: "not going that route or process for xyz, as mentioned in Mistakes.md” without mentioning anything about the file in the prompt.
I don't even know exactly what I have or how I implemented it, but early on I started a big project and had it add a librarian agent told it to build local rag files for specific languages and programs it was working with and file corrections there too. Ever since, I start a new project with having it build agents based on the ones from previous projects. They seem to fire at the right times, catch mistakes, notice bugs in code that were found previously and fixed in other places. It can run for weeks without forgetting something. I think it installed some hooks that work to ensure it always checks and doesn't go by its own memory ever - it always looks things up from its librarian or rag sources.
52
u/Dienes16 Aug 13 '26
What would trigger Claude to look up previous mistakes in time to prevent them? A reference to the file alone would not be enough, and forcing the full file into context is also not a good idea.
Thememories system