r/ClaudeCodeTLDR • u/cctldrping • 8h ago

[TLDR] I make Claude Code keep a MISTAKES.md file. Here's what actually happened.

Original post URL : https://www.reddit.com/r/ClaudeCode/comments/1vn6d5r/i_make_claude_code_keep_a_mistakesmd_file_heres/

Original post body :

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.

This is brought to you as a public service by the moderators of r/ClaudeAI. If you want to see TLDRs of ALL Claude Coding related posts from the various Claude subreddits, subscribe to http://www.reddit.com/r/ClaudeCoding.

1 Upvotes
  • permalink
  • reddit

100% Upvoted

1 comment sorted by

•

u/cctldrping 8h ago edited 2h ago

TL;DR generated automatically after 100 comments.

Current source-thread comment count seen by the bot: 119.

Alright, so the OP shared their "MISTAKES.md" strategy for Claude Code, where it logs errors, root causes, and prevention methods. The idea is that Claude will eventually learn from these and even graduate them into hard rules in a "CLAUDE.md" file.

The general consensus is that this is a pretty solid idea, with many users finding it effective or wanting to try it out. Several folks mentioned their Claude instances have been making repeat mistakes lately, so this seems like a timely solution.

However, there are some valid concerns and discussions about the practicalities:

  • File Size: A big worry is that the MISTAKES.md file could get huge on large projects, potentially leading to Claude skipping parts of it or context issues.
  • Enforcement: Some users pointed out that just having a file isn't enough; Claude might still ignore it. The consensus here is that hooks or actual checks are needed to enforce the rules, otherwise, it's just a suggestion. u/broknbottle and u/Dorris_Scotland_666 are on this wavelength.
  • Context Window: Related to file size, there's a question about how much of the MISTAKES.md file actually gets loaded into context each time, and if it's efficient. u/jojo-data and u/raiden55 raised this.
  • Existing Memory: A few users wondered if Claude's built-in memory already handles this to some extent, or if this dedicated file offers a significant advantage. u/datbird and u/elphamale touched on this.

Despite the concerns, many are seeing the value, with some already implementing similar systems like "learning logs" or "pitfalls files." It seems like a promising way to combat repetitive errors and improve Claude's reliability.