前言¶

做过几年后端或基础设施的同学，多半遇到过这种场景：半年前的 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