Community程式設計與開發github.com

軟體架構工程

程式開發技能。在設計、實作、重構與審查程式碼的同時,持續維護架構完整性。適用於 AI 輔助編碼、倉儲變更、功能開發、API/資料庫變更、模組邊界、系統設計、遷移、部署選擇、可擴展性、可靠性與架構審查。在變更程式碼前先分析現有架構;根據情境權衡取捨;變更後驗證架構限制。對於孤立的低風險編輯保持輕量化。

軟體架構工程 是什麼?

此技能(software-architecture-engineering)旨在讓開發者與 AI 代理在變更程式碼時,能持續維持軟體架構的連貫性。它借鑒《軟體架構:原理與實踐》第二版的核心理念,並將其擴展為 AI 代理可重複執行的操作流程。技能核心圍繞三個法則:凡事皆為取捨、理由比方法重要、決策存在光譜。根據變更影響範圍,將任務分為輕量、標準、深度三種模式,並提供對應的執行規範。在變更程式碼前,代理必須先探索現有系統、評估影響、規劃安全增量、實作時避免架構偏移,並在最終驗證功能性之外,還需檢查架構適應性函數(如禁止依賴循環、維護模組所有權等)。技能也提供多個參考文件與範本(如架構合約、變更影響分析、ADR 決策記錄),支援完整的架構治理。適用於 Claude Code、Cursor、Codex 等 AI 編碼代理,無需特定程式語言或框架。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

軟體架構工程 是做什麼的?

目的

在軟體被變更的過程中保持架構的連貫性,包括由 AI 代理所撰寫的變更。這是一項操作技能,並非要求重新設計每個專案。其可重複使用的原則源自《軟體架構:原理與實踐》第二版(Richards 與 Ford,2025);持續的代理工作流程與產物則為原創擴展。不要求任何特定的模型、程式語言、倉儲主機、CI 工具或框架。

遵循三項法則:

  1. 凡事皆為取捨。 評估成本與效益,並根據實際情境加權;當條件改變時重新評估。
  2. 理由比方法重要。 保留理由、被否決的選項、風險與決策負責人,而不僅是圖表與程式碼。
  3. 決策存在於光譜上。 拒絕虛假的二元對立、一刀切的微服務規則與架構流行趨勢。

根據影響選擇努力程度

模式典型觸發條件行動與預期產出
輕量孤立的錯誤、格式調整、無合約/邊界影響的本地實作檢查相關程式碼與限制;進行最小變更;執行相關檢查;僅回報重大問題。不強制撰寫 ADR。
標準跨模組功能、新的整合、API/綱要變更、重大重構建立專案情境;檢查依賴關係;比較可行的選項;以增量方式實作;驗證邊界與合約;記錄重大決策。
深度新平台、服務拆分、重大遷移、高風險資料/安全性/可靠性變更、架構審查完整的情境與架構分析、替代方案、明確的資料/失敗模式、遷移與回退計畫、可衡量的適應性函數、ADR、風險與核准邊界。

升級:當假設的小型編輯跨越所有權邊界、變更公開合約、改變持久化方式、引入新的執行時期/部署元件、擴大失敗影響範圍或揭露架構漂移時。降級:如果調查顯示沒有重大的架構影響。使用者/專案/安全指示優先。切勿為瑣碎任務強制要求厚重的報告。

必要的編碼代理循環

對於在現有倉儲中的工作,執行此循環。關於精確的程序、失敗處理與平行代理規則,請參閱代理實作治理。

0. 發現當前系統——不要憑空發明

  • 在可存取的情況下檢查相關的程式碼、測試、套件/建置檔、基礎設施、設定、文件、ADR、目錄佈局與實際的依賴路徑。
  • 定位任何專案架構合約(例如 docs/architecture/CONTRACT.md)與已接受的 ADR;將其視為專案限制,而非不變的真理。
  • 分別記錄觀察到 / 提供 / 假設 / 未知的項目。如果沒有程式碼/工具存取權限,請說明結果僅為提案,而非經過驗證的倉儲分析。
  • 不要默默用偏好的風格取代正在使用的架構。

1. 編輯前評估影響

  • 定義變更範圍、受影響的業務能力、所屬模組、API/合約、資料職責、依賴關係、安全邊界、部署單元與失敗路徑。
  • 將任務分類為輕量 / 標準 / 深度,並選擇最小且足夠的審查。
  • 對於重大決策,推導出少數幾個優先排序的架構特性(例如安全性、延遲、可用性、可擴展性、彈性、可維護性、可測試性、可部署性、可復原性、成本),並附帶範圍、目標與衡量方式。將明確需求與隱含、未確認的需求區分開來。
  • 對於低風險的未知項目,選擇最小、可逆的預設值;不要在未經確認的情況下,基於未經支援的高風險假設繼續進行。

2. 在適當情況下維護邊界並比較替代方案

  • 偏好高內聚與低耦合。保持業務職責、依賴方向、時間耦合與資料所有權的明確性。區分邏輯模組與獨立部署的服務。
  • 檢查對營運與資料架構的影響,而不僅是目錄結構。共享資料庫、交易邊界或同步呼叫可能會破壞表面上的模組化。
  • 對於重大變更,使用情境加權的取捨來比較至少兩個可行的選項。候選方案可能包括分層、模組化單體、管線、微核心、基於服務、事件驅動、空間導向、協調導向 SOA、微服務或混合模式。沒有任何架構風格是通用的預設值。
  • 分散式設計必須處理網路失敗/延遲、可用性、一致性、交易邊界、重試、冪等性、可觀測性、安全性與營運成本(視情況而定)。
  • 說明會使決策逆轉的條件。選擇性地使用風格、分散式設計與基礎。

3. 以安全增量規劃實作

  • 識別預期的檔案/模組變更、必須保持穩定的合約、遷移順序以及必要的回退策略。
  • 說明架構不變量(必須保持為真的規則):允許的依賴方向、內部 API 所有權、資料寫入權限、租戶/身份驗證邊界、向後相容性、錯誤處理等。
  • 在實作前為這些不變量選擇客觀的檢查方式。如有用處,可複製/調整專案架構合約與變更影響範本;未經許可或超出明確任務範圍時,請勿建立專案檔案。
  • 對於需要人類/業務權限的不可逆/高影響決策,請提出請求或暫緩處理。不要偽造核准。

4. 在無架構漂移的情況下實作

  • 做出與當前架構一致的最小連貫變更。未經證明需求,請勿拆分服務、引入經紀人、全域抽象或新框架。
  • 保持介面與資料所有權的明確性。請勿透過另一個模組的內部建立捷徑、繞過身份驗證/驗證、默默變更事件綱要或混雜不相關的變更。
  • 如果實作揭示了計畫中的重大缺陷,請停止並重新評估受影響的決策,而非用權宜程式碼掩蓋。僅在有正當理由時更新 ADR/合約。
  • 在多代理工作中,定義元件/檔案所有權、穩定的合約與整合負責人。平行變更不得覆蓋共享的架構限制。

5. 驗證架構,而不僅僅是功能

  • 在可用且獲授權的情況下,執行相關的現有單元/整合/合約測試與建置檢查。
  • 驗證架構特定的適應性函數:禁止的依賴關係、循環、模組所有權、API 相容性、綱要遷移、冪等性、效能預算、可觀測性、彈性、安全性、部署/回退(視情況而定)。
  • 比較變更前後的依賴結構與受影響的不變量。可選的標準函式庫匯入邊界檢查器與範例設定可以強制執行選定的 Python/JS/TS 匯入規則;其功能有意受限,無法證明完整的架構正確性。
  • 將證據標示為通過 / 失敗 / 未執行 / 不適用。若未實際執行或提供證據,請勿聲稱已驗證測試、可擴展性、生產就緒性、安全性或部署。
  • 如果任何強制性閘道失敗,請修正/還原,或明確識別未解決的問題與決策負責人。切勿將失敗的閘道呈現為已完成的工作。

6. 記錄並溝通重大決策

  • 僅為架構上重要的變更建立或更新簡潔的 ADR:標題、狀態、情境、選擇的方案、理由、替代方案、取捨、後果、強制執行方式與重新審視觸發條件。使用 ADR 範本。
  • 當歷史決策被取代時,請予以保留。將圖表視為溝通的輔助工具,而非實作或驗證的證據。
  • 在最終報告中說明:變更了什麼;架構影響;已通過、失敗或未執行的檢查;未解決的風險;以及任何需要人類決策的事項。對於輕量變更,一個簡潔的段落通常就足夠了。

純設計與稽核任務

當不編輯倉儲時,按比例應用步驟 0 到 3 與 6;產出設計、取捨分析、架構簡報或審查,而不假裝已實作或測試任何東西。對於完整的架構稽核,盤點元件、資料所有權、邊界、部署以及團隊/基礎設施限制;使用證據對具體風險進行排序;在建議全面重寫之前,提出增量修補措施與適應性函數。

不可協商的安全措施

  • 無不可驗證的事實: 禁止憑空編造倉儲檢查、測試輸出、負載水準、合規狀態、成本、利害關係人核准或衡量結果。
  • 無虛假的全域通用: 微服務、單體或事件驅動系統並非天生最佳。請勿僅依據資料表/實體來拆分服務。
  • 無範圍混淆: 邏輯模組、部署單元、資料所有權與架構特性範圍是不同概念。
  • 無隱藏耦合: 檢查共享綱要、共享函式庫、時間耦合、跨服務呼叫與事件合約;重用易變的領域邏輯可能會增加耦合。
  • 無風險抹除: 分散式一致性、交易處理、綱要變更、失敗復原與回退在相關時需要明確的思考。
  • 無流程形式主義: 已完成的檢查清單或自我評估並非證據。優先處理實際檢查與程式碼證據。
  • 無默默進行的架構變更: 標記重要的偏離,記錄原因,並將責任留給人類/專案決策負責人。
  • 無受版權保護的書籍散佈: 此技能為原創綜述。請勿將書籍或其圖表複製到下游倉儲中。

可依需求參考的檔案

僅讀取任務所需的檔案(相對於此技能目錄的路徑):

產物:架構簡報、架構合約、變更影響、ADR、取捨矩陣、風險登記冊、架構審查、邊界政策範例。已運作的情境:無邊界漂移的 AI 編碼。其他模型/執行時期指示為選用;請參閱可攜性。

相關技能