Designing a Lessons Log to Prevent Repeated AI Mistakes: How lessons.md Stops the Same Problem from Happening Twice
When a Resolved Problem Comes Back
When using AI continuously in a project, situations arise where a problem I had fixed the previous week surfaces again the following week.
AI does not retain memory across conversations. When a problem is resolved in one session, the resolution exists only within that session. In the next conversation, AI starts fresh with no knowledge of what was fixed or why. If the same instruction is given, the same judgment is made, and the same problem can occur.
A situation I encountered repeatedly while building this site was with file placement. I would explain that content files for a certain type should go in a specific directory, but in the next conversation AI would place them somewhere else. Correcting this each time was inefficient. The background of why the rule existed also had to be re-explained every time.
The Role of lessons.md
The response I developed was a file called lessons.md: a log that records problems that occurred during AI sessions, along with how each problem was resolved.
When AI reads this file at the start of a session, it has access to context from past problems. Rather than relying on memory AI cannot retain, the information is stored in a file AI can always reference.
The Recording Format
Each entry in lessons.md follows a five-part structure.
## [Problem title]
- **Date**: When it occurred
- **Situation**: What I was trying to do; what happened
- **Cause**: Why it happened
- **Resolution**: How it was fixed
- **Prevention**: What to do differently next timeFor the file-placement problem, the entry looks like this.
## Blog article created in the wrong directory
- **Date**: 2026-06-10
- **Situation**: I asked AI to create a new blog article. It created the file under src/content/docs/ instead.
- **Cause**: CLAUDE.md did not clearly describe the distinction between the blog and docs directories.
- **Resolution**: Moved the file to src/content/blog/ja/ and added a directory explanation to CLAUDE.md.
- **Prevention**: Refer to the Content Routing section of CLAUDE.md.Notes on Maintenance
Recording promptly matters. Trying to write entries later from memory means the details of the situation and cause become vague.
Not every minor issue needs to be logged. The entries worth recording are those involving problems that are structurally likely to recur. I prioritize problems that arise from the way instructions are phrased or from ambiguity in the project setup, rather than one-off technical errors.
Once the log grows to a reasonable size, referencing it from CLAUDE.md ensures AI reads it reliably at the start of each session.
The Effect
Since I introduced lessons.md, the frequency of the same category of problem recurring has decreased. Because the relevant context is included in a file AI reads at the outset, the conditions that led to a problem are communicated before work begins.
A secondary benefit has been the record of why each rule exists. When I revisit a rule months later and wonder what prompted it, the lessons log provides the history.
Summary
AI memory resets. Files do not. lessons.md is a mechanism for reducing repeated corrections by recording past problems and their resolutions in a form AI can reference. The format is straightforward. What matters most is the habit of recording problems when they occur.