compile-knowledge

compile-knowledge

いつ実行するか

次の2つのトリガーに限ります。

1. 明示的な永続化の依頼 — 「これを保存して」「これをWikiに書いて」 「Wiki／メモリを更新して」「この調査結果を記録して」「この知識を整理して」 「karpathyメソッドに従って」など。
2. 長く残す価値のある、判断を含む成果物 — 意思決定の記録、調査結果の背後にある 原因、ギャップ分析、習得に実作業を要し、もう一度習得するにも実作業を要する 自明ではない事実。

通常の分析作業では実行しません。事実に関する質問への回答、ファイルの要約、 コードの説明、定例タスクの結果報告からは、後で活用できる知識は生まれません。 リポジトリや会話の記録にすでにある内容を言い換えるだけなら、記録は不要です。

長く残す価値のある知識は、巨大な文書やチャットログ、すぐに古くなる単発のファイルではなく、 時間をかけてまとめた、相互につながる小さなMarkdownファイルとして保存し、インデックスから 参照できるようにする価値があります。このスキルを使えば、知識の整理に一貫性が生まれ、 エージェントは同じことを何度も学び直すのではなく、時間とともに賢くなります。

保存先 — 適切なストアを選ぶ

• エージェントメモリ（デフォルト、常に利用可能）：.claude/.../memory/ フォルダー内にあり、インデックスとして MEMORY.md を使います。エージェントごとの ストアで、再起動後も残ります。セッションをまたいで能力を保つ、karpathyの 「外部メモリ」に相当します。システムプロンプトに定められたメモリのルールに従ってください。 ほとんどのエージェントにとって、必要なストアはこれだけです。
• チームWiki（ほかのエージェントと環境を共有している場合）：オーナーのビジネスについて チーム全体が知っておくべきこと、たとえば顧客、価格、サプライヤー、意思決定、 オーナーの好む作業方法などを記録します。5dive memory add --store=wiki --name=<slug> --description="<one line>" （本文は標準入力から）で公開すると、ファイルとインデックスの項目が書き込まれ、 同僚の 5dive memory search から検索できるようになります。代わりにプロジェクト内に wiki/ フォルダーを作らないでください。ほかのエージェントの検索では読み取れません。 自分だけがエージェントである場合は省略してください。チーム向けの手順を無理に作る必要はありません。

目安：「自分だけがこれに基づいて行動する」ならメモリ。「チームの誰かが必要とする 可能性がある」ならチームWikiです。関連する場合は [[slug]] で相互リンクしてください。

非同期パイプラインとあなたの役割 — 分担

一部のプラットフォームでは、終了したセッションを対象に自動統合処理が実行されます （5diveでは 5dive memory consolidate が、heartbeatによってスケジュールされます）。 利用中のプラットフォームにこの機能がある場合、処理の対象と、自分にしかできないことを 把握してください。

• 自動処理 — 事実そのもの。 統合処理は、終了したセッションの会話記録を要約し、 自分のストアにメモリアトムとして保存します。進行中のセッションを読むことはなく、 書き込んだ内容が自分の環境の外に出ることもありません。セッション内の事実を残すために、 手作業でコピーする必要はありません。コンテキストウィンドウが閉じても知識が失われないように するのが、この処理の役目です。
• 自分の役割 — 判断。 Wikiページ、理由を伴う意思決定、ギャップ分析、調査結果の 背後にある原因は、会話の記録に明記された内容しかパイプラインで取り出せません。 自分が導き出した結論は、そこに書かれているとは限りません。また、共有Wikiへの公開も できません。ストアを選択する機能がなく、共有ストアは設計上デフォルトで拒否されるため、 チームストアへの公開は、内容を選んで行う作業であり、その役目はあなたにあります。

これにより、整理する内容の範囲は絞られますが、整理そのものが不要になるわけではありません。 判断を含む知識は、タスクを終える前に、引き続き以下の手順で整理してください。

書く前に — 整理の確認

長く残す価値があり、自明ではない事実だけをまとめてください。次に該当する場合は省略して、 先に進んでください。

• 定例的な内容、またはリポジトリ、Gitの履歴、既存のドキュメントから導き出せる内容
• この会話でしか当てはまらない内容
• 既存のファイルで扱われている内容（→ 重複させず、そのファイルを更新してください）

デプロイ、再起動、1行の修正など、ほとんどのタスクから長く残す価値のある知識は生まれません。 それで問題ありません。「何かを書いた」実績を作るために、無理にメモリを作らないでください。 中身のない情報は、何も残さないよりも悪く、情報検索の品質を損ないます。

手順

1. まず検索します。 このトピックに関する既存のファイルを探します（5dive では、5dive memory search "<topic>" を実行すると、自分のストアとチームの Wiki が検索されます）。既存のファイルがあれば、それを編集します。内容がほぼ重複するファイルを新規作成してはいけません。
2. 1ファイル1項目にします。 1つの事実、または1つのトピックにつき1ファイルです。無関係な別の事実も追加したくなったら、それは別ファイルにします。
3. 名前を付けます。 kebab-case のスラッグを使います。メモリには種類を示すプレフィックス（feedback_…、project_…、reference_…、user_…）を付け、Wiki にはトピックが明確に分かるスラッグを使います。このスラッグがリンク先になります。
4. フロントマターを付けます。 name（＝スラッグ）、description（1行のみ。想起時の照合に使われるため、具体的に記述します）、および type／カテゴリを指定します。
5. 本文を記述します。 事実を簡潔に明記します。関連項目には [[slug]] でリンクします。まだ存在しないファイルへのリンクも、問題なく TODO の目印として使えます。feedback／project の場合は、続けて Why: と How to apply: の行を記述します。
6. インデックスを更新します。 インデックスに1行の参照を追加または更新します（メモリの場合は MEMORY.md、チーム Wiki の場合は 5dive memory add が該当行を自動で書き込みます）。 - [Title](slug.md) — hook。約200文字以内に収めます。詳細はファイルに記述し、インデックスには載せません。
7. 整理します。 誤りだと分かったファイルは削除します。相対日付は絶対日付に直します。インデックスが長くなってきたら、行を簡潔にして、肥大化させないようにします。

ライフサイクル — 黙って上書きせず、置き換えを明示する

事実は古くなります。時間に左右されるもの、不確かなもの、古い事実を置き換えるものには、想起時に古い情報として扱えるよう、エンベロープに以下を記録します。

• valid_to: YYYY-MM-DD — 事実の有効期限、または再確認が必要になる日付です。期限を過ぎると、事実は残りますが、想起時に優先度が下がり、⚠ expired のフラグが付きます。
• supersedes: <slug> — 新しい事実が古い事実を置き換える場合、古いスラッグを指定します。これにより、想起時には古い事実の優先度が下がり（⤴ superseded）、矛盾する回答が2つ残り続けることを防げます。古い値を監査記録として残す価値がある場合は、既存の内容をその場で編集するよりも、この方法を優先してください。古い値を残す必要がない場合は、その場で編集します。
• confidence: high|medium|low — 確信度が低または中の事実は優先度が下がるため、推測が検証済みの事実より優先されることはありません。
• provenance: "<source>" — 事実の出所を示します。メモを書いた人を示す compiled_by とは異なります。

ストアに CLI がある場合、これらをフラグとして指定できることが多くあります。5dive では、5dive memory add に --valid-to=、--supersedes=、--confidence=、--provenance= を指定できます。いずれも省略可能です。省略しても動作は変わらず、上記のフロントマター項目はどの環境でも使える形式です。

アンチパターン

• 内容を項目ごとのファイルに分けず、長文のドキュメントにまとめる。
• 調査結果を、統合されないまま独立した notes.md として残すこと。これは作業メモであり、ナレッジではありません。長期的に役立つ情報を整理してストアにまとめてください。
• 同じ事実をメモリと Wiki の両方に重複して記載する。保存先は1つに決め、相互にリンクしてください。
• ファイル全体の内容を繰り返すインデックス項目。
• 習慣やチェックリストを満たすためだけに、意味のない文章を書くこと。

簡易チェックリスト

[ ] 長期的に役立ち、ひと目では分からない内容か？ [ ] 適切なストアか？ [ ] 既存項目の更新ではなく新規作成が適切か？ [ ] 1ファイル1項目で、名前とフロントマターを設定したか？ [ ] [[リンク]]を追加したか？ [ ] インデックスに1行追加したか？