wiki-update

Wiki の更新 — 任意のプロジェクトを Wiki に同期

現在のプロジェクトから知識を抽出し、ユーザーの Obsidian Wiki にまとめます。このスキルは、obsidian-wiki リポジトリだけでなく、任意のプロジェクトディレクトリで動作します。

開始前に

執筆プロファイル： 自然言語の Markdown を新規作成または書き直す前に、llm-wiki/SKILL.md の Writing Profile Resolution セクションを読み、適用してください。フレームワークのスキーマ、出典、安全性、および操作固有の要件が優先されます。 WRITING.md の設定は、新たに作成または書き直す自然言語の Markdown にのみ適用されます。ソースコンテンツと構造化レコードはそのまま保持してください。

1. 設定を解決する — llm-wiki/SKILL.md の Config Resolution Protocol（インラインの @name による上書き → CWD を起点に .env を上方向にたどる → グローバル設定 → セットアップを促す）に従います。これにより、OBSIDIAN_VAULT_PATH、OBSIDIAN_WIKI_REPO、OBSIDIAN_LINK_FORMAT（既定値は wikilink、または markdown）、および QMD_WIKI_COLLECTION などの任意の QMD 設定が決まります。任意のプロジェクトディレクトリで動作します。
2. $OBSIDIAN_VAULT_PATH/.manifest.json を読み、このプロジェクトが以前に同期されているか確認します。
3. $OBSIDIAN_VAULT_PATH/index.md を読み、Wiki にすでに何が含まれているか確認します。

ステップ 4〜5 で内部リンクを書く際は、OBSIDIAN_LINK_FORMAT の値を使い、llm-wiki/SKILL.md のリンク形式セクションに記載されたリンク形式を適用してください。

ステップ 1：プロジェクトを理解する

現在の作業ディレクトリを調べて、このプロジェクトが何かを把握します。

• README.md、docs/、その他の Markdown ファイル
• ソースの構成（フレームワーク、言語、主要な抽象化）
• プロジェクトの定義に使われている package.json、pyproject.toml、go.mod、Cargo.toml など
• Git ログ（「誤字を修正」などではなく、意思決定を示すコミットメッセージに注目）
• プロジェクト内にあれば Claude のメモリファイル（.claude/）

ディレクトリ名から、簡潔なプロジェクト名を導き出します。

ステップ 2：差分を算出する

このプロジェクトの .manifest.json を確認します。

• 初回ですか？ 全体をスキャンします。すべてが新規です。
• 以前に同期済みですか？ last_commit_synced を確認します。差分を算出する前に、保存されている SHA が現在も到達可能か検証します。

  git merge-base --is-ancestor <last_commit_synced> HEAD
  

  • 終了コード 0（祖先）： 問題ありません。git log <last_commit_synced>..HEAD --oneline を実行し、変更内容を確認します。
  • 終了コード 1（祖先ではない — リベースまたは強制プッシュが発生）： 保存されている SHA は、このブランチの履歴に存在しなくなっています。ユーザーに次のように警告します。「保存されているコミット <sha> に到達できません — ブランチがリベースされたか、強制プッシュされた可能性があります。全体スキャンに切り替えます。」 その後、初回同期として扱い、すべてを再スキャンし、ステップ 6 の最後に last_commit_synced を現在の HEAD SHA に更新します。

前回の同期以降、意味のある変更がなければ、ユーザーにその旨を伝えて終了します。

ステップ 3：抽出する内容を決める

これは Karpathy のパターンにおける中心的な問いです。3 か月後、何も覚えていない状態で戻ってきたとしたら、このプロジェクトについて何を知りたいでしょうか？

抽出する価値があるもの：

• アーキテクチャ上の意思決定と、その理由
• 構築中に見つかったパターン（何もしなければ、また Google で検索することになるもの）
• プロジェクトが依存するツール、サービス、API と、それらの連携方法
• 主要な抽象化、それらのつながり、メンタルモデル
• 評価したトレードオフ、選んだものとその理由
• 構築中に学んだ、コードを読むだけでは明らかでないこと

抽出する価値がないもの：

• ファイル一覧、ボイラープレート、明白な設定
• より広い教訓につながらない個別のバグ修正
• 依存関係のバージョン、ロックファイルの内容
• コードにすでに明確に記載されている実装の詳細
• 差分を見れば誰でもわかる定型的な変更

目安：コードベースを読めば答えがわかる問いは、Wiki に書かないでください。20 件のコミットにまたがる git blame を読んで考えを再構築する必要があるなら、Wiki に記録してください。

ステップ 3b：コード理解フォーカスマップを作成する（任意）

ガード：obsidian-wiki code-understand コマンドが失敗する、または利用できない場合は、このステップをスキップして続行してください。これは最適化であり、必須要件ではありません。

このプロジェクトにコードが含まれている場合は、情報を整理する前にローカルのコード理解抽出ツールを実行してください。コードベースをローカルで解析し、フォーカスマップ（アーキテクチャの基盤となるファイルとシンボルを重要度順に並べたもの）を返すため、すべてを調べるのではなく、重要な部分を読み取れます。

obsidian-wiki code-understand --project "$(pwd)" --pretty

初回の同期ではない場合（ステップ 2 で last_commit_synced が計算されている場合）は、差分を基にフォーカスマップを作成します。

obsidian-wiki code-understand --project "$(pwd)" --since <last_commit_synced> --pretty

（初回の同期では --since を省略してください。）

フォーカスマップの出力の扱い方

1. 出力を選択的に確認する — backend: codegraph の場合、フォーカスマップの項目は file:line の引用を伴う構造上の事実として扱います。backend: builtin の場合、defines／imports の項目は事実として扱いますが、rg-reference の項目はより弱い根拠として扱い、引用する前にファイルを開いて確認してください。フォーカスマップが示す重要度順の files／file:lines だけを開いてください。JSON を wiki や vault に貼り付けないでください。
2. 根拠を引用する — ページに記載するアーキテクチャ上の主張にはすべて、フォーカスマップまたは開いたソースから得た根拠を (file:lines) の形式で示してください。既存の出典マーカーも引き続き使用してください。
3. 古くなった関連を削除する（必須） — 既存の projects/<name>/ ページを更新する際は、以前に記録したコード上の関連をそれぞれ現在のフォーカスマップと照合してください（シンボル単位で再確認する場合は obsidian-wiki ast-extract を使用）。対象のシンボルが存在しなくなった、または到達できなくなった関連は削除し、ページを更新したうえで、削除内容を log.md に記録してください。これにより、誤検出の蓄積を防げます。
4. **$OBSIDIAN_VAULT_PATH に .codegraph/ や code-understand の JSON を書き込まないでください。**グラフはプロジェクトリポジトリ内のキャッシュ／サイドカーであり、wiki の知識ではありません。
5. CodeGraph がない場合は提案する（任意） — codegraph が利用できず、出力に backend: builtin と表示されており、ユーザーが拡張バックエンドを希望する場合は、インストールを提案してください：npm install -g @colbymchenry/codegraph（または既存のバイナリを指すよう CODE_UNDERSTANDING_CODEGRAPH_BIN を設定）。その後、このステップを再実行して、フォーカスマップでグラフを使用します。ユーザーの許可なくインストールせず、codegraph がないことで同期を妨げないでください。

obsidian-wiki がインストールされていない、またはコマンドが失敗する場合は、このステップをスキップし、通常どおりステップ 4 に進んでください。これは最適化であり、必須要件ではありません。

ステップ 4：wiki ページに整理する

プロジェクト固有の知識

$VAULT/projects/<project-name>/ の下に配置します。

projects/<project-name>/
├── <project-name>.md          ← project overview (named after the project, NOT _project.md)
├── concepts/                  ← project-specific ideas, architectures
├── skills/                    ← project-specific how-tos, patterns
└── references/                ← project-specific source summaries

概要ページ（<project-name>.md）には、以下を記載してください。

• プロジェクトの概要（1 段落）
• 主要な概念と、それらのつながり
• プロジェクト固有およびグローバルな wiki ページへのリンク

グローバルな知識

プロジェクト固有ではない情報は、グローバルなカテゴリに配置します。

見つけた情報	配置先
学んだ一般的な概念	concepts/
再利用可能なパターンや手法	skills/
ツール／サービス／人物	entities/
プロジェクト横断の分析	synthesis/

ページ形式

すべてのページには YAML frontmatter が必要です:

---
title: >-
    Page Title
category: concepts
tags: [tag1, tag2]
sources: [projects/<project-name>]
summary: >-
    One or two sentences (≤200 chars) describing what this page covers.
provenance:
  extracted: 0.6
  inferred: 0.35
  ambiguous: 0.05
base_confidence: 0.59
lifecycle: draft
lifecycle_changed: TIMESTAMP_DATE
created: TIMESTAMP
updated: TIMESTAMP
---

Use folded scalar syntax (summary: >-) for title and summary to keep frontmatter parser-safe across punctuation (:, #, quotes) without escaping rules.
Keep the title and summary contents indented by two spaces under summary: >-.

# Page Title

- A fact the codebase or a doc actually states.
- A reason the design works this way. ^[inferred]

Use [[wikilinks]] to connect to other pages.

新しい/更新されたすべてのページに summary: frontmatter フィールドを書いてください(1〜2文、200文字以内)。>- 折りたたみスタイルを使用します。プロジェクト同期の場合、優れた summary は「このページは、タイトルからは推測できない、そのプロジェクトについて何を教えてくれるのか?」に答えるものです。このフィールドは wiki-query による低コストな検索を支えます。

llm-wiki に従って来歴マーカーを適用してください(来歴マーカーのセクション)。特にプロジェクト同期では:

• Extracted(抽出) — コード、設定、あるいはドキュメント/コミットメッセージに見えるものすべて: ファイル構造、依存関係、関数シグネチャ、あるファイルが何をするか。
• Inferred(推論) — ある決定がなぜなされたか、設計根拠、トレードオフ、「チームは Y という理由で X を選んだ」 — ただしコミットメッセージ、ドキュメント、または ADR が明示的に述べている場合を除きます。
• Ambiguous(曖昧) — コードとドキュメントが矛盾している場合、または明らかに進行中の移行があり、2つのパターンが併存している場合。

おおよその割合を計算し、新しい/更新されたすべてのページに provenance: ブロックを書いてください。

更新 vs 作成

• ページがすでに vault に存在する場合は、新しい情報をそこにマージしてください。重複を作らないでください。
• 既存のページに追加する場合は、updated タイムスタンプを更新し、新しいソースを追加してください。
• 新しいものを作成する前に、index.md を確認して何がすでにあるかを把握してください。

Step 5: クロスリンク

ページを作成/更新した後:

• 新しいページから既存の関連ページへ [[wikilinks]] を追加する
• 関連する場合、既存のページから新しいページへ戻る [[wikilinks]] を追加する
• プロジェクト概要を、すべてのプロジェクト固有ページと関連するグローバルページにリンクする

Step 6: トラッキングの更新

.manifest.json の更新

このプロジェクトのエントリを追加または更新します。プロジェクトの identity はマシン間でポータブルでなければなりません: リポジトリ URL を source_repo に記録し(git remote get-url origin から取得し、host/owner/name に正規化)、このマシンがたまたまそれをチェックアウトしている場所を示す任意の source_cwd_hint のみを記録します。マシンの絶対パスは決して書かないでください — llm-wiki/SKILL.md → .manifest.json (Source key contract v2) を参照してください。

{
  "projects": {
    "<project-name>": {
      "source_repo": "github.com/owner/<project-name>",
      "source_cwd_hint": "~/code/<project-name>",
      "last_synced": "TIMESTAMP",
      "last_commit_synced": "abc123f",
      "pages_in_vault": ["projects/<project-name>/<project-name>.md", "..."]
    }
  }
}

プロジェクトが git リポジトリでない場合は、source_repo に repo:<stable-name> 疑似キーを使用し、source_cwd_hint を唯一の場所フィールドとして保持してください。

index.md の更新

作成した新しいページのエントリを追加します。

index.md、log.md、hot.md の更新

3回の手作業による編集ではなく、1回のロックされた呼び出しで行います:

obsidian-wiki memory sync WIKI_UPDATE project=<project-name> \
  pages_created=X pages_updated=Y \
  source_repo=github.com/owner/<project-name> \
  --takeaways "Synced obsidian-wiki — wiki-capture and wiki-research added; the new capabilities are autonomous web research and conversation capture."

--takeaways には、この同期中に明らかになった最も重要なアーキテクチャ上の洞察または決定を、ファイルリストではなく概念的に書いてください。省略すると、以前の takeaways は変更されないままになります。

このプロジェクトが継続的なフォーカスである場合は、次のセッションが引き継げるようスレッドを記録してください:

obsidian-wiki memory todo add "<the open thread>" --origin projects/<project-name>.md

完全な手順については .skills/llm-wiki/references/MEMORY.md を参照してください。

Step 7: QMD Wiki インデックスの更新(任意 — QMD_WIKI_COLLECTION が必要)

ガード: $QMD_WIKI_COLLECTION が空または未設定の場合、このステップをスキップしてください。 markdown vault が信頼できる情報源であり、QMD は検索インデックスにすぎません。

このステップは、ページ、.manifest.json、index.md、log.md、hot.md が書き込まれた後にのみ実行してください。Step 2 で意味のある変更が見つからず、同期が早期に停止した場合は、QMD を更新しないでください。

この更新は現在、ローカルの QMD CLI を必要とします。設定されていれば $QMD_CLI を使用し、そうでなければ qmd を使用してください。CLI が利用できないかエラーを返す場合でも、wiki の更新をロールバックしないでください。wiki は更新されたが QMD の更新はスキップされたまたは失敗したことを報告してください。

CLI による更新の場合:

${QMD_CLI:-qmd} update

出力が新しいハッシュにベクトルが必要と述べている場合、またはページが作成/更新されて埋め込みが古くなっている可能性がある場合は、次を実行してください:

${QMD_CLI:-qmd} embed

作成された、または実質的に更新された少なくとも1つのページが wiki コレクションで表示されることを確認してください:

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/projects/<project-name>/<page>.md" -l 5

正確な qmd:// パスが不明な場合は、次を使用してください:

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION" | rg "<project-name>"

最終レポートで QMD の更新を次のいずれかとして記録してください:

• QMD refreshed: update + embed + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>

ヒント

• 積極的に統合してください。 プロジェクトが React Server Components を使用している場合、concepts/react-server-components.md がすでに存在するなら、新しいページは作成しないでください。既存のページを更新し、このプロジェクトを出典として追加してください。
• タグの分類体系を参照してください。 $VAULT/_meta/taxonomy.md が存在する場合は読み、標準タグを使用してください。
• コードをコピーしないでください。 実装ではなく、知識を抽出してください。「このプロジェクトでは、300ms の遅延を設けたデバウンス検索パターンを使用しています」は有用です。実際のデバウンス関数を貼り付けるのはやめてください。
• プロジェクトの概要を軸にしてください。 <project-name>.md ファイルは、プロジェクトの全体像を把握するために読むものです。充実した内容にしてください。