| name | sunnydata-architecture-review |
| description | Architecture-level code review using a three-phase smells → principles → fixes flow. Use when reviewing existing system architecture, identifying design debt, evaluating refactor candidates, or auditing module boundaries and dependencies. Complements sunnydata-code-review (line-level) and architect agent (greenfield design). |
繁體中文說明：此技能提供「架構級」code review 的結構化流程 — 先掃壞味道 (smells) → 反向對應違反的原則 (principles) → 推薦具體修法 (fixes)。三階段順序固定，不可跳過。本 skill 補充 sunnydata-code-review（行級實作審查）與 architect agent（全新設計）之間的空缺：對既有系統做結構性、有證據的、可決策的架構審查。
Architecture Review
Overview
Three phases, fixed order. Skipping a phase invalidates the review.
Detect Smells → Map to Principles → Propose Fixes → Output Report
Why this order is mandatory:
- 沒有 smells = 沒有要修的東西，不要硬找。
- 找到 smells 卻對應不上原則 = 主觀判斷，必須剔除。
- 對應上原則卻沒有具體 fix = 抱怨而非審查。
Core principles across all phases:
- Evidence before claims — 每個 finding 必須有檔案路徑＋行號或可驗證的指標。
- Severity over sentiment — 用 Critical/High/Medium/Low 分級，不用「好/不好」。
- Vocabulary over vibes — 必須使用業界共通行話（見
terminology.md），不接受自創詞。
When to invoke:
- 模組／服務合併到 main 前的架構守門
- 技術債盤點與重構優先級排序
- 新人 onboarding 走讀既有系統
- 評估「要重寫還是要修」的決策依據
- PR 觸及 3+ 模組或新增 100+ 行時的結構性審查
When NOT to invoke:
- 行級實作審查 → 用
sunnydata-code-review
- 全新系統的架構設計 → 用
architect agent
- 模板合規檢查 → 用
template-check command
- Bug 修復、typo、單檔小改 → 直接審查不需此流程
Phase 1: Detect Smells
Iron Rule
NO SMELL WITHOUT EVIDENCE
「感覺有問題」「好像不對」不算證據。每個 smell 必須附：
- 檔案路徑＋行號 或
- 可量化指標（方法行數、圈複雜度、依賴數量、N+1 查詢次數、p99 延遲等）
Five-Dimension Scan Matrix
掃描必須覆蓋全部 5 個維度。即使某維度無 finding，也要在報告中明確聲明 "no findings"。
| 維度 | 對應 smell（節錄自 terminology.md） | 證據蒐集指令範例 |
|---|
| Dependency 依賴 | Cyclic Dependency、Big Ball of Mud、Inappropriate Intimacy、Parallel Inheritance | rg -l "import.*from" / 模組依賴圖 / git log --follow |
| Modularity 模組化 | God Object、Long Method、Large Class、Feature Envy、Divergent Change、Shotgun Surgery | wc -l / 函式行數分布 / 同檔案修改頻率 |
| Performance 效能 | N+1 查詢、Switch Statements、Primitive Obsession（在熱路徑上） | rg "for.*\.find" / APM trace / DB query log |
| Distributed reliability 分散式可靠性 | 缺 Circuit Breaker、缺 Idempotent Consumer、缺 Outbox、缺 DLQ、雙寫不一致、Backpressure 缺失 | rg "retry|circuit|idempot" / 訊息系統設定 |
| Technical debt 技術債 | Lava Flow、Speculative Generality、Refused Bequest、Comments Smell、Middle Man、Temporary Field | git blame / rg "TODO|FIXME|HACK" / 死碼掃描 |
Severity Definitions
| 等級 | 定義 | 範例 |
|---|
| Critical | 立即危害正確性或可用性，或會導致資料遺失 | 雙寫不一致、缺 idempotent 導致重複扣款、循環依賴致無法部署 |
| High | 6 個月內必修，否則阻礙可擴展性／團隊速度 | God Object 已 1500+ 行、缺 Circuit Breaker 在外部依賴上 |
| Medium | 影響可維護性，但可規劃 1-2 季處理 | Long Method、N+1 在非熱路徑、過多 switch |
| Low | 風格或可讀性問題 | 命名不一致、過度註解、Temporary Field |
Smell Output Template
每個 finding 在 Phase 1 結束時必須能填完此表：
Smell: <terminology.md 中的標準名稱>
Location: <絕對或專案相對路徑:行號>
Evidence: <一行可驗證的事實或指標>
Severity: Critical | High | Medium | Low
找不到 5 個以上 smell 的審查通常不可信 — 不是系統完美，是審查太淺。挑戰自己再掃一次。
Phase 2: Map to Principles
Iron Rule
EVERY SMELL MUST VIOLATE A NAMED PRINCIPLE
對應不上原則的 smell 一律剔除。可選原則必須來自 terminology.md 的 Principles 區段（SOLID / KISS / DRY / YAGNI / LoD / Tell-Don't-Ask / Boy Scout Rule / Clean Architecture / Hexagonal / Onion）。
Mapping Cheat Sheet（節錄）
| Smell | 違反原則 | 為什麼 |
|---|
| God Object | SRP | 一個類承擔多個變更理由 |
| Feature Envy | LoD | 過度與「非直接朋友」對話 |
| Long Parameter List | KISS / Tell-Don't-Ask | 暴露內部細節給呼叫方 |
| Duplicated Code | DRY | 同邏輯多處複製 |
| Speculative Generality | YAGNI | 為不存在的需求預留彈性 |
| Cyclic Dependency | DIP / Hexagonal | 內層依賴外層或彼此糾纏 |
| Switch Statements | OCP / LSP | 新增類型必須改現有程式碼 |
| Refused Bequest | LSP | 子類無法替換父類 |
| 雙寫不一致 | Outbox（缺）/ Transaction Boundary | 跨資源無一致性保證 |
| 缺 Circuit Breaker | Bulkhead 隔艙原則 | 單點失敗會擴散 |
Principle Match Output Template
Smell: <Phase 1 finding>
Violates: <原則名稱（terminology.md 編號）>
Why: <一句話說明違反在哪>
Counter-evidence: <若反駁此原則違反，需提供什麼證據？>
Counter-evidence 欄位是防呆 — 強迫審查者預想反駁，避免主觀套用原則。
Phase 3: Propose Fixes
Iron Rule
EVERY FIX MUST CITE A PATTERN OR PRACTICE FROM terminology.md
不接受「重寫一下」「優化一下」這種無詞彙的建議。每個 fix 必須命名一個或多個 Pattern / Practice。
Fix Proposal Template
For Smell: <Phase 1 finding>
Violates: <Phase 2 principle>
Option A (recommended):
Pattern: <terminology.md Pattern/Practice 名稱>
Steps: <3-5 條具體執行步驟>
Effort: S (< 1 day) | M (1-5 days) | L (> 1 week)
Risk: <破壞性 / 回歸風險 / 團隊熟悉度評估>
ADR needed: Yes | No
Option B (alternative):
...同上格式...
Trade-off: <為何選 A 而非 B 的一句話>
至少兩個方案是強制要求 — 單一方案 = 沒做取捨。Trade-off 欄位必填。
Common Smell-to-Fix Map（節錄）
| Smell | 候選 Pattern / Practice |
|---|
| God Object | Extract Class、Compound Pattern (Composite/Strategy) |
| Long Method | Extract Method、Replace Conditional with Polymorphism |
| Feature Envy | Move Method、Introduce Service |
| Switch Statements | Strategy、State、Polymorphism |
| Cyclic Dependency | Dependency Inversion、Anti-Corruption Layer |
| N+1 Query | Eager Loading、Batch Fetch、DataLoader Pattern |
| 缺 Idempotent | Idempotent Consumer、Idempotency Key |
| 雙寫不一致 | Outbox Pattern、Saga |
| 缺 Circuit Breaker | Circuit Breaker、Bulkhead、Retry+Backoff+Jitter |
| Lava Flow | Strangler Fig、Branch by Abstraction |
| Speculative Generality | YAGNI Cleanup、Inline 化 |
ADR Trigger
任何 Critical 或 High 的 fix 必須建議寫入 .claude/context/decisions/architecture-review-{YYYY-MM-DD}-{topic}.md，依 subagent-context.md 規則執行。
Output Format
審查最終報告必須使用此骨架，不可省略任何區段。
# Architecture Review: <Scope>
- **Date**: <YYYY-MM-DD>
- **Reviewer**: <agent / human>
- **Scope**: <模組路徑 / 服務名 / PR 範圍>
- **Commit range**: <git SHA range, 若適用>
## Summary
- **Smells found**: <總數> (Critical: <n>, High: <n>, Medium: <n>, Low: <n>)
- **Dimensions covered**: Dependency / Modularity / Performance / Distributed / TechDebt
- **Recommended next action**: <一句話, 例如「先修 Critical 的 Outbox 缺失再合併」>
- **ADR candidates**: <數量>
## Findings
### [Critical] Smell: <名稱>
- **Evidence**: `path/to/file.py:123` — <一行事實>
- **Violates**: <原則名稱>
- **Why it matters**: <一句話>
- **Proposed fix**:
- Option A: <Pattern> — <Effort: S/M/L> — <Risk>
- Option B: <Pattern> — <Effort: S/M/L> — <Risk>
- Trade-off: <一句話>
- **ADR needed**: Yes
### [High] Smell: <名稱>
...
### [Medium] Smell: <名稱>
...
## Dimension Coverage
| 維度 | Findings | Status |
| :--- | :--- | :--- |
| Dependency | <n> | covered / no findings |
| Modularity | <n> | covered / no findings |
| Performance | <n> | covered / no findings |
| Distributed reliability | <n> | covered / no findings |
| Technical debt | <n> | covered / no findings |
## ADR Candidates
- [ ] `architecture-review-<date>-<topic>.md` — <一句話標題>
## Open Questions
- <無法在審查中決定、需要 stakeholder 回答的問題>
Forbidden Phrases
仿 sunnydata-code-review 規則，以下表述在審查報告中禁止出現：
| 禁止 | 必須 |
|---|
| "looks good" | "passes dimensions X, Y, Z with no findings" |
| "seems fine" | "no Critical/High findings; Medium documented" |
| "should be ok" | "verified by ; pass" |
| "could be better" | " at ; severity " |
| "maybe consider" | "Option A: ; Option B: ; recommend A because " |
| "in my opinion" | " requires ; current code shows " |
| "perhaps refactor" | "Apply with effort <S/M/L> and risk " |
Integration with Other Skills
| 場景 | 流程 |
|---|
| PR 合併前 | sunnydata-architecture-review → 若無 Critical → sunnydata-code-review（行級） |
| 新模組設計 | architect agent（設計）→ 實作 → sunnydata-architecture-review（驗收） |
| 技術債盤點 | sunnydata-architecture-review（找出所有 High+）→ 排序 → ADR 寫入 decisions/ |
| Onboarding 走讀 | sunnydata-architecture-review（產出系統地圖）→ 補入 docs |
| 大型重構決策 | sunnydata-architecture-review → architect agent（重新設計受影響部分） |
How to Invoke
Direct invocation（主 agent 直接執行）
主 agent 載入此 skill，依三階段流程執行，產出報告。適合單次、範圍明確的審查。
Via subagent（dispatch architecture-reviewer.md）
使用 architecture-reviewer.md 作為 subagent 模板，dispatch 給專責 agent 執行，回傳結構化報告。適合：
- 範圍大（多模組／整個服務）
- 需要與其他 subagent 平行執行
- 主 agent 想保留 context window
dispatch 後的結論依 subagent-context.md 規則寫入 .claude/context/decisions/。
Reference loading
terminology.md 預設不載入 context — 由 reviewer 在需要查特定詞彙時主動 Read。這降低 skill 啟動成本。
Quick Reference
| 我想… | 用什麼 |
|---|
| 找出系統有哪些壞味道 | Phase 1 + 五維度矩陣 |
| 知道某 smell 的標準名稱 | terminology.md Smells 區段 |
| 為某 smell 找修復模式 | terminology.md Patterns 區段 + Smell-to-Fix Map |
| 評估重構優先級 | Severity 表 + Effort 評估 |
| 把審查報告寫成 ADR | .claude/context/decisions/ + subagent-context.md 範本 |
| 大型範圍／平行審查 | architecture-reviewer.md subagent |
