Communitygithub.com

renatoxm/leanagentkit

一種精簡的替代方案,用於取代 GitHub Spec Kit。

leanagentkit 是什麼?

此技能提供了一個基於「乾淨架構」(Clean Architecture)的嚴謹軟體設計框架,強調業務規則應獨立於框架、資料庫及傳遞機制。它詳細說明了相依性規則(Dependency Rule)、實體與用例(Entities and Use Cases)、介面適配器(Interface Adapters)、元件原則(Component Principles)以及 SOLID 原則的實作方式。透過遵守這些原則,開發者可以建立易於測試、可替換實作且對技術堆疊變動具有高韌性的系統。該技能支援任何遵循物件導向或函數式設計的程式語言與平台,並提供了常見錯誤的診斷清單與評分機制,協助團隊持續改善架構品質。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

在你喜歡的 AI 中提問

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

說明文件

乾淨架構框架

一種有紀律的軟體結構化方法,確保業務規則獨立於框架、資料庫以及傳遞機制。在設計系統架構、審查模組邊界或提供相依性管理建議時,請應用這些原則。

核心原則

原始碼相依性必須指向內側——朝向更高層級的政策。 內圈的任何事物都不能知道外圈的任何事物。這條單一規則產生了可測試、獨立於框架、UI、資料庫及任何外部機構的系統。業務規則才是重點;資料庫、網頁框架和傳遞機制都是細節——當細節依賴於政策時,你可以延遲決策、替換實作,並在隔離環境中測試業務邏輯。

評分

目標:10/10。 根據架構滿足的七項快速診斷問題(Quick Diagnostic)各得一分(0-7),然後映射到 0-10 的區間:滿足 6-7 項 = 9-10(相依性規則成立,業務邏輯獨立於框架和資料庫);4-5 項 = 6-8(核心可測試,但部分細節向內洩漏);2-3 項 = 3-5(框架或持久化機制主導結構);0-1 項 = 0-2(無邊界——業務規則存在於控制器和 ORM 模型中)。報告分數、未通過的診斷項目,以及修復每個項目所需的特定反轉。

1. 相依性規則與同心圓

核心概念: 將架構組織為同心圓——最內層是實體(Entity,企業業務規則),其次是用例(Use Case,應用程式業務規則),然後是介面適配器,最外層是框架與驅動程式。原始碼相依性永遠指向內側。

為何有效: 當高層級政策不依賴於低層級細節時,你可以更換資料庫、網頁框架或 API 風格,而無需觸及業務邏輯——系統變得能夠抵禦技術堆疊中最易變的部分。

關鍵見解:

  • 內圈不能提及外圈的名稱——不能有來自外部的類別、函式、變數或資料格式
  • 跨越邊界的資料必須以對內圈最方便的形式呈現,而不是由外圈決定
  • 依賴反轉(介面向內定義,向外實作)是執行此規則的機制
  • 圓的數量並非固定——四個是典型;規則保持不變
  • 框架是細節,不是架構——它們屬於最外圈

程式碼應用:

情境模式範例
層級方向內圈定義介面;外圈實作UserRepository 介面在用例中;PostgresUserRepository 在適配器中
資料跨越DTO 跨越邊界,不是 ORM 實體用例回傳 UserResponse DTO,而不是 ActiveRecord 模型
相依性方向匯入箭頭永遠指向內側控制器匯入用例;用例從不匯入控制器

當內圈的匯入指向外圈時,請參閱 references/dependency-rule.md 取得四圈程式碼逐步解說、資料跨越規則,以及修復問題的四步驟依賴反轉程序。

2. 實體與用例

核心概念: 實體封裝了企業層級的業務規則——即使沒有軟體也會存在的規則。用例包含了應用程式特定的規則,用來協調進出實體的資料流。

為何有效: 將「業務做什麼」(實體)與「應用程式如何協調」(用例)分開,可以讓您在多個應用程式中重用實體,並在不改變核心業務規則的情況下變更應用程式行為。

關鍵見解:

  • 實體不是資料庫行——它們是封裝關鍵業務規則的物件或純函式
  • 用例接受請求模型(Request Model)並回傳回應模型(Response Model)——絕不使用框架物件
  • 每個用例都是一個單一的應用程式操作(CreateOrder、ApproveExpense)
  • 互動器模式(Interactor pattern):一個用例類別實作輸入邊界介面,並呼叫輸出邊界介面
  • 用例的變更絕不應影響實體;實體的變更可能會波及用例

程式碼應用:

情境模式範例
實體設計關鍵業務規則,零框架依賴Order.calculateTotal() 套用稅務規則;對 HTTP 一無所知
請求/回應簡單的資料結構跨越邊界CreateOrderRequest { items, customerId }——沒有 ORM 模型
單一職責每個操作一個用例PlaceOrder、CancelOrder、RefundOrder 作為獨立的類別
互動器實作輸入埠,呼叫輸出埠PlaceOrderInteractor implements PlaceOrderInput

在設計互動器或決定哪些屬於實體、哪些屬於用例時,請參閱 references/entities-use-cases.md——包含完整的企業與應用程式業務規則處理,以及請求/回應模型範例。

3. 介面適配器與框架

核心概念: 介面適配器在對用例/實體方便的格式與外部機構要求的格式之間轉換資料。框架和驅動程式是最外層——與外界溝通的黏合程式碼。

為何有效: 當網頁框架、ORM 或訊息佇列被限制在外圈時,更換其中任何一個都是局部性的變更。資料庫是細節;網頁是細節;細節應該是你業務規則的外掛程式,而不是應用程式的骨架。

關鍵見解:

  • 控制器將 HTTP 轉換為用例輸入;呈現器將用例輸出轉換為視圖模型
  • 閘道器實作用例定義的儲存庫介面——內圈定義合約,外圈履行合約
  • 業務規則從不知道資料是存在 SQL、NoSQL 還是純文字檔案中,也不知道傳遞方式是 HTTP
  • 對待框架要保持懷疑——它們希望你與它們耦合;讓它們保持距離

程式碼應用:

情境模式範例
控制器傳遞機制 → 用例輸入OrderController.create(req) 建構 CreateOrderRequest,呼叫互動器
呈現器用例輸出 → 視圖模型OrderPresenter.present(response) 格式化為 JSON/HTML
閘道器每個資料庫實作儲存庫介面SqlOrderRepository implements OrderRepository
框架邊界框架向內呼叫,絕不反向Express 路由處理器呼叫控制器;控制器從不匯入 Express

在接線控制器、呈現器或閘道器,或論證資料庫/網頁是細節時,請參閱 references/adapters-frameworks.md——涵蓋外掛程式架構以及如何將框架限制在邊緣。

4. 元件原則

核心概念: 元件是部署的單元。三個內聚原則管理元件內部的內容;三個耦合原則管理元件之間的關係。

為何有效: 組合不良的元件會產生連鎖效應,一個變更迫使無關的程式碼重新部署;這些原則將變更局部化,並使發布保持獨立。

關鍵見解:

  • REP(重用/發布等價原則):元件中的類別必須可以作為一個單元進行版本控制與發布
  • CCP(共同封閉原則):因相同原因在同一時間變更的類別應放在一起——這是針對元件的 SRP
  • CRP(共同重用原則):不要強迫使用者依賴他們不使用的類別
  • ADP(無環依賴原則):元件圖不能有循環——使用 DIP 或建立新元件來打破循環
  • SDP(穩定依賴原則):朝穩定方向依賴
  • SAP(穩定抽象原則):穩定的元件應該是抽象的;不穩定的元件應該是具體的

程式碼應用:

情境模式範例
元件分組將一起變更的類別分組(CCP)所有與訂單相關的用例放在一個元件中
打破循環套用 DIP 來反轉依賴邊將介面萃取到新元件中以打破循環
穩定性度量不穩定性 I = Ce / (Ca + Ce)多個傳入,無傳出依賴 → I 接近 0(穩定)

在將類別分組到可部署元件或打破依賴循環時,請參閱 references/component-principles.md——使用不穩定性指標逐步處理 REP、CCP、CRP、ADP、SDP、SAP。

5. SOLID 原則

核心概念: 五個類別與模組層級的原則——單一職責、開閉原則、里氏替換、介面隔離、依賴反轉——是使相依性規則成為可能的中階建構區塊。

為何有效: 每個原則都針對依賴關係出錯的特定方式,防止將程式碼庫變成遺留噩夢的僵化性、脆弱性和不可移動性。

關鍵見解:

  • SRP:一個模組只有一個改變的理由——它服務於一個角色(而不是「做一件事」)
  • OCP:通過新增程式碼來擴展行為,而不是修改現有程式碼——策略模式和外掛程式模式
  • LSP:子型別必須能透過基底介面使用,而客戶端無需察覺——被未預期的異常或忽略的方法所違反
  • ISP:客戶端不應依賴他們不使用的方法——胖介面會產生不必要的耦合
  • DIP:高層級模組和低層級模組都依賴於高層級模組定義的抽象

程式碼應用:

情境模式範例
SRP 違反類別服務多個角色Employee 處理薪資(CFO)、報告(COO)、持久化(CTO)
OCP 透過策略透過新類別實作新行為新增 ExpressShipping 實作 ShippingStrategy;Order 不變
LSP 違反子型別改變預期行為Square extends Rectangle 破壞了 setWidth()/setHeight() 合約
ISP 應用將胖介面拆分為角色介面使用 Printer、Scanner、Fax 而不是一個 MultiFunctionDevice
DIP 接線高層級定義介面;低層級實作OrderService 依賴於 PaymentGateway,而不是 StripeClient

在將 SRP/OCP/LSP/ISP/DIP 應用於特定類別或診斷違反時,請參閱 references/solid-principles.md——每個原則都透過程式碼範例及其預防的程式碼壞味道逐步說明。

6. 邊界與邊界結構

核心概念: 邊界是重要事物與細節事物之間的一條線,通過多型來實作:依賴關係指向內側,而控制流可以從任一方向跨越。

為何有效: 每個邊界都提供了延遲決策或替換實作的選項;策略性地放置邊界決定了系統在多年維護中是令人愉悅還是痛苦。

關鍵見解:

  • 完整邊界在兩側使用相互的介面;部分邊界使用更簡單的策略或外觀模式
  • 謙卑物件模式:將邊界程式碼拆分為難以測試的部分(靠近邊界)和易於測試的部分(邏輯)
  • 服務不自動構成架構邊界——一個具有龐大共享資料模型的微服務就是一個帶有網路呼叫的單體
  • 測試是最孤立的元件:它們向內依賴,沒有什麼依賴於它們
  • 過早的邊界是昂貴的,但缺失的邊界也同樣昂貴——在可能變動的點上繪製邊界

程式碼應用:

情境模式範例
完整與部分邊界相互的埠,或單一的策略用例定義 PlaceOrderInput/PlaceOrderOutput;較簡單的情況使用 ShippingStrategy
謙卑物件將可測試的邏輯與基礎設施分開PresenterLogic(可測試)產生 ViewModel;View(謙卑)渲染它
主程式作為外掛組合根組裝系統main() 接線所有具體實作並啟動應用程式

在決定邊界繪製位置、選擇完整或部分邊界、或應用謙卑物件模式時,請參閱 references/boundaries.md——也涵蓋了服務作為邊界、測試邊界以及主程式作為終極外掛。

常見錯誤

錯誤為何失敗修正方式
ORM 洩漏到業務邏輯中實體耦合到資料庫綱要;資料庫變更會改寫業務規則將領域實體與持久化模型分開;在適配器層進行映射
業務規則放在控制器中未經 HTTP 無法測試;在端點間重複將邏輯移到用例互動器中;控制器僅負責轉譯與委派
框架優先的架構框架主導結構;更換意味著重寫將框架視為外掛;根據業務能力組織程式碼
循環的元件依賴變更不可預測地擴散;無法獨立發布套用 DIP 或萃取一個共享抽象元件
每個特性一個巨型用例數千行的膨脹協調器拆分為專注的單一操作用例
因為「簡單」而跳過邊界耦合悄悄累積,直到成本變得巨大在可能變動的點上主動繪製邊界
微服務自動代表好架構分散式單體比乾淨的單體更差在服務內部和服務之間套用相依性規則;服務是部署邊界,不是架構邊界

快速診斷

問題如果沒有行動
你能在沒有資料庫、網頁伺服器或框架的情況下測試業務規則嗎?規則與基礎設施耦合在介面後萃取實體和用例;模擬外層
所有原始碼相依性都指向內側嗎?(無內圈匯入外圈)相依性方向錯誤找到向外指向的匯入,套用依賴反轉
實體是否不包含任何框架、資料庫或 Web 匯入?實體被細節污染從實體中移除外部匯入;透過介面注入依賴
用例是否以 DTO(或原始類型)的形式接收請求並回傳回應,而不是 ORM 模型?資料洩漏邊界為每個跨越邊界的操作定義請求/回應模型
控制器是否只執行轉譯和委派而不包含業務邏輯?控制器含有業務規則將規則移至用例中;讓控制器僅管理 HTTP/框架關注點
是否將元件分組,使得因相同原因變更的類別放在一起?變更跨元件擴散套用 CCP 重組;檢查是否有循環或穩定依賴問題
系統是否與框架和資料庫解耦,足以讓切換兩者中的任何一個只需在適配器層進行局部變更?框架/資料庫影響了架構從最外層隔離框架細節;使用儲存庫模式抽象化資料庫

相關技能