adr-writer

adr-writer 技能是軟體工程師與架構師的結構化助手，旨在維護儲存庫中的高品質技術文件。透過嚴格遵守「Design It!」方法論，此工具協助建立架構決策記錄 (ADR)，解釋關鍵技術決策背後的動機，確保團隊知識得以長期保存，並在程式碼審查或系統重構期間使決策易於追溯。它提供包含狀態追蹤、情境分析、具體決策陳述以及正反面影響評估的標準化範本，協助團隊避免架構漂移並提升決策透明度。

• 提供 ADR 的預先設定 Markdown 範本，確保包含所有必要章節（狀態、情境、決策、結果）。

• 引導使用者完成架構決策生命週期，從草稿 (Draft)、提案 (Proposed) 到已接受 (Accepted)、已取代 (Superseded) 或已棄用 (Deprecated) 的狀態。

• 協助根據既定標準判斷特定技術變更是否構成架構決策。

• 鼓勵落實最佳實踐，例如保持 ADR 專注、簡短（1-2 頁），並與版本控制的原始碼共置。

• 提供明確的協議以將決策標記為「已取代」而非直接刪除，促進存檔流程。

• 使用者輸入其架構變更的標題與範疇，即可獲得格式化的 ADR 草稿。

• 非常適合用於新功能設計階段、系統遷移，或是當需要共識來應對複雜技術挑戰時。

• 最佳實踐建議將這些文件儲存在特定目錄（例如 docs/adr/）中，以確保它們能與相關程式碼庫一起被輕易發現。

• 產出物應被視為程式碼，這意味著在標記為「已接受」之前，應經過同行評審與 PR 流程。

• 堅持「一個檔案一個決策」的原則，以維持不斷發展的軟體架構中的清晰度與維護便利性。