maxgfr/ultradoc

ultradoc — 記憶ではなく、ソースから答えを導く

ultradoc は、オープンソースプロジェクトに関する超高精度な質問に対して、根拠となるエビデンスを取得し、そのエビデンスに基づいて推論することで回答します。決定論的なエンジン（scripts/ultradoc.mjs、依存関係ゼロのNode.jsスクリプト）が検索とインデックス作成をコードで行います。あなたの役割は、取得されたエビデンスを読み、精密で引用された回答を書くことです。すべての主張は実際のソースを指している必要があります。これは強制されます：ultradoc check は、引用が取得されたエビデンスに解決できない場合に失敗します。

核心ルール： あなた自身のライブラリに関する知識から回答しないでください。あなたの訓練データは古く、APIを幻覚します。ultradoc が実際のリポジトリ、Issue、PR、ドキュメント、Webから取得したエビデンスのみから回答してください。エビデンスがカバーしていない場合は、その旨を伝え、さらに取得してください。決して推測しないでください。

スクリプト

コミットされた、依存関係のないバンドル：node scripts/ultradoc.mjs <command>。 npm install もAPIキーも不要です。すべての機能については --help を実行してください。主要なコマンド：

• ask --repo <url|path> --q "<質問>" [--sources ...] [--package <p>] [--semantic] [--docs-url <u>] クローン（任意のgit URL、/tmp/ultradoc/<slug> にキャッシュ）、インデックス作成、選択されたすべてのソースからの取得を行い、エビデンス資料（EVIDENCE.md、evidence.json、meta.json）を実行フォルダに書き込みます。これは、--out を渡さない限り、クローン先の <clone>/.ultradoc/runs/<id> の下に保存されます（コミットに固定された安定したホームで、複数の質問間で再利用されます）。デフォルトのソースは： code,issues,prs,docs（リポジトリだけでは答えられない場合は web,so を追加；「Xが追加/変更されたのはいつか」という質問には releases,history を追加；コミュニティのQ&Aには discussions を追加（gh CLIが必要））。 モノレポの場合、--package <name|dir> でコード/ドキュメントの取得を1つのワークスペースパッケージにスコープします。
• code|issues|prs|docs|releases|history|discussions|so --repo <...> --q "..." — 1つのソースに絞り込み、エビデンスをstdoutに出力します（資料は作成しません）。薄い領域を拡張するために使用します。history はクローン上でgitのpickaxe（log -S/-G）を実行します — リモートリポジトリへの最初の呼び出しでは、全履歴を1回だけ取得します。
• web --repo <...> [--q "..."] [--url <u,...>] — キーレスなWeb発見（SearXNG → DuckDuckGo → あなたのWebSearch）+ 取得/抽出。--url を渡すと、あなた自身のWebSearchで見つけた特定のページに根拠を定めます。
• overview --repo <...> [--refresh] — リポジトリのキャッシュされたマークダウンダイジェストを（1回だけ）生成します：それが何か、ワークスペースパッケージ、レイアウト、公開API、ドキュメントマップ。クローンの隣にキャッシュされ、コミットが変更されていない限り再利用されます — 再インデックスせずに複数の質問にわたって方向性を定めるために読んでください。これはナビゲーションマップであり、引用可能なエビデースではありません。
• doc --repo <...> [--package <p>] [--sources ...] — 根拠のあるリファレンスドキュメントの骨組みを作成します：決定論的なセクション概要（概要、インストール、公開API/パッケージごと、設定、アーキテクチャ）、セクションごとに1つの取得された資料を1つの evidence.json にマージしたもの、および DOC.todo.md の作業リスト。あなたは引用された散文を DOC.md に書き込みます；check はそれを回答と同じように検証します。<clone>/.ultradoc/doc/ の下に保存されます。以下の「ドキュメントの生成」を参照してください。
• check --run <dossier-dir> — ANSWER.md（または doc 実行の DOC.md）の引用をダッシュボードの evidence.json に対して検証します。ゼロ以外で終了 ⇒ 根拠なし。--answer <file> は特定のファイルを検証します。
• index --repo <...> — 構造インデックスを構築/表示します（デバッグ/検査）；モノレポの検出されたワークスペースパッケージをリストします。
• semantic up|down|status — オプションのローカルベクトルバックエンド（以下参照）。

ワークフロー

あなたはこのタスクをエンドツーエンドで担当します：1つの根拠のある引用付きの回答を返し、決して半分だけ取得された資料を返さないでください。しかし、取得と検証の作業は独立した、ほぼコストのかからない呼び出しです — あなたのハーネスが可能であれば並列化してください（1つのメッセージで独立したドリルをバッチ処理；利用可能であればサブエージェントまたはワークフローにファンアウト）。それ以外の場合はインラインで行ってください。エビデンスが完了するまでラウンドを繰り返してください；完了するまでは返さないでください。references/orchestration.md を参照してください。

1. ターゲットを特定する。 プロジェクトと正確な質問を特定します。名前しかない場合は、正規のリポジトリURLを見つけてください（WebSearchを使用するか、あいまいな場合はユーザーに尋ねてください）。ユーザーが気にするバージョン/ブランチがあれば注意してください（--ref）。

   同じリポジトリに関する複数の質問？ overview --repo <url> を1回実行し、キャッシュされた OVERVIEW.md を読んでください：リポジトリ（パッケージ、レイアウト、公開API、ドキュメント）をマッピングするので、フォローアップの質問は同じクローン+インデックスを再利用でき、ゼロから方向性を定める必要がありません。エビデンスとして引用しないでください — ナビゲーションであり、エビデンスではありません。

   モノレポ？ ask/index/overview がワークスペースパッケージを報告した場合（例：socialgouv/code-du-travail-numerique → @cdt/frontend、@socialgouv/modeles-social、…）、名前/ディレクトリが質問対象のサブシステムと一致するパッケージを選択し、--package <name|dir> を追加して、他のパッケージに検索が埋もれないようにします。パッケージ名が明らかに一致しない場合は、最初にスコープなしで ask を1回実行し、上位のヒットがどのパッケージに集中しているかを確認してから、そのパッケージにスコープして再実行します。未知のパッケージ名はエラーで失敗し、存在するものをリストします。

2. 取得する。 まず、開発者のように考え、質問に対して2〜3のクエリバリアントを導き出します — エンジンは文字通り検索するため、言い回しが重要です：

   • 自然言語の言い回し（「リトライバックオフ」）、
   • コードベースでおそらく使用されている識別子形式（retryBackoff、retry_backoff、MAX_RETRIES）、
   • ユーザーが引用した場合は、リテラルなエラーメッセージ、オプション、またはフラグ名。

   マルチパートの質問？ 今すぐサブ質問に分割してください — それぞれに独自のエビデンスが必要か、最後に明示的な「不明」が必要です。サブ質問ごとにカバレッジを追跡してください。

   エンジンはすでに複数形とアクセント（「retries」/「retry」、「délai」/「delai」）を畳み込み、識別子をサブトークンに分割し、キーワードにちなんで名付けられたファイルをブーストします — したがって、バリアントは同じ単語の語形変化ではなく、同義語と識別子（「heartbeat」対 ping、「pool」対 connectionLimit）に費やしてください。また、字句検索が薄くなる時を認識してください：リポジトリに文字通り現れる単語が必要です。概念的な質問や「なぜこのように設計されたのか」という質問には、code が答えを運ぶことを期待する代わりに、docs、discussions、web（または --semantic）を先に使用してください。

   最適なバリアントと適切なソースを使用して ask を実行します：

   node scripts/ultradoc.mjs ask --repo <url> --q "<正確な質問>" --sources code,issues,prs,docs
   

   ultradocは、プロジェクトの公式ドキュメントURLを自身のREADME/マニフェストから自動的に発見し（リポジトリ内の正規の docs/ ツリーを優先）、それに基づいて根拠を定めます — 上書きする場合のみ --docs-url <url> を渡してください。質問が概念的であるかリポジトリがまばらな場合は web,so を追加；何かが変更された時期/理由/どのバージョンに関する質問の場合は releases,history を追加します。コマンドはダッシュボードのパスを出力します。次に、残りのバリアント × ドリルソースをファンアウトとして扱います — それらの独立したドリルを1つのメッセージで並列呼び出しとして発行します（またはセルごとに1つのサブエージェント）。references/orchestration.md を参照してください。

3. ダッシュボードを読む。 実行フォルダ内の EVIDENCE.md を開きます。各アイテムにはID（[E1]、[E2]、…）、出典 ref、およびスニペットがあります。これがあなたのエビデンスです — 実際のコード/Issue/PR/ドキュメントのテキストを読んでください。

4. ギャップを掘り下げる。 サブ質問は、トピックに関するアイテムが約2つ未満の場合、または質問されたシンボル/動作を実際に含むアイテムがない場合に薄いと見なされます。ダッシュボードが薄く見えるまでバリアントドリルを待たないでください — 最初からバリアントドリルを並行して実行してください（ドリルはほぼ無料：クローンとインデックスはキャッシュされています）。それらをソース全体にファンアウトします：

   • code --repo <...> --q "<シンボルまたは動作>" でさらにコード領域を取得。
   • issues/prs で関連する議論と進行中の変更を読む。
   • releases（変更ログ + リリースノート）と history（git pickaxe）は、質問が何かが変更された時期/理由/どのバージョンに関する場合。
   • discussions はコミュニティのQ&Aと設計スレッド用（gh CLIが必要）。
   • web（またはあなたのWebSearch → web --url <u>）は外部参照用。 繰り返し方法については references/retrieval-playbook.md を、並行してドリルを実行する方法については references/orchestration.md を参照してください。

   作成前にトリアージする。 取得は再現性指向であるため、ダッシュボードにはキーワードを共有するだけのトピック外のアイテムが含まれます。テスト：アイテムのスニペットが質問されたシンボル/動作を命名しているか、同じメカニズムを説明している場合のみ、そのアイテムは質問に関係します — キーワードを共有するだけでは不十分です。どのエビデンスIDがそのテストを通過するかをリストし、残りは無視します — トピック外のアイテムは、存在するという理由だけで引用してはいけません。トリアージ後にコアとなる主張をサポートするアイテムが約2つ未満の場合は、戻ってさらに取得してください。

   再読み込みではなく再クエリ。 上位3つのコードアイテムがトピック外の場合、リストを読み続けないでください — 手順2からの次の識別子のようなバリアントで code --q を再実行してください。連続する2つのトピック外のダッシュボードは、言い回しが間違っていることを意味し、リポジトリに答えがないということではありません。

   枯渇するまでループ。 ラウンドでドリルします（最大約3回）。ラウンドで新しいトピック内エビデンスが表面化しなくなった場合、またはすべてのサブ質問に2つ以上のサポートアイテムがある場合に停止します — その後トリアージして書き込みます。上限後もサポートされていないサブ質問は明示的に不明とし、決して記憶から埋めません。

5. 回答を書く。 同じ実行フォルダに ANSWER.md を作成します。正確かつ簡潔にしてください。すべての事実的主張を引用し、それが基づくエビデンスIDを示します。例：リトライはジッター付きの指数バックオフを使用します [E1]、そしてPR #79はこれを書き換えています [E7]。references/citation-format.md を参照してください。バージョンが重要な場合は、meta.json に示されているコミットに回答を固定してください。手順2からのすべてのサブ質問をカバーします；エビデンスが確定しないものは明示的に不明としてフラグを立てます — 記憶から埋めないでください。

6. 検証（2層）。

   • 構造的： node scripts/ultradoc.mjs check --run <dossier-dir>。エビデンスに解決できない引用がある場合、または引用のない回答がある場合に失敗します。修正して再実行し、パスするまで続けます。
   • 意味的（敵対的サポートチェック）： node scripts/ultradoc.mjs verify --run <dossier-dir> は、主張↔エビデンスの作業リスト（VERIFY.todo.json + VERIFY.md）を書き込みます。各ペアを懐疑論者として判断します：引用されたスニペットが文字通り主張を裏付けない限り、デフォルトで unsupported/refuted とし、verdict を supported · partial · refuted · unsupported に設定します（短いメモ付き）。ペアごとに1人の懐疑論者を実行します — 利用可能な場合はサブエージェントにファンアウトします（各エージェントは自身の判定を返します）、それ以外の場合は各ペアをインラインで判断します — そしてすべての判定を1つの verdicts.json に収集します（references/orchestration.md を参照）、その後：

   node scripts/ultradoc.mjs verify --apply verdicts.json --run <dossier-dir>
   node scripts/ultradoc.mjs check  --semantic --run <dossier-dir>
   

   これにより、未解決/未ソース（構造的）および反証またはサポートされていない主張がある場合に失敗します — 引用が解決されるが、実際には主張を裏付けないギャップを閉じます。主張を修正し（再引用、弱める、削除する、またはより良いアイテムを取得する）、パスするまで再検証します。また、references/answer-rubric.md に対して自己レビューし、完全性/最新性/不明点を確認します。

7. 提示する。 根拠のある回答を、その引用とリンク（ファイル:行、Issue/PR番号、エビデンスからのドキュメント/SO/Web URL）、および検証されたコミットとともにユーザーに提供します。

ドキュメントの生成

ユーザーが1つの回答ではなく、プロジェクト全体（またはパッケージ全体）のドキュメントを希望する場合は、doc を使用します — これは同じ根拠のあるループを、セクション概要にファンアウトしたものです：

1. 骨組みを作成する。 node scripts/ultradoc.mjs doc --repo <url> [--package <p>]。エンジンは決定論的なアウトライン（概要、インストール/使用法、公開APIまたはワークスペースパッケージごとに1つのセクション、設定、アーキテクチャ）を構築し、セクションごとに資料を取得し、それらを1つの evidence.json にグローバルな [E#] ID でマージし、DOC.todo.md（セクションごとの作業リスト）+ DOC.plan.json を書き込みます。--sources code,docs,issues,prs を追加して、コード+ドキュメント以外にもセクションを根拠付けます。<clone>/.ultradoc/doc/ の下に保存されます。
2. 各セクションを書く。 DOC.todo.md と EVIDENCE.md を読み、実行フォルダに DOC.md を書きます：アウトラインエントリごとに1つのセクション、すべての主張は [E#] で引用。エビデンスが薄いセクションはファンアウトユニットです — それをドリルするか（code|docs|issues …）、またはギャップを明示的に不明とマークします；決して記憶から書きません。セクションごとの作業は並列化されます — references/orchestration.md を参照してください。
3. 検証と提示。 node scripts/ultradoc.mjs check --run <doc-dir>（および verify + check --semantic をサポートゲートとして、手順6とまったく同じです — 両方とも DOC.md を自動検出します）。根拠が定まるまで修正し、その後 DOC.md をそのコミットに固定して提示します。

オプションのセマンティックモード（完全ローカル、APIキー不要）

決定論的Tier-1検索（ripgrep + シンボルインデックス）がデフォルトであり、何も必要としません。より曖昧で概念的な質問には、ローカルセマンティック検索を有効にできます：

node scripts/ultradoc.mjs semantic up      # docker compose: Qdrant + Ollama (+ SearXNG)
node scripts/ultradoc.mjs ask --repo <url> --q "..." --semantic

すべてローカルのDockerコンテナで実行されます — キーもデータがマシンを離れることもありません。スタックが上がっていない場合、--semantic は通知をログに記録し、Tier 1にフォールバックします。references/semantic-setup.md を参照してください。

リファレンス

• references/orchestration.md — 取得ドリルと検証を呼び出し/サブエージェント間で並列化する方法、戻り値と判定アセンブリの契約、および順次フォールバック。
• references/retrieval-playbook.md — ソースを選択し、完全な回答に繰り返す方法。
• references/citation-format.md — check が強制する引用文法。
• references/answer-rubric.md — 提示前の意味的自己レビュー。
• references/provider-apis.md — ホストごとにIssue/PRがどのように取得されるか、キーレス。

…

[翻訳のため省略]