Shambhavagrawal/rotless-github-research

GitHub リサーチ

ユーザーのトピックや質問に関連する、あらゆるリポジトリと抽出可能なコンポーネントを見つけます: $ARGUMENTS （Claude Code がこの変数を入力します。他のエージェントでは、ユーザーのリクエストになります）

リテラルキーワード検索はニッチなトピックでは失敗します。開発者はリポジトリに、コンセプトではなく「触れるもの」（Webサイト、API、組織、ライブラリ）にちなんだ名前を付けます。あらゆる実装に含まれているはずの成果物を、コード、リポジトリ、コミット、Issue、他のホスト、ウェブといった複数の方向から検索し、すべてのヒットを確認し、候補を再利用可能な部品に分解して、ターゲットとするソリューションに組み込みます。

rotless ファミリー

rotless の一部であり、単体でも完全に使用可能です。このリサーチがスキルの先行技術である場合、呼び出し元はファイルとその形式（prior-art.md。rotless-skill-modernizer によって定義されます）を指定します。レポートはその形式でそこに作成します。呼び出し元: rotless-skill-creator（ステップ0、ビルド前）、rotless-skill-modernizer（置き換えられたツールの fix、ランドスケープ全体の refresh）、rotless-skill-refiner（「より良い方法」の教訓を、採用前に既存のものと照合するため）

ツールボックス

ヘルパーはこのスキルの scripts/ フォルダにあります。S にそのフォルダの絶対パスを一度だけ設定します（このスキルのベースディレクトリからの相対パス。この SKILL.md を含むフォルダです。Claude Code はスキル読み込み時に "Base directory for this skill: …" として表示します）。そして、常に $S を介してヘルパーを呼び出します（カレントワーキングディレクトリはユーザーのプロジェクトです）。-h でフラグを一覧表示します。python3（Windows の場合は python）を使用します。GitHub 以外のエンドポイントは references/sources.md（同じフォルダ）にあります。PowerShell よりも POSIX シェル（bash、Windows の場合は Git Bash）を推奨します（-、!、jq の引用が原因）。sarkari/UPSC の例は説明目的のみです。

ツール	検索対象	最適な用途
grepapp.py（grep MCP がインストールされていれば searchGitHub ツールと同じ）	ファイル内容、約100万の人気リポジトリ、正規表現、認証不要	ハードコードされたドメイン、インポート行、設定キー
gh api -X GET search/code -f q='…'	ファイル内容、GitHub のレガシーインデックス（より多くのリポジトリ、正規表現は不可）	第2のコードソース。path:/filename: シグネチャ
ghsweep.py	リポジトリ名/説明/README/トピック、多数のクエリ、重複排除	幅広い検索。総数、共通トピック、[noise?] タグ
gh search commits …	コミットメッセージ	名前や README に何も書かれていないリポジトリ
gh search issues … --include-prs	Issue/PR テキスト	リポジトリ + 実際の課題（特定のフレーズが必要。一般的な単語はボットの Issue に埋もれる）
ghverify.py	GraphQL バッチ、25リポジトリ/コール	存在確認、名前変更、実際のアクティビティ、健全性、証拠、警告フラグ
gh repo read-dir / read-file、gh api …/contents	1つのリポジトリのファイル、クローン不要	実際のコードの確認
srcsweep.py	npm、crates、Packagist、Hex、NuGet、Maven、RubyGems、Hackage、Docker Hub、ArtifactHub、AUR、Open VSX、GitLab、Codeberg、MCP Registry、skills.sh、Hugging Face（モデル/データセット/スペース/ペーパー、ペーパーがリンクするコードリポジトリを含む）、Hacker News の21の非GitHubソースを並列検索	GitHub 外の先行技術。最後に検索したソース/到達しなかったソースの台帳を出力。--repos で GitHub リポジトリを ghverify.py - にパイプ
references/sources.md	エンドポイントノート + 検索APIのないソース（PyPI、Homebrew、pkg.go.dev、Product Hunt、Reddit）	手動フォローアップ

重要な gh search ルール（テスト済み。無視すると黙って [] または間違った結果が返ります）

• 引用: gh search <kind> "two words" = 完全一致フレーズ。AND の場合は引用符なしで単語を渡します。OR は引用符なしで機能します。
• 重要なものには Raw API を使用します（完全な構文 + total_count）: gh api -X GET search/{repositories|code|commits|issues} -f q='<query>' -f per_page=100 --cache 1h
• リポジトリ検索ではすべての単語が一致する必要があります。そのため、各クエリは2〜3単語に抑え、用語を1つのクエリに詰め込むのではなく、表現を変えてください。スイープで5件未満のリポジトリしか返ってこない場合は、クエリを短くしてください。
• 除外: NOT word を含む単語、-qualifier:value を含む修飾子。-word は0を返します。gh search では、-- の後に除外を配置します。
• API 経由のコード検索 = レガシーエンジン: 正規表現は不可。OR/NOT、path:、filename:、extension:、language: は機能します。デフォルトブランチのみ。大きなファイルはスキップされます。正規表現には grep.app を使用してください。
• クエリごとの結果上限は1000件です。 大きな結果セットは分割します: created:A..B、pushed:>DATE、スター帯域 stars:0..24、stars:25..99、stars:100..499（これにより人気の低いものも発見できます）、language:。
• レート制限: 検索は30/分。コード検索は10/分（gh skill search と共有）。GraphQL は5000ポイント/時。確認: gh api rate_limit --jq '.resources | {search: .search.remaining, code: .code_search.remaining, graphql: .graphql.remaining}'。繰り返し呼び出す場合は --cache 1h を使用。コード検索が枯渇した場合は、スリープする代わりにベクターを切り替えます。
• プライバシー: 認証済み検索は、アカウントが閲覧可能なプライベートリポジトリを返します。それらを決して報告しないでください。jq に select(.repository.private == false)（コード）/ select(.private == false)（リポジトリ）を追加します。ghsweep.py はこれらをフィルタリングします。ユーザーのプライベート/インターナルリポジトリ名を検索クエリに絶対に入れないでください。
• gh repo read-file / read-dir / gh discussion / gh skill を使用するには、新しい gh（テスト済み 2.103）が必要です。古い場合は、ステップ3の gh api フォールバックを使用するか、winget upgrade GitHub.cli / brew upgrade gh を提案してください。

ステップ 0 — ブリーフ（短いブロック1つ。本当にあいまいな場合を除き、ラウンドトリップは不要）

以下を記述します: ゴール · ターゲットソリューションの分割（モジュール化されたサブ問題。例: 認証/セッション、スクレイパー/パーサー、正規化/スキーマ、ストレージ、API/インターフェース — 何をどこから活用できるかを特定するため）· 必須要件 · あるとよいもの · アンチパターン（例: 薄いラッパー、放棄、有料APIが必要、GPUのみ）· 制約事項（言語、オフライン…: これらは合格/不合格のチェックであり、検索語ではありません）· カットオフ日（絶対日付。「最近」→ pushed:>2025-10-24）· 労力: クイックパス（安価で、元に戻せる選択: 約10クエリ、上位5件）またはフルメソッド（先行技術/ビルドvsバイ/ブレンドの場合のデフォルト）。 リクエストが「Xの代替 / Xのようなもの / Xのクローン」の場合は、まず X を解決してそのリポジトリを特定し、そこから（そのトピック、README、依存関係から）種をまきます。 最初にローカルをチェックします（無料、10秒）: 既にインストールされているもので答えられるかもしれません。エージェントがロードするスキルフォルダ（プロジェクトおよびユーザーレベル: .agents/skills/、.claude/skills/、~/.codex/skills/…）、その MCP サーバーリスト（例: claude mcp list）、gh extension list を確認します。世界を検索する前にヒットを報告します。

ステップ 1 — トピックの特徴付け

15〜30の具体的な検索語を記述します:

1. タッチポイント — あらゆる実装がアクセスしなければならないドメイン、URL、APIエンドポイント、ホスト名、RSSパス、アプリID。
2. コードシグネチャ — インポート行、SDKクラス/関数名、環境変数、設定キー、CSSセレクター、特徴的な定数。
3. 複数の視点からの語彙 — ビルダー、エンドユーザー、アカデミック、インフラストラクチャ、そしておそらく最初に解決したであろう隣接分野。地域的な用語/非英語用語、略語、スペルミス。曖昧な単語には補助用語が必要です（agent + llm。単なる agent ではありません）。
4. 形状 — ボット、スクレイパー、API、CLI、ライブラリ、拡張機能、MCPサーバー、エージェントスキル、データセット、モデル、GitHub Action。およびそれらのファイルシグネチャ（.github/workflows cron、manifest.json、SKILL.md、.claude-plugin/marketplace.json）。エージェントスキルとプラグインは、多くの場合、より大きなリポジトリ内に存在します（80k★のモノレポ内の skills/x/SKILL.md）。リポジトリ検索では見えません。コード検索 filename:SKILL.md "<descriptionのフレーズ>" でそれらを見つけます（ノイズが多い: 数百から数千のヒットがあるため、特徴的なフレーズを2つ使用し、2〜3ページスキャンします）。および skills.sh（srcsweep.py --sources skills。セマンティックで、スキルの目的よりも名前でうまく機能します）。スキルの検索は最も弱いベクトルです。アンカースキルが決して見つからない場合は、その名前を直接検索し、カバレッジノートでそのように述べてください。
5. アンカー — 優れた回答に含まれるであろう、よく知られた3〜10のプロジェクト/製品。ステップ2でリコールチェックとして使用します。
6. 理想のREADME段落 — 完璧なリポジトリを説明する2文。その作成者が書くであろう方法で書き、そこから検索語を抽出します。

ステップ 2 — あらゆるベクターでの検索

ベクターを並列実行します。各リポジトリが見つかったクエリを記録します（found_by: より多くのクエリ = より強い関連性）。

A. コード検索（最もシグナルが強い）。 多数の狭いクエリ。タッチポイント/シグネチャごとに1つ:

S="<このスキルのベースディレクトリ>/scripts"     # 例: S="$HOME/.agents/skills/rotless-github-research/scripts" (Claude Code では ~/.claude/skills/…)
python "$S/grepapp.py" "sarkariresult.com" --repos-only
python "$S/grepapp.py" "(sarkariresult|freejobalert)\.com" --regex --lang Python --lang JavaScript --repos-only
python "$S/grepapp.py" "upsc.gov.in" --path .github/workflows/ --repos-only          # スケジュールされたボット
github api -X GET search/code -f q='sarkariresult OR freejobalert language:python' -f per_page=100 \
  --jq '"total \(.total_count)", (.items[] | select(.repository.private == false) | "\(.repository.full_name)\t\(.path)")'

grep.app はクエリあたり約10ファイルを返し、広範な正規表現では504エラーになります。稀なリテラルにアンカーを設定し、--lang/--path を追加します。ノイズを削除します: クロールされたURLデータセット、広告ブロックリスト、用語が一度だけ出現するモノレポ。

B. リポジトリ検索（幅 + ランドスケープサイズ）。

python "$S/ghsweep.py" --pushed ">2024-01-01" --order hits "sarkari OR naukri NOT resume" "freejobalert" "topic:government-jobs"
python "$S/ghsweep.py" --sort stars "topic:sarkari-result"      # 説明が一般的な単語をスキップするフラッグシップ
python "$S/ghsweep.py" --sort updated "sarkari scraper"         # ベストマッチに埋もれた新しい作業
python "$S/ghsweep.py" --must "scrap|crawl|alert|job" --exclude "resume|linkedin" "sarkari OR naukri"   # 関連性フィルター。同音異義語（「prior art」= 特許）は、そうしないと結果に殺到します
github api -X GET search/topics -f q=sarkari --jq '.items[].name'   # トピックスラッグを発見

ghsweep.py は総数（分野の混雑度）、最も一般的なトピック（→ 次のクエリ。また、上位2以上のヒットで共有されるトピックのペアも試してください: topic:a topic:b）、および [noise?] タグ（チュートリアル/テンプレート/デモ/dotfiles/awesome: 格下げしますが、自動削除はしません）を出力します。古さを問わない先行技術の場合は --pushed を削除します。

C. コミット検索: gh search commits sarkariresult --limit 50 --json repository,commit --jq '.[] | "\(.repository.fullName)\t\(.commit.message | split("\n")[0])"'

D. Issue/PR 検索: gh search issues "freejobalert" --include-prs --limit 50 --json repository,title,url（特定のフレーズのみ）。

E. ベストヒットからのスノーボール（上位3〜5）:

• ラップされた依存関係を追跡: ヒットがXを「ラップ」、「上に構築」、または「使用」している場合、Xも調査します。多くの場合、それが本当の現職者です。最もよくある、早すぎる停止ポイントです。
• Awesome リスト: python "$S/ghsweep.py" --sort stars "awesome <kw> in:name"。200★以上の awesome-* リストを取得し、そのリポジトリリンクを抽出し（gh repo read-file README.md --repo o/awesome-x | grep -oE 'github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+' | sort -u）、ghverify.py - にパイプします。リストに載っていることは、ソフトな品質シグナルです。
• 類似リポジトリ: トップヒットのトピック + 言語 → topic:a topic:b language:x。同程度のスター層を優先します。
• READMEの「代替品 / 類似品 / インスパイア元 / クレジット」セクション。特徴的なコード文字列 → grep.app（コピーとポートを見つけます）。著者の他のリポジトリ（gh repo list <owner> --limit 100）。独自の作業を含むフォーク（gh api "repos/o/r/forks?per_page=100" --jq '.[] | select(.pushed_at > .created_at) | .full_name'）。Webフェッチツールまたは curl（github.com/o/r/network/dependents）を介したライブラリ依存関係ページ。

F. GitHub 外: 1つのコマンド。いくつかの表現（各1〜3単語。レジストリと用語の両方）:

python "$S/srcsweep.py" "repository discovery" --limit 4        # 21ソース、約10秒。検索済み / NOT REACHED 台帳で終了
python "$S/srcsweep.py" "sarkari" --repos | python "$S/ghverify.py" -   # 結果からリンクされたGitHubリポジトリを検証

次に、検索APIのないもの（PyPI site:pypi.org、Homebrew、pkg.go.dev、Product Hunt、Reddit、ブログ、awesome <topic>）にはウェブ検索を使用します。先行技術/競合調査では、注目すべき商用製品もリストアップします。非GitHubヒット（GitLab、Codeberg、レジストリのみ）は ghverify.py を通過できません。手動でチェックし、証拠を Documented/Metadata としてマークします。

停止とリコール。 新しいクエリが主に既知のリポジトリを返すようになったら停止します。ただし、同じリポジトリを返す3つのクエリは、極小値であり、カバレッジではありません。ステップ1のアンカーをチェックします。検索で浮上しなかったアンカーは、語彙のギャップを意味します。そのアンカーが使用する単語を見つけ、それらを検索します。結果がゼロということは「このルートでは見えない」という意味であり、「存在しない」という意味ではありません。結論を出す前に、言い換えるかルートを1回変更します。

ステップ 3 — 検証と評価

すべての候補は ghverify.py を通過します（架空の名前は NOT FOUND と表示され、名前が変更されたものは現在の名前が表示されます）:

python "$S/ghverify.py" owner/repo https://github.com/o2/r2 ...      # または: ... | python "$S/ghverify.py" -

そのカラムを読みます: 最終実質コミット（bump/chore/deps/merge/typo/docs は無視。pushedAt ではありません）;Issue解決率;マージされたPR;人数;組織/ユーザー;リリース/年;証拠（テスト、CI、マニフェスト、security.md。NONE = READMEのみ。しっかり検証）。フラグ !velocity（>100★/日: バイラルまたは購入。コンテキストが必要）、!lowfork（≥1000★、フォーク/スター < 0.005）、new（<14日）、stale Ny（2年以上実質コミットなし:フラグされますが、決して格下げはされません: 放棄されたツールでも、アイデアが構築されたことを証明します）、noise?。

次に、報告するすべてのリポジトリについて実際のコードを確認します（README は両方の方法で嘘をつきます）。証拠をコミットに固定します:

sha=$(gh api repos/o/r/commits/HEAD --jq .sha)
gh repo read-dir src --repo o/r --ref $sha                    # JSON: --json name,type --jq '.entries[]'
gh repo read-file path/to/main.py --repo o/r --ref $sha       # フォールバック: gh api "repos/o/r/contents/PATH?ref=$sha" -H "Accept: application/vnd.github.raw"
gh api "repos/o/r/git/trees/$sha?recursive=1" --jq '"\(.tree|length) files", (.tree[:80][] | .path)'

ブランチリンクではなく、パーマリンク https://github.com/o/r/blob/<sha>/<path>#L10-L40 を引用します。

• 適合性と抽出可能性: strong / partial / weak / off_target。リストアップ...

（翻訳のため省略）