adr-skill

adr-skill 技能總覽

adr-skill 是做什麼的

adr-skill 幫助你建立與維護 Architecture Decision Records，讓它們成為可直接落地實作的文件，而不只是事後備忘。它真正的價值在於：把一個架構選擇整理成一份 coding agent 幾乎不需額外追問就能執行的 ADR，包含清楚的限制條件、明確的非目標、要修改的檔案、驗證步驟，以及具體後果。

adr-skill 最適合誰

這個技能最適合 engineering leads、staff engineers、platform teams，以及負責撰寫後續會指導開發工作的 technical writers。特別是在決策不易回頭、會影響多位貢獻者，或需要同時讓人類與 AI agents 都能理解時，adr-skill 會特別有用。

這個技能主要解決什麼工作

當你需要以下情境時，就適合使用 adr-skill：

• 提出新的架構決策
• 在實作開始前先把決策文件化
• 更新或取代既有 ADR
• 在原本沒有 ADR 的 repo 中建立初始架構
• 在整個 codebase 中維持一致的 ADR 結構

對於 adr-skill for Technical Writing 而言，最強的適配點在於：產出既能讓利害關係人讀得懂、又足夠具體到實作者可以直接採取行動的決策文件。

為什麼這個技能特別突出

它最大的差異化在於以 agent-first 的方式來設計。這個技能不會停在 context、decision 和 consequences，而是進一步要求實作計畫，包含受影響路徑、依賴關係、應遵循的模式、應避免的模式、設定變更與驗證標準。比起一般「幫我寫一份 ADR」的 prompt，這樣更能直接拿來執行。

採用前要先確認什麼

在安裝或正式依賴 adr-skill 之前，先確認你的團隊是否真的希望用 ADR 來驅動執行。如果你們流程只需要輕量的決策理由備註，這個技能可能會顯得比實際需求更有結構。如果你們需要的是能經得起交接、降低模糊地帶的 ADR，那麼這份額外嚴謹度正是它的價值所在。

如何使用 adr-skill 技能

adr-skill 的安裝情境

repo 摘要中沒有在 SKILL.md 內直接列出此技能專屬的安裝指令，但常見用法通常是：

npx skills add vercel/ai --skill adr-skill

加入後，就可以在你的 AI coding environment 裡，於即將做出或記錄架構決策時使用它。

先讀這些檔案

如果你想用最快路徑進入有效的 adr-skill usage，建議依序閱讀：

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

接著再看：

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

這個順序很重要：conventions 會先告訴你 ADR 應該放在哪裡；checklist 說明品質門檻；template variants 幫你選對結構；examples 則讓你看見預期的具體程度應該到哪裡。

adr-skill 需要你提供哪些輸入

當你提供以下資訊時，adr-skill 的表現會最好：

• 要做出的決策是什麼
• 是什麼觸發因素或問題，讓這個決策必須現在做
• repo 背景與既有架構
• 像是延遲、成本、合規、部署模式或團隊能力等限制條件
• 非目標
• 預期會受到影響的檔案、模組、服務或工作流程
• 已知且已經考慮過的替代方案

如果缺少這些輸入，這個技能還是能起草，但比較容易產出一份泛泛而談的 ADR，而不是可直接執行的版本。

如何把模糊想法變成強而有力的 prompt

一個較弱的 prompt：

• 「Write an ADR for switching databases.」

一個更適合 adr-skill usage 的 prompt：

• 「Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.」

第二種寫法，才會給 adr-skill 足夠素材，寫出另一位工程師或 agent 真正能照著實作的決策文件。

有意識地選對 template

如果決策其實大致已定，你主要是需要記錄原因、變更內容與如何實作，就用 simple template。

如果存在真正需要比較的競爭方案、有多個 decision drivers，或有利害關係人需要審查 tradeoff，就用 MADR-style template。這個技能透過以下檔案同時提供這兩種模式：

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

實務上的典型 adr-skill 工作流程

一個實際可行的流程通常會像這樣：

1. 先問這個技能：這次變更是否值得寫成 ADR。
2. 讓它反問你 context、constraints 與 non-goals。
3. 用合適的 template 起草 ADR。
4. 對照 references/review-checklist.md 做檢查。
5. 依 repo 實際路徑、命名與慣例再編修一次。
6. 在選定的 ADR 目錄中建立或更新檔案。
7. 如果有需要，之後再變更 lifecycle status。

這也是 adr-skill guide 真正有價值的地方：它支援的是整個生命週期，而不只是第一版草稿。

如何在沒有 ADR 的 repo 中建立起點

如果你的 repository 目前還沒有 ADR 結構，內附 script 會很好用：

• scripts/bootstrap_adr.js

它可以建立 ADR 目錄、產生 index/README，並新增一份初始的「Adopt architecture decision records」文件。比起手動發明資料夾布局，這樣更實際，因為 repo 已經把像是目錄偵測與命名策略這類 convention 選擇編碼進去了。

如何更快建立新的 ADR

如果你想讓建立流程可重複，請查看 scripts/new_adr.js。它支援不少實務上有用的選項，例如：

• repo root
• ADR directory override
• title
• status
• template choice: simple 或 madr
• filename strategy
• deciders、consulted 與 informed 欄位
• index updates

對於想要可重複流程、而不是一次性產文的團隊來說，這也讓 adr-skill install 更值得採用。

如何處理 status 變更

內建的 scripts/set_adr_status.js 會直接更新 ADR 內的 status。這點很重要，尤其當你的團隊把 ADR 視為會持續演進的文件，會經歷 proposed、accepted、rejected、deprecated 或 superseded 等狀態，而不是一份靜態 markdown 檔案。

會影響輸出品質的 repository 慣例

這個技能對 ADR 品質有明確主張：

• constraints 應該可衡量
• non-goals 應該明確寫出
• consequences 應該能推導出後續工作
• implementation plans 應該點出實際路徑
• verification 應該說明如何確認這個決策已被正確落實

如果你的 prompt 沒有提供這些內容，即使文字表面上仍然流暢，輸出品質也會明顯下滑。

要對齊的目錄與命名慣例

根據 references/adr-conventions.md，這個技能會優先遵循 repo 既有慣例；否則才會建議像 docs/decisions/ 或 adr/ 這類位置。它也偏好可預測的檔名格式，例如 YYYY-MM-DD-title-with-dashes.md，除非 repo 本來就使用其他慣例。

這代表你不應該盲目用技能預設值去覆蓋專案既有模式。

adr-skill 技能 FAQ

adr-skill 比一般 prompt 更好嗎？

如果你的目標是產出可長期維護、且以實作為導向的 ADR，那答案是肯定的。一般 prompt 可以寫出可讀文件，但 adr-skill 額外補上了 triggers、可衡量 constraints、non-goals、implementation planning 與 review criteria 的結構。相較於臨時拼湊的 prompt，通常更能減少模糊空間。

adr-skill 適合初學者嗎？

適合，但有一個前提：它能幫初學者寫出更好的 ADR，卻無法憑空補出缺失的架構背景。如果你剛接觸 ADR，examples 與 template variants 能有效降低上手門檻；如果你對被記錄的系統本身還不熟，就要先補足更多輸入資訊。

什麼情況下 adr-skill 不適合？

以下情況可以跳過 adr-skill：

• 變更很小，而且可逆
• 你只需要一份簡短設計備註
• 團隊不會長期維護 ADR
• 這份文件不會被拿來指導實作

在這些情境下，這套結構可能會比決策本身更重。

adr-skill 能處理更新與 superseded ADR 嗎？

可以。這個技能不只適用於建立新的 ADR，也支援更新、接受、拒絕、淘汰與 supersede 既有決策。對於架構會持續演進、而不是一成不變的 repository 來說，這點尤其重要。

adr-skill 只幫工程師，還是 technical writers 也適合？

兩者都適合。就 Technical Writing 的使用情境來說，adr-skill 的價值在於它會逼決策文件回答：到底改了什麼、為什麼是現在、哪些不在範圍內，以及該如何驗證實作。這會讓文件對工程團隊與未來維護者都更有用。

我一定要用內附 scripts 嗎？

不需要。你可以把 adr-skill 單純當成起草與審閱輔助工具。只有當你想在整個 repo 中標準化建立流程、初始化 ADR 架構，或管理 status 更新時，這些 scripts 才會特別重要。

如何提升 adr-skill 的使用效果

給 adr-skill 的是決策觸發因素，不只是主題

你最能立即改善輸出的方式，就是說清楚這份 ADR 為什麼是現在要寫。「Need an ADR for caching」很弱；「Current API p95 is 900ms, traffic doubled, and we need sub-200ms reads for product search」就強很多。觸發因素會塑造整份文件的走向。

指出具體限制與門檻

adr-skill 是為可衡量的決策而設計的。能給數字與限制時就盡量給，例如：

• latency targets
• cost ceilings
• compatibility requirements
• rollout windows
• compliance constraints
• operational ownership boundaries

這會讓輸出從抽象的架構討論，提升成真正可用於決策的文件。

及早寫出 non-goals

很多 ADR 會失敗，是因為它暗示了太多事情。請直接告訴 adr-skill 哪些明確不在範圍內：

• 不遷移 production data
• 不變更 API version
• 這份 ADR 不處理 vendor lock-in 決策
• 不做 UI redesign

明確的 non-goals 能減少 scope creep，也會讓 implementation plan 更好。

指向真實路徑與既有模式

如果你想得到真正可用的 implementation plan，就要提到 repo 裡已存在的實際檔案、模組，或可參考的相似程式碼。例如：

• 「Follow the pattern in src/payments/stripe.ts.」
• 「Avoid adding logic to pages/api/*; use route handlers under app/api/.」
• 「Config lives in infra/terraform/ and .github/workflows/.」

這是提升 adr-skill skill 輸出品質最有力的手段之一。

第一版完成後，拿 review checklist 再檢一次

不要停在第一份輸出。請把 ADR 對照 references/review-checklist.md，尤其要確認：

• newcomer 是否能看懂 trigger？
• constraints 是否具體到可以採取行動？
• 是否有點出受影響的 paths？
• follow-up tasks 與 verification steps 是否明確？
• 是否有任何 consequence 只是把 decision 換句話說？

這份 checklist 才是這個技能許多實務價值真正落地的地方。

選擇符合決策型態的 template

常見失敗模式之一，是把選項很多的 MADR 結構套在一個單純選擇上，或是在利害關係人需要查看 tradeoff 時反而用 simple template。讓 template 跟決策複雜度匹配，ADR 才會維持可讀性。

避免停留在 placeholder 等級的文字

repo 裡的 examples 已經明確表達：placeholder 式文字不應該留在正式 ADR 裡。如果第一版草稿裡還有像「use best practices」或「update relevant files」這種模糊說法，請把它重寫成具體可操作的細節，例如：

• 特定 dependency versions
• 指名的 configs
• migration order
• rollout 或 rollback checks
• 精確的 test classes 或 suites

不只打磨 Decision，也要打磨 Consequences

很多人會反覆修改 Decision 區段，卻忽略 Consequences。這是常見錯誤。強而有力的 consequences 應該要讓未來實作者知道：接下來什麼會更容易、什麼會更困難、什麼風險更高、成本更高，或有哪些事項從此變成必做。如果 consequences 太弱，這份 ADR 就無法真正指導執行。

提升 adr-skill 的團隊採用度

如果你希望團隊更廣泛使用 adr-skill，請先在這三件事上標準化：

• 一種 ADR directory convention
• 依決策類型對應的一個預設 template choice
• 一套 status vocabulary

這會降低使用摩擦，也會讓這個技能附帶的 scripts 在不同 repositories 中更好發揮作用。

發布前最值得做的最後檢查

在接受一份由 adr-skill 起草的 ADR 之前，請先問一個嚴格的問題：一個 coding agent 是否能在不依賴隱性團隊知識的情況下，直接實作這項變更？如果答案是否定的，就繼續補上 context、paths、patterns、constraints 或 verification steps，直到答案變成可以。