文件化軟體架構
架構文件的存在是為了回答利害關係人在系統的生命週期中會不斷在會議中提出的問題：這是怎麼組合的？為什麼這樣做？我要在哪裡修改 X？它在 Y 的情況下撐得住嗎？ 好的文件會一次性用書面方式回答這些問題，並以每位讀者都能實際運用的形式呈現。
這個技能是一套產出這類文件，以及審查他人所寫文件的方法。它建立在開放、可自由取得的標準與模型之上，而非任何單一的版權文本：
- ISO/IEC/IEEE 42010 — 架構描述的國際標準。它提供了貫穿全文的詞彙：利害關係人、關注點、觀點、視圖、模型、架構決策、理由。
- C4 模型 (Simon Brown) — 一套輕量化的結構性圖表，分為四個縮放層級：脈絡、容器、元件、程式碼。
- 4+1 視圖模型 (Philippe Kruchten) — 五個同時存在的視角：邏輯、流程、開發、部署，以及將它們串聯起來的情境。
- arc42 — 一個創用 CC 授權的文件範本，其章節結構可作為完整架構描述的實用骨架。
- 架構決策記錄 (由 Michael Nygard 推廣的 ADR 格式) — 每項重大決策一個簡短的檔案。
方法
文件是由誰會讀它以及他們需要決定或做什麼事所驅動的。請依下列順序進行。
-
識別利害關係人及其關注點。 列出依賴此架構的人員（開發者、維運人員、安全審查人員、產品負責人、整合者、稽核人員），以及他們各自需要文件回答什麼問題。關注點是對某人來說很重要的問題或品質："我可以在不停機的情況下部署嗎？"、"客戶資料存放在哪裡？"、"我要如何新增一個支付提供者？"。關注點決定了後續的一切。請參閱
references/viewpoints-and-views.md。 -
選擇能涵蓋關注點的觀點。 觀點是一種可重複使用的視圖類型：建立某一種表示法的慣例（它顯示哪些元素、什麼關係、什麼符號）。選擇最小的觀點集合，使其共同涵蓋所有重要的關注點。不要撰寫沒有人需要的視圖。請參閱
references/view-catalog.md。 -
建構視圖。 每個視圖都是從一個觀點對系統的一種表示：一個圖表加上解釋它的文字。大多數系統需要一個結構視圖（有哪些元件以及它們如何互相依賴）、一個執行期視圖（執行時發生什麼事：流程、流程、互動）以及一個部署視圖（軟體如何對映到基礎設施）。對於那些時間或順序是核心的部分，再加入行為視圖。C4 的層級與 4+1 的視角是具體且經過驗證的填充方式。請參閱
references/view-catalog.md。 -
記錄決策及其理由。 架構文件中最有價值卻也最常遺漏的部分是為什麼。將每項重大決策（背景、考慮過的選項、做出的選擇以及後果）記錄為一個架構決策記錄。理由是讓下一個人能安全修改系統，而不是胡亂猜測的關鍵。請參閱
references/decisions-and-rationale.md。 -
彙整描述並加入導覽說明。 一堆視圖並不等於一份文件。加入連結組織：一頁的系統概覽、範圍與脈絡說明、詞彙表，以及一份明確說明視圖之間如何關聯的備註（同一個元素出現在兩個視圖中是讀者混淆的主要來源，因此必須解決）。使用
references/documentation-template.md來獲得完整的章節骨架。 -
在交付前進行審查。 將文件對照
references/review-checklist.md進行檢查。兩種失敗模式是不完整（某個關注點沒有任何視圖涵蓋）和不易讀（圖表沒有圖例、未定義的術語、沒有說明讀者正在看什麼）。
如何使用這個技能
- 從零開始 → 遵循上述六個步驟，以
references/documentation-template.md作為目標結構。 - 決定要寫什麼 →
references/viewpoints-and-views.md（關注點 → 觀點）和references/view-catalog.md（視圖類型目錄）。 - 記錄一個決策 →
references/decisions-and-rationale.md（ADR 格式與範例）。 - 審查現有文件 →
references/review-checklist.md。 - 在框架之間做選擇或將一個框架對映到另一個 →
references/frameworks-map.md。
原則
- 為讀者而寫，不是為了求完整。 每個視圖、圖表與段落都應追溯到某個利害關係人的關注點。如果你說不出誰需要它，就把它刪掉。
- 每個圖表都需要圖例。 「看起來很明顯」的符號其實不然。說明方框和線條代表什麼。一個未說明的圖表就是一個等待出錯的猜測。
- 邊做邊記錄理由。 在做出決策的當下捕捉決策很容易，事後重建則代價高昂。
- 讓文件貼近程式碼，並保持更新。 與現實脫節的文件比沒有文件更糟，因為人們會信任它。寧可有一份你願意維護的小文件，也不要一份你無力維護的大文件。
- 讓系統的風險決定深度。 對於那些出錯代價高昂的部分，詳細記錄；其餘部分則簡述即可。