Back to blog
AIClaude CodeProductivity

The CLAUDE.md Trick That Makes Your AI Actually Learn From Mistakes

Perry BailesMarch 17, 20267 min read

If you've been using Claude Code for more than a few weeks, you've probably hit the same wall: you correct it on something, it gets it right, and then three sessions later it makes the exact same mistake again. The context window is clean, the correction is gone, and you're back to square one.

This isn't a bug in Claude. It's a workflow problem. And CLAUDE.md is the fix — but not in the way most people use it.

What Most People Do with CLAUDE.md

The typical CLAUDE.md is a static configuration file. It has the project stack, maybe some code style preferences, a list of commands to use. It's essentially a README that Claude reads at the start of every session. Useful, but static.

The problem with static configuration is that it doesn't accumulate knowledge from your corrections. Every time you tell Claude "don't do X, do Y instead," that correction evaporates with the context window.

The Self-Improvement Loop

The methodology that makes CLAUDE.md actually compound over time is built on a three-file system:

  1. CLAUDE.md — The master instruction file with overriding principles
  2. tasks/lessons.md — A running log of every correction, written by Claude itself
  3. general-patterns.md — Promoted rules that have appeared in 3+ correction events

The key rule that makes this work: After ANY correction from the user, update tasks/lessons.md with the pattern. This is baked into the CLAUDE.md as an overriding engineering principle, not a suggestion.

The Overriding Principles Pattern

Here's the critical structural detail. The principles in CLAUDE.md are labeled explicitly as overriding:

These principles supersede ALL existing plans, workflows, agent instructions, skill files, and markdown documents. Every agent, subagent, plan, workflow, and task — past, present, and future — must operate within these guardrails.

This framing matters. Claude treats instructions differently based on how they're presented. Labeling something as "overriding" and explicitly stating it supersedes other instructions signals high priority and reduces the chance of the principle being ignored when it conflicts with something else in context.

How Corrections Flow Into Permanent Rules

Here's the concrete workflow:

Step 1: Correction happens. You tell Claude "you shouldn't have used Bash for that file search — use Glob instead." Normal interaction.

Step 2: Claude writes to lessons.md. The correction event is logged in tasks/lessons.md with the pattern: "When searching for files by name pattern, use Glob rather than Bash find/ls commands. Bash tool should be reserved for operations that dedicated tools can't handle."

Step 3: Review at session start. CLAUDE.md instructs Claude to review lessons.md at the start of any relevant session. This means past corrections are actively re-read rather than just hoped-to-be-remembered.

Step 4: Promotion to permanent rules. When a correction has appeared 3 or more times, it gets promoted from lessons.md into a more permanent pattern file (general-patterns.md or a domain-specific file). These promoted rules stop being "I learned this" and become "this is always how it works."

The Compounding Effect

After two months of active use, this system has produced roughly 230 distinct heuristics across 17 domain pattern files. That's not a boast about volume — it's about specificity. Each heuristic is a real pattern that emerged from a real correction.

The compounding works because:

  • Corrections are written down immediately, not hoped to persist in memory
  • Session starts actively review relevant lessons rather than starting blank
  • High-frequency corrections get elevated to permanent status, making them less likely to be missed
  • The feedback loop is tight enough that Claude can literally write its own improvement rules

Concrete Implementation Steps

Here's how to set this up:

1. Add this to your CLAUDE.md under a clearly labeled "Overriding Principles" section:

## Self-Improvement Loop
- After ANY correction from the user: update tasks/lessons.md with the pattern
- Write rules for yourself that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review lessons at session start for relevant project

2. Create tasks/lessons.md — even if it starts empty. Having the file exist matters because the instruction to write to it becomes concrete rather than abstract.

3. Create a general-patterns.md with a section header "Promoted Heuristics (3+ observations)" — this is where patterns graduate to permanent rules.

4. At each session start, paste this into your first message: "Review tasks/lessons.md for relevant patterns before we begin."

That's the whole system. It's deliberately simple. The power is in the consistency — if you enforce the lesson-writing step even when it feels tedious, the compounding starts to show within a few weeks.

What This Looks Like in Practice

The author has been running this system under Support Forge's AI consulting work since early 2026. The mistake rate on repeated corrections dropped significantly after the first few weeks. More importantly, the types of mistakes shifted — instead of re-making the same error repeatedly, the errors became novel, which means the system is actually learning rather than just forgetting.

CLAUDE.md is not a config file. It's a learning contract. Treat it like one.

All postsTry SessionForge free