評軟體架構

於系統層評軟體架構之品質屬性、設計原則遵循與長期可維護性。

適用時機

• 實作開始前評提議之架構
• 評既有系統之可擴展性、可維護性或安全
• 評項目之架構決策記錄（ADR）
• 作技術債評估
• 評系統是否備重大擴展或功能擴張
• 別於行層代碼評（其聚焦於 PR 層變更）

輸入

• 必要：系統代碼庫或架構文件（圖表、ADR、README）
• 必要：關於系統目的、規模與限制之上下文
• 選擇性：非功能需求（延遲、吞吐、可用性目標）
• 選擇性：團隊大小與技能組成
• 選擇性：技術限制或偏好
• 選擇性：已知痛點或關注區

步驟

步驟一：解系統上下文

繪系統邊界與介面：

## System Context
- **Name**: [System name]
- **Purpose**: [One-line description]
- **Users**: [Who uses it and how]
- **Scale**: [Requests/sec, data volume, user count]
- **Age**: [Years in production, major versions]
- **Team**: [Size, composition]

## External Dependencies
| Dependency | Type | Criticality | Notes |
|-----------|------|-------------|-------|
| PostgreSQL | Database | Critical | Primary data store |
| Redis | Cache | High | Session store + caching |
| Stripe | External API | Critical | Payment processing |
| S3 | Object storage | High | File uploads |

預期： 對系統何作及其依賴有清晰圖。 失敗時： 若架構文件缺，自代碼結構、配置與部署文件推導上下文。

步驟二：評結構品質

耦合評估

察模組相依之緊：

• 依賴方向：依賴單向流（分層）抑或循環？
• 介面邊界：模組以定義之介面／契約相連抑或直接實作引用？
• 共享狀態：模組間是否共享可變狀態？
• 資料庫耦合：多服務直接讀／寫同表？
• 時間耦合：操作須以特定順序發生而無明顯協調？

# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/

# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20

內聚評估

評每模組是否有單一明確之職責：

• 模組命名：名稱是否準描述模組所為？
• 文件大小：文件或類過大（>500 行暗示多職責）？
• 變更頻率：無關功能是否要求改同模組？
• 上帝物件：是否有所有物皆依之類／模組？

預期： 已評耦合與內聚，附代碼庫之具體例。 失敗時： 若代碼庫過大不宜手評，採樣 3-5 主要模組與最常變之文件。

步驟三：評 SOLID 原則

## SOLID Assessment
| Principle | Status | Evidence | Impact |
|-----------|--------|----------|--------|
| SRP | Concern | UserService handles auth, profile, notifications, and billing | High — changes to billing risk breaking auth |
| OCP | Good | Plugin system for payment providers | Low |
| LSP | Good | No type-checking anti-patterns found | Low |
| ISP | Concern | IRepository has 15 methods, most implementors use 3-4 | Medium |
| DIP | Concern | Controllers directly instantiate database repositories | Medium |

預期： 每原則皆評，附至少一具體例。 失敗時： 非所有原則對所有架構風格皆等適。註某原則較不相關時（如 ISP 於函數式代碼庫中較不重要）。

步驟四：評 API 設計

對暴露 API（REST、GraphQL、gRPC）之系統：

• 一致性：命名慣例、錯誤格式、分頁模式統一
• 版本化：策略存在且已施（URL、標頭、內容協商）
• 錯誤處理：錯回應結構化、一致、不洩內部
• 認證／授權：於 API 層適當執行
• 速率限制：防濫用之保護
• 文件：OpenAPI／Swagger、GraphQL 結構或 protobuf 定義已維護
• 冪等：變更操作（POST／PUT）安全處理重試

## API Design Review
| Aspect | Status | Notes |
|--------|--------|-------|
| Naming consistency | Good | RESTful resource naming throughout |
| Versioning | Concern | No versioning strategy — breaking changes affect all clients |
| Error format | Good | RFC 7807 Problem Details used consistently |
| Auth | Good | JWT with role-based scopes |
| Rate limiting | Missing | No rate limiting on any endpoint |
| Documentation | Concern | OpenAPI spec exists but 6 months out of date |

預期： 已對常見標準評 API 設計，附具體發現。 失敗時： 若無 API 暴露，略此步並聚焦內部模組介面。

步驟五：評可擴展性與可靠性

• 無狀態：應用可水平擴展否（無本地狀態）？
• 資料庫可擴展：查詢有索引否？結構合資料量否？
• 快取策略：快取施於適當層（資料庫、應用、CDN）否？
• 失敗處理：依賴不可用時生何事（斷路器、重試、回退）？
• 可觀測性：日誌、指標、追蹤已實作否？
• 資料一致性：最終一致性可受抑或須強一致性？

預期： 對所陳之非功能需求已評可擴展性與可靠性。 失敗時： 若非功能需求未記，建議將其定義為首步。

步驟六：評技術債

## Technical Debt Inventory
| Item | Severity | Impact | Estimated Effort | Recommendation |
|------|----------|--------|-----------------|----------------|
| No database migrations | High | Schema changes are manual and error-prone | 1 sprint | Adopt Alembic/Flyway |
| Monolithic test suite | Medium | Tests take 45 min, developers skip them | 2 sprints | Split into unit/integration/e2e |
| Hardcoded config values | Medium | Environment-specific values in source code | 1 sprint | Extract to env vars/config service |
| No CI/CD pipeline | High | Manual deployment prone to errors | 1 sprint | Set up GitHub Actions |

預期： 技術債已編目，附嚴重度、影響與工作量估。 失敗時： 若債清冊壓人，按影響／工作量比優先排前 5 項。

步驟七：評架構決策記錄（ADR）

若 ADR 存在，評：

• 決策有清上下文（解何問題）
• 已考慮並記錄替代方案
• 取捨明顯
• 決策仍當前（未經文件而被取代）
• 新重大決策有 ADR

若 ADR 不存在，建議為主要決策確立之。

步驟八：撰架構評論

## Architecture Review Report

### Executive Summary
[2-3 sentences: overall health, key concerns, recommended actions]

### Strengths
1. [Specific architectural strength with evidence]
2. ...

### Concerns (by severity)

#### Critical
1. **[Title]**: [Description, impact, recommendation]

#### Major
1. **[Title]**: [Description, impact, recommendation]

#### Minor
1. **[Title]**: [Description, recommendation]

### Technical Debt Summary
[Top 5 debt items with prioritized recommendations]

### Recommended Next Steps
1. [Actionable recommendation with clear scope]
2. ...

預期： 評論報告可行，附按優先排之建議。 失敗時： 若評時受限，清陳何已涵與何未評。

驗證

• 系統上下文已記（目的、規模、依賴、團隊）
• 已評耦合與內聚，附具體代碼例
• 已評 SOLID 原則（適用時）
• 已評 API 設計（適用時）
• 已對需求評可擴展性與可靠性
• 技術債已編目並按優先排
• 已評 ADR 或註其無
• 建議具體、按優先排、可行

常見陷阱

• 評代碼非評架構：本技能關於系統層設計，非行層代碼品質。PR 層回饋用 code-reviewer
• 指定特定技術：架構評論宜識問題，非命特定工具，除非有明技術因
• 忽團隊上下文：3 人團隊之「最佳」架構異於 30 人團隊。考量組織限制
• 完美主義：每系統皆有技術債。聚焦於正致痛或阻將來工作之債
• 假設規模：勿為服 100 用戶之應用建議分散系統。架構合實需

相關技能

• security-audit-codebase — 安全聚焦之代碼與配置評
• configure-git-repository — 倉庫結構與慣例
• design-serialization-schema — 資料結構設計與演化
• review-data-analysis — 分析正確性之評（補性視角）