WORK

mdq-rg

mdq-rgは、Markdownを見出し単位で検索する、AI向けのローカルCLIツールです。Apple Silicon搭載Macなどのターミナルでmdrgコマンドを実行すると、検索結果をJSON Lines形式で返します。

利用者と課題

制作前はdahatakeさんのmarkdown-queryを使っていました。Python製で、ディレクトリによって使い方が変わったりして、自分の使い方には合わないかなと感じていました。ripgrepの速さと軽さを生かせばmarkdown-queryを最適化できるのではないかと考えたことが、制作の発端です。mdq-rgはmarkdown-queryの考え方をもとに設計し、コードは移植していません。

機能

  • mdrg search --q QUERYは検索キーワードを必須引数として受け取り、デフォルトの--mode rankでMarkdownのセクションをランキングします。
  • --top-k Nのデフォルト値は5件、--max-tokens Nのデフォルト値は推定出力トークン数1300で、出力予算を超える場合も最初の1件は返します。
  • 検索結果は1行1オブジェクトのJSON Linesで、相対path、両端を含むlines、見出しを > で連結したheading_path、score、snippetを返します。
  • スニペットは検索キーワードを含む行から最大5行を取り、400文字以内に切り詰めます。
  • 検索キーワードを含む行がない場合はセクションの先頭3行を使います。
  • mdrg get 'PATH:START-END'は相対ファイルパスと1始まりの行範囲を受け取り、両端を含む原文をJSON Linesのtextとして返します。
  • mdrg listは見出しと位置を列挙し、JSON Linesでpath、lines、heading_path、levelを返します。
  • listの--heading-level Nは見出しの深さ、--limit Nは出力行数を制限し、どちらもデフォルトでは無制限です。

使用技術

  • Rustで実装し、ripgrepのignoreライブラリ、rayon、clap、serde、toml、unicode-normalization、unicode-segmentationを使用しています。
  • Apple Silicon搭載macOS向けにHomebrewとCargoでインストールでき、GitHub Releasesでも配布しています。

制作期間

構想を練り始めたのは、記憶では2026年10月中旬ごろです。開発用リポジトリの記録は10月30日に始まり、公開リポジトリの最初のリリースは11月9日です。

工夫した点

Claudeに検索のパフォーマンスを測定させるときの測定方法が難しかったです。どこをゴールにするかが進めるうちにぶれて、途中でゴールを見失いました。開発記録では、長いセクションをウィンドウに分ける案を基準のバージョンと比較したところ、開発用のクエリでは期待するドキュメントを検索結果に含むクエリが減り、ランキングの指標も下がり、別のクエリで測ったCPUの命令数も増え、採用しませんでした。形態素解析ライブラリは、デフォルトで使っておらず、ランキングの実測でも利点がなかったので外しました。外した後も開発用のクエリで、検索結果の標準出力が以前の測定に使ったバージョンと一致し、実行ファイルは小さくなりました。使ってみて、情報に届くまでが前より早くなったかなという印象があり、トークン消費も少し抑えられている感じがあるかなと思います。今後はClaude Code・Codex・CursorなどのAIツールのコネクタやツールとして配布できるようにしていきたいと考えています。

リンク