imozuru

日本語 | English

imozuruは知らない分野を原文にたどりつくまで芋づる式に掘るClaude Codeのスキルです。 Batesのberrypicking、Ellisの探索行動のモデル、Kuhlthauの探索過程の研究など、図書館情報学の情報探索の研究から考え方を応用しています。

AIの判断能力は形式知・ノウハウを収集することで強化されます。 原文に書かれた形式知・ノウハウを集めて、AIの判断の材料にすることが、imozuruの元からの役割です。

2.0のメジャーアップデートでは、人間が読むことに重点を置いて強化しました。 調べた分野を読み手の水準に合わせて解説する詳細レポートと、すべての調査を1枚で見返せるダッシュボードを追加しています。 バージョンごとの変更は CHANGELOG.md に記載しています。

既存のAI調査手法との差別化点

スキルなしで「調べて」と頼むと、LLMは検索上位の数件を読んで要約を返しがちです。 要約はすぐに読めますが、判断に必要な細部が抜け落ちやすくなります。 分野の用語を知らないうちは検索語も選べないため、検索は最初に思いついた言葉の範囲にとどまってしまいます。

imozuruはまず『分野の用語・中心にいる人・知見が集まる媒体』を押さえ、そこから引用やリンク、著者をたどって原文を集めます。 集めた原文は要約せずに保存し、答えに必要な論点ごとに「どのファイルの何行目か」を示すところまでにとどめます。 AIは集めた原文を材料に判断し、ユーザーは示された場所の原文を読んで、その判断の根拠を確認できます。

スキルのフロー

Claudeはまず、問いと、答えるために必要な論点を3〜6個書き出します。 次に、探し方を変えた2本の検索役（Webを検索するサブエージェント）で用語、人、媒体を集め、地図（map.md）にまとめます。 その後、原文が見つかるまで参考文献や被引用、著者をたどっていきます。 論文のない分野では、記事の中のリンクや「〇〇さんの記事を参考にした」という記述をたどります。

見つけた原文は sources/ に保存し、404やログインを求めるページは中身を見て除きます。 すべての論点に原文が付くか、新しい資料が出てこなくなったら探すのをやめます。 最後に、原文から切り出した文を論点ごとに並べたページ（抜き書きのページ）と、その分野の解説（詳細レポート）を作ります。

見張りのモード（/imozuru watch <話題>）は、ここまでの調査の流れとは別に動きます。 掘って見つけた媒体（QiitaやZennのタグ、note、YouTube、ブログ、arXiv）の新着をRSSで集めて並べます。

入れ方

Claude Code のプラグイン

このリポジトリをマーケットプレイスとして追加し、プラグインとして入れます。

/plugin marketplace add MaryCache/imozuru
/plugin install imozuru@imozuru

プラグインにはバージョン番号を付けていて、使っている人へ更新が届くのは、番号を上げたリリースのときだけです。 main の枝はいつも最新のリリースと同じ中身で、開発中の直しは dev の枝にあります。 自動で最新にしたいときは、/plugin のマーケットプレイスの画面で imozuru の自動更新を入れてください。 手で更新するときは claude plugin marketplace update imozuru を実行します。

skills のCLI

skills のCLIでも入れられます。

npx skills add MaryCache/imozuru

手動の場合は、skills/imozuru/ を ~/.claude/skills/imozuru/ にコピーしてください。

Codex CLI

skills/imozuru/ を ~/.agents/skills/imozuru/ にコピーするか、リンクを作ります。 リポジトリごとに使いたい場合は、そのリポジトリの .agents/skills/imozuru/ に置いてください。

macOS / Linuxでは、次のようにリンクを作れます。

git clone https://github.com/MaryCache/imozuru ~/src/imozuru
mkdir -p ~/.agents/skills && ln -s ~/src/imozuru/skills/imozuru ~/.agents/skills/imozuru

Windows（PowerShell）では、<clone先> をcloneした場所の絶対パスに置き換えてください。 ジャンクションは管理者権限なしで作れます。

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
New-Item -ItemType Junction -Path "$env:USERPROFILE\.agents\skills\imozuru" -Target "<clone先>\skills\imozuru"

リンクで入れた場合は、clone先で git pull を実行すると更新できます。

Codexの対話画面では、/imozuru の代わりに $imozuru を使います。 一覧は /skills で見られ、スキルの説明に合う頼み方なら自動でも選ばれます。

$imozuru 芋づる式に調べて: Reactの状態管理
$imozuru watch react

対話画面を開かずに動かすときは codex exec を使います。 Web検索と、原文を取得するスクリプトのネットワーク接続が必要です。 次の例は両方を有効にし、結果を作業フォルダ内の ./research/react/ に保存します。

codex --search exec -s workspace-write -c sandbox_workspace_write.network_access=true '$imozuru 芋づる式に調べて: Reactの状態管理。保存先は ./research/react にして'

codex exec は、gitリポジトリか信頼済みのフォルダの中で動かします。 それ以外の場所で動かすときは、exec のあとに --skip-git-repo-check を付けてください。

必要なもの

スクリプトはPython 3.10以上の標準ライブラリだけで動き、次のコマンドは入っていれば使います。

コマンド	使う場面	入っていない場合
pdftotext（popplerかXpdf）	PDFから本文を取り出す	pdfminer.six が入っていれば、代わりにそれで取り出す（スクリプトを動かすPythonに python3 -m pip install --user pdfminer.six で入れる。popplerを入れられない環境向け）。PATHにある pdf2txt.py でもよい（Windows以外）。pdftotextより遅く、大きなPDFは時間の上限で FAIL になることがある。どれも無ければ FAIL になる
pdftoppm（popplerかXpdf）と tesseract	文字の層がない古いPDFをOCRにかける	そのPDFは FAIL になる
tesseract の言語データ jpn と jpn_vert	日本語のスキャンPDFを、横書きも縦書きも読む（入っていれば自動で使う。環境変数 IMOZURU_OCR_LANG で jpn+eng のように指定もできる）	英語だけで読む。日本語のPDFは読み取りの確信度が低いので FAIL になる
yt-dlp	YouTubeの字幕を取得する	動画は FAIL になる
ax	HTMLをmarkdownにする	標準ライブラリで文字だけを取り出す（見出しや表の形はaxのほうがよく残る）

引用をたどる chain.py は OpenAlex のAPIを使いますが、APIキーは必要ありません。

使い方

Claude Codeで、次のように頼みます。Codex CLIでは、頼み方の先頭に $imozuru を付けられます。

芋づる式に調べて: 歌ってみたのMIXで、上手い人がどういう順番で処理しているか

Gaussian Splattingってよく聞くけど全然わからない。論文とか解説の流れを掘ってほしい

/imozuru watch react

結果は ~/research/<話題>/ に、次の形で保存されます。

map.md         問い・題・調査の論点・用語・人・媒体・原文の表・次の手がかり
log.md         周ごとに、何を探して何が出たか・判断とその理由
sources/       保存した原文
extracts.json  抜き書き
report.html    抜き書きのページ
queries.jsonl  検索語ごとのヒットの全件
fetch-log.jsonl 取得の記録（URL と OK/FAIL）
digest.json    詳細レポートの解説
digest.html    詳細レポート（Lv1〜Lv3 の解説と、検索の全記録）

人間が読む・見返す

集めた原文は、人間が読んで判断できる形で見せます。

抜き書きのページ

原文から切り出した文を、調査の論点ごとに並べたページです。 見本は examples/demo/ にあり、次のコマンドでスクリプトだけを試せます。

python3 skills/imozuru/scripts/report.py examples/demo

切り出した文を機械で照合する理由は、下の「抜き書きを機械で照合する理由」に書いています。

詳細レポート

調べた分野を、前提知識の違う読み手ごとに3編で解説するページです。 解説の1文ごとに原文の引用が根拠として付き、何を探して何が出たかの全記録も一緒に載ります。

調べ終えたあとにClaudeが解説を書き、digest.py が引用を原文と照合してからページにします。 解説と記録の2層に分けた理由は下の「詳細レポートの2層」に書いています。

調査記録のダッシュボード

2.0で追加したページです。 調査の置き場（既定 ~/research）にあるすべての調査を、トピックごとに1枚のページへまとめます。 トピックは1つの問いを調べたひとまとまりで、~/research の中のフォルダ1つに当たります。

python3 skills/imozuru/scripts/dashboard.py ~/research

~/research/index.html ができます。

ホームには、調べるのをやめた理由（終了理由）・原文の取得元・引用やリンクをたどった回数（周回数）の集計が並びます。 左のサイドバーからトピックを選ぶと、調査の論点・周回数・原文・文書をまとめたトピック詳細が開き、詳細レポートや抜き書きもその中で読めます。 サイドバーの検索は題名・疑問・用語・人物・媒体を対象にし、ひらがなやローマ字でも一致します。 画面の使い方は右上の「?」から開くヘルプにまとめています。 文書は表示中に左下のボタンでPDFに保存でき、右上の吹き出しのボタンからは作者へ感想・要望を送れます。

スマホで見る

ダッシュボードを配信すると、スマホのブラウザからも閲覧できます。

IMOZURU_SERVE_TOKEN=<合言葉> python3 skills/imozuru/scripts/dashboard.py ~/research --serve 8765
tailscale serve --bg 8765

配信はPCの中（127.0.0.1）だけで待ち受け、合言葉の付いたURLでしか開けません。 スマホからはTailscaleで自分の機器にだけ中継して、https://<PCの名前>.<tailnet>.ts.net/?k=<合言葉> を開きます。 <tailnet> は、Tailscaleの管理画面に出るネットワークの名前です。

合言葉は環境変数 IMOZURU_SERVE_TOKEN で固定できます（16文字以上）。 固定しないと起動のたびに変わり、ホーム画面に追加したアイコンから開けなくなります。

配信した画面はアプリとして入れられます。 スマホでもパソコンのChrome・Edgeでも、右上の入れるボタンを押すと、ブラウザの入れる画面か、そのブラウザでの手順が出ます。 入れたアプリは合言葉を入力せずに開けます。

設計の考え方

要約しない理由

Kuhlthau（1991）は調べ始めの混乱した段階で詳しくまとめると、早すぎる閉じ（premature closure）を招き、探索の過程が妨げられると述べています。 そのためimozuruは、調べている間は原文の場所を示すところまでにとどめています。 解説を書くのは、止める判定が出たあとの詳細レポートだけです。

This is the beginning of the README. Read the rest at the original. Read the full README ↗