You are rebuilding the same thing every week. Not the code. The context. Every time you open a new Claude Code session, you explain your stack, your conventions, your quirks. Claude makes a mistake. You correct it in chat. The session ends. Next week, same mistake. Same correction. Same tax, over and over.
That is not a tool problem. It is a workflow problem. And the fix is a single file called lessons.md.
The Real Cost of Starting From Scratch
Most developers using Claude Code treat every session as a fresh start. They correct mistakes in line, get the output they need, and move on. The correction is effective. It is also invisible. It disappears the moment the window closes.
This matters more than most people realise. Every correction you make in chat that you do not capture is knowledge you throw away. You paid for it with time and attention. Then you let it evaporate.
Do that for a month, and your Claude Code workflow is flat. Do it for a year, and you have made no progress. The tool has not gotten better. You have not gotten better at using the tool. You are exactly where you started, just with more hours logged.
There is a better way.
What lessons.md Actually Is
Boris Cherny, the engineer who built Claude Code at Anthropic, runs a feedback loop that compounds. Every mistake Claude makes in his workflow becomes a rule. That rule goes into a file called lessons.md. In the next session, Claude reads the file. The mistake does not happen again.
lessons.md is not a style guide. It is not a preferences document. It is not architecture documentation.
It is a correction log. Each entry has two parts:
The mistake. Concrete and specific. Not “Claude wrote messy code.” Something like: “Claude used npm install instead of bun add when adding a dependency.”
The rule. The minimum instruction that prevents the mistake. “Use bun, not npm, for all package operations.”
That is it. No commentary. No explanation. The file grows only when something actually goes wrong, and only with the rule that would have caught it.
How the Loop Works
The workflow has three steps. Each takes under a minute.
Step 1: Notice the mistake. You are mid-session. Claude does something wrong. Wrong package manager, wrong test runner, wrong assumption about your auth layer. Whatever it is.
Step 2: Correct it in chat. Fix it the normal way. Tell Claude what to do instead. Move on.
Step 3: Write the rule before you close. One line in lessons.md. The mistake. The rule. Done.
Next session, Claude reads lessons.md. The mistake does not happen again. That correction you made yesterday is now permanent.
Do this for 30 days. You will have a file that no generic CLAUDE.md template could ever produce, because no template knows your codebase, your stack, or your specific habits. This file does.
Here is what to do right now. Open your project. Create lessons.md in the root. Add one line to your CLAUDE.md: “Read lessons.md at the start of every session. Follow every rule in it.” That is the whole setup. The file starts empty and earns its content from real mistakes.
Why This Beats Anticipating Everything Upfront
Most CLAUDE.md files grow to 800 or 1,000 lines because developers try to anticipate every possible problem. They write rules for edge cases that Claude handles correctly by default. They explain best practices Claude already knows.
The result is noise. The more irrelevant content Claude has to process, the harder it is for the important rules to surface when they matter.
lessons.md takes the opposite approach. You do not anticipate. You react. Nothing goes in the file until a mistake actually happens. Every line earns its place by preventing something real.
Boris’s CLAUDE.md is around 100 lines for the same reason. He does not write rules speculatively. He waits for Claude to get something wrong, then captures the fix. The full breakdown of his approach is worth reading if you have not already.
What Compound Engineering Actually Means
Most people treat Claude Code like a vending machine. Insert prompt, get output, move on. That is a fine way to use it. It is also a flat way to use it. The tool stays exactly as useful as it was on day one.
Compound engineering means your system improves through use. Every session makes the next session faster. Every correction becomes a permanent upgrade. The work you do today pays you back tomorrow.
lessons.md is the mechanism. It is the simplest possible implementation of a learning loop. It requires no tooling, no plugins, no configuration. A text file and a habit.
The developers who figure this out early stop paying the same correction tax every session. Their Claude Code setup does things that no template or shared CLAUDE.md can replicate, because it has been trained on their specific mistakes, in their specific codebase, over real time.
The gap between that group and everyone else compounds too.
The Shift That Changes Everything
You stop treating Claude Code as a tool that produces output. You start treating it as a system you improve.
Every mistake is a free upgrade if you capture it. Every session where you do not write a rule is a session where you paid for a lesson and threw it away.
That mindset shift is the whole point. The vending machine crowd will keep retyping the same corrections next year. The developers who build the feedback loop will be running a system that gets sharper every week.
Start today. One file. One line in CLAUDE.md. One rule after the next mistake.
If you want the full picture on how this fits into a modern AI-augmented workflow, agentic engineering covers the bigger shift. And if you want to see how Boris structures his CLAUDE.md to stay lean while this file grows, 32 Claude Code hacks that actually move the needle is the right next read.
The question is not whether Claude Code can get smarter. It can. The question is whether you are running the loop that makes it happen.