ADR 建立器 是做什麼的?
建立簡潔的架構決策記錄,解釋一項決策、促使決策的背景、考量的選項,以及接受的後果。
觸發合約
當使用者要求建立 ADR、架構決策記錄、技術決策記錄,或任何關於技術或架構選擇的正式記錄時,使用此技能。
預設使用訪談模式,除非使用者已提供足夠資訊來草擬完整的 ADR。以使用者的語言提出訪談問題。ADR 成品語言為英文,除非使用者明確要求其他語言。
嚴格規則
- 訪談模式下一次只問一個問題。
- 在訪談開始時陳述一次:使用者可以跳過問題或隨時終止訪談。
- 維持動態的估計剩餘問題計數器;當依賴關係出現或消失時更新它。
- 當有助於使用者回應時,推薦簡短的範例答案。
- 將訪談問題格式化為可讀的 Markdown,而非純文字。
- 在草擬前,建設性挑戰模糊、矛盾或缺乏理由的答案;若使用者明確要求繼續,則繼續進行。
- 不要自行發明選項、優點、缺點或理由。當缺少選項時提問。
- 當決策已做出時使用
Accepted;對於提案、評估或不確定狀態使用Proposed。 - 只有當使用者明確要求檔案/路徑時,才寫入或修改檔案。
訪談流程
僅收集必要的資訊,以依賴關係優先:
- 決策標題與狀態。
- 背景:問題、限制、驅動因素,以及為何此決策現在很重要。
- 選擇的方案或提案。
- 考量的選項,每個優缺點。
- 後果:好處、缺點、風險與取捨。
- 只有在有有用的待辦事項或未解決問題時才進行後續追蹤。
問題格式:
### 問題 N — [聚焦的問題]
**推薦回答:** [有用時的簡短範例]
**為何重要:** [簡短原因]
**估計剩餘問題數:** ~M
迷你範例:
### 問題 1 — 此決策是否已做出,還是仍處於提案階段?
**推薦回答:** 「已接受——我們已經為帳務資料選擇了 PostgreSQL。」
**為何重要:** 狀態會決定 ADR 記錄的是最終選擇,還是正在審核中的提案。
**估計剩餘問題數:** ~5
輸出合約
在草擬之前,先讀取 assets/template-markdown.md 並填入該結構。
預設情況下,將最終 ADR 回傳為一個 Markdown 程式碼區塊,且不建立檔案。若使用者明確要求檔案/路徑,則將 ADR 儲存至該處,並在對話中摘要儲存的路徑。
永遠不要在最終 ADR 中留下預留指示。若使用者故意跳過必要細節,則僅對該跳過的細節使用 TBD,並盡量少用。
參考資料
- 範本:
assets/template-markdown.md