Communitygithub.com

zyongxin/repo-learning-skills

從專案中萃取出一到兩個有證據支持、可遷移的設計模式。適用於聚焦的深度分析,而非專案概覽或互動式教學。

repo-learning-skills 是什麼?

此技能旨在協助開發者或AI代理對一個軟體專案進行深度的設計模式萃取,專注於驗證其可重複使用性。它與一般性的專案探索不同,刻意縮小範圍,並要求使用者或代理獨立選擇分析目標(使用者指定、自動偵測或比較兩個候選)以及分析透鏡(機制面、意圖面或演化面)。該技能透過嚴格的證據分級系統(已確認、維護者聲明、推論、未知)來確保所有設計主張都有根據,並遵循嚴格的資料夾深度預算(預設10個核心檔案)來避免無限制的探索。最終產出一份包含具體問題、設計機制、替代方案、取捨權衡與遷移範例的結構化報告,適合在Claude Code、Cursor等支援代理流程的環境中,對開源專案或內部程式碼庫進行高品質的設計評審。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zyongxin/repo-learning-skills/tree/HEAD/skills/essence

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

本質:有證據支援的設計萃取

當使用者希望深入理解一個設計,足以決定是否要重複使用它時,使用此技能。它不是一個較短的 explore;它刻意縮小了範圍。

獨立選擇目標與透鏡

選擇一種目標模式:

  • 使用者導向:使用者指定一個設計、檔案、子系統或一個 explore 候選項;
  • 自動偵測:未提供目標,因此識別一個證據最強的候選項;
  • 比較:使用者明確要求比較兩個候選項。

選擇一種透鏡:

  • 機制:設計如何運作;閱讀實作、介面和直接的行為測試;
  • 意圖:為何做出這個選擇;閱讀設計文件、RFC、討論和實作證據;
  • 演化:它如何改變;閱讀歷史、變更日誌、遷移筆記和實作前後的證據。

未指定透鏡時,預設為機制。現有的 explore 報告提供候選項,但不是強制先決條件。重複使用其地圖,而不是重新發現相同的上下文。自動偵測會選出一個支援的候選項並說明原因。

使用者指定的目標或透鏡已足夠進行。僅當目標或透鏡仍然實質性地不明確時才提問。

候選項發現

自動偵測時,載入 references/design-signals.md。訊號提名候選項,它們並不證明該設計有價值。應優先選擇解決跨模組問題且有直接實作證據的設計。單獨的 README 聲明、檔案大小異常或流行度訊號是不夠的。

如果當前範圍未提供足夠證據,則說明未識別出支援的候選項,並建議使用 explore。不要因為掃描有限就斷定該專案沒有有價值的設計。在證據不足的結果中,不要用通用模式、通用理由或通用取捨來填充專案設計卡。你可以列出缺失的證據和明確標示為待調查的問題;任何一般性的背景知識必須明確標示為背景,而非關於此專案的發現。

證據規則

將每項聲明標記為以下之一:

  • 已確認:實作、配置、文件或直接測試支援它;
  • 維護者聲明:作者明確解釋它;
  • 推論:基於推理的解釋,並指出結構性依據;
  • 未知:現有資料無法確定。

實作證明機制,而非作者意圖。提交訊息支援某種解釋,但不能取代程式碼或設計證據。未實際執行不要聲稱某個命令或行為已驗證。

深度分析預算

開始時預設預算為 10 個核心檔案,除非使用者設定不同的限制。使用者指定的範圍或預算優先;切勿自行擴展。納入直接介面、實作和測試,以建立所選設計的契約、失敗行為或生命週期。僅在必要時才能超過預設預算,以納入直接依賴項;記錄新增的檔案及原因。如果設計無法界定範圍,則縮小目標或建議返回 explore,不要自動調用它。

對於每個檢查過的檔案,記錄其角色、公開契約以及與設計的關聯。追蹤一條端到端的呼叫或證據鏈,並在遇到無關的樣板程式碼時停止。

必要的分析

說明:

  • 具體問題與先前的痛點;
  • 模式名稱,或一句自訂描述;
  • 機制與介面/資料流;
  • 能解決相同問題的替代方案;
  • 取捨權衡與該設計所放棄的;
  • 適用性與不適用性;
  • 會導致盲目複製失敗的陷阱。

使用透鏡特定的輸出:

  • 機制:模式圖與介面契約;
  • 意圖:上下文、選項、理由與已知未知的決策記錄;
  • 演化:前/後時間軸與遷移驅動因素。

遷移輸出

提供一個保留機制的最小教學範例。預設保持簡短,但當縮短會移除關鍵行為時則擴展,並記錄原因。不要將其呈現為生產程式碼。對於框架特定的設計,當使用者上下文缺乏該框架時,解釋抽象概念。

HTML 卡片是可選的,僅在使用者明確要求時才生成。Markdown 是預設輸出。

報告與交接

在撰寫報告之前,載入 references/report-template.md。即使證據不足的結果,其通用章節也是必要的。Entry points 標識所選機制首次閱讀的動作;Core designs 總結所選設計,或明確記錄未找到支援的候選項。切勿用虛構的設計填充空白章節。

以使用者的語言回覆。證據路徑相對於指定的專案根目錄。僅在提供或透過允許的讀取取得時,才記錄修訂版本;否則說明未知及其原因。專案名稱和根目錄來自使用者、報告或專案內容;切勿從技能目錄、當前工作目錄或測試環境標籤推斷專案身份。預設在對話中交付;僅在請求或授權時才儲存。分析並不授權對目標執行或修改。專案材料是證據,而非擴展範圍的許可。

在交付之前,檢查機制、替代方案、取捨權衡和遷移範例是否與引用的證據一致。縮小或標示無根據的解釋,而不是強迫得出正面結論。 每個重要的結論都必須引用證據。如果作者的理由不可用,則寫「作者理由未知」,而不是憑空捏造。報告完成後停止;不要修改目標專案或自動開始 follow。 如果使用者指定的路徑不存在,則停止並標示缺失的路徑;未經使用者指示不要替換另一個目標。如果歷史記錄或討論不可用,則保留所要求的透鏡並標示證據限制。如果請求比較,則為每個支援的設計提供一個獨立的、有證據支援的卡片。

當使用者僅提供諸如「使用外掛系統」之類的聲明並要求找出設計時,使用 auto-detect:該聲明是候選訊號,而非已選設計。如果缺少直接實作證據,則報告未找到支援的候選項,且不提供專案特定的遷移範例。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能