How to Preserve AI Workflow Decisions in lessons.md
What you’ll learn
- Why lessons.md turns conversational cautions into a verifiable decision history
- A format for recording the problem, cause, resolution, prevention, and verification method
- How to distinguish one-time mistakes from issues that need durable records and updates
Turn Conversational Cautions into a Verifiable Decision History
A reusable decision history records the problem, cause, resolution, prevention, and verification method in a form people can inspect. On this site, a conversational warning did not always prevent a corrected problem from returning in another task. lessons.md is a project record for the next owner or session to verify, not a claim about an AI product’s memory.
By the end of this article, you will have practical criteria for answering “Which problems belong in lessons.md, and how should recurrence conditions and verification be recorded?” in your own context.
When a Resolved Problem Comes Back
When using AI continuously in a project, a problem resolved in one task can surface again in another.
Cross-session memory and history depend on the AI product, execution environment, and configuration. Even when a product provides memory, placing publication responsibility or required team rules only in product-internal memory makes the content and its update history difficult for people to inspect. This article therefore manages required decisions in the repository without assuming what a later session remembers.
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.
lessons.md Carries Problems, Causes, Decisions, and Prevention into Later Work
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 a root instruction file or workflow points to this file, a later task can inspect what happened, under which conditions, and how it was handled. The file does not replace product memory; it gives people and AI tools a shared record they can both review.
Record Problem, Cause, Response, and Verification in a Consistent 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.Keep lessons.md Focused on Decisions That Can Recur
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, point to its location and reading conditions from an initial instruction file such as CLAUDE.md or AGENTS.md. A Markdown reference does not guarantee loading or compliance by itself. Important items also need validation scripts, permission settings, hooks (automatic actions at a specified timing), or review.
Choose What Belongs in lessons.md
Prioritize a problem when:
- it can recur under the same input or task conditions
- its cause and resolution can separate observed facts from inference
- the next check or stopping condition can be stated
Do not promote a one-time error, an unverified cause, or a personal preference into a permanent lesson without first narrowing its scope.
lessons.md Makes Recurrence Conditions and Verification Steps Traceable
In this repository, keeping the date, cause, resolution, and prevention together makes the reason for a rule traceable later. This is an observable workflow change, not a measured result showing that issue counts decreased.
When a lesson becomes a rule, link the rule back to the originating lesson. When removing a rule, check whether the original problem can still recur in the current system. Review older lessons periodically instead of applying them indefinitely after the code or workflow changes.
Summary: Keep Recurring Decisions in lessons.md and Record How to Verify Them
lessons.md keeps past problems and resolutions in a form people can inspect without depending on what an AI product remembers. Record the situation, cause, resolution, and next verification method separately. Initial instruction files should point to the record; validation and review should confirm whether critical requirements were followed.
Start with one recurring problem and record its cause separately from the next verification method. One-time events and unconfirmed guesses make the record harder to use, so retain only items whose recurrence condition and maintenance owner can be explained.