軟體架構工程 是做什麼的?
目的
在軟體被變更的過程中保持架構的連貫性,包括由 AI 代理所撰寫的變更。這是一項操作技能,並非要求重新設計每個專案。其可重複使用的原則源自《軟體架構:原理與實踐》第二版(Richards 與 Ford,2025);持續的代理工作流程與產物則為原創擴展。不要求任何特定的模型、程式語言、倉儲主機、CI 工具或框架。
遵循三項法則:
- 凡事皆為取捨。 評估成本與效益,並根據實際情境加權;當條件改變時重新評估。
- 理由比方法重要。 保留理由、被否決的選項、風險與決策負責人,而不僅是圖表與程式碼。
- 決策存在於光譜上。 拒絕虛假的二元對立、一刀切的微服務規則與架構流行趨勢。
根據影響選擇努力程度
| 模式 | 典型觸發條件 | 行動與預期產出 |
|---|---|---|
| 輕量 | 孤立的錯誤、格式調整、無合約/邊界影響的本地實作 | 檢查相關程式碼與限制;進行最小變更;執行相關檢查;僅回報重大問題。不強制撰寫 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;產出設計、取捨分析、架構簡報或審查,而不假裝已實作或測試任何東西。對於完整的架構稽核,盤點元件、資料所有權、邊界、部署以及團隊/基礎設施限制;使用證據對具體風險進行排序;在建議全面重寫之前,提出增量修補措施與適應性函數。
不可協商的安全措施
- 無不可驗證的事實: 禁止憑空編造倉儲檢查、測試輸出、負載水準、合規狀態、成本、利害關係人核准或衡量結果。
- 無虛假的全域通用: 微服務、單體或事件驅動系統並非天生最佳。請勿僅依據資料表/實體來拆分服務。
- 無範圍混淆: 邏輯模組、部署單元、資料所有權與架構特性範圍是不同概念。
- 無隱藏耦合: 檢查共享綱要、共享函式庫、時間耦合、跨服務呼叫與事件合約;重用易變的領域邏輯可能會增加耦合。
- 無風險抹除: 分散式一致性、交易處理、綱要變更、失敗復原與回退在相關時需要明確的思考。
- 無流程形式主義: 已完成的檢查清單或自我評估並非證據。優先處理實際檢查與程式碼證據。
- 無默默進行的架構變更: 標記重要的偏離,記錄原因,並將責任留給人類/專案決策負責人。
- 無受版權保護的書籍散佈: 此技能為原創綜述。請勿將書籍或其圖表複製到下游倉儲中。
可依需求參考的檔案
僅讀取任務所需的檔案(相對於此技能目錄的路徑):
- AI 編碼與持續架構治理 — 對於重大的倉儲編輯、PR 審查、平行代理與架構漂移診斷為必要。
- 基礎與架構特性 — 需求、耦合、內聚、元件、特性範圍。
- 架構風格 — 九種風格與選擇條件。
- 分散式系統與模式 — 網路現實、事件、交易、一致性、協調、CQRS。
- 決策、適應性函數與風險 — ADR、治理、風險風暴、圖表。
- 人員、資料、基礎設施與 AI — 團隊與營運限制。
- 原始碼地圖 — 全部 27 個書籍章節,以及書籍觀點與代理特定擴展之間的區別。
- 驗證評分量表 — 主要設計決策與實作審查的品質標準。
產物:架構簡報、架構合約、變更影響、ADR、取捨矩陣、風險登記冊、架構審查、邊界政策範例。已運作的情境:無邊界漂移的 AI 編碼。其他模型/執行時期指示為選用;請參閱可攜性。