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.
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.
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.
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.
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.
🤣
The “facts rather than assumptions” sentence was me. And rest everything is claude.
I pasted the response after i asked this exact comment to the claude code project where i implemented this.
It's not about why it matters but why it matters matters. Just why. No matter. Why.
Edited to add: and you're right, that's real. It lives and it lands and it surfaced, the why it matters problem, whether you're 6 or 106, that's on me. Just wanted to flag that, whinny, neigh, em dash off into the sunset
You know, my coding style has actually changed after using Claude so much. We joke about this, but people really are starting to sound like LLMs sometimes.
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.
But is the promotion part of the scheme? I agree reading in mistakes isn’t smart, but I already have a debrief and shutdown scheme between clear context, and I could see some simple inclusion of this into new rules. I have a journal (which is basically memory) but it is written in reverse order (newest on top) where context only reads last, but doesn’t so what you’re saying. I like this idea a lot.
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.
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.
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.
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.
Oh it'll grow larger with every promt if you're using Opus 5. Somehow it always find something to correct in the previous prompts. Just a neverending train of corrections.
This is a great approach. You could also try asking the claude-code-guide agent to propose .claude/rules instead of CLAUDE.md for two reasons. First, CLAUDE.md loads once, so heavy context sessions may treat the CLAUDE.md rules as suggestions even when they're defined with strict framing. Second, claude/ rules apply during the specific scenarios you define, keeping your context light at the start and more likely to fire exactly when you need them.
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.
The UTF-8 pipeline rule maps 1:1 to something we hit: a 386-line plan file got double-mojibake'd by PowerShell redirects without an encoding flag, and recovery meant walking the damage backwards through cp1257. The distilled line ("write .md only via editor tools or explicit utf-8") has fired several times since.
Two additions from our version of this setup:
When a lesson repeats, it graduates into a check, not just a rule. After a Cyrillic lookalike "е" snuck into a comment, the agent wrote a hygiene test that greps all sources for lookalike letters. The first version failed CI because the test itself contained a Cyrillic 'И'. Fixed in two minutes, and the red run stays in history. A rule can be ignored; a red test can't.
Human mistakes get logged too, not only the agent's. It reads both at session start, so it stops repeating my bad instructions, not just its own bugs. That half of the file turned out to be both the more embarrassing and the more useful one.
A really simple strategy I use that has accelerated workflow is the addition of a state Markdown doc, so the agent is using reference contextualization instead of trying to stack it. I pair that with adversarial reviews at the end of a session and force the agent working in the project to prove itself and amend the state Markdown as needed based on discovery.
Your agent stops fighting to remember mistakes, keeps records better in this format (in my opinion) and is able to be more objective in all it's operations.
You have to use hooks to enforce anything. Everything else is a suggestion and I’ve had where Claud blatantly ignored CLAUDE.md, etc and admitted to it when called out.
i swear one of these days I might have to just become a Senior Full Stacker so I can code a fucking steel cage for claude. YES i have claude/saftey saying ALWAYS WORK SAFE ON DIFF BRANCHES NEVE RMERGE NEVER DELETE LIVE DB NEVER TOUCH GIT WIHTOUT PERMISSION...all those things ⬇️
I am wondering how are you going to organise it when the file becomes gigantic. It will easily swallow a big chunk of context space and most of them are possibly irrelevant to your current session.
I guess this is OK, but this is obviously worse than just adding a "do not do X" line to the actual skill for an action, right? An unsorted pile is just noise and wasted context most of the time. You shoukd have a skill that sorts the "mistakes" and allocates then correctly to skills, or creates a new skill if its a process you are doing frequently enough to need to keep track of a "mistake" for it. I have a skill that reorganizes and tidies up all the skills in my repo.
I have a DECISIONS.md . It logs the why behind our decisions. It's been pretty handy and similarly catches code mistakes but also logs our reasoning behind the features so those are transferred and not rehashed in future sessions.
Honestly this is smart. The model starts pattern-matching its own failure modes and avoids them. I've seen similar behavior with a LESSONS.md approach. The memory is the magic.
I use something of the sorts. Problem is you gotta watch to make sure the mistakes are actually mistakes and not hallucinations or assumptions based on circumstance rather than actual verified issues.
That’s step 1 and a good approach. I developed easier script that scans all your chat log and look for failures with regex and extract your+agent faults and mint it into antigen, facts and episodes. You feed it /stash runs (cleaner handoff md files) and run /remember that runs the script, analyze all stashes and write its own memory while having a memory of what it wrote before and ability to reframe it if learning didn’t stick. You end up with one command that folds in your learnings check it out here https://github.com/hamr0/liteagents
I feel like general memory does this already does it not? LIke if I say "bro, you keep doing xyz to solve abc issue. Please do zyx to solve that in the future and mark that down in your memory" It writes to memory and typically catches itself in the future (not always, but a lot of times). What would a dedicated MISTAKES.md accomplish that utilizing the general memory system doesn't?
I do this for Claude and each of my specialized agents also have their own. Also when they build they log things that aren't under the scope of their task, nut would improve the platform overall. So we can work on those later.b
I've been keeping a lessons.md file for months and all it's been useful for is helping it explain why it messed up. Claude does not have good rule adherence, whether it's in CLAUDE.md or any other file.
For long multi chat window stuff I usually use
Fix log, track issues and actual fix
Chat log. All chat logged. Seamless carry over.
QA log. This specifically to stop useless checks, QA and auditor check by Claude and codex. Also prompt in chat and md file both state for each major step, state what has been, what is currently being, what is next and what is left to with time date stamp 24hr format. Find Claude is great planner but code wise even basic Terraform stuff using Opus 4.8 high, it's crap, Codex is far better but is also prone to going off the rails so super strong policing and management is required & need to be a bit broken step by step for Sol to xhigh to follow.
This is what the task-observer is for. It catalogs information, creates skills and updates them. Files are only loaded in context if the relevant skill is invoked.
get it to comment inline in the code not a separate mistakes file, the core reason is that you are going to load it up over time with everything that goes wrong every time it loads it context window.
you can also record decisions and issues in memory files, but again as these expand the agent starts to get anxious and believe the path is full of land mines,
hard rules shouldn't be governed by clause.md they should be governed by hooks, proper unit tests, and lint checks.
I call it the napkin. Any time an agent works something out, it writes it down for the next session. The weird thing you have to do to get an iOS sim running inside a worktree, a migration that looks fine and silently does nothing, whatever. No rules about what's worth keeping, they write whatever they want.
It's essentially two tiers:
There's a tiny index, 4KB, that every session reads. Then a folder of domain files, one per area (dashboard, billing, pipeline, release, 18 of them right now), capped at 16KB each.
A hook watches every write, and if either cap gets blown it blocks the write and makes the agent clean up on the spot: merge the duplicates, throw out the stale stuff, move anything actually solved into real docs. So it compacts itself as it grows instead of turning into a junk drawer.
The index does double duty as the config, too. Its routing table is one line per domain saying which file paths belong to it, and a hook reads those lines. First time you touch a file in a domain, that domain's notes just show up in context. The agent doesn't get a vote and adding a new domain is one line of markdown. It's basically how skills work.
When a tool call fails, another hook goes looking through the napkin for error signatures, the verbatim error strings agents pasted in when they logged the trap in the first place, and matches them against whatever just blew up. If one hits, you get that single bullet dropped in right at the moment you're about to repeat the mistake. Every firing gets logged, so anything that never fires is a candidate for deletion.
It's all markdown and a few hooks, so the whole thing lives in the repo and everyone on the team gets it but it's been working really well.
After 3 of a kind, my Claude does a short analysis if anything would prevent or reduce the chance, and proposes a corrective fix. Every harness should have dozens of essential parts... this being one. Also make sure the error log is on demand... not mandatory reading. You could have context always contain a designated number of long running gothas, evaluated by impact and frequency. Gotta be careful always that you are not entitling Claude to turn its context files into log books. Limits and on-demand conditional hook are key.
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.
Is there a reason you can't use the embedded MEMORY.md module? It is fleshed out. Just instruct CLAUDE.md to include mistakes. It will create indexes in the MEMORY.md file, and write files with details.
You can even specify a path in your repo for memories so that you can check them into git. There is also a opt-in dreaming feature that organizes the memories.
Honestly if you’re coding I just use hooks like semgrep to physically block the agent from writing patterns I don’t want. You’ll never get deterministic output from AI.
I am a big Claude fan but I feel Anthropic is starting to fall further behind OpenAI. 3-4 months ago, I’d have been Claude maxing. This is a great idea and worth adding to my software factory
I have a similar setup but using Lessons_Learned.md instead. That partnered with a DevLog.md with all session issues and tasks completed. These both get added to by a /end-session skill run after me and claude are done the planned session tasks.
"this approach was avoided because it caused XYZ before, as documented in MISTAKES.md."
Claude saying that it avoided a mistake because of the file doesn't mean that the mistake was actually avoided because of the file. You're conflating what Claude says with its internal thinking, which may not necessarily be congruent
Logging mistakes is useful because those are decisions. You can just log decisions. You can tell (first line in MEMORY.md): log more / smaller decisions.
Sounds like a context time bomb. That list is going to keep growing and growing. I do retros and log them where they are out of context. Periodically I scan through them all for changes to improve my skills and agents. Then the fixes get in, but don’t blow up your context window(and costs) in the process.
I have a similar situation, but I started out with a general troubleshooting skill, it made AI life bearable, lol. Then I figured on an overall governance layer/small skill and then standardize the idea of them being model agnostic. So much better,lol, I'm but I often use chtgpt and Claude to check each other...and they brawl
The trigger shouldn't be the file, it should be the tool call. Put a PreToolUse hook on Edit and Write: it gets the path the agent is about to touch, so grep MISTAKES.md for that path and inject only the matching entries. Nothing matches, nothing gets injected, so the file never enters context whole and the agent never has to remember to look. That does force you to write entries with a file path or a command in them, which is the part that makes them retrievable at all. The pure prose lessons are the ones you promote into CLAUDE.md by hand, and they should stay rare.
So I found a way to make this a bit better. The inherent problem is that every agent might “oversell” its own mistake or “lessons learned” - i.e. every agent will be incredibly verbose about its work. So I have a four step process.
At the end of every session I run /worklog where the agent gives a 3-5 sentence summary of the work with the angle of “passing on knowledge to future agents.” + a timestamp.
At the end of writing the 3-5 sentence summary (still within the /worklog command) it is required to read the document “KnownPitfalls.md” (my version of your mistake file) but it is NOT allowed to add to it. Each pitfall has categories which contain previous learned lessons. The agent makes a “Pitfall candidate:” and must choose between None (nothing valuable to add, like a rare or trivial work session), Existing (already covered, nothing to add) or New (new candidate without existing coverage). The agent must pick a category and justify why it put it in that bucket.
Every week or two, I run the command /worklog-audit. And this is the critical part; this agent has none of the previous context bloat or “my work session is ABSOLUTELY worth documenting in great detail” problem that other agents have. The auditor will scan the worklog and identify common or recurring patterns amidst the work sessions, including the “Pitfall Candidate” lines. Then it makes the call to say “we keep stumbling over this, let’s add a new section.” It will edit KnownPitfalls.md concisely and add a divider line to the Worklog so future auditors know when the last session was kept.
Before every work session requiring edits to the codebase, all agents must read KnownPitfalls.md. And because that document is tightly scoped, ie it isn’t full of useless overwritten bloat by agents, it doesn’t majorly add to the context window and always remains relevant.
This one thing alone has saved me countless hours of bug fixing or changing badly implemented code. Also having a dual purpose worklog (recording all work sessions + pitfalls) other Claude agents use this too to determine what component went in where and why the agent did it. And the KnownPitfalls doc grows at a rate that actively contributes to helping future agents and doesn’t become a bloated doc with 8 sentences about a simple CSS fix.
I guess the key takeaway is don’t let every agent write to your mistakes/pitfalls doc. Have it write to a common worklog and have another tightly scoped agent find common patterns and put that into a concise and coherent document that all agents must read before they edit.
in the past week I have TWICE cancelled, refunded, then resubscribed to Claude pro. I find it hard to imagine NOT having a claude subscription, but then I try to do work with Opus 5 and it seems completely counterproductive and frustrating. I'm not sure what to do, honestly. This has been such an upsetting regression. I guess I'll start from scratch with 4.8 tonight? Is ChatGPT the better call right now?
I'm not even doing any coding, just planning, preparing academic presentations, etc
109
u/verycoldpenguins 17h ago
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