【markdive】AIエージェントのMarkdown読解を、目次から読む形に変えるCLI

はじめに

npmのパッケージどころかまともなツールを作成して公開できるところまで完成できたのも初めてなので、アドバイスやフィードバック大歓迎です。

日頃AIエージェントを使って開発を行っている中で気になったことがありました。
仕様書やREADMEを読み込む際に、200行くらいのチャンクで上から順番に読んでいるのです。
コンテキスト削減のためだとは思いますが、あまり効率が良くないのではないかと感じていました。

• 目的のセクションまで読み進める際にトークンが無駄になっているのでは？
• Agent Skillのように段階的開示の思想を採用できないか？

と思い、markdiveというCLIツールを作ってみました。

対象読者

• AIエージェントに仕様書やREADMEを読ませる機会が多い開発者
• 大きいMarkdownを読むときのトークン消費や文脈ロスに悩んでいる人
• 「上から全文読む」以外の読み方を試したい人

TL;DR

• markdive は大規模Markdownを目次から読むためのCLI
• 基本操作は dive（構造探索）と read（本文取得）の2段階
• 設計思想は「段階的理解・構造的アドレッシング・文脈保全・軽量性・役割分離」
• mdsel / treemd とは競合というより得意領域が異なる

markdiveの設計思想（コア要件）

markdive では、実装や将来機能を判断する際に次の5点をコア要件にしています。

1. 段階的開示（Progressive Disclosure）
   文書はまず構造を把握し、必要な箇所だけを掘り下げる。

2. 構造的アドレッシング（Structured Addressing）
   見出し名だけでなくセクションID（例: 1.2.3）で現在地を追跡する。

3. 文脈保全（Context Preservation）
   行単位ではなくセクション単位で読むことで、周辺文脈の欠落を防ぐ。

4. 軽量・可搬性（Lightweight and Portable）
   重い依存を増やさず、CLI単体で再現可能な動作を優先する。

5. 役割分離（Separation of Concerns）
   markdive は読み取りと探索に特化し、編集は他ツールに委譲する。

この5点は、機能追加の可否を判断する際のチェックリストとしても使えます。

markdive について

markdiveは大規模なMarkdownファイルを段階的に探索するためのTypeScript製CLIツールです。
Markdownを少しずつ潜っていくイメージで、markdown + dive で markdiveと名付けました。

インストール

npm install -g markdive
# または npx で使う
npx markdive dive index.md

Skillsも用意しています。リポジトリのskills/markdiveにありますし、パッケージに同梱もされています。

2つのコマンド

dive: 構造を探索する

Markdownドキュメントの見出し構造を目次の形で表示します。
ルート全体を見るか、--path で指定した章を起点に掘り下げます。

最初に dive を実行することで、どこを読むべきかをIDベースで決められます。

概要の把握

$ markdive dive index.md --depth 2
1: 【markdive】AIエージェントのMarkdown読解を、目次から読む形に変えるCLI
  1.1: はじめに — npmのパッケージどころかまともなツールを作成して公開できるところまで完成できたのも初めてなので、ア...
  1.2: 対象読者 — - AIエージェントに仕様書やREADMEを読ませる機会が多い開発者
  1.3: TL;DR — - markdive は大規模Markdownを目次から読むためのCLI
  1.4: markdiveの設計思想（コア要件） — markdive では、実装や将来機能を判断する際に次の5点をコア要件にしています。
  1.5: markdive について — https://www.npmjs.com/package/markdive
  1.6: mdsel / treemd との比較 — 突貫で作って公開までしたので事前の詳しい調査はしていなかったのですが、後から調べると、近い機能を持つ...
  1.7: まとめ — markdive は、AIエージェントにMarkdownを「上から順に読む」代わりに、
  1.8: 謝辞 — [mdsel](https://github.com/dabstractor/mdsel) 作者の ...

特定のセクションを起点にすることもできます。

特定セクションの掘り下げ

$ markdive dive index.md --path 1.6 --depth 1
  1.6: mdsel / treemd との比較 — 突貫で作って公開までしたので事前の詳しい調査はしていなかったのですが、後から調べると、近い機能を持つ...
    1.6.1: 機能と設計思想を比較 — そこで3者の機能と設計思想を比較してみました。
    1.6.2: 使い分けの目安 — 使い分けの目安としては、次のイメージが分かりやすいです。

read: 必要なセクションだけ読む

指定したセクションIDの見出しと子孫セクション本文を出力します。
メタデータヘッダーが付くため、今どこを読んでいるかを追跡しやすくなります。

この「構造確認（dive）→ 精読（read）」の2段階が、markdiveの基本運用です。

特定セクションの精読

$ markdive read index.md --path 1.6
---
markdive:
  source: index.md
  path: 1.6
  context: 【markdive】AIエージェントのMarkdown読解を、目次から読む形に変えるCLI > mdsel / treemd との比較
---

## mdsel / treemd との比較

突貫で作って公開までしたので事前の詳しい調査はしていなかったのですが、後から調べると、近い機能を持つ `mdsel` と `treemd` というツールがありました。

https://github.com/dabstractor/mdsel

https://github.com/Epistates/treemd

### 機能と設計思想を比較

そこで3者の機能と設計思想を比較してみました。
この比較を通じて、`markdive` のコンセプトもより具体化できました。
機能追加の判断をするうえでも参考になっていて、先行して取り組まれている両ツールには学ぶところが多いと感じています。

比較すると、3者は似ているようで「何を目的としているか」が違います。

| 観点 | markdive | mdsel | treemd |
|---|---|---|---|
| 主目的 | 未知の大規模文書を構造的に探索する | 必要箇所を素早く抽出する | ツリー操作と高度な抽出を両立する |
| 基本操作 | dive → read の2段階 | セレクタ指定で直接抽出 | クエリ指定で構造要素を抽出 |
| 現在地の扱い | セクションIDとパンくずで追跡しやすい | 抽出結果中心で、導線管理は呼び出し側次第 | クエリ結果中心で、導線管理は呼び出し側次第 |
| 文脈の扱い | セクション単位で保持 | 抽出条件によっては断片化しやすい | 抽出条件によっては断片化しやすい |
| 向いている場面 | どこに何があるか分からない仕様書探索 | 読みたい箇所が分かっているときの高速取得 | 大規模READMEの精読、コードブロックやリンク抽出 |

つまり、

- mdsel は「対象が分かっている状態での抽出」が強い
- markdive は「対象が分からない状態からの探索」が強い
- treemd は「クエリで構造要素を抽出する」のが強い

という棲み分けです。

### 使い分けの目安

使い分けの目安としては、次のイメージが分かりやすいです。

- 最短で一点を取りたい: mdsel
- 文書全体を把握しつつ迷子にならず掘りたい: markdive
- 見出し・コードブロック・リンクを構造的に抽出したい: treemd

JSON出力

すべてのコマンドで --json が使えます。
ツール連携では次のような流れが扱いやすいです。

JSON出力

# 1. 全体把握
$ markdive dive index.md --json

# 2. 関心章をドリルダウン
$ markdive dive index.md --path 3 --depth 1 --json

# 3. 必要箇所を精読
$ markdive read index.md --path 3.2

mdsel / treemd との比較

突貫で作って公開までしたので事前の詳しい調査はしていなかったのですが、後から調べると、近い機能を持つ mdsel と treemd というツールがありました。

機能と設計思想を比較

そこで3者の機能と設計思想を比較してみました。
この比較を通じて、markdive のコンセプトもより具体化できました。
機能追加の判断をするうえでも参考になっていて、先行して取り組まれている両ツールには学ぶところが多いと感じています。

比較すると、3者は似ているようで「何を目的としているか」が違います。

観点	markdive	mdsel	treemd
主目的	未知の大規模文書を構造的に探索する	必要箇所を素早く抽出する	ツリー操作と高度な抽出を両立する
基本操作	dive → read の2段階	セレクタ指定で直接抽出	クエリ指定で構造要素を抽出
現在地の扱い	セクションIDとパンくずで追跡しやすい	抽出結果中心で、導線管理は呼び出し側次第	クエリ結果中心で、導線管理は呼び出し側次第
文脈の扱い	セクション単位で保持	抽出条件によっては断片化しやすい	抽出条件によっては断片化しやすい
向いている場面	どこに何があるか分からない仕様書探索	読みたい箇所が分かっているときの高速取得	大規模READMEの精読、コードブロックやリンク抽出

つまり、

• mdsel は「対象が分かっている状態での抽出」が強い
• markdive は「対象が分からない状態からの探索」が強い
• treemd は「クエリで構造要素を抽出する」のが強い

という棲み分けです。

使い分けの目安

使い分けの目安としては、次のイメージが分かりやすいです。

• 最短で一点を取りたい: mdsel
• 文書全体を把握しつつ迷子にならず掘りたい: markdive
• 見出し・コードブロック・リンクを構造的に抽出したい: treemd

まとめ

markdive は、AIエージェントにMarkdownを「上から順に読む」代わりに、
「構造を把握して必要箇所から読む」という手順を与えるためのツールです。

mdsel や treemd のような抽出系ツールが活きる場面もありますが、
未知の文書を探索しながら読み解くワークロードでは markdive の相性が良いと考えています。

まだ自分でも使い込めていないので、みなさんのフィードバックや活用例をぜひ聞いてみたいです。PRも大歓迎です！

謝辞

mdsel 作者の dabstractor さん、treemd 作者の Epistates さんに感謝します。