AIの繰り返しミスを防ぐ教訓ログの設計：lessons.mdで同じ問題を二度起こさない仕組み
修正したはずの問題が繰り返される
AIをプロジェクトで継続的に使っていると、「先週修正してもらった問題が今週また起きた」という状況に直面します。
AIは会話をまたいで記憶を保持しません。つまり、ある会話でAIが問題を修正したとしても、次の会話ではその修正の経緯を知らない状態でスタートします。同じ指示を出せば同じ判断をするため、同じ問題が繰り返されることがあります。
私がこのサイトを構築する中でよく経験したのは、コンテンツのファイルを特定のディレクトリに配置するルールを一度説明しても、次の会話では別の場所に配置しようとするケースでした。毎回修正するのは非効率です。また「なぜそのルールが存在するのか」という背景も毎回伝え直す必要がありました。
lessons.mdの役割
この問題への対応として作成したのが「lessons.md」というファイルです。過去にAIとのやり取りで発生した問題と、その対処方法を記録するファイルです。
AIが作業を始める前にこのファイルを参照することで、「過去にこういう問題が起きた、このように対処するべき」という情報が提供されます。記憶の代わりに、記録を参照する仕組みです。
記録のフォーマット
lessons.mdの各エントリは、次の5つの要素を含むようにしています。
## [問題のタイトル]
- **発生日**: いつ起きたか
- **状況**: 何をしようとしていたか、何が起きたか
- **原因**: なぜ起きたか
- **対処**: どう修正したか
- **再発防止**: 次回どうすれば防げるかたとえば、ファイル配置の問題であれば次のように書きます。
## ブログ記事を誤ったディレクトリに配置した
- **発生日**: 2026-06-10
- **状況**: 新しいブログ記事を作成する指示を出したところ、src/content/docs/配下に作成された
- **原因**: CLAUDE.mdにブログとドキュメントのディレクトリの区別が明記されていなかった
- **対処**: 記事をsrc/content/blog/ja/配下に移動し、CLAUDE.mdにディレクトリの説明を追記した
- **再発防止**: CLAUDE.mdの「Content Routing」セクションを参照する運用のポイント
lessons.mdは、問題が発生したときにすぐ書くことが重要です。後から思い出して書こうとすると、状況や原因の詳細が曖昧になります。
また、すべての小さな問題を書く必要はありません。記録する価値があるのは「同じ状況で再び発生する可能性が高い問題」です。一度きりの特殊な問題よりも、構造的に繰り返されやすい問題を優先して記録します。
記録が増えてきたら、CLAUDE.mdから参照する形でlessons.mdを位置づけると、AIが作業開始時に確実に参照するようになります。
効果
lessons.mdを導入してから、同じ種類の問題が繰り返される頻度が下がりました。AIが最初に参照するファイルに教訓が含まれることで、問題の前提条件ごとAIに伝わるためです。
また副次的な効果として、問題を記録する習慣ができたことで「なぜそのルールが存在するのか」の背景が残るようになりました。時間が経ってからルールを見直す際にも、経緯が追えるようになっています。
まとめ
AIの記憶はリセットされますが、ファイルはリセットされません。lessons.mdは、過去の問題と対処方法を記録し、AIが参照できる形で保持することで、繰り返しの修正作業を減らすための仕組みです。フォーマットは単純で、重要なのは問題が起きたときにすぐ書く習慣です。