「Caveat」をnpm公開：AI開発における「長期記憶レイヤ」で、過去の技術的罠を構造的に記録・共有
本記事は、Claude Code向けの「Caveat」という長期記憶レイヤをnpmに公開した技術的な取り組みについて詳細に解説している。開発者がClaude Codeを利用する際、単なる実装以上の「他人の仕様解明」に膨大な時間を費やすという課題を解決することを目的としている。具体的には、GPUドライバのバージョン制約、ネイティブモジュールのビルド失敗、IDEの癖、特定OSでのパス問題など、一度ハマって解決した「罠」を、後から同じプロジェクトや別プロジェクトで再遭遇するのを防ぐ仕組みを提供する。
Caveatの核となる機能は、単なるキーワード検索ではなく、プロンプト送信時、ツールエラー時、セッション終了時の3つの「発火点」で動作することにある。プロンプト送信時には、過去のメモと2語以上が共起するエントリを自動で浮上させ、関連性を構造的に検出する。ツールエラー時にはバックグラウンド検索を行い、既知の罠として通知する。セッション終了時には、AIが自覚していない「もがきシグナル」（ツール失敗、同じファイル編集の繰り返しなど）を抽出し、新規の罠として記録すべきかユーザーに促す。
また、検索ロジックはキーワードリストを持たず、「共起FTS」のみに依存することで、新しい罠カテゴリが増えてもコードやキーワード表の修正が不要な自己拡張性を実現している。ナレッジはMarkdown形式でGit管理され、Obsidianなどの標準的なMarkdownビューアで開けるため、中央サーバーを持たず、高い移植性を保っている。エントリには「Public」（誰でも共有可能な罠）と「Private」（プロジェクト固有の機密情報）の2層の可視化があり、機密性の管理も考慮されている。
導入は`npm install -g caveat-cli`で可能であり、個人から小規模チームでの利用を想定している。
背景
大規模言語モデル（LLM）を用いた開発環境では、コードの実装自体よりも、外部ライブラリやOS、IDEといった「環境の仕様」の解明に多くの工数が費やされる。この「仕様の罠」を個人の記憶やドキュメントに頼るのではなく、構造的かつ自動的に捕捉・共有する仕組みが必要とされてきた。
重要用語解説
- 長期記憶レイヤ: LLMのセッション外で、過去の経験や環境の制約といった「罠」を構造的に記録し、必要なタイミングで自動的に関連情報を提示する仕組み。単なる検索ではなく、文脈的な関連性を重視する。
- 共起FTS: キーワードリストに頼らず、入力されたプロンプト内の複数の単語（2語以上）が同時に含まれるエントリを検索する技術。これにより、事前に定義されていない新しい関連性も発見できる。
- もがきシグナル: AI（LLM）が自覚していないが、客観的な行動ログ（ツール失敗、同じファイルの繰り返し編集など）から抽出される、ユーザーが技術的な困難に直面していた痕跡やパターン。
今後の影響
本ツールは、AIを活用した開発プロセスにおける「非構造化な知識（暗黙知）」の形式知化を大きく進める。これにより、開発者は環境設定や仕様の調査に費やす時間を大幅に削減し、より本質的なロジック構築に集中できるようになる。小規模チームや個人開発者にとって、知識共有の障壁を劇的に下げる可能性を秘めている。