前言¶

做過幾年後端或基礎設施的同學，多半遇到過這種場景：半年前的 PR 裏把主庫從 MySQL 換成了 PostgreSQL，當時拍板的人已經離職，代碼裏也沒有留下像樣的說明。新人接手後只能對着 migration 文件猜原因，改表結構時戰戰兢兢，生怕踩中某個沒人記得的約束。

架構決策記錄（Architecture Decision Record，簡稱 ADR）正是爲了解決這個問題——把「爲什麼選 A 不選 B」寫進倉庫，讓未來的自己和隊友能追溯上下文。Michael Nygard 在 2011 年推廣了這一輕量文檔格式，Martin Fowler 也在其 Bliki 中將其總結爲「短文檔 + 不可篡改 + 被取代時鏈接新 ADR」的實踐。

難點在於：知道 ADR 有用是一回事，每次做技術選型時按模板落筆又是另一回事。Cursor 生態裏的 architecture-decision-records Skill，就是把這套工程管理流程教給 AI Agent 的可複用指令包——它不替你拍板，但能在你討論數據庫、框架或鑑權方案時，自動按規範起草 ADR，補齊備選方案與後果分析。本文基於官方 SKILL.md 與 awesome-cursor-skills 倉庫說明，介紹其定位、安裝與典型用法。

這是什麼¶

architecture-decision-records 是 spencerpauly/awesome-cursor-skills 收錄的一個 Agent Skill，歸類在「Planning & Architecture」。其核心描述爲：

Document technical decisions as Architecture Decision Records (ADRs) with context, options considered, and rationale.

（將技術決策文檔化爲 ADR，記錄背景、備選方案與決策理由。）

它遵循通用的 SKILL.md 格式，可在 Cursor、Claude Code、Codex CLI 等支持 Agent Skills 標準的工具中使用。與寫代碼、跑測試類 Skill 不同，這一條把 Agent 的能力從「補全實現」延伸到了「架構治理」——幫助團隊在決策當下就把上下文結構化落盤，而不是事後補文檔。

Skill 元數據中設置了 user-invocable: true，意味着你可以在 Agent 對話裏通過 /architecture-decision-records 顯式調用；也可以在討論架構選型時，由 Agent 根據上下文自動匹配啓用。

核心功能與亮點¶

官方 SKILL.md 主要覆蓋以下幾塊能力。

1. 明確「何時該寫 ADR」¶

Skill 規定，遇到下列特徵的技術決策時應撰寫 ADR：

• 日後難以逆轉；
• 影響系統多個部分；
• 在多個合理選項之間存在權衡；
• 六個月後很可能被同事追問「當時爲什麼這樣選」。

典型例子包括：選擇數據庫、引入新框架、調整鑑權策略、重構 API 結構、引入新的構建工具等。這與 Nygard 原文中「architecturally significant decisions」的界定一致——影響結構、非功能特性、依賴、接口或構建方式的決策，都值得留下記錄。

2. 內置 ADR 模板¶

Skill 提供了可直接複用的 Markdown 模板，建議將文件放在 docs/decisions/ 或 adr/ 目錄，並按序號命名。模板包含以下章節：

官方示例以「ADR-001: Use PostgreSQL for primary database」爲題，對比了 PostgreSQL、MongoDB、PlanetScale 三種方案，並在 Decision 中列出四條選型理由，在 Consequences 中寫明連接池、遷移兼容與擴展上限等後續工作——這種寫法比「我們用了 Postgres」信息量高出一個數量級。

3. 六步工作流¶

Skill 定義的標準流程爲：

1. Identify — 識別正在做的決策；
2. Research — 調研至少 2～3 個備選方案；
3. Write — 按模板撰寫 ADR；
4. Review — 通過 PR 或團隊討論評審；
5. Merge — 評審通過後標記爲 Accepted；
6. Reference — 在相關代碼處引用，例如 // See ADR-001。

4. 文件命名與維護規範¶

推薦目錄結構如下：

docs/decisions/
├── 001-use-postgresql.md
├── 002-adopt-trpc-over-rest.md
├── 003-switch-to-pnpm.md
└── template.md

Skill 還附帶了若干寫作建議：

• 篇幅控制在 1～2 頁；
• 使用現在時（「We choose X」而非「We chose X」）；
• 決策當時忘了寫，事後補寫也可以；
• 被取代的 ADR 應鏈接到新 ADR，不要直接刪除；
• ADR 記錄的是「決策本身」，不是完整設計文檔。

這些規則與 adr.github.io 社區實踐及 Nygard 原文精神一致：Accepted 狀態的 ADR 原則上不修改內容，變更通過新 ADR 並更新舊 ADR 的 Status 來完成。

安裝與啓用¶

該 Skill 在 awesome-cursor-skills 倉庫中僅包含一個 SKILL.md 文件，安裝方式是把整個 skill 目錄複製到 Agent 的技能目錄中。

Cursor¶

根據 Cursor 官方文檔，Skill 會從以下路徑自動發現：

推薦安裝步驟：

# 進入你的項目根目錄
cd your-project

# 創建 skill 目錄並下載官方 SKILL.md
mkdir -p .cursor/skills/architecture-decision-records
curl -o .cursor/skills/architecture-decision-records/SKILL.md \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/architecture-decision-records/SKILL.md

也可以手動從 GitHub 複製：

https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/architecture-decision-records

安裝後，打開 Cursor 側邊欄 Customize → Skills，應能在 Agent Decides 區域看到 architecture-decision-records。由於設置了 user-invocable: true，你也可以在 Agent 對話輸入 / 搜索並手動調用。

Claude Code / Codex CLI¶

Agent Skills 是開放標準（見 agentskills.io）。Cursor 文檔說明，爲兼容 Claude 與 Codex，也會從 .claude/skills/、.codex/skills/ 及對應用戶目錄加載 Skill。將同名目錄放到這些路徑下即可，具體目錄以各工具官方文檔爲準。

典型用法示例¶

場景一：數據庫選型¶

在 Agent 對話中輸入：

/architecture-decision-records

我們要爲新的訂單服務選主庫，候選是 PostgreSQL 和 MongoDB。
數據關係清晰，賬單模塊需要 ACID 事務，團隊熟悉 Prisma。
請按 ADR 模板寫一份決策記錄，放到 docs/decisions/ 目錄。

Agent 會按 Skill 中的模板生成包含 Context、Options Considered、Decision、Consequences 的 Markdown 文件，並建議合適的序號文件名（如 001-use-postgresql-for-orders.md）。

場景二：框架遷移討論¶

我們考慮把 REST API 遷移到 tRPC，請幫我起草 ADR。
至少對比 REST、tRPC、GraphQL 三種方案，列出對前端類型安全和部署的影響。

Skill 要求 Research 階段至少調研 2～3 個備選方案，Agent 會據此展開對比，而不是隻寫「我們選了 tRPC」一句話。

場景三：決策後補文檔¶

這個 PR 裏已經把包管理器從 npm 換成了 pnpm，當時沒寫 ADR。
請補一份 ADR-003，狀態直接標 Accepted，並在 Consequences 裏寫 CI 緩存變更。

Skill 明確允許事後補寫，這對治理存量項目尤其實用。

模板片段（來自官方 SKILL.md）¶

以下爲官方提供的 ADR 骨架，Agent 會在此基礎上填充項目具體內容：

# ADR-001: Use PostgreSQL for primary database

## Status

Accepted | Proposed | Deprecated | Superseded by ADR-XXX

## Date

2026-04-10

## Context

What is the problem or situation that requires a decision?
Include constraints, requirements, and forces at play.

## Options Considered

### Option A: PostgreSQL
- Pros: ACID compliance, JSON support, mature ecosystem, free
- Cons: Requires managing connections, vertical scaling limits

### Option B: MongoDB
- Pros: Flexible schema, horizontal scaling
- Cons: No transactions across collections, eventual consistency issues

## Decision

We choose **PostgreSQL** because:
1. Our data is relational — users, teams, projects with clear relationships
2. We need ACID transactions for billing operations
3. JSON columns give us schema flexibility where needed

## Consequences

- We need to manage connection pooling (use PgBouncer or Prisma's built-in pool)
- Migrations must be backwards-compatible for zero-downtime deploys
- We accept vertical scaling limits and will shard later if needed

評審通過後，可在代碼中引用 ADR 編號，例如：

// See ADR-001 — PostgreSQL chosen for ACID billing requirements

適用場景與注意事項¶

適合誰用¶

• Tech Lead / 架構師：在重大選型討論後快速產出可評審的 ADR 草稿；
• 中小團隊：沒有專職架構文檔崗位，但需要可檢索的決策日誌（decision log）；
• 開源維護者：讓貢獻者理解歷史設計約束，減少重複爭論；
• AI 輔助開發用戶：希望 Agent 不只寫代碼，也參與工程規範落地。

使用限制¶

1. Skill 是指令，不是決策引擎。它不會替你做技術判斷，輸出質量取決於你提供的上下文是否完整。
2. 需要人工 Review。Skill 工作流第 4 步明確要求團隊評審；Agent 生成的 ADR 應作爲草稿，而非直接 Accepted。
3. 不替代完整設計文檔。複雜系統的詳細設計仍需要獨立文檔；ADR 只捕獲「選了什麼、爲什麼、後果是什麼」。
4. 目錄需自行約定。Skill 建議 docs/decisions/ 或 adr/，但不會在安裝時自動創建；首次使用前可在項目中建好目錄並提交 template.md。
5. 與 saving-workspace-context 等 Skill 互補。awesome-cursor-skills 裏還有 saving-workspace-context 等 Skill 負責跨會話持久化上下文；architecture-decision-records 更聚焦「正式決策記錄」這一特定文檔類型。

小結¶

技術債不只體現在爛代碼裏，也體現在「沒人記得爲什麼當初這麼設計」。architecture-decision-records 把 ADR 這套經過十餘年驗證的輕量實踐，打包成 Agent 可執行的 Skill：何時寫、怎麼寫、如何評審與引用，都有章可循。對已經把 Cursor 用於日常開發的團隊來說，安裝成本不過複製一個 SKILL.md，卻能顯著降低架構知識隨人員流動而流失的風險。

官方 Skill 地址：

https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/architecture-decision-records