llm-wiki

LLM Wiki — Karpathy ナレッジベースパターン

実験的なスキル — 改良を重ねています。 Lewis Liu（[email protected]）作 · Karpathy の llm-wiki Gist に触発

基本的な考え方

クエリのたびに生のドキュメントを再取得する RAG ではなく、LLM が生のソースを永続的で相互にリンクされた Wiki にコンパイルします。取り込み、クエリ、リント、監査を行うたびに Wiki は充実していきます。知識は蓄積され、人間はその場しのぎの修正が失われるのを防ぐ、構造化されたフィードバック経路を通じて、プロセスに関与し続けます。

• あなたが担当すること：生の資料の収集、適切な質問、方向性の調整、AI の誤りに対するフィードバックの提出。
• LLMが担当すること：執筆、相互参照、ファイリング、記録管理、およびフィードバックへの対応のすべて。

Wiki は、compile、ingest、query、lint、auditの5 つの操作を持つ、常に更新される成果物です。すべてのセッションは CLAUDE.md と wiki/index.md の読み込みから始めます。

ディレクトリ構成

<wiki-root>/
├── CLAUDE.md          ← Schema: scope, conventions, current articles, gaps
├── log/               ← Per-day operation log (one file per day)
│   ├── 20260409.md
│   └── 20260410.md
├── audit/             ← Human feedback inbox (one file per comment)
│   ├── 20260409-143022-claude-code-size.md
│   └── resolved/      ← Processed feedback, archived with resolution notes
├── raw/               ← Immutable source documents (LLM reads, never writes)
│   ├── articles/
│   ├── papers/
│   ├── notes/
│   └── refs/          ← Pointer files for large binaries kept outside raw/
├── wiki/              ← LLM-generated knowledge (LLM writes, you read)
│   ├── index.md       ← Master catalog — every page, structured by category
│   ├── concepts/      ← Concept/topic pages (split into subfolders when >1200 words)
│   ├── entities/      ← People, tools, papers, organizations
│   └── summaries/     ← Per-source summary pages
└── outputs/
    └── queries/       ← Query answers (promote durable ones to wiki/)

CLAUDE.md はスキーマファイルであり、最も重要な設定ファイルです。Wiki の対象範囲、命名規則、現在の記事一覧、未解決の質問、調査の不足箇所を LLM に伝えます。記載すべき内容については references/schema-guide.md を読んでください。毎回のセッションの開始時に読み込みます。

基本原則

以下のすべてを規定するルールは 4 つあります。今後の指示がいずれかに矛盾する場合は、実行する前にユーザーに伝えてください。

1. 分割して攻略する

1 つの概念ページで、複雑なトピック全体を最初から最後まで扱おうとしてはいけません。目安はページあたり 400～1200 語です。トピックがこの分量を大幅に超える場合は、次のようにします。

• サブフォルダー wiki/concepts/<topic>/ を作成します。
• wiki/concepts/<topic>/index.md に短いインデックスページを置きます。定義、サブページの一覧、各ページの 1 行の要約を記載します。
• 各側面を個別のファイル wiki/concepts/<topic>/<aspect>.md に記載します。
• wiki/index.md では、インデント付きの箇条書きで階層を示します。

実際の Wiki の構成例：

wiki/tech/claude-code/
├── index.md                         (overview + links to sub-pages)
├── Claude_Code_Architecture.md
├── Claude_Code_Agent_Framework.md
├── Claude_Code_Bridge_System.md
├── Claude_Code_Query_Engine.md
├── Claude_Code_Skills_Plugins.md
├── Claude_Code_State_Management.md
└── Claude_Code_Tool_System.md

7 つの側面すべてを 1 つの肥大化したファイルにまとめると、読みにくく、リンクもできません。焦点を絞った 7 つのファイルとインデックスページを用意すれば、ナビゲーション、必要な部分だけの読み込み、明確なバックリンク、対象を絞った監査が可能になります。

2. 図には Mermaid、数式には KaTeX

• フロー、シーケンス、階層、状態を表す図は、すべて Mermaid で記述してください。ASCII アートは使わないでください。ASCII のボックス図はすぐに劣化し、注釈を付けることもできません。

  ```mermaid
  flowchart LR
      A[raw/article.md] --> B[summary]
      B --> C[concept page]
      C --> D[index.md]
  ```
  

• 数式はすべて KaTeX で記述してください。インライン形式は $f(x) = \sum_i w_i x_i$、ブロック形式は $$...$$ です。

どちらも Web ビューアー（サーバー側の KaTeX、クライアント側の Mermaid）と、デフォルト設定の Obsidian で表示できます。

3. 生ファイルの方針

小さなテキストベースのソース（md、txt、小さな pdf、小さな画像）→ raw/<subfolder>/ にコピーします。

大きなバイナリ（動画、モデルの重み、インストーラー、データセット、10 MB を超える大きな PDF）→ コピーしません。代わりに、次のようにします。

• raw/refs/<slug>.md にポインターファイルを作成し、次の内容を記載します。

  ---
  kind: ref
  external_path: /Volumes/external/models/llama-3-70b/
  size: ~140 GB
  ---
  

  続けて、それが何であり、この Wiki にとってなぜ重要なのかを簡潔に説明します。
• Wiki のページでは、他のソースと同様に [[raw/refs/<slug>]] を引用します。

これにより、Wiki リポジトリを Git で扱いやすく、持ち運び可能な状態に保てます。

4. 監査は人間からのフィードバック窓口

Wiki は AI が書くため、誤りが含まれることがあります。生のソースは人間が書くため、互いに矛盾することがあります。audit/ ディレクトリを使えば、チャット履歴の中に修正内容を埋もれさせずに、人間がその両方を修正できます。

• 人間は Obsidian プラグインまたは Web ビューアーからフィードバックを提出します。フィードバックごとに audit/ 内に 1 つのファイルを作成し、YAML フロントマター（anchor、target、severity）と Markdown 本文を記述します。
• AI は定期的に audit 操作を実行しなければなりません。audit/*.md ファイルを黙って無視してはいけません。
• フィードバックを反映したら、ファイルを audit/resolved/ に移動し、# Resolution セクションを追記して、log/YYYYMMDD.md に記録します。

ファイル形式と処理ワークフローの詳細については、references/audit-guide.md を参照してください。

---

5 つの操作

Wiki に対するすべてのアクションは、これら 5 つのいずれかです。それぞれのアクションは、当日分のログファイル（log/YYYYMMDD.md）に記録を追加します。

1. compile

既存の raw/ 素材から wiki のコンテンツを再構成します。大きすぎるページの分割、類似ページの統合、index.md の再構築などを行います。

実行するタイミング：大量の素材を取り込んだ後、既存のページが1200語を超えたとき、index.md の内容が実情に合わなくなったとき、またはユーザーから「wikiを整理して」と言われたときです。

手順：

1. CLAUDE.md、wiki/index.md、対象サブツリー内のすべてのファイルを読みます。
2. 約1200語を超えるページごとに、concepts/<topic>/ 内にインデックスとサブページを作成する分割案を立てます。書き込みを行う前に、ユーザーに案を確認します。
3. 類似ページの各ペアについて、統合案を提示します。確認後、書き直します。
4. すべてのページがちょうど1回ずつ掲載されるよう、wiki/index.md を再生成します。
5. 次の形式で記録します：## [HH:MM] compile | <実施内容 — 変更したファイル、分割、統合>

2. ingest

新しいソースを追加します。通常、1つのソースにつき5～15ページの wiki が更新されます。

手順：

1. ソースを適切なサブフォルダーに保存します。
   • Web記事 → raw/articles/<slug>.md
   • 論文 → raw/papers/<slug>.md（大きなPDFはテキストを抽出）
   • メモ → raw/notes/<slug>.md
   • 大きなバイナリファイル → raw/refs/<slug>.md のポインターファイル（rawファイルのポリシーを参照）
2. ソースを最後まで読みます。
3. wiki/summaries/<slug>.md を作成します（200～400語。書き直しではなく、重要なポイントをまとめます。references/article-guide.md を参照）。
4. wiki/concepts/ 内の関連する概念ページを新規作成または更新します。分割統治の原則を守り、概念ページが1200語を超える場合は、詰め込まずに分割します。
5. 参照されている新しい人物、ツール、論文、組織について、wiki/entities/ 内にエンティティページを新規作成または更新します。
6. 新しいページが適切なカテゴリに掲載されるよう、wiki/index.md を更新します。
7. 次の形式で記録します：## [HH:MM] ingest | <slug> — <1行の説明> (更新したページ数: N)

3. query

一般知識ではなく、wiki に基づいて質問に回答します。

手順：

1. wiki/index.md を読みます。カテゴリから関連するページを探します。
2. 特定したページを最後まで読み、ウィキリンクを1階層たどります。
3. wiki に十分な情報がない場合は、作り上げて回答せず、その旨を伝え、次に取り込むソースを提案します。
4. [[Page Name]] 形式でページを本文中に引用しながら、回答をまとめます。
5. outputs/queries/<YYYY-MM-DD>-<question-slug>.md に保存します。
6. 回答が長期的に有用な場合（比較、分析、新たな統合など）、整理したバージョンを wiki/concepts/ に追加し、index.md に掲載します。
7. 次の形式で記録します：## [HH:MM] query | <question-slug>（昇格した場合は、別途 ## [HH:MM] promote | ... の行も記録します）。

4. lint

ヘルスチェックです。次を実行します。

python3 scripts/lint_wiki.py <wiki-root>

スクリプトは次の項目を報告します。

• リンク先が存在しないウィキリンク — Target.md が存在しない [[Target]]
• 孤立ページ — 被リンクがないページ
• インデックス項目の欠落 — wiki/index.md に掲載されていないページ
• 頻繁にリンクされる未作成ページ — [[X]] が3回以上参照されているが、ページが存在しないもの
• log/ の構成 — log/ 内の不要なファイルや、ファイル名の誤り
• audit/ の構成 — audit/*.md 内の不正なYAMLフロントマター
• 監査対象の解決 — 未完了の各監査の target ファイルが存在すること

問題ごとに修正案を提示してユーザーに確認し、その後に適用します。次の形式で記録します：## [HH:MM] lint | 検出した問題: <N> 件、修正した問題: <M> 件

5. audit

audit/ の人間からのフィードバックを処理します。

手順:

1. python3 scripts/audit_review.py <wiki-root> --open を実行して、グループ化された一覧を取得します。
2. 未解決の各監査について、ファイルを読みます。anchor_before／anchor_text／anchor_after の範囲を使って、対象ファイル内の正確な箇所を特定します（行番号がずれている場合があります）。
3. 対応を決定します。
   • 承認: 修正を対象ファイルに適用します。
   • 一部承認: 妥当な部分を適用し、残りは解決内容に記録します。
   • 却下: 解決内容に理由を説明します。フィードバックがスコープの誤読や、矛盾する情報源に基づいている場合があります。
   • 保留: CLAUDE.md の「未解決の調査課題」に追加し、コメントを添えて監査ファイルをそのまま残します。
4. 適用した監査については、監査ファイルに # Resolution セクションを追記します。

   # Resolution
   
   2026-04-10 · accepted.
   Fixed the file count (was "~1,900", corrected to "~1,800" per commit abc123).
   Updated: tech/Claude_Code.md lines 47–48.
   

5. ファイルを audit/ から audit/resolved/ に移動します。ファイル名は変更しません。
6. 解決した監査ごとに記録します。

   ## [HH:MM] audit | resolved 20260409-143022-a1b2 — <one-line what>
   

7. 監査ファイルは決して削除しないでください。却下したものも、解決セクションに却下理由を記載して resolved/ に移動します。これは貴重な履歴になります。

監査ファイルの形式の詳細は references/audit-guide.md を参照してください。

---

ツール

ツール	目的
Obsidian	Wiki を閲覧するための IDE。グラフビューでつながりを確認できます
plugins/obsidian-audit/	Obsidian プラグイン。テキストを選択 → フィードバックを追加 → audit/ に書き込みます
web/	ローカル Node.js サーバー。mermaid／数式をレンダリングして Wiki をプレビューできます。選択 → フィードバック → audit/
scripts/scaffold.py	新しい Wiki のディレクトリツリーを作成します
scripts/lint_wiki.py	7 段階のヘルスチェック
scripts/audit_review.py	未解決／解決済みの監査を対象ファイルごとにグループ化します
qmd	任意で使えるローカルのセマンティック検索（100 ページを超える場合に便利です）

Obsidian プラグインと Web ビューアーは、どちらも同じ形式で同じアンカーアルゴリズムを使って監査ファイルを書き込むため、どちらで送信したフィードバックも、どちらからでも解決できます。

新しい Wiki を始める

python3 scripts/scaffold.py <wiki-root> "<Topic Title>"

log/<today>.md、audit/、audit/resolved/ を含むツリー全体、新しいテンプレートに基づく空の CLAUDE.md、および推奨カテゴリ構成を備えた空の wiki/index.md を作成します。

スキャフォールディングの後:

1. CLAUDE.md を記入します。スコープ、命名規則、初期の調査課題を定義します。
2. 情報源の取り込みを始めます。
3. 質問をして outputs/queries/ を充実させ、長期的に有用な回答を昇格させます。
4. 定期的に lint を実行します。
5. 新しいフィードバックが集まったら audit を実行します。

wiki/index.md の形式

LLM はコンパイルのたびに index.md を再構築し、取り込みのたびに更新します。形式:

# Index — <Topic>

> One-sentence scope of the wiki.

## 🔖 Navigation
- [[#Concepts]] · [[#Entities]] · [[#Summaries]] · [[#Open Questions]]

## Concepts
### <Category A>
- [[concepts/Foo]] — one-line summary
- [[concepts/Bar/index|Bar]] — (folder-split) one-line summary
    - [[concepts/Bar/aspect-1]] — ...
    - [[concepts/Bar/aspect-2]] — ...

### <Category B>
- ...

## Entities
- [[entities/Andrej Karpathy]] — AI researcher, author of the llm-wiki pattern

## Summaries (chronological)
- 2026-04-09 — [[summaries/llm-wiki-gist]] — Karpathy's original Gist

## Open Questions
- Q1: ...

ルール:

• Wiki のすべてのページを index.md に一度だけ記載する必要があります。lint でこれを検証します。
• フォルダーに分割された概念は、インデント付き箇条書きで階層を表します。
• AI はセッション開始時に index.md と CLAUDE.md の両方を読み込みます。

log/ の形式

詳細は references/log-guide.md を参照してください。最低限、次の形式にします。

• 1 日につき 1 ファイル: log/YYYYMMDD.md
• H1 は日付、エントリごとに H2 を置き、## [HH:MM] <op> | <one-line description> とします。
• 操作: compile、ingest、query、lint、audit、promote、split、scaffold

履歴をすばやく検索するには: grep -rh "^## \[" log/ | tail -20。

ユースケース

• 深掘り調査 — 数週間にわたって、あるトピックに関する論文や記事を読む用途です。理解の深まりに応じて Wiki が進化し、監査履歴によって AI の誤りが気づかれないまま蓄積するのを防ぎます。
• 個人 Wiki — 日記、メモ、アイデアを個人用百科事典にまとめる用途です。後から異議のある箇所にコメントすると、AI が修正します。
• チームのナレッジベース — Slack のスレッド、会議メモ、ドキュメントを取り込み、チームメンバーが Web ビューアーから修正を送信する用途です。
• 読書のお供 — 本の各章を読み進めながら取り込み、読み終える頃には充実した関連 Wiki を構築できます。

参考資料

• references/schema-guide.md — CLAUDE.md に記載する内容
• references/article-guide.md — 優れた Wiki 記事の書き方（長さ、Wiki リンク、mermaid、数式、分割統治）
• references/log-guide.md — log/ フォルダーの規約
• references/audit-guide.md — 監査ファイルの形式、アンカー戦略、処理ワークフロー
• references/tooling-tips.md — Obsidian のセットアップ、Web Clipper、qmd、プラグインと Web からのインストール