gh-shoulders

gh-shoulders — 站在開源巨hub的肩上

總覽

設計系統之前，先看開源世界怎麼解這個問題。 憑既有知識直接設計會錯過兩種東西：別人已經驗證可行的做法，以及別人已經遇過、你還沒遇到的問題。

這個 skill 只負責找到類似的開源作法、讀懂它們，然後產出一份調查報告。規劃與實作仍然走你原本的流程。

Step 0：適用性判斷

先做這一步，但不要在這裡卡住。判斷不出來就當成適用，繼續往下走——多查一輪的成本遠低於漏掉一個現成方案。

從需求裡抽出通用成分：把公司或專案專屬的部分剝掉之後，剩下的問題是不是開源世界也會遇到的？

• 「會員積分排行榜」→ 剝掉業務規則之後是「排行榜 + 定時結算」→ 通用，要調查
• 「在後台設定檔新增一筆分店資料」→ 純內部設定資料 → 不適用
• 「串接公司內部 ERP 的簽核 API」→ 專有協定 → 不適用。但如果需求裡含「token 快取與刷新」這類通用子問題，就只調查那個子問題

不適用時回報一句「此需求為內部領域邏輯，跳過先例調查」，直接回到原本的規劃流程。

不要為了省事把通用問題判成內部邏輯。 判斷依據是「開源世界可能有沒有」，不是「這是不是公司需求」。

Step 1：環境偵測

依序偵測可用的搜尋管道，以第一個可用的為主力，其餘當補充：

順位	管道	偵測方式
1	gh CLI（已登入）	gh auth status 成功
2	GitHub REST API（未認證）	curl 可用（搜尋 API 限每分鐘 10 次，加延遲）
3	網頁搜尋	你的環境有 web search 能力

不要只用一個管道。不同管道搜出來的結果重疊度比想像中低——GitHub 搜尋看得到 topic 與程式碼，網頁搜尋看得到部落格與比較文章，只靠一邊會整類漏掉。

用順位 2 之前先查剩餘額度（curl -s https://api.github.com/rate_limit）。額度不多時把呼叫留給 repo 搜尋，因為那一次就能拿回整批 metadata；其餘改用 git clone 加本地 grep，那條路不吃額度。

Step 2：關鍵字展開

先把搜尋詞彙列出來，再開始搜。邊搜邊想關鍵字會有兩個後果：你一直用自己的用詞打轉，搜不到社群實際在用的說法；而且搜過哪些詞沒有紀錄，最後分不出來是「沒有人做過」還是「你沒搜到」。

1. 分四類列詞，每類中英文都要：
   • 領域詞（如：遊戲、即時）
   • 能力詞（如：排行榜 / leaderboard / ranking）
   • 技術詞（如：redis sorted set / zset）
   • 生態系錨點（你已知的相關函式庫名，如 redis-py）
2. 詞彙探測：先搜 awesome <領域> 清單、看 2–3 個明顯相關 repo 的 topic tags，學社群的行話再回頭補詞。你說「限時排行榜」，社群說 "leaderboard"、"tournament ranking"，用你的詞搜不到他們的專案。
3. 負面詞：對有歧義的詞列出排除詞，GitHub 語法用 -term（如 ranking -seo），不支援 NOT。

Step 3：廣搜（列 5–10 個候選）

先廣後窄，多個管道並用。star 數只用來排序，不用來排除——小而精準的 repo 常比大專案更值得參考。

同一個專案的 fork 與 mirror 算一個發現，不要重複計數，否則會誤判成「很多人都這樣做」。

# gh CLI（首選）
gh search repos "leaderboard redis" --language python --sort stars \
  --limit 20 --json fullName,description,stargazersCount,updatedAt,license
gh search code "zadd leaderboard" --language python --limit 20

# curl fallback（未認證，注意速率）
curl -s "https://api.github.com/search/repositories?q=leaderboard+redis+language:python&sort=stars&per_page=20"

管道至少涵蓋：GitHub repo 搜尋、GitHub code 搜尋（僅順位 1 可用；未登入就 clone 候選後本地 grep）、awesome 清單、以及可用時用網頁搜尋補「<主題> open source alternatives」。