qmd：AI Agent 向けのローカル Markdown ドキュメント検索ツール

Fri, 01 May 2026 03:12:57 +0800

qmd は、ローカル Markdown ドキュメント向けの検索ツールです。主な利用対象は AI Agent です。

解決する問題は具体的です。プロジェクトに大量の .md ドキュメントがある場合、AI コーディングアシスタントは、どのファイルを読むべきか、どの段落を引用すべきか、どの説明が最新かを判断しづらくなります。全文 grep はキーワードを見つけられますが、意味の理解は苦手です。ドキュメント全体をコンテキストに詰め込むと、ウィンドウを浪費し、無関係な内容も混ざりやすくなります。

qmd の考え方は、まず Markdown ドキュメントにインデックスを作り、その後検索インターフェースを通じて最も関連する断片を AI に渡すことです。CLI ツールとして使うことも、SDK で統合することも、MCP Server として MCP 対応クライアントに接続することもできます。

解決する問題

実際のプロジェクトのドキュメントは、README が 1、2 個あるだけではありません。

たとえば次のようなものがあります。

アーキテクチャ説明
API ドキュメント
開発規約
デプロイ手順
設計判断記録
トラブルシューティングメモ
要件ドキュメント
AI 利用説明
各種ツールチェーンのメモ

人間はディレクトリをたどってドキュメントを読めますが、AI Agent には明確な検索入口が必要です。そうでないと、次のようなことが起こります。

間違ったドキュメントを読む
重要な制約を見落とす
古い説明を使う
無関係な内容をコンテキストに入れる
存在しないルールを経験で補完して回答する

qmd の価値はここにあります。ローカル Markdown ドキュメントを検索可能な知識源にし、AI がコンテキストを必要とするときにまず検索し、一致した断片に基づいて回答や作業を行えるようにします。

検索方式の特徴

README によると、qmd は複数の検索方式を組み合わせています。

BM25 キーワード検索
ベクトル検索
LLM reranking

BM25 は明確なキーワードに向いています。関数名、設定項目、エラーコード、ファイル名を探す場合は直接的です。

ベクトル検索は意味的な質問に向いています。たとえば「このプロジェクトは権限検証をどう扱っているか」と聞く場合、ドキュメントにその exact な語句がなくても、認証、アクセス制御、ロール判定に関する説明が見つかる可能性があります。

LLM reranking は候補結果の並べ替えに使われます。最初の 2 つのステップで関連しそうな内容を集め、その後モデルが現在の質問により合う断片を判断します。

この組み合わせは、単純なキーワード検索より AI Agent に向いています。Agent の質問は固定キーワードではなく、タスク意図であることが多いからです。

なぜ Markdown なのか

Markdown は開発プロジェクトで最もよく使われるドキュメント形式です。

Git に入れやすいほど単純で、見出し、リスト、コードブロック、リンク、表を持てる程度には構造化されています。AI にとっても、Markdown は PDF、Web スナップショット、スクリーンショットより解析しやすい形式です。

qmd が Markdown に集中しているため、開発ドキュメントに対してより直接的な処理ができます。

見出しと段落で内容を分割する
コードブロックを保持する
ドキュメントパスを保持する
引用しやすい断片を返す
Agent が回答の出典ドキュメントを把握できる

これは、AI にリポジトリをランダムに走査させるより安定しており、すべてのドキュメントを一度に prompt へ入れるよりコンテキストを節約できます。

3 つの利用入口

qmd は CLI、SDK、MCP Server の 3 つの入口を提供します。

1. CLI

CLI はターミナルで直接使う場合や、スクリプトに組み込む場合に向いています。

ドキュメントディレクトリをインデックス化し、コマンドで関連内容を検索できます。開発者にとって CLI は最も効果を確認しやすい入口です。まず正しいドキュメントが見つかるかを確認し、その後より複雑なワークフローへの統合を考えられます。

この種のツールはローカルプロジェクトで便利です。コード変更前に設計ドキュメントを検索し、デバッグ前に障害メモを確認し、API を書く前に API 規約を調べることができます。

2. SDK

SDK は qmd を自分のツールに組み込む場合に向いています。

社内開発アシスタント、ドキュメント Q&A システム、コードレビューボット、プロジェクト知識ベースを作っている場合、ユーザーに直接コマンドを打たせるのではなく、SDK から検索機能を呼び出せます。

SDK では次のような制御がしやすくなります。

検索ディレクトリ
クエリ内容
返す件数
結果形式
後続でモデルに要約させるか

深い統合が必要な場面に向いています。

3. MCP Server

MCP は、qmd が AI Agent にとって最も価値を持つ入口です。

MCP Server を通じて、MCP 対応クライアントは qmd をドキュメント検索ツールとして呼び出せます。これにより Agent は、タスク実行時にプロジェクトルールを推測するのではなく、まずローカル Markdown ドキュメントを検索できます。

典型的な流れは次のようになります。

ユーザーが AI にある機能の変更を依頼する
AI がまず qmd を呼び出して関連設計ドキュメントを検索する
qmd が最も関連する Markdown 断片を返す
AI がドキュメント制約に基づいてコードを変更する

これは「新しい会話のたびにすべてのルールを手で貼る」より自然で、長期プロジェクトにも向いています。

向いている場面

qmd は次のような場面に向いています。

プロジェクトに大量の Markdown ドキュメントがある
AI Agent が頻繁にプロジェクトルールを調べる必要がある
チームが AI の回答にローカルドキュメントを引用させたい
ドキュメントが複数ディレクトリに分散している
CLI、SDK、MCP の間で同じ検索機能を再利用したい
AI コーディングアシスタントがプロジェクト規約を推測するのを減らしたい
ローカル知識ベースを Claude Desktop、Claude Code、その他の MCP クライアントに接続したい

プロジェクトに短い README が 1 つだけなら、AI にそのファイルを読ませれば十分です。

しかし、ドキュメントが数十、数百ファイルに増えている場合や、Agent に毎回ドキュメントを検索してから行動してほしい場合、この種のインデックスツールには意味があります。

grep との違い

grep や rg は正確な検索に非常に向いています。

DATABASE_URL、authMiddleware、404、docker compose を探したいと分かっているなら、キーワード検索がたいてい最速です。

qmd は、正確な語句が分からない場合に向いています。

たとえば次のような質問です。

このプロジェクトのリリース手順は何か
新しい API を追加するときに守る規約は何か
キャッシュ戦略について過去に記録があるか
AI がコードを変更する前に読むべきドキュメントはどれか
あるモジュールの設計背景はどこにあるか

これらは一語の一致ではなく、意味検索が必要なことが多いです。qmd の BM25 + ベクトル + reranking の組み合わせは、こうした質問で正しいコンテキストを見つけやすくするためのものです。

RAG との関係

qmd は、Markdown ドキュメント向けの軽量 RAG コンポーネントと見ることができます。

完全な Q&A システムを代わりに作るものではありません。「関連するドキュメント断片を見つける」ことに集中しています。その後、それらの断片をどう使うかは、CLI、SDK、MCP クライアント、または自分の Agent ワークフローに任せられます。

この位置づけは実用的です。多くのプロジェクトは巨大な知識ベースシステムを必要としていません。必要なのは、AI がローカルドキュメントをより正確かつ素早く検索し、その結果を現在のタスクへ戻せることです。

利用時の注意

第一に、ドキュメント品質は依然として重要です。

検索ツールは既存の内容を見つけるだけです。ドキュメント自体が古い、重複している、矛盾している場合、AI は誤ったコンテキストを受け取る可能性があります。qmd を Agent に接続する前に、重要なドキュメントを整理した方がよいです。

第二に、インデックス範囲を広げすぎないことです。

リポジトリ内のすべての Markdown を入れれば良いとは限りません。依存パッケージのドキュメント、一時メモ、古い案の草稿は結果を汚す可能性があります。どのディレクトリが信頼できるドキュメントソースかを明確にする方がよいです。

第三に、検索結果には出典を残すことです。

AI がドキュメント断片を使うとき、それがどのファイル、どの章から来たのか分かる方がよいです。人間が確認しやすくなり、「ドキュメントの結論に見えるが実はモデルの要約」という問題も減ります。

第四に、人間の判断を完全に置き換えないことです。

qmd はコンテキストの再現率を高められますが、プロジェクトの真実の源を置き換えるものではありません。重要な変更では、現在のコード、テスト結果、最新要件を確認する必要があります。

向いているチーム

チームがすでに AI Agent を日常開発フローに入れ始めているなら、qmd のようなツールは価値があります。

特に次のようなチームに向いています。

ドキュメントを多く書いている
プロジェクト履歴が長い
新メンバーと AI の両方が素早く背景を理解する必要がある
アーキテクチャ決定記録をよく保守している
Markdown の規約ドキュメントが多い
AI がコード変更前にルールを確認するようにしたい

目的は AI を「全知全能」にすることではありません。AI が推測を減らし、より多く調べるようにすることです。

参考

tobi/qmd

最後に

qmd の価値は、ローカル Markdown ドキュメントを AI Agent が安定して呼び出せる検索入口に変えることです。

プロジェクトドキュメントが「人間が読む説明」から「人間と AI の両方が検索できるコンテキスト源」になると、AI コーディングアシスタントはプロジェクトルールに従いやすくなります。

Qmd on KnightLiブログ