Vaultの構造とデバッグ

検索可能な第二の記憶としてMarkdown Vaultを整理します。Claudeが予期しない動作をした場合の4つの失敗モードをトリアージします。

STATE.mdとMEMORY.mdは、すべてのセッションが必要とするものを保持します。Markdown Vault（Obsidianまたは任意のフォルダ）は、それ以外のすべてを保持します: 戦略ノート、会議の議事録、プロジェクトジャーナル、研究、競合分析。

Vaultは機関の記憶に成長します: 6ヶ月前に行った決定とその理由、現在の作業に役立つ参照資料、プロジェクトにまたがるパターン。ObsidianまたはファイルシステムMCPを介して接続すると、Claudeはオンデマンドで全体を検索できます。Vaultがなければ、この知識はあなたの頭の中にあるか、古いドキュメントに埋もれているだけです。

Markdownがデータベースよりも優れている理由: プレーンファイルはgrep可能で、gitでバージョン管理され、どのエディタでも開き、すべてのツール変更を生き残ります。機能する構造:

~/notes/

├── STATE.md # Always loaded

├── MEMORY.md # Index, always loaded

├── STRATEGY-DIGEST.md # Summaries of strategy docs

├── strategy/ # Full docs, read on demand

├── projects/ # Dated project notes

├── resources/

└── reference/スケーリングの鍵はダイジェストパターンです: 1,000語の戦略ドキュメントを作成するときは、それと並行して3文のダイジェストを作成し、MEMORY.mdにダイジェストをインデックス化します。Claudeはセッション開始時に約50トークンを読み取り、完全なドキュメントの約1,500トークンは読み取りません。25個の戦略ドキュメントがある場合、37,500トークンではなく1,250トークンになり、セッションは高速に保たれます。

Claudeが予期しない動作をした場合、4つの失敗モードを順に確認してください（最も一般的なものから最も一般的でないものへ）:

古い記憶: STATE.mdは1つのことを言っているが、現実は別のことを言っている。Claudeはあなたの指示に完璧に従ったが、指示が間違っていた。毎回、最初に「STATE.mdを見せて」と尋ねてください。

コンテキストの欠落: 関連ファイルがロードされなかったため、Claudeは合理的な推測をした。ファイルを明示的にロードし、再度尋ねてください。

ツールが利用できない: MCPがダウンしているか、フックがコマンドをブロックし、Claudeがそれをひどく回避した。推論を責める前に、ツールの可用性を確認してください。

幻覚: 最もまれな原因。最初に確認してください: 関数をgrepし、エンドポイントが存在することを確認してください。ほとんどの「幻覚」は、最初の3つのいずれかであることが判明します。

失敗モードごとに1つの診断質問:

古い記憶: 「あなたのSTATE.mdは[トピック]について何と言っていますか？」 3セッション前のコンテンツは古い状態を意味します。

コンテキストの欠落: 「[トピック]についてロードされているファイルは何ですか？」 関連ファイルがない場合は、正しいファイルをロードします。

ツールが利用できない: 「現在利用できるツールは何ですか？」

幻覚: 「[関数/エンドポイント]をgrepして、何が見つかったか教えてください。」

このシーケンスは2分かかり、ほとんどの場合原因を見つけます。「Claudeが幻覚を見た」とすぐに結論付けると、通常、書き直す必要のないコードを書き直すことで、実際の修正が遅れます。

デバッグよりも予防が優れています。 習慣:

セッション終了時のSTATE.md更新。 古い記憶の問題の80%を排除します。

出荷されたプロジェクトをアーカイブし、日付付きのproject_*ファイルに入れます。

毎月のMEMORY.md監査: すべてのポインタが既存のファイルを指していることを確認します。

500語を超えるすべてのドキュメントをダイジェストします。

決定の瞬間に決定を記述します。 週の終わりではなく。遡及的な捕捉は推論を失います。

プロジェクトノートをアーカイブする前に、 永続的な教訓をfeedback_*エントリに抽出します。プロジェクトは履歴になりますが、教訓はアクティブなままです。

よく維持された10個のドキュメントを持つVaultは、200個の古いドキュメントを持つVaultよりも優れています。品質と鮮度が量よりも優れています。

ObsidianまたはファイルシステムMCPを使用すると、Vaultはライブ知識ベースになります:

決定の考古学: 「PostgresをMySQLよりも選択した理由をVaultで検索。」10分の手動検索が15秒になります。

パターン検出: 「プロジェクト全体でレート制限の問題または429エラーのすべての言及を見つける。」Claudeは、5つのプロジェクトファイルにまたがる共通の根本原因を表面化します。

参照ルックアップ: 「ベンダーノートの連絡先情報を見つける。」インデックス化されていないファイルからの即時取得。

検索品質は命名の一貫性に依存します: project_[name]_[date].mdとfeedback_[rule].mdは、その時に自然に感じたものよりも優れています。命名規則は、必要になる前に構築するインデックスです。

4つのモードすべてがクリーンにチェックアウトされ、出力がまだ間違っている場合？ 幻覚のように見えるがそうではない2つの原因。

コンテキストの順序: ロードされたファイルが競合する場合、後からロードされたコンテンツが勝つ傾向があります。古いプロジェクトノートがSTATE.mdと矛盾する場合、権限を明示的に割り当てます: 「STATE.mdが現在の真実です。プロジェクトノートのすべてに優先します。」

制約の衝突: CLAUDE.mdが「すべてのSQLをパラメータ化する」と指示しているため、Claudeはあなたがスタイルのみのリファクタリングを意図していたときにSQLを書き換えます。バグではありません。明示的にスコープを設定します: 「スタイルのみ、SQLパターンは変更しないでください。」

両方の診断: 「[この決定]を管理するどのような指示に従っていますか？ ルールを優先順位順にリストしてください。」 古いソース、競合するルール、またはCLAUDE.mdのギャップが見つかるでしょう。すべて修正可能です。

ダイジェストファイルを含むMarkdown Vaultは、あなたの第二の記憶を拡張します。ダイジェストはセッションを高速に保ち、完全なドキュメントはオンデマンドでロードされます。Claudeが誤動作した場合、古い記憶、コンテキストの欠落、ツールの利用不可、幻覚の順にトリアージし、常に「STATE.mdを見せて」から始めます。決定の瞬間にVaultにフィードすると、毎週その価値が複合的に増加します。