giant-shoulders
當使用者要在既有網站、系統或程式專案內新增一項可獨立描述的能力,且應優先搜尋、評估、引用或抽取 GitHub 與套件生態中的成熟實作時,使用此技能。能力可包含 UI 互動、狀態管理、連線方式、通訊協定、驗證授權、資安中介層、資料轉換、演算法、服務轉接器或背景工作。此技能以專案內的能力組件為採用單位;完整 starter、boilerplate 或整套系統選型只有在使用者明確要求時才適用。
SKILL.mdskill/giant-shoulders/SKILL.md
GitHub巨人的肩膀
在既有專案內重用社群已解決的局部能力。GitHub repository、套件與範例專案提供候選來源;實際採用單位是一項邊界清楚、可測試、可替換、可追溯的能力組件。
核心判斷
先區分三個概念:
- 來源容器:repository、套件、範例專案、Gist、技術規格或官方文件。
- 採用單位:目前專案真正需要的單一能力,例如拖曳排序、WebSocket 重連、Rate limiting、輸入驗證或地圖標記聚合。
- 最小完整單位:能完整承擔該能力的最小邊界,包含必要介面、錯誤處理、設定、相依關係與安全不變條件。不要為了減少程式碼行數而切斷必要上下文。
整個 repository 預設只作為搜尋與理解能力實作的來源。使用者明確要求完整 starter、boilerplate、框架或子系統選型時,才評估整體採用。
適用範圍
遇到下列情況時主動使用:
- 使用者要求實作一項常見功能,社群很可能已有成熟組件。
- 使用者要求找現成套件、library、開源程式碼或參考實作。
- 功能涉及特定互動、連線生命週期、協定、驗證、權限、安全控制、資料處理或演算法。
- 使用者要求減少重造輪子,同時保留來源、授權與維護脈絡。
下列情況不套用預設組件重用流程:
- 需求完全由專案獨有的商業規則構成,外部實作無法提供穩定能力邊界。
- 任務只要求產品或專案靈感,沒有程式能力的搜尋、採用或整合需求。
- 使用者指定自行開發且明確排除外部程式碼與依賴。
工作流程
1. 建立能力契約
把需求切成可獨立驗收的能力。每項能力分開搜尋與決策,不把整個產品需求當成單一候選。
能力契約至少包含:
- 要完成的具體行為。
- 輸入、輸出與呼叫者。
- 預計放入的專案邊界。
- 必要條件與可接受差異。
- 失敗、離線、逾時、權限不足或資料異常等情境。
- 技術棧、版本、效能、瀏覽器或部署限制。
- 授權、隱私、資安與維運限制。
- 可證明完成的測試或觀察結果。
需要正式記錄或比較多個候選時,讀取 references/component-brief-template.md。
2. 搜尋能力實作
以「能力+技術棧+關鍵限制或失敗情境」組成查詢。可以搜尋完整 repository,但搜尋結果必須回到具體組件、公開 API、檔案範圍或服務邊界。
優先查看:
- 官方套件庫與專案文件。
- 原始 repository、release、commit、issue 與測試。
- 語言或框架官方推薦的整合方式。
- 能說明錯誤處理、相依關係與限制的範例。
不要只看 star、下載數或搜尋排名。這些訊號只能協助排序,不能證明能力適合目前專案。
3. 找出最小完整單位
對每個候選回答:
- 真正承擔目標能力的是哪個 package、module、class、hook、middleware、service 或函式群?
- 它依賴哪些設定、型別、狀態、事件、資料結構與生命週期?
- 哪些錯誤處理、驗證或安全條件必須連同保留?
- 能否透過公開 API 使用?是否需要抽取原始碼?
- 抽取後能否獨立測試、更新與替換?
只找到零散片段、無法辨識相依關係或切開後會破壞安全條件時,視為邊界不完整。
4. 通過必要關卡後排序
候選必須先通過:
- 來源、作者、版本或 commit 可識別。
- 授權與目前專案的使用及散布方式相容。
- 能完成能力契約中的全部必要行為。
- 關鍵失敗情境與安全、資料或操作不變條件沒有被切斷。
- 相依關係與整合邊界可理解、可控制。
- 有可執行的驗收方法。
任一必要關卡失敗即淘汰,其他項目的高分不能抵銷。通過關卡的候選再依能力符合度、邊界可抽取性、技術相容性、測試與可讀性、維護與風險進行相對排序。詳細規則見 references/scoring-rubric.md。
5. 選擇重用方式
依能力邊界與維護成本選擇:
- 依賴引用:安裝成熟套件,使用其公開 API;優先採用。
- 轉接封裝:用 adapter 或 wrapper 把第三方 API 隔離在專案邊界內。
- 局部抽取:授權允許且邊界完整時,複製必要原始碼並保留上游版本。
- 參考重寫:授權、技術棧或耦合度不允許直接沿用時,依公開行為與概念自行實作,不複製受限制的表達。
- 自行開發:沒有候選通過必要關卡時,記錄搜尋證據並自行建立能力。
資安、加密、身分驗證、金流與通訊協定實作應採用仍受維護、具測試或審查證據的完整依賴邊界。禁止從多個零散片段拼裝安全關鍵流程。
需要判斷不同使用方式的授權影響時,讀取 references/license-compatibility.md。
6. 整合與測試
- 以專案內部介面隔離第三方實作,避免呼叫端直接依賴外部 API 細節。
- 改動限制在介面對接、設定、必要差異與移除無用分支;核心邏輯需要大幅重寫時,重新評估是否仍值得沿用。
- 測試能力契約的正常行為、關鍵失敗情境與必要安全條件。
- 保留可替換性:呼叫端應能在不理解第三方內部實作的情況下使用能力。
- 檢查版本鎖定、更新策略、相依衝突與上游停止維護的處理方式。
可以存取專案時,完成整合與測試;無法存取專案時,交付候選決策、介面建議與驗收計畫,不宣稱已完成整合。
7. 保留來源與角色
每項採用或參考能力都要記錄:
- 能力名稱與專案內角色。
- 來源 URL、版本或 commit、抓取日期與授權。
- 採用方式:依賴引用、轉接封裝、局部抽取、參考重寫或自行開發。
- 實際使用的 API、檔案或原始碼範圍。
- 修改內容、驗收證據、已知限制與更新策略。
只有局部抽取或 vendoring 才需要保存 vendor/<capability>/original/。套件依賴使用 lockfile、能力紀錄與 SOURCES.md 追溯,不重複保存整套套件原始碼。範本見 references/vendor-manifest-template.md。
交付格式
若使用者要求搜尋、評估或實作,最終至少交代:
- 本次能力契約與採用單位。
- 候選來源及被淘汰的關鍵原因。
- 選定候選與重用方式。
- 整合邊界、實際修改範圍與測試證據。
- 授權、來源紀錄、更新與剩餘風險。
沒有候選通過關卡時,明確交付「自行開發」決策與搜尋紀錄,不為了展示搜尋成果而硬採用不合格程式碼。
反模式
- 把完整 repository 當成預設採用單位,連同無關架構一起搬入專案。
- 先選熱門套件,之後才回頭改需求以配合套件。
- 用總分掩蓋必要行為、授權或安全關卡失敗。
- 抽取單一函式卻遺漏驗證、錯誤處理、狀態或生命週期。
- 為了「最小修改」保留不必要依賴,讓組件無法獨立理解與測試。
- 套件引用一律複製整套原始碼到
vendor/。 - 參考受限制程式碼後逐行翻譯,卻宣稱為自行開發。
- 沿用程式碼卻沒有來源、版本、授權、角色與修改紀錄。
參考檔案
- references/component-brief-template.md:能力契約與候選比較範本。
- references/scoring-rubric.md:必要關卡與候選相對排序。
- references/license-compatibility.md:依使用與散布方式判斷授權風險。
- references/vendor-manifest-template.md:能力來源、角色與修改紀錄範本。
只在相應決策需要細節時讀取 reference,不要每次全部載入。