knowledge-ops

# ナレッジ操作 複数のストアにわたって知識を取り込み・整理・同期・検索するための多層ナレッジシステムを管理します。 ライブワークスペースモデルを優先してください: - コード作業は実際にクローンしたリポジトリ内に置く - アクティブな実行コンテキストは GitHub、Linear、リポジトリローカルの working-context ファイルに置く - 広範な人間向けノートはリポジトリ外のコンテキスト/アーカイブフォルダに置くことができる - 耐久性のあるクロスマシンメモリはシャドウリポジトリのワークスペースではなく、ナレッジベースに置く ## アクティベートするタイミング - ユーザーがナレッジベースに情報を保存したい - ドキュメント・会話・データを構造化されたストレージに取り込む - システム間で知識を同期する（ローカルファイル、MCP メモリ、Supabase、Git リポジトリ） - 既存の知識を重複排除または整理する - ユーザーが「KB に保存して」「ナレッジを同期して」「X について何を知っているか」「取り込んで」「ナレッジベースを更新して」と言う - 単純なメモリ呼び出しを超えたあらゆるナレッジ管理タスク ## ナレッジアーキテクチャ ### レイヤー 1: アクティブな実行の真実 - **ソース:** GitHub のイシュー、PR、ディスカッション、リリースノート、Linear のイシュー/プロジェクト/ドキュメント - **用途:** 作業の現在の運用状態 - **ルール:** アクティブなエンジニアリング計画・ロードマップ・ロールアウト・リリースに影響する場合は、まずここに置くことを優先する ### レイヤー 2: Claude Code メモリ（クイックアクセス） - **パス:** `~/.claude/projects/*/memory/` - **フォーマット:** フロントマター付き Markdown ファイル - **タイプ:** ユーザー設定、フィードバック、プロジェクトコンテキスト、リファレンス - **用途:** 会話間で持続するクイックアクセスコンテキスト - **セッション開始時に自動読み込み** ### レイヤー 3: MCP メモリサーバー（構造化ナレッジグラフ） - **アクセス:** MCP メモリツール（create_entities、create_relations、add_observations、search_nodes） - **用途:** 保存されたすべてのメモリに対するセマンティック検索、関係マッピング - **クエリ可能なグラフ構造によるクロスセッション永続化** ### レイヤー 4: ナレッジベースリポジトリ / 耐久性ドキュメントストア - **用途:** キュレートされた耐久性ノート、セッションエクスポート、合成されたリサーチ、オペレーターメモリ、長文ドキュメント - **ルール:** コンテンツがリポジトリ所有のコードでない場合の、クロスマシンコンテキストの優先耐久性ストア ### レイヤー 5: 外部データストア（Supabase、PostgreSQL など） - **用途:** 構造化データ、大規模ドキュメントストレージ、全文検索 - **最適な場面:** メモリファイルには大きすぎるドキュメント、SQL クエリが必要なデータ ### レイヤー 6: ローカルコンテキスト/アーカイブフォルダ - **用途:** 人間向けノート、アーカイブされたゲームプラン、ローカルメディア整理、一時的な非コードドキュメント - **ルール:** 情報ストレージには書き込み可能だが、シャドウコードワークスペースとしては使用しない - **使用しない場面:** アクティブなコード変更や上流に置くべきリポジトリの真実 ## 取り込みワークフロー 新しい知識を取り込む必要がある場合: ### 1. 分類 どのタイプの知識か？ - ビジネス決定 -> メモリファイル（プロジェクトタイプ）+ MCP メモリ - アクティブなロードマップ / リリース / 実装状態 -> まず GitHub + Linear - 個人的な好み -> メモリファイル（ユーザー/フィードバックタイプ） - リファレンス情報 -> メモリファイル（リファレンスタイプ）+ MCP メモリ - 大規模ドキュメント -> 外部データストア + メモリ内サマリー - 会話/セッション -> ナレッジベースリポジトリ + メモリ内短いサマリー ### 2. 重複排除 この知識がすでに存在するか確認する: - 既存エントリのメモリファイルを検索する - 関連用語で MCP メモリをクエリする - 別のローカルノートを作成する前に、その情報が既に GitHub や Linear に存在するか確認する - 重複を作らない。代わりに既存エントリを更新する。 ### 3. 保存 適切なレイヤーに書き込む: - クイックアクセスのために常に Claude Code メモリを更新する - セマンティック検索可能性と関係マッピングのために MCP メモリを使用する - 情報がライブプロジェクトの真実を変える場合はまず GitHub / Linear を更新する - 耐久性のある長文追記はナレッジベースリポジトリにコミットする ### 4. インデックス化 関連するインデックスまたはサマリーファイルを更新する。 ## 同期操作 ### 会話の同期 会話履歴を定期的にナレッジベースに同期する: - ソース: Claude セッションファイル、Codex セッション、その他のエージェントセッション - 宛先: ナレッジベースリポジトリ - クイックブラウジング用のセッションインデックスを生成する - コミットしてプッシュする ### ワークスペース状態の同期 重要なワークスペース設定とスクリプトをナレッジベースにミラーする: - ディレクトリマップを生成する - コミット前に機密設定を編集する - 時系列で変更を追跡する - ナレッジベースやアーカイブフォルダをライブコードワークスペースとして扱わない ### GitHub / Linear の同期 情報がアクティブな実行に影響する場合: - 関連する GitHub イシュー、PR、ディスカッション、リリースノート、またはロードマップスレッドを更新する - 作業に耐久性のある計画コンテキストが必要な場合は Linear にサポートドキュメントを添付する - ローカルノートが追加の価値を提供する場合のみ、後でミラーする ### クロスソースナレッジの同期 複数のソースから一箇所に知識を集める: - Claude/ChatGPT/Grok 会話エクスポート - ブラウザブックマーク - GitHub アクティビティイベント - ステータスサマリーを書き、コミットしてプッシュする ## メモリパターン ``` # 短期: 現在のセッションコンテキスト セッション内タスク追跡には TodoWrite を使用 # 中期: プロジェクトメモリファイル クロスセッション呼び出しのために ~/.claude/projects/*/memory/ に書き込む # 長期: GitHub / Linear / KB アクティブな実行の真実は GitHub + Linear に 耐久性のある合成コンテキストはナレッジベースリポジトリに # セマンティックレイヤー: MCP ナレッジグラフ 永続的な構造化データには mcp__memory__create_entities を使用 関係マッピングには mcp__memory__create_relations を使用 既知エンティティへの新しい事実には mcp__memory__add_observations を使用 既存の知識を見つけるには mcp__memory__search_nodes を使用 ``` ## ベストプラクティス - メモリファイルを簡潔に保つ。ファイルが無限に成長するのではなく、古いデータをアーカイブする。 - すべてのナレッジファイルのメタデータにフロントマター（YAML）を使用する。 - 保存前に重複排除する。まず検索し、次に作成または更新する。 - 事実セットごとに正規のホームを 1 つにする。ローカルノート・リポジトリファイル・トラッカードキュメントにまたがる同じ計画の並行コピーを避ける。 - Git にコミットする前に機密情報（API キー、パスワード）を編集する。 - ナレッジファイルに一貫した命名規則を使用する（lowercase-kebab-case）。 - 取得しやすくするためにエントリにトピック/カテゴリのタグを付ける。 ## 品質ゲート ナレッジ操作を完了する前に: - 重複エントリが作成されていないこと - Git 追跡ファイルから機密データが編集されていること - インデックスとサマリーが更新されていること - データタイプに適切なストレージレイヤーが選択されていること - 関連する場合はクロスリファレンスが追加されていること