Research Scan

research-scan

Research Scan は、研究上の問い、プロジェクト、または意思決定にとって最も重要な最近の論文を5〜10件見つけ、検証します。概要や単一の質問を起点に、文献を検索し、引用グラフをたどって調査範囲を広げ、網羅性を測定し、すべての DOI を最新の記録と照合して検証し、エビデンスオブジェクトを出力します。その間、これを操作するエージェントは検索クエリを計画し、候補をスクリーニングして、候補リストの順位を付けます。これは推論エージェント向けのエビデンスパイプラインであり、質問に答えるアシスタントではありません。

ドキュメント：https://researchscan.synectic.org

作業は意図的に2つに分かれています。

CLI は決定論的で、モデルに依存しません。 OpenAlex、Semantic Scholar、arXiv を横断して検索し、引用グラフをたどり、重複を除去し、基準ごとに網羅性を数え、候補リストを作成し、すべての DOI を最新の記録と照合して検証し、選定ルールを適用して、結果をレンダリングします。LLM SDK は含まず、論文について判断することもありません。

エージェントが認知処理を担います。 検索クエリの計画、候補ごとの0〜3のスコア付け、網羅性が不十分な場合のギャップ検索クエリの作成、候補リストの順位付けは、すべてモデルによる判断です。スキルには、その判断に使う評価基準がプレーンな Markdown として skills/research-scan/references/ にまとめられています。スキルをホストするエージェントが、それらを実行します。

2つの処理の間をつなぐのはファイルです。ファイルシステムは、単なる保存場所ではなく、推論と実行の間のプロトコル境界です。これにより、Claude Code、Codex、Cursor、あるいは単純な Python ループでも、同じ成果物を使って同じ一連の処理を実行できます。

brief ─▶ [plan queries] ─▶ retrieve ─▶ [screen 0–3] ─▶ expand ─▶ [screen] ─▶ coverage
      ─▶ [gap round, if coverage is thin] ─▶ shortlist ─▶ [rerank] ─▶ verify ─▶ emit

角括弧で囲まれたステップはエージェントが担当し、それ以外は CLI のステージです。

結果を左右する要素は2つです。目的（build、research、orient）によって、論文が選定枠を得るために満たすべき条件が決まります。プロファイル（quick、standard、deep）によって、スキャンにかかるコストが決まります。どちらも仕組みで説明しています。

出力は、検証済みの JSON と、人に渡せる Markdown の概要を含む実行ディレクトリです。各論文の DOI、タイトル、発行年、筆頭著者はすべて、最新の記録と照合して確認されています。

インストール

Python ≥ 3.11 と uv が必要です。

uvx research-scan doctor          # run any command without installing
uv tool install research-scan     # or put it on PATH permanently

設定

configure は各認証情報の入力を求め、現在設定されている内容を表示し、~/.config/research-scan/.env を 0700 のディレクトリ内にモード 0600 で書き込み、最後に doctor を実行します。

research-scan configure          # `setup` is an alias for the same command

キーは入力時に画面へ表示されません。再実行しても安全です。各変数の現在値は末尾4文字を残してマスク表示され、Enter キーを押すと現在の値が維持され、入力すると置き換わります。configure が尋ねないファイル内の項目（コメントを含む）は、すべてそのまま残ります。標準入力が端末でない場合は、書き込むファイルの内容を表示して終了コード2で終了します。Dockerfile やプロビジョニングスクリプトでは、この動作が適切です。

変数	用途
OPENALEX_API_KEY	OpenAlex（主要な情報源）。必須です。設定されていない場合、doctor は終了コード3で終了します。
OPENALEX_MAILTO	強く推奨します。OpenAlex のレートを5 req/sに引き上げ、Crossref の polite プールにも参加できます。
S2_API_KEY	推奨します。Semantic Scholar の検索と引用グラフの拡張は、設定しなくても動作しますが、レートは約3分の1に制限されます。doctor は警告を表示します。
NCBI_API_KEY	任意です。PubMed のみ対象で、レートが3 req/sから10 req/sに上がります。

ファイルを手動で書き込む場合は、リポジトリ内の .env.example をテンプレートとして使います。優先順位は、プロセス環境変数、~/.config/research-scan/.env、リポジトリ内の ./.env の順です。

動作を確認する

doctorはキャッシュをバイパスしてすべてのソースを実際に呼び出します。設定されていると思われる内容を一覧表示するだけではありません。

research-scan doctor             # a four-line summary and a verdict
research-scan doctor --verbose   # every check, with timings and paths
research-scan doctor --json      # machine-readable; this is the CI/agent interface

Research Scan <version>
✓ configuration
✓ OpenAlex   ✓ Semantic Scholar   ✓ Crossref   ✓ arXiv   ○ PubMed
  PubMed: endpoint reachable; source routed for biomed but not built
✓ writable run store
Ready.

終了コード0なら問題ありません。終了コード3は必須のチェックに失敗したことを示します。トラブルシューティングを参照してください。チェック内容と終了コードは3つすべての出力モードで同じで、異なるのは表示形式だけです。

○は、ルーティングされているものの取得アダプターがないソースを示します。ソースの表を参照してください。プローブは引き続き実行され、正確に報告します。PubMedの行には、E-utilitiesエンドポイントが応答したと記載されますが、これはそこから取得できるという主張とは異なります。doctor --jsonでは、同じ情報がsources_not_builtとして記載され、キーと値が変更されていないprovidersマップも含まれます。

最初のスキャン

スキルをインストールしたら、エージェントにスキャンを依頼します。

/research-scan "I am designing a financial education product for young adults. 
Research question: What interventions have the strongest recent evidence for increasing 
long-term savings behavior?

Context:
- I am interested in mechanisms that change real-world behavior, not just 
financial literacy scores.
- Prioritize randomized trials, large field studies, and strong causal evidence.
- Include evidence that challenges the assumption that education alone works.

Find the 10 papers that should shape our product decisions. Explain why each paper matters, what it 
found, and what evidence gaps remain." --profile standard

1行の質問でも機能します。背景を含む簡単な概要を添えると、計画ステップで各セクションが検索計画の特定の部分に対応付けられるため、より効果的です。テンプレートはskills/research-scan/examples/brief.example.mdです。これはbuild用に記入した概要で、brief.research-example.mdはPurpose: researchにした同じテンプレートです。

/research-scan research/my-brief.md --profile standard --top 10

概要のセクション	反映先
Purpose:行	計画から導出されるサブ基準と、why_it_mattersで論じる内容です。build、research、orientのいずれかを指定します。省略した場合、エージェントが推測します。
概要の対象	brief_summaryとドメインのルーティングです。トピックだけでなく、状況も記述してください。
決定または回答が必要な内容	すべての論文を評価するサブ基準です。未解決の選択肢、または実際の質問を明記してください。
すでに信じていること（前提）	contradictoryクエリです。前提を確認するだけのスキャンはエビデンスになりません。
除外対象	単語の境界でコードによって適用されるqueries.json.must_notです。クエリテキストにNOT条件として含めないでください。
既知の論文や著者	anchorsです。プールに固定され、フィルターと上限の対象外となり、常に拡張シードとして使用されます。

結果はresearch/scans/<YYYY-MM-DD>-<slug>/に保存されます。出力を参照してください。

引数の全リスト：

/research-scan <brief.md | "question"> [--profile quick|standard|deep] [--top N] [--foundational N]
                                       [--from YYYY-MM] [--to YYYY-MM] [--slug name]
                                       [--domain behavioral|cs|biomed|general]
                                       [--max-candidates N] [--per-query N]

エージェントを接続する

同じパイプラインにつながる2つの入口があります。ルーブリックがあるのはスキルであり、スクリーニングと再順位付けの判断を担います。MCP サーバーは同じ4つの判断ポイントをツールとして公開し、MCPに対応する任意のクライアントから利用できます。

Claude Code — スキル

次のいずれか1つを使用できます。3つとも同じskills/research-scan/を参照します。

# 1. symlink a clone — edits to the rubrics take effect immediately
ln -s "$PWD/skills/research-scan" ~/.claude/skills/research-scan

# 2. load the repo as a plugin, per invocation (it carries .claude-plugin/plugin.json)
claude --plugin-dir /path/to/research-scan

# 3. skills CLI
npx skills add Synectic-Research/research-scan

Claude Code — プラグイン

プラグインを使うと、スキルのインストールとuvx MCP サーバーの設定を一度に行えます。以下の.mcp.jsonを使う方法は、Claude DesktopやCursorなど、プラグインを使わないクライアント向けです。

/plugin marketplace add Synectic-Research/research-scan
/plugin install research-scan@synectic

任意のMCPクライアント — stdio

research-scan mcpは、標準入力／標準出力でMCPを使用し、それ以外は出力しません。トークンは読み取らず、必要もありません。クライアントが起動したプロセスは信頼されているためです。追加のインストールは不要です。サーバーはパッケージに含まれています。

{
  "mcpServers": {
    "research-scan": {
      "command": "uvx",
      "args": ["research-scan", "mcp"]
    }
  }
}

クライアント	設定先
Claude Code	プロジェクトのルートにある.mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json

ツールは4つあり、パイプラインが必要とするモデルの判断ごとに1つあります。scan_start（クエリ計画を渡します）、scan_continue（スクリーニングのスコア、ギャップクエリ、または再順位付け対象の項目ページを渡します）、scan_verify、scan_resultです。パイプラインに対するチャット用エンドポイントではありません。それぞれが判断を必要とするポイントであり、クライアントのモデルがスキルとまったく同じ判断を担います。段階の順序も成果物も同じです。アダプターはサブプロセスとしてCLIを実行し、その終了コードを読み取ります。別のトランスポートについては、research-scan mcp --helpを実行してください。

動作の仕組み

各段階は冪等で、再実行できます。queries.json を変更するかフラグを指定して、その変更が影響する段階から再実行してください。CLI が candidates.json、shortlist.json、manifest.json、evidence.* を管理し、エージェントが queries.json、screen.json、ranked.json を管理します。互いのファイルを編集することはありません。

目的

概要の Purpose: 行で宣言するか、推定します。目的によって、計画から導き出す下位基準、スクリーニングで関連性があるとみなす対象、why_it_matters で論じるべき内容が決まります。

目的	論文が選ばれる理由	例
build	設計や計画の判断を前進させる	「登録フローを設計する前に、何を知っておくべきでしょうか？」
research	私たちの考え、検証する内容、または測定方法を変える	「デフォルト登録が人々の貯蓄額に影響することを示す、近年の最も有力なエビデンスは何でしょうか？」
orient	初心者が知っておくべき内容であり、新しいものを優先する	「メカニスティック・インタープリタビリティの初心者です。新しいものから、何を読むべきでしょうか？」

プロファイル

フラグ 1 つで、スキャンにかかるコストを設定します。--profile は init に属し、マニフェストに記録されます。明示的に指定したフラグは引き続き優先されます。たとえば、--per-query 60 を指定すると、プロファイルの設定にかかわらず 60 になります。

プロファイル	クエリあたり	プール上限	期間外の合計	ギャップラウンド
quick	20	250	12	なし
standard（デフォルト）	40	450	20	カバレッジに偏りがある場合
deep	40	450 × ソース数 ÷ 2	30	常に実行

期間外の合計は実行全体の予算であり、段階ごとの上限ではありません。まずは standard を使用してください。「どんな情報があるか」を調べるには quick を、見落としのコストが大きい場合は deep を使用してください。それぞれの測定済み再現率は測定結果をご覧ください。

ギャップラウンド

ギャップラウンドは最大 1 回実行されます。standard では、coverage によって基準のカバレッジに偏りがある、またはクエリの結果がほぼ空であると報告された場合にのみ実行されます。それ以外の場合はスキップされ、その旨がレポートに記載されます。coverage は、スクリーニングを通過した論文数を下位基準ごとに数えます。エージェントは、結果が最も少なかった基準に対するクエリを 1 つまたは 2 つ作成します。retrieve --round 2 と expand --round 2 は、そのクエリで見つかった論文を追加します。ラウンド 1 の論文とそのスコアは破棄されず、プールは増えるだけです。

対応ソース

ソース	用途	ステータス
OpenAlex	主な検索、メタデータ、撤回フラグ、グラフ検索のフォールバック	実装済み。キーが必要です。
Semantic Scholar	検索、および参考文献、引用、推薦を対象とした引用グラフの展開	実装済み。キーは任意ですが、キーがない場合はスロットリングされます。
arXiv	cs の追加ソース、およびクエリが手法に関するものの場合の general の追加ソース	実装済み。
PubMed	biomed のルーティング先	ルーティングされていますが、まだ実装されていません。 biomed のスキャンは OpenAlex + Semantic Scholar で実行され、manifest.json に unavailable: true が記録されます。ルーティング先が未実装の場合は記録され、黙って除外されることはありません。
Crossref	DOI の検証のみ。検索ソースとしては使用しません	実装済み。接続できない場合、検証は OpenAlex に切り替わります。

--domain でルーティングを選択します。behavioral と general → OpenAlex + Semantic Scholar、cs → それらに arXiv を追加、biomed → それらに PubMed を追加します。--sources を指定すると、このマップが完全に上書きされます。

測定結果

行動経済学と LLM 文献検索エージェントという、厳選した 2 つのゴールデントピックについて、候補段階でスコアを付け、独立したジャッジモデルで評価しました。この 2 つのトピックは、他のツールとのベンチマークではありません。

プロファイル	スクリーニングした候補数	再現率（トピック 1 · トピック 2）	≈ 経過時間
quick	~355	7/10 · 4/6	20–25 分
standard	~570	8/10 · 5/6	35–40 分
deep	575–805	9/10 · 5/6	40–55 分

対象期間内の上位 10 件の、ジャッジによる適合率はどちらのトピックも 0.875 でした（独立したジャッジによる評価）。

候補プールが増えるほど再現率は上がり、効率は下がります。トピック 1 では、quick はスクリーニングした候補 100 件あたり 0.199 の再現率を得る一方、deep は 0.157 です。プロファイルを最も大きく分けるのは、対象期間外の予算（12 / 20 / 30）です。トピック 1 で残った見落としはすべて対象期間前の古典的な論文で、各段階で 1 件ずつ追加されます。

すべての表、試して元に戻した内容、数値の算出ルールについては、こちらをご覧ください： docs/measurements.md。

出力

すべての出力は research/scans/<YYYY-MM-DD>-<slug>/ に保存されます。

ファイル	内容
evidence.json	成果物です。論文ごとに 1 つの EvidencePacket が含まれます。メタデータ、再ランキングスコア、主な知見、重要性、制約事項、検証記録が含まれます。
evidence.md	同じ一覧を人が読みやすい形式で表示したものです。基礎となる古典的な論文は現在の研究の後に表示され、順位は通し番号になります。そのため、2004 年の論文は回答ではなく背景情報として読めます。
evidence.bib	出力された論文の BibTeX です。--no-bib で出力を抑制できます。
manifest.json	監査記録です。撤回済み、must_not、種別フィルター、プール上限などによるすべての除外と、再試行後も失敗したすべてのソースがここに記録されます。何も通知なく上限で切り捨てられることはありません。
coverage.json	サブ基準ごとに、該当する採用論文の件数をクエリ種別とソース別に示します。また、クエリごとの取得件数とシードごとの拡張適合率も含まれます。各ラウンドで 1 つのスナップショットが記録されるため、ギャップラウンドで回収した分は差分として確認できます。evidence.md の「Coverage」セクションとして表示されます。
queries.json、candidates.json、screen.json、expanded.json、shortlist.json、ranked.json	中間段階のデータです。すべてスキーマ検証済みです。
retrieval.log.jsonl、expansion.log.jsonl、verify.log.jsonl	各段階の構造化ログです。

DOI が解決できなかった論文や、タイトル、出版年、筆頭著者が最新の記録と一致しない論文は、フラグが付けられ、通知なく修正されることはありません。mismatches[] と [UNVERIFIED — check manually] マーカーが付いた状態で出力されます。論文が除外されるのは撤回された場合のみです。

データ契約を個別に表示するには research-scan schema --name <Model> を、すべてを Markdown で表示するには research-scan schema --md を実行してください。

コストと所要時間

経過時間は候補プールの規模に応じて変わります。スクリーニングが最も時間のかかる工程だからです。エンドツーエンドの実測値（counts.wall_clock_s、init → emit）は次のとおりです。

プール	スクリーニングのバッチ数	経過時間
~675 件 — cs、デフォルト上限で 3 ソース	~27	37 分
~250 件 — デフォルト上限で 2 ソース	~10	22 分
~120 件 — --max-candidates 120	5	19 分

OpenAlex の料金はいずれの場合も ≈ $0.008 です。per_page による取得件数の拡張は無料なので、プールの規模による API 料金への影響はほとんどありません。

実際のコストはエージェントのトークンです。候補プールほど急には減りません。120 件の候補を処理する実行でも、フロンティアモデルのトークン費用は ≈ $5.70 かかり、250 件の場合より短縮できた時間はわずか 3 分でした。スクリーニング対象が少なくなると、再ランキング（プールの規模にかかわらず 52 件の全レコードを処理）と固定の工程オーバーヘッドが支配的になるためです。--max-candidates は、cs の候補プールが際限なく増えるのを抑えるための設定であり、スキャンを安くするためのものではありません。

デフォルト上限は構築されたソース数に応じて変わります（450 × n/2。cs の場合は 675、ソース 2 つの場合は 450）。--max-candidates と --per-query は retrieve に属し、実行ごとに上限を上書きします。どちらも実行時のフラグであり、設定ではありません。

ヘッドレス

このスキルは ScanSummary を返すため、スキャンを無人で実行し、構造化 JSON を後続の処理に渡せます：

claude -p "Use the research-scan skill to scan brief.md with --slug nightly --top 5. \
           When it finishes, return its ScanSummary as your final answer." \
  --plugin-dir /path/to/research-scan \
  --allowedTools "Bash(research-scan *),Read,Write,Edit,Glob,Grep" \
  --output-format json \
  --json-schema "$(research-scan schema --name ScanSummary)" \
  > scan.json

jq '.structured_output.counts' scan.json

スキルは文章で依頼してください。ここでは単独の /research-scan … スラッシュコマンドを使わないでください。 このスキルは context: fork を宣言しているため、単独のスラッシュコマンドはフォーク内で完結し、セッションは num_turns: 0 と result: "Command completed" を返します。スキャンは成功して実行ディレクトリを書き込みますが、--json-schema の紐付け先となるトップレベルのアシスタントターンがないため、structured_output は null になります。指示の形で依頼すると、セッションはスキルを実行し、フォークのレポートを受け取り、ScanSummary 自体を出力します。スキーマが紐付くのはこの出力です。2026-08-19 に両方の方法で検証済みです。

もう2つ、正しく設定する必要があるフラグがあります：

• スキルがすでに ~/.claude/skills/ にインストールされている場合、--plugin-dir は不要です。これを --bare と組み合わせないでください。ベアモードでは --plugin-dir がスキップされるため、スキルが読み込まれなくなります。
• --allowedTools には Bash(research-scan *)、Read、Write、Edit、Glob、Grep を指定する必要があります。Glob は省略できません。スキルは screen-batches/ を glob で検索し、スコアを付けるバッチを見つけるためです。

対象外

システマティックレビュー。 PRISMA の記録も、何千件ものレコードをスクリーニングするワークフローもありません。

論文の引用管理。 evidence.bib は便宜上のものであり、文献管理ライブラリではありません。引用管理ツールを使用してください。

全文を対象とした作業。 検索とスクリーニングは、タイトル、抄録、メタデータを対象に実行されます。PDF の取得、解析、閲覧は行いません。

Google Scholar、Scopus、Web of Science、PsycInfo は情報源ではなく、今後も対応予定はありません。個人用 API キーを使えるサービスも、利用規約に準拠した利用方法も存在しないためです。

トラブルシューティング

doctor が 3 で終了する。 必須チェックに失敗しています。回避策を探すのではなく、チェック名を確認して問題を修正してください。OPENALEX_API_KEY がない場合は FAIL となり、OpenAlex のプローブは実行されていないため、合格ではなく SKIP として報告されます。S2_API_KEY または NCBI_API_KEY がない場合は WARN にとどまり、スキャンは速度を制限して実行されます。デフォルトの出力には必要な対応が示されます。--verbose を指定すると、タイミングを含むチェック一覧全体が表示されます。--sources openalex,s2 を指定すると、チェック対象を絞れます。

スクリプトまたはエージェントから doctor の結果を読み取る。 インターフェースには doctor --json を使用してください。キーは安定しています。ready はブール値で、providers はチェック対象の各ソースを ok／warn／fail／skip に対応付けます。skip はプローブが実行されなかったことを意味し、合格とは決して同じではありません。checks には個々の結果がすべて含まれます。終了コードは3つの出力モードすべてで同じです。

arxiv HTTP 429, cs/physics routing skipped。 arXiv はレート制限が厳しく（クライアントはすでに1リクエスト／3秒を守っています）、負荷が高いと 429 を返します。これは失敗ではなく WARN です。cs のスキャンは OpenAlex と Semantic Scholar にフォールバックします。どちらにも arXiv のプレプリントが含まれるため、失われるのは当日の掲載情報と1つの出所シグナルであり、カバレッジではありません。新しさが重要な場合は、後で再実行してください。ソースごとのクエリ数と失敗は、manifest.json の retrieval.per_source に記録されます。

Semantic Scholar のバックログ。 キューが混雑していると、S2 は 429／503 を返します。http.py は再試行した後、例外を発生させずに最後のレスポンスを返します。不正なステータスもデータとして扱われます。グラフ展開は OpenAlex の ID のみの参照リストにフォールバックします。これは機能しますが、順位付けはできません（順位付けには参照ごとにメタデータを取得するコストがかかるためです）。そのため、展開時の再現率が低下します。expansion.log.jsonl には呼び出しごとの記録が残ります。

ステージが 2 で終了する。 エージェントが作成したファイルの検証に失敗しました。エラーには問題のあるパスがすべて列挙されます。未知のキーはどこでも拒否されるため、タイプミスは握りつぶされずに表面化します。ファイルを修正して、そのステージを再実行してください。

research-scan mcp がサーバーをインポートできない。 fastmcp は中核的な依存関係です。そのため、これはオプションが不足しているのではなく、インストールが不完全であることを意味します。uv tool install research-scan で再インストールしてください。正常なインストールでは、research-scan version --json が "mcp": "enabled" を報告します。

シェル補完

eval "$(research-scan completion bash)"   # add to ~/.bashrc
eval "$(research-scan completion zsh)"    # add to ~/.zshrc
research-scan completion fish > ~/.config/fish/completions/research-scan.fish

開発

git clone https://github.com/Synectic-Research/research-scan
cd research-scan
uv sync
uv run ruff check && uv run pytest -q     # the before-commit gate
uv run pytest -m live                     # the only tests that touch the network
uv tool install --editable .              # put research-scan on PATH, tracking the working tree

src/research_scan/schema.pyが信頼できる唯一の情報源です。JSON Schema、エージェントが読む仕様ドキュメント（skills/research-scan/references/schemas.md — 同じコミット内で再生成してください。テストで両者を比較します）、および終了コード2のエラーメッセージを生成します。

AGENTS.mdには運用方針が、docs/measurements.mdには現在のデフォルト設定の根拠となる測定結果が記載されています。また、eval/にはゴールデンセットのハーネス（research-scan eval --topic <t> --run <dir>）があります。

drivers/には、認知エンジンの実験的なリファレンス実装が含まれています。これは、スキャンに必要な判断を生成するコードで、ホスティングエージェント以外のものを使って動かしたい人向けです。これらはリポジトリ内にのみ存在します。パッケージによってインストールまたはインポートされることも、sdistやwheelに含まれることもありません。また、このリリースにはエンジンプロトコルは含まれていません。

ドキュメント · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md · CODE_OF_CONDUCT.md · CITATION.cff · LICENSE（Apache-2.0）

依存関係にはそれぞれ独自のライセンスがあります。THIRD_PARTY_LICENSES.mdに、各ライセンスの内容と表の再生成方法が記載されています。