mcpField
G
git-wiki

git-wiki

github.com/yysun開発353 回インストール22 週間前に更新
リポジトリ

git-wiki について

git-wikiは、GitのHEADで追跡されているファイルを基に、読者向けのローカルプロジェクトWikiを管理するエージェントスキルです。言語別の独立したWikiルート、差分更新、検索、エクスポートに対応します。

主な機能

  1. 01選択したルートでWikiを管理
  2. 02GitのHEADで追跡されたソースを使用
  3. 03ファイル変更に応じてページを更新
  4. 04frontmatterとWikiリンクでページを整理
  5. 05WikiページをMarkdownバンドルとして出力

活用シーン

  1. 01コードベースを理解するためのガイド作成
  2. 02コミット済みソースの変更後にWikiを更新
  3. 03WikiをNotebookLM用のソースとして出力

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/yysun/awesome-agent-world --skill git-wiki

インストール後、Claude Code で/git-wikiを入力して読み込まれたか確認します。

同梱ファイルscripts/export-wiki-bundle.mjs

詳細

プロジェクトWiki

コードプロジェクトのローカルWikiを、既定では .wiki の下に管理します。必要に応じて、.wiki-cn や .wiki-fr など言語別のルートや、ユーザーが指定した wiki-cn などの正確なWikiディレクトリも使用できます。

信頼できる情報源は常に現在のGit管理対象リポジトリファイルの HEAD です。これには .docs/ と docs/ の管理対象ドキュメントも含まれ、Wikiは含まれません。 Wikiファイル自体は未追跡でもかまいません。選択したWikiルートが作業ツリーに存在する場合は、そこにある最新の内容を読み取り、更新してください。

ルール

  • Git管理対象のファイルとGit履歴だけを対象にします
  • ステージ済みおよび未ステージの未コミット変更は無視します。取り込みとクエリの検証には、コミット済みの HEAD の内容のみを使用します
  • リクエストごとにWikiルートを正確に1つ選択します。既定では .wiki を使用し、ユーザーが .wiki-cn、wiki-cn、.wiki-fr、「Chinese wiki」、「French wiki」など、ルートまたは言語を明示した場合はそれを使用します
  • 各Wikiルートは独立しています。ユーザーが明示的に求めない限り、言語別ルート間でページを同期、比較、翻訳、統合、コピーしないでください
  • Gitベースのソース選択からすべてのWikiルートを除外します：.wiki/**、.wiki-*/**、wiki-*/**
  • WikiルートがGit管理対象だと想定しないでください。選択したルートに index.md のチェックポイントがある場合は、それを使用します
  • すべてのWikiページにYAMLフロントマターが必要です
  • 取り込みのたびに、選択したルートの index.md を更新する必要があります
  • 取り込みの前にユーザーへ確認しないでください
  • エクスポートでは、Git管理対象リポジトリの HEAD ではなく、選択したWikiルート内の作業ツリーファイルを読み取ります

Wikiの構成

必須：

  • <wiki-root>/index.md — 人間向けの入口とマスターカタログ（そのルートの最終取り込みコミットを記録）

任意（必要に応じて作成）：

  • <wiki-root>/overview/ — プロジェクト、起動経路、ストレージ、読み進め方を説明する概要ページ
  • <wiki-root>/features/ — 重要な製品機能または実装領域ごとのページ
  • <wiki-root>/bug-fixes/ — 重要なバグ修正またはパッチごとのページ
  • <wiki-root>/concepts/ — 複数の領域にまたがるアイデアやパターン
  • <wiki-root>/entities/ — データモデル、スキーマ、型
  • <wiki-root>/flows/ — シーケンス、パイプライン、リクエストのライフサイクル
  • <wiki-root>/risks/ — 不変条件、互換性の契約、壊れやすい動作、壊してはいけないもの
  • <wiki-root>/reference/ — ソースパスに焦点を絞った説明が必要な場合の、コードに即したリファレンスページ
  • <wiki-root>/notes/ — その場で生じた疑問や未解決の質問
人間が理解しやすい構成

Wikiは、リポジトリ自身に説明させるためではなく、人がコードベースを理解するためのものです。コードのフォルダー構成より先に、読者の疑問を中心に入口を構成してください。

<wiki-root>/index.md では、次の質問にこの順序で答える必要があります：

  1. これは何ですか？
  2. 使い始める
  3. なぜ存在するのですか？
  4. 実行すると何が起きますか？
  5. データはどこに保存されますか？
  6. 重要な構成要素は何ですか？
  7. 何を壊さないようにすべきですか？
  8. 最初にどこを見ればよいですか？

これらの質問を主要なナビゲーションとして使用してください。features/、entities/、flows/、reference/ は補足資料であり、最初に提示する考え方ではありません。

Get Started セクションは、READMEの重複ではなく、コードベースの概要をつかむためのものです。要領のよい新規読者が最初の10分で把握できるよう、次の内容を示してください：

  • 実行する主要なコマンド
  • 必要な環境またはサービス
  • 成功時に想定される出力
  • 最初に読むべきファイル
  • 安全に試せる最初の変更を1つ
  • つい手を出しがちな危険な変更を1つ

リポジトリの README.md または docs/ にセットアップ手順がすでにある場合は、そこへリンクし、読者がコードを理解するうえで役立つ内容だけを要約してください。

Wiki ルートの選択
  • デフォルトの Wiki ルート：.wiki
  • 言語固有のルート：新しい言語 Wiki を作成する場合は、.wiki-<language-code> を優先します。たとえば、中国語には .wiki-cn、フランス語には .wiki-fr を使用します
  • ユーザーが wiki-cn のような正確なディレクトリを指定した場合は、正規化せず、そのルートをそのまま使用します
  • 言語ルート間で、チェックポイント、ページ、リンク、古くなった状態を引き継ぐことはありません
  • ユーザーが言語名で言語 Wiki を指定した場合は、ページ本文をその言語で記述し、コード識別子、ファイルパス、API 名は変更しないでください

ページの規約

index.md のフロントマター

index.md には、取り込み状態を追跡するための追加フィールドがあります。

---
title: "Project Wiki"
type: "index"
status: "active"
language: "<language-code|default>"
last_commit: "<full-sha>"
updated_at: "YYYY-MM-DD"
---

last_commit は、選択した Wiki ルートに対してリポジトリ全体の取り込みを最後に実行した時点の完全な git コミット SHA です。このチェックポイントは、ルートが git で追跡されているかどうかにかかわらず、選択したルートの現在の index.md ファイルに保存されます。同じルートで次回取り込みを行う際は、この保存済みの last_commit を優先して、git diff --name-status -M <last_commit> HEAD で変更されたファイルを特定してください。

git メタデータを利用できない場合は、ファイルシステムのスキャンに切り替えないでください。git にアクセスできるようになるまで、取り込みと lint は利用できません。

その他のページ
---
title: "Page Title"
type: "overview|feature|bug-fix|concept|entity|flow|risk|reference|note"
status: "draft|active|stale"
language: "<language-code|default>"
source_paths: []
updated_at: "YYYY-MM-DD"
---

.wiki では language を default に、.wiki-cn または wiki-cn では cn に、.wiki-fr では fr に設定し、その他の言語固有ルートでは対応する言語コードに設定してください。

ソースファイルがページの最終更新後に大幅に変更された場合、またはページが現在は存在しないものについて説明している場合は、status: "stale" を使用してください。取り込み時に、last_commit 以降に source_paths が変更されたページは、更新するか stale としてマークしてください。stale ページを自動的に削除せず、差異を記録してユーザーが判断できるようにしてください。

ページの命名
  • 小文字とハイフンを使ったファイル名にします：auth-middleware.md、user-schema.md
  • 人が理解する概念を優先してページ名を付けます：login-check.md、saved-data-shape.md、startup-flow.md
  • 参照用ページ、または読者にとってより分かりやすい名前がない場合にのみ、ソースパスに基づく名前を使用します：src/api/routes.ts → <wiki-root>/reference/src-api-routes.md
  • 概念やフローには、内容が分かる名前を付けます：<wiki-root>/concepts/request-lifecycle.md
Wiki リンク

ページで別のページに記載されている内容を参照する場合は、ページ間のリンクに [[page-slug]] を使用してください。リンク先には、.md 拡張子を除いたリンク先ファイル名を指定します。これにより Wiki 内を移動でき、lint でリンクを確実に解決できます。

取り込み

次の入力で起動します：

  • ingest
  • ingest [file]
  • ingest [folder]
  • ingest wiki-cn
  • ingest .wiki-fr
  • refresh wiki
  • update wiki
  • update Chinese wiki

ワークフロー：

  1. リクエストから Wiki のルートを選択します。既定では .wiki を使用し、明示的なルートまたは言語固有のルートが指定されている場合はそれを使用します
  2. 作業ツリーに <wiki-root>/index.md が存在する場合は、Wiki のルートが未追跡であっても読み込みます — フロントマターから last_commit を確認します
    • <wiki-root>/index.md がない場合、または last_commit がない場合、そのルートには以前の取り込みチェックポイントがありません
  3. git rev-parse HEAD を実行して、現在の HEAD コミット SHA を取得します
  4. 変更されたファイルを検出します：
    • last_commit が設定されている場合は、git diff --name-status -M <last_commit> HEAD を実行し、すべての Wiki ルート（.wiki/**、.wiki-*/**、wiki-*/**）を除外します
    • 選択した Wiki のルートが未追跡であっても、保存済みの last_commit を使用します。未追跡の Wiki ルートを、HEAD からの新規取り込みとして扱わないでください
    • Wiki ページの更新時は、git のステータスコードを使用して、追加、変更、削除、名前変更されたパスを区別します
    • 以前の取り込みがない場合は、git ls-files を HEAD で実行して、すべての Wiki ルートを除外したうえで、幅広い取り込み候補の集合を作成します（以下の「取り込みの優先順位」を参照）
  5. 対象範囲を決定します：
    • ファイルまたはフォルダーが指定されている場合は、それを優先し、追跡対象の候補をその範囲に限定します
    • 対象を絞った取り込みでは、last_commit 以降に変更されたすべてのファイルを含まない限り、<wiki-root>/index.md:last_commit を更新しないでください
    • それ以外の場合は、まず変更されたファイルを取り込み、その後、未カバーの範囲を補完します
  6. 関連する追跡対象のリポジトリファイルを読み、その役割を把握します
  7. 選択した Wiki のルート内の Wiki ページを更新または作成します
  8. 削除されたソースファイルに対応する、選択した Wiki のルート内のページに status: "stale" を設定し、ページ本文に注記を追加します。また、git の名前変更情報に基づいて、移動または名前変更されたページを更新します
  9. <wiki-root>/index.md を更新します：
    • updated_at は必ず今日の日付に設定します
    • 完全な取り込みの後、または以前の last_commit 以降に変更されたファイル一式をすべて処理した後に限り、last_commit を現在の HEAD SHA に設定します
    • 幅広い取り込みが一部の範囲のみをカバーした状態で早期終了する場合は、last_commit を変更せず、ブートストラップのカバー範囲がまだ部分的であることを index.md に記載します
    • 選択した Wiki のルートが未追跡であることを理由に、既存の保存済み last_commit を破棄しないでください

取り込みは自動で行われます。ユーザーに確認を求めないでください。

git コマンドが失敗した場合は、git へのアクセスが復旧するまで Wiki スキルで取り込みを実行できないことを報告します。ディレクトリの走査で代用しないでください。

エクスポート

次の場合に実行します。

  • export wiki
  • bundle wiki
  • archive wiki
  • one-page wiki
  • prepare wiki for notebooklm
  • send wiki to notebooklm

ワークフロー：

  1. リクエストから Wiki のルートを選択します。指定がない場合は .wiki を使用し、明示的なルートまたは言語固有のルートが指定されている場合はそれを使用します
  2. 作業ツリーに <wiki-root>/index.md が存在するか確認します
    • 選択した Wiki ルートが存在しない、または明らかに不完全な場合は、確認を求めずに先に取り込みを実行します
  3. HEAD ではなく、作業ツリー内の選択した Wiki の現行版をエクスポートします
  4. 同梱されている依存関係不要の CLI を使用します。
node skills/git-wiki/scripts/export-wiki-bundle.mjs \
  --input-dir <wiki-root>
  1. デフォルトの出力先は、選択した Wiki ルート内の index-{simple-timestamp}.md です
  2. 別の出力先が指定された場合は、--output-file <path> を渡します
  3. エクスポートヘッダーにカスタムラベルを指定する場合は、--root-name <name> を渡します
  4. エクスポートには次の内容を含める必要があります。
    • 生成日を含むリポジトリ／Wiki ヘッダー
    • バンドル内のすべてのページを含む目次
    • 選択したフロントマターを保持した、Wiki ファイルごとのセクション
    • バンドルをアーカイブ成果物または NotebookLM のソースとして利用できるようにする、明示的なファイル開始／終了マーカー
  5. リクエストが NotebookLM に関するものである場合は、先にエクスポートし、生成したバンドルファイルをソース成果物として notebooklm スキルに渡します

エクスポート時の要件：

  • <wiki-root>/**/*.md のバンドルを優先します
  • title、type、status、language、tags、description、source_paths、updated_at、last_commit など、有用なフロントマター項目だけを保持します
  • 下流のツールが Obsidian のセマンティクスに依存しなくて済むよう、[[wiki-links]] をプレーンテキストに正規化します
  • ![[image.png]] などの Obsidian 画像埋め込みを削除します
  • 相対パス順にファイルを並べ、出力を決定的にします
  • デフォルトのファイル名には、たとえば .wiki-fr/index-20260510-143522.md のようなシンプルなタイムスタンプを使用します
  • エクスポートを取り込みの代わりにしてはいけません。エクスポートは現在の Wiki をパッケージ化するものであり、再構築するものではありません
取り込みの優先順位

Git で追跡されているファイルを広範囲に取り込む場合は、まず人が読むための入り口を作成し、その後で補足的なコードページを追加します。以下の順序で作業し、十分に網羅できた時点で終了します（中規模のプロジェクトでは通常 10～20 ページです）。

  1. ルートの README と、.docs/ および docs/ 内の追跡対象ドキュメント
  2. パッケージ／ビルド／ワークスペースの設定（package.json、pyproject.toml、Cargo.toml など）を確認し、プロジェクトの実行方法を把握します
  3. エントリーポイント（main.ts、index.ts、app.py、cmd/ など）を確認し、起動方法と実行時の動作を説明します
  4. ストレージ、生成物、設定、シークレット、キャッシュ、ログ、永続化の境界 → <wiki-root>/overview/ または <wiki-root>/entities/
  5. 主要なユーザー／システムのワークフロー → <wiki-root>/flows/
  6. 重要な構成要素、概念、サブシステムの境界 → <wiki-root>/concepts/ または <wiki-root>/features/
  7. 読者が壊さないよう注意すべき契約と脆弱な箇所 → <wiki-root>/risks/
  8. API 定義、スキーマ、永続化レイヤー → <wiki-root>/features/ または <wiki-root>/entities/
  9. ジョブ、キュー、バックグラウンドワーカー → <wiki-root>/features/
  10. UI 構造（存在する場合）→ <wiki-root>/features/
  11. テスト（すべてのテストファイルを記述するのではなく、動作上の期待と安全策を要約します）
  12. Git の履歴から確認できる注目すべきバグ修正 → <wiki-root>/bug-fixes/

大規模なリポジトリ（ファイル数 100 以上）では、範囲を広げるよりも掘り下げることを優先します。重要なモジュール 10 個を浅く 50 個扱うのではなく、深く記述します。

Query

プロジェクトに関する質問を受けたとき：

  1. リクエストから wiki のルートを選択します。指定がない場合は .wiki を使用し、明示的なルートまたは言語別のルートが指定されている場合はそれを使用します
  2. <wiki-root>/index.md が存在する場合は読み込みます
  3. 選択したルートに関連する wiki ページが存在する場合は読み込みます
  4. 選択した wiki が存在しない場合、関連ページが存在しない場合、またはページに古い内容であることが記されている場合は、回答する前に git で追跡されているリポジトリのソースを直接確認します
  5. 質問に関連する場合は、まず .docs/ と docs/ にある追跡対象のドキュメントを優先し、必要に応じてコードや設定で確認します
  6. 回答に具体的な値（件数、名前、設定など）が含まれる場合は、git で追跡されているリポジトリのソースで確認します
  7. ユーザーが言語別のルートを指定した場合は、選択した wiki の言語で回答し、簡潔に説明します。関連する wiki ページが存在する場合は [[wiki-link]] 形式で引用します
  8. 選択した wiki ルートにまだ反映されていない新たな知見を得た場合は、その旨を伝えます。ユーザーは保存を依頼できます

Lint

次の場合に実行します：

  • lint
  • lint wiki
  • check wiki
  • lint .wiki-fr
  • check Chinese wiki

チェック項目：

  • ページ間の矛盾（互いに矛盾する主張をしているページ）
  • 被リンクのない孤立したページ（[[links]] がないページ）
  • 複数のページで言及されているが、専用ページがない概念
  • 古くなっている可能性のあるページ（status: "stale"）で、現在のソースとの差異が生じているもの
  • 主要な変更済みモジュールに関する説明の不足（last_commit 以降に変更されたファイルに対応する wiki ページがない場合）
  • リンク先のページが存在しない、壊れた [[wiki-links]]
Lint の出力形式
## Wiki Lint Report — YYYY-MM-DD

### Errors
- [page] description of contradiction or broken link

### Warnings
- [page] description of potential issue

### Suggestions
- description of missing coverage or improvement

### Next Questions
- open questions worth investigating

明示的に依頼されない限り、自動修正しないでください。

Writing Guidance

  • メンテナーではなく、理解力のある初心者に向けて書きます。まず平易な言葉を使い、役立つ場合に限って正確なコード用語を加えます。「認証ミドルウェア」より先に「ログイン確認」、「スキーマ」より先に「保存データの形式」、「ワーカー」より先に「バックグラウンドタスク」と説明します
  • 読者の疑問を中心にページを構成し、その後、ファイルを根拠として説明します。ページが明示的にリファレンス資料でない限り、ディレクトリの案内から始めないでください
  • 実装の詳細を挙げる前に、そのファイルがプロダクトやワークフローでなぜ重要なのかを説明します
  • 説明のない略語、フレームワークの専門用語、内部の略称は避けます。技術用語が必要な場合は、同じ文の中で定義します
  • 要約し、大きなコードブロックをそのまま載せないでください。数行のコード例は問題ありませんが、実装を貼り付けるのではなく、パターンを説明します
  • 具体的なファイルパスを手掛かりとして示します（src/api/routes.ts:42）
  • 事実（ソースを直接読んで確認した内容）と推測（解釈）を区別します
  • 関連ページは [[wiki-links]] で相互にリンクします
  • ページは約500語以内に収めます。長くなる場合は、ページを増やしてください
  • 網羅性よりも有用な情報を優先します。優れた wiki は百科事典ではなく、必要な情報を見つけやすいものです

Quality Bar

wiki が次の状態を満たしていれば成功です：

  • <wiki-root>/index.md によって、新しい読者が2分以内にプロジェクトを把握できます
  • 初心者が、プロジェクトの概要、存在する理由、実行時の動作、データの保存先、重要な点、壊してはいけない点、最初に確認すべき場所を理解できます
  • wiki ページから回答を始め、コードで検証できます
  • Ingest が保存された last_commit を使って、変更されたファイルを自動的に検出します
  • Lint が、wiki が誤解を招く内容になる前に情報のずれを検出します

コメント

Markdown 対応