documentation-and-adrs：記下為什麼這樣做，不只記下改了什麼
記錄架構決定、替代方案與限制，讓後來的人和代理理解程式背後的原因。
學完會知道
- 理解 documentation-and-adrs 在開發流程裡負責的工作
- 判斷什麼情況適合使用 documentation-and-adrs
- 完成通用 Skills CLI、Codex 或 Claude Code 安裝
開始前先準備
- 可使用支援 Agent Skills 的 coding agent
- 準備一個能實際驗證的小型開發任務
這個 Skill 在做什麼
記錄架構決定、替代方案與限制，讓後來的人和代理理解程式背後的原因。
為什麼有用
程式碼能告訴你現在怎麼做，卻很少說明當初排除了哪些選項。這個 Skill 把背景、取捨與後果寫進 ADR，避免下一個人誤把刻意的限制當成錯誤。
適合什麼場景
- 團隊在兩種架構方案中做出選擇。
- 公開 API 或使用者行為發生改變。
- 新成員與代理需要理解既有設計理由。
和站內相近內容的差別
Wayfinder、Research 與 Handoff 用 map 和 tickets 保存跨 session 決策。documentation-and-adrs 不負責探索路線，它負責把已做出的架構決定寫成能長期維護的紀錄。
如何安裝
想先查看可選清單，可以執行：
npx skills add addyosmani/agent-skills --list只安裝這一個 Skill：
npx skills add addyosmani/agent-skills --skill documentation-and-adrs安裝完整 24 個 Skills：
npx skills add addyosmani/agent-skills這個 Skill 的 SKILL.md 沒有引用上游根目錄的共用 references。只想使用這一個流程時，可以單獨安裝；若會串接其他開發階段，再裝整套會比較省事。
手動安裝時，先 clone 上游 repo，再把整個 Skill 資料夾放進代理使用的 skills 目錄：
git clone https://github.com/addyosmani/agent-skills.git來源資料夾是 skills/documentation-and-adrs/。如果上面列出共用 references，還要保留上游的相對路徑。
Codex
Codex CLI 0.122 以上可安裝整套原生外掛：
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills安裝後重新開啟 session。手動指定時輸入 @documentation-and-adrs；也可以直接描述任務，讓 Codex 依 Skill 的 description 自動選用。
Claude Code
Claude Code 可從 marketplace 安裝：
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills此外掛也提供 /spec、/plan、/build、/test、/review、/code-simplify 與 /ship 等流程指令。這些指令會編排對應 Skills，不代表每個指令都只使用本頁這一個 Skill。
自動啟用還是手動指定
自動優先。架構或公開介面改變時就應主動提醒補 ADR。內容與取捨仍要由人檢查，不能讓代理自行宣告決策成立。
在 Codex 手動呼叫的寫法：
@documentation-and-adrs
請依這個 Skill 的原始流程處理目前任務，完成後列出驗證證據。