opencode-workflow/skills/error-model-design

錯誤模型設計 (Error Model Design) 知識合約指南

概述

error-model-design 是知識合約，用來設計錯誤分類、傳播策略、可重試 vs 不可重試錯誤、Partial Failure 行為與回退策略。供 design-architecture 在定義錯誤處理時參考。

核心原則

錯誤處理必須系統性設計，不能事後才追加。每個錯誤分類必須可追溯到 PRD edge case 或 NFR。錯誤模型必須在整個系統中保持一致。

設計重點

• 錯誤分類：Client Errors (4xx)、Server Errors (5xx)、Business Rule Violations、Timeout Errors、Cascading Failures
• 錯誤傳播策略：Fail-Fast、Graceful Degradation、Circuit Breaker
• 錯誤回應格式：一致的錯誤碼、機器可讀與人類可讀的訊息
• Retryable vs Non-Retryable：何時可重試、何時不可重試
• Partial Failure 行為：All-or-nothing、Best-effort、Saga/Compensation
• 回退策略：每個外部依賴的回退行為

知識合約職責

• 提供錯誤處理的理論指引
• 說明各種模式的 Trade-offs 與適用場景
• 不直接產生錯誤代碼定義或實作程式碼

不應做的事

• 不替系統定義具體的錯誤碼
• 不假設所有錯誤都是同樣處理方式
• 不忽略 Partial Failure 場景