giant-shoulders

當使用者要在既有網站、系統或程式專案內新增一項可獨立描述的能力,且應優先搜尋、評估、引用或抽取 GitHub 與套件生態中的成熟實作時,使用此技能。能力可包含 UI 互動、狀態管理、連線方式、通訊協定、驗證授權、資安中介層、資料轉換、演算法、服務轉接器或背景工作。此技能以專案內的能力組件為採用單位;完整 starter、boilerplate 或整套系統選型只有在使用者明確要求時才適用。

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. 通過必要關卡後排序

候選必須先通過:

  1. 來源、作者、版本或 commit 可識別。
  2. 授權與目前專案的使用及散布方式相容。
  3. 能完成能力契約中的全部必要行為。
  4. 關鍵失敗情境與安全、資料或操作不變條件沒有被切斷。
  5. 相依關係與整合邊界可理解、可控制。
  6. 有可執行的驗收方法。

任一必要關卡失敗即淘汰,其他項目的高分不能抵銷。通過關卡的候選再依能力符合度、邊界可抽取性、技術相容性、測試與可讀性、維護與風險進行相對排序。詳細規則見 references/scoring-rubric.md。

5. 選擇重用方式

依能力邊界與維護成本選擇:

  1. 依賴引用:安裝成熟套件,使用其公開 API;優先採用。
  2. 轉接封裝:用 adapter 或 wrapper 把第三方 API 隔離在專案邊界內。
  3. 局部抽取:授權允許且邊界完整時,複製必要原始碼並保留上游版本。
  4. 參考重寫:授權、技術棧或耦合度不允許直接沿用時,依公開行為與概念自行實作,不複製受限制的表達。
  5. 自行開發:沒有候選通過必要關卡時,記錄搜尋證據並自行建立能力。

資安、加密、身分驗證、金流與通訊協定實作應採用仍受維護、具測試或審查證據的完整依賴邊界。禁止從多個零散片段拼裝安全關鍵流程。

需要判斷不同使用方式的授權影響時,讀取 references/license-compatibility.md。

6. 整合與測試

  • 以專案內部介面隔離第三方實作,避免呼叫端直接依賴外部 API 細節。
  • 改動限制在介面對接、設定、必要差異與移除無用分支;核心邏輯需要大幅重寫時,重新評估是否仍值得沿用。
  • 測試能力契約的正常行為、關鍵失敗情境與必要安全條件。
  • 保留可替換性:呼叫端應能在不理解第三方內部實作的情況下使用能力。
  • 檢查版本鎖定、更新策略、相依衝突與上游停止維護的處理方式。

可以存取專案時,完成整合與測試;無法存取專案時,交付候選決策、介面建議與驗收計畫,不宣稱已完成整合。

7. 保留來源與角色

每項採用或參考能力都要記錄:

  • 能力名稱與專案內角色。
  • 來源 URL、版本或 commit、抓取日期與授權。
  • 採用方式:依賴引用、轉接封裝、局部抽取、參考重寫或自行開發。
  • 實際使用的 API、檔案或原始碼範圍。
  • 修改內容、驗收證據、已知限制與更新策略。

只有局部抽取或 vendoring 才需要保存 vendor/<capability>/original/。套件依賴使用 lockfile、能力紀錄與 SOURCES.md 追溯,不重複保存整套套件原始碼。範本見 references/vendor-manifest-template.md。

交付格式

若使用者要求搜尋、評估或實作,最終至少交代:

  1. 本次能力契約與採用單位。
  2. 候選來源及被淘汰的關鍵原因。
  3. 選定候選與重用方式。
  4. 整合邊界、實際修改範圍與測試證據。
  5. 授權、來源紀錄、更新與剩餘風險。

沒有候選通過關卡時,明確交付「自行開發」決策與搜尋紀錄,不為了展示搜尋成果而硬採用不合格程式碼。

反模式

  • 把完整 repository 當成預設採用單位,連同無關架構一起搬入專案。
  • 先選熱門套件,之後才回頭改需求以配合套件。
  • 用總分掩蓋必要行為、授權或安全關卡失敗。
  • 抽取單一函式卻遺漏驗證、錯誤處理、狀態或生命週期。
  • 為了「最小修改」保留不必要依賴,讓組件無法獨立理解與測試。
  • 套件引用一律複製整套原始碼到 vendor/。
  • 參考受限制程式碼後逐行翻譯,卻宣稱為自行開發。
  • 沿用程式碼卻沒有來源、版本、授權、角色與修改紀錄。

參考檔案

只在相應決策需要細節時讀取 reference,不要每次全部載入。