lessons.mdでAI作業の判断経緯を残す方法
この記事で学べること
- 会話上の注意をlessons.mdへ残し、検証可能な判断履歴へ変える理由
- 問題、原因、対処、再発防止、確認方法を記録するフォーマット
- 一度限りのミスと、継続的に記録・更新すべき問題を分ける基準
会話の注意事項を検証できる判断履歴へ変える
AI作業の判断履歴を再利用できる状態にするには、問題、原因、対処、再発防止、確認方法を人が読める記録へ残します。このサイトでは、一度直した問題でも会話中の注意だけでは別の作業で戻ることがありました。lessons.mdはAIの記憶ではなく、次の担当やセッションが検証できるプロジェクトの記録として使います。
この記事では、「どの問題をlessons.mdへ残し、再発条件と確認方法をどう記録するか」という問いに焦点を当て、実行前の前提、作業手順、完了を確かめる方法を扱います。
最後まで読むと、「どの問題をlessons.mdへ残し、再発条件と確認方法をどう記録するか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
修正したはずの問題が繰り返される
AIをプロジェクトで継続的に使っていると、以前修正した問題が別の作業で再び現れることがあります。
セッションをまたいだ記憶や履歴の扱いは、AI製品、実行環境、設定によって異なります。Memory機能がある場合でも、公開責任やチームの必須ルールを製品内部の記憶だけへ置くと、人が内容と更新履歴を確認しにくくなります。本記事では、AIが過去の会話を覚えているかどうかに依存せず、必要な判断をリポジトリで管理する方法を扱います。
私がこのサイトを構築する中でよく経験したのは、コンテンツのファイルを特定のディレクトリに配置するルールを一度説明しても、次の会話では別の場所に配置しようとするケースでした。毎回修正するのは非効率です。また「なぜそのルールが存在するのか」という背景も毎回伝え直す必要がありました。
lessons.mdは問題・原因・判断・再発防止を次の作業へ残す
この問題への対応として作成したのが「lessons.md」というファイルです。過去にAIとのやり取りで発生した問題と、その対処方法を記録するファイルです。
ルートの指示ファイルや作業手順からこのファイルを参照するよう案内すると、「過去に何が起き、どの条件でどう対処したか」を次の作業で確認できます。AI内部の記憶を置き換えるのではなく、人とAIが同じ記録を読める状態を作る仕組みです。
lessons.mdは問題・原因・対処・確認方法を同じ形式で記録する
lessons.mdの各エントリは、次の5つの要素を含むようにしています。
## [問題のタイトル]
- **発生日**: いつ起きたか
- **状況**: 何をしようとしていたか、何が起きたか
- **原因**: なぜ起きたか
- **対処**: どう修正したか
- **再発防止**: 次回どうすれば防げるかたとえば、ファイル配置の問題であれば次のように書きます。
## ブログ記事を誤ったディレクトリに配置した
- **発生日**: 2026-06-10
- **状況**: 新しいブログ記事を作成する指示を出したところ、src/content/docs/配下に作成された
- **原因**: CLAUDE.mdにブログとドキュメントのディレクトリの区別が明記されていなかった
- **対処**: 記事をsrc/content/blog/ja/配下に移動し、CLAUDE.mdにディレクトリの説明を追記した
- **再発防止**: CLAUDE.mdの「Content Routing」セクションを参照するlessons.mdは再発可能な判断だけを短く保守する
lessons.mdは、問題が発生したときにすぐ書くことが重要です。後から思い出して書こうとすると、状況や原因の詳細が曖昧になります。
また、すべての小さな問題を書く必要はありません。記録する価値があるのは「同じ状況で再び発生する可能性が高い問題」です。一度きりの特殊な問題よりも、構造的に繰り返されやすい問題を優先して記録します。
記録が増えてきたら、CLAUDE.mdやAGENTS.mdなどの初期指示ファイルからlessons.mdの場所と読む条件を案内します。ただし、Markdownの参照だけで読み込みや遵守が保証されるわけではありません。重要な項目は、検証スクリプト、権限設定、フック（特定のタイミングで処理を自動実行する仕組み）、レビューでも確認します。
lessons.mdへ残す項目を選ぶ
次の条件を満たす問題を優先して記録します。
- 同じ入力や作業条件で再び起きる可能性がある
- 原因と対処を、観測した事実と推測に分けて書ける
- 次回の確認方法または停止条件を示せる
一度きりのエラー、原因を確認できていない推測、個人の好みだけに基づく指摘は、恒久的な教訓として残す前に整理します。
lessons.mdから再発条件と確認手順を追跡できる
このリポジトリでは、問題の発生日、原因、対処、再発防止を同じ場所に残すことで、「なぜそのルールが存在するのか」を後から追えるようにしています。これは問題件数の減少を測定した結果ではなく、判断経緯をリポジトリから確認できるようになったという運用上の変化です。
ルールへ昇格させる場合は該当するlessonから参照し、ルールを削除する場合も元の問題が現在の構成で再発しないか確認します。古いlessonをそのまま適用し続けず、現在のコードや運用と一致しているかを定期的に見直します。
まとめ：再発する判断だけをlessons.mdへ残し、検証方法まで書く
lessons.mdは、AIが記憶しているかどうかに依存せず、過去の問題と対処を人が確認できる形で残す仕組みです。問題が起きたら、状況、原因、対処、次回の確認方法を分けて記録します。初期指示ファイルは参照を促す役割、検証スクリプトやレビューは遵守を確認する役割として分けることが重要です。
最初に再発した問題を1つ選び、原因と次回の確認方法を別々に記録します。一度限りの出来事や未確認の推測まで蓄積すると記録が探しにくくなるため、再発条件と更新責任を説明できる項目に絞ってください。