octkp/ba2-docs-search

Docs Search（docs 横断検索）

docs/ 配下に蓄積された全ナレッジを、任意のクエリ（キーワード・人名・トピック・日付・チケット名の一部など）で全ユーザー横断に検索し、出典つきで要約して提示するスキル。

膨大化しても破綻しないよう、「まず安く件数を測る → 量に応じてエージェントで読み込みを並列化する」 という二段構えで動く。

既存スキルとの違い・委譲

| スキル | 入力 | 探す範囲 | |---|---|---| | ba2-ticket-knowledge-reader | BAX-XXXX 番号（既知の前提） | そのチケットの README/LOG/PLAN | | ba2-memo（ワークフローB） | キーワード | 自分の メモ/ だけ | | ba2-docs-search（本スキル） | 任意のクエリ | docs/ 全体（全ユーザー・全カテゴリ・雑記含む） |

• 入力が 純粋な BAX-\d+ 番号だけ（例: 「BAX-10987」「BAX-10325読んで」）なら、本スキルではなく ba2-ticket-knowledge-reader に委譲する（あちらの方が構造を理解して的確に出す）。
• 「BAX-11467 の認可漏れの考え方」のように番号＋自由文なら、本スキルでキーワード検索した方が広く拾える。

検索対象の構造

docs/
  {ユーザー名}/            ← takano / tokita / ushiroyama / yukioka …（全員が対象）
    調査/ 実装/ その他/    ← BAX-XXXX_{名前}/{README,LOG,PLAN}.md
    メモ/                  ← YYYY-MM.md（日付軸メモ）
    レビュー/              ← PR レビュー結果
    雑記/                  ← gitignore・非共有・ローカルのみ（後述）
  {ユーザー名}/*.md         ← 直下に置かれた単発 md もある（例: BAX-5399_*.md）

• docs/.obsidian/ は Obsidian 設定なので常に除外する。
• ディレクトリ構成はユーザーによってまちまち（カテゴリが無い人もいる）。docs/*/ を一律に対象にする。

雑記/ の扱い（重要）

docs/*/雑記/ は .gitignore 対象で共有されないローカル専用メモ。ただし本人にとっては実質的な記録（共有を避けたい私的トピックの退避先）でもある。

• 検索対象に含める。ただしヒットした行・ファイルは必ず 「雑記(非共有)」と明示して提示する（共有メモと混同させない）。
• 他人の 雑記/ はそもそもローカルに存在しない（gitignore で同期されない）ため、実際に当たるのは自分の雑記だけになる。これは正常。

出力先・リポジトリの解決

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -z "$REPO_ROOT" ]; then
  echo "ERROR: ba2-workspace リポ内で実行してください" >&2
  exit 1
fi
DOCS_DIR="$REPO_ROOT/docs"

• 最新の他ユーザー分も拾いたいので、可能なら検索前に軽く最新化する（失敗しても続行）：

  cd "$REPO_ROOT" && git pull --ff-only 2>/dev/null || true
  

ワークフロー

1. クエリを解釈する

ユーザー入力から検索語を取り出す。

• 単一キーワード（「ソニペイ」「DMS」「IDOR」）、人名（「中野さん」→「中野」）、トピック、日付（「5/19」「2026-05」）など。
• 複数語が AND なら「両方含むファイル」、OR なら 語1|語2 のパターンにする（下記コマンド参照）。
• 入力が BAX-\d+ だけなら ba2-ticket-knowledge-reader に委譲して終了。

2. 国勢調査（常に実行・激安）— 本文は読まない

rg で「どのファイルに何件ヒットするか」だけを取る。ここは数千ファイルでもミリ秒。この時点ではファイル本文を読み込まない（コンテキストを汚さない）。

# 候補ファイル一覧（.obsidian は除外。雑記は含める）
rg -l -i --glob '!.obsidian/**' -- "<pattern>" "$DOCS_DIR"

# ファイルごとのヒット件数（多い順の判断材料）
rg -c -i --glob '!.obsidian/**' -- "<pattern>" "$DOCS_DIR" | sort -t: -k2 -nr

# 候補の規模感（ファイル数と概算バイト数）
rg -l -i --glob '!.obsidian/**' -- "<pattern>" "$DOCS_DIR" | wc -l
rg -l -i --glob '!.obsidian/**' -- "<pattern>" "$DOCS_DIR" | xargs -I{} wc -c {} | tail -1

• 複数語 AND：rg -l 語1 ... | xargs rg -l 語2（候補を絞り込む）。
• 複数語 OR：-- "語1|語2"。
• ヒット 0 件なら、表記ゆれ（カタカナ/英字、敬称の有無「中野/中野さん」、BAX- の有無）を変えて 1〜2 回リトライしてから「見つからない」と報告する。

3. 量に応じて戦略を分岐する

重要な原則：重いのは rg ではなく、ヒットした大量ファイルを読み込んで関連性を判断・要約する工程。だからエージェントは「読み込み＋要約の並列化」に使う。

| 規模（目安） | 戦略 | |---|---| | 候補ファイル ≤ 15 かつ 合計 ≤ 約500KB | インライン処理。rg -n -C2 で該当箇所＋前後だけ読み、必要なファイルだけ Read して直接要約。エージェント不要。 | | それ超（候補が多い／大きい／全ユーザーに散在） | Explore エージェントを並列 fan-out（次節） |

迷ったら小規模側（インライン）で始めてよい。途中で「思ったより多い」と分かったらエージェントに切り替える。

4. Explore エージェントの並列 fan-out（大規模時）

候補がヒットしたユーザーディレクトリ単位で Explore サブエージェントを立て、1メッセージ内で複数 Agent 呼び出しして並列実行する（独立タスクなので同時に投げる）。

• パーティション = docs/{ユーザー}/。候補ファイルが 0 のユーザーにはエージェントを立てない。
• 1ユーザー内がさらに膨大なら、そのユーザーだけカテゴリ単位（調査/・実装/・メモ/ …）に再分割する。
• 各エージェントには担当パスとクエリを渡し、該当箇所の抜粋だけを構造化して返させる（ファイル全文を本体に持ち帰らせない）。本体は各エージェントのダイジェストを受け取り、統合・ランキング・要約する。

各エージェントへのプロンプト雛形

あなたは docs ナレッジの横断検索担当。担当範囲だけを調べて結果を返す（要約しすぎず、具体を残す）。

担当パス: docs/{ユーザー}/
クエリ: "<検索語>"

手順:
1. rg -n -i -C2 --glob '!.obsidian/**' -- "<検索語>" docs/{ユーザー}/ でヒット箇所を洗い出す
2. ヒットしたファイルの該当箇所周辺だけ読む（全文は読まない）
3. 各ヒットを以下の形式で返す（最大20件。多ければヒット件数の多い順）:
   - file: 相対パス（例 docs/takano/メモ/2026-05.md）
   - line: 行番号
   - context: 日付見出し / BAX番号 / トピック見出し など、その箇所が何の話か
   - excerpt: 該当部分の1〜2行引用
   - relevance: クエリとどう関係するか一言
   - private: そのファイルが docs/*/雑記/ 配下なら true（非共有メモ）

ヒットが無ければ「該当なし」とだけ返す。

Agent ツールの subagent_type は Explore（読み取り専用・fan-out 検索向き）を使う。

5. 統合して提示する

• 全エージェント（またはインライン）の結果をマージし、関連度の高い順に並べる。
• 出典 path:line を必ず付ける（後から本人が辿れるように）。
• 同じトピックが複数日・複数ファイルに跨る場合は、日付順に経緯（初出 → 進展 → 現状）を時系列でまとめる。
• 雑記(非共有)のヒットは明示ラベルを付ける（例: 📁雑記(非共有) docs/takano/雑記/2026-05.md:12）。
• ヒットが多すぎる場合は上位だけ提示し、「ほかに N 件（ユーザー別内訳）」と省略を明記する（黙って打ち切らない）。

使用例

例1: 小規模（インライン）

ユーザー: 「ソニペイの調査ってどこに書いたっけ」

1. rg -l "ソニペイ" docs → 候補 5 ファイル（小規模）
2. rg -n -C2 "ソニペイ" docs で該当箇所を読む
3. 「docs/takano/調査/BAX-11281_ソニーペイメント調査/ と メモ/2026-05.md:242（5/18 会員削除処理のエラーハンドリング）に記録。結論は…」と出典つきで要約

例2: 大規模（エージェント fan-out）

ユーザー: 「リロクラブ関連の記録、全員分まとめて」

1. rg -c "リロ" docs → 4ユーザー中3ユーザー・40+ファイルに散在（大規模）
2. docs/takano/・docs/ushiroyama/・docs/tokita/ に Explore エージェントを並列で3つ起動
3. 各ダイジェストを統合 →「物理削除（BAX-11462/11482）/ 同期不具合（BAX-11202）/ バッチ化（BAX-11496）」とテーマ別＋時系列で提示。雑記ヒットは別枠で明示

例3: 委譲

ユーザー: 「BAX-10987」→ 番号だけなので ba2-ticket-knowledge-reader に委譲。

注意事項

• 読み取り専用。本スキルは検索・要約だけで、docs を書き換えない（記録は logger / oni-memo、レビューは ba2-review-pr）。
• .obsidian/ は常に除外。雑記/ は含めるが必ず「非共有」と明示する。
• エージェントは「読み込み＋要約の並列化」のために使う。小規模なら使わない（オーバーヘッドの方が大きい）。
• 出典 path:line を省略しない。省略・打ち切りをするときは件数を明記する（黙って切らない）。
• 検索で 0 件のときは表記ゆれを 1〜2 回試してから「無い」と報告する。