Preface¶

Most developers who have worked in backend or infrastructure roles for a few years have encountered this scenario: a PR from six months ago switched the primary database from MySQL to PostgreSQL, the person who approved the decision has since left the company, and there is no proper documentation left in the codebase. New team members can only guess the reasoning from migration files, and tremble when modifying table structures for fear of stumbling upon some long-forgotten constraint.

The Architecture Decision Record (ADR) was created to solve this exact problem—documenting “why we chose A over B” directly in the repository, so that future you and your teammates can trace the original context. Michael Nygard popularized this lightweight documentation format in 2011, and Martin Fowler summarized the practice in his Bliki as “short documents + immutability + linking to new ADRs when superseded”.

The challenge lies in this: knowing that ADRs are useful is one thing, but actually following a template for every technical decision is another. The architecture-decision-records Skill in the Cursor ecosystem is a reusable instruction pack that teaches this engineering management workflow to AI Agents. It does not make decisions for you, but will automatically draft ADRs according to specifications when you discuss databases, frameworks, or authentication schemes, filling in alternative options and consequence analysis. This article introduces its positioning, installation, and typical usage based on the official SKILL.md and the awesome-cursor-skills repository.

What It Is¶

architecture-decision-records is an Agent Skill featured in spencerpauly/awesome-cursor-skills, categorized under “Planning & Architecture”. Its core description is:

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

It follows the universal SKILL.md format and can be used in tools that support the Agent Skills standard, such as Cursor, Claude Code, and Codex CLI. Unlike skills for writing code or running tests, this skill extends Agent capabilities from “completing implementations” to “architecture governance”—helping teams formally document context at the time of decision-making, rather than retroactively writing documentation later.

The Skill metadata sets user-invocable: true, meaning you can explicitly call it via /architecture-decision-records in Agent conversations; it can also be automatically matched and enabled by the Agent based on context during architecture selection discussions.

Core Features and Highlights¶

The official SKILL.md covers the following key capabilities:

1. Clarify “When to Write an ADR”¶

The Skill specifies that ADRs should be written for technical decisions with these characteristics:
- Difficult to reverse in the future
- Affect multiple parts of the system
- Involve tradeoffs between multiple reasonable options
- Likely to be questioned by colleagues six months later about why the choice was made

Typical examples include: selecting a database, introducing a new framework, adjusting authentication policies, refactoring API structures, or introducing new build tools. This aligns with the definition of “architecturally significant decisions” from Nygard’s original article—decisions that affect structure, non-functional characteristics, dependencies, interfaces, or build processes all deserve to be recorded.

2. Built-in ADR Template¶

The Skill provides a reusable Markdown template, recommended to be placed in the docs/decisions/ or adr/ directory and named with a sequential number. The template includes these sections:

The official example is titled “ADR-001: Use PostgreSQL for primary database”, comparing three options: PostgreSQL, MongoDB, and PlanetScale. It lists four selection justifications in the Decision section and details follow-up work such as connection pooling, migration compatibility, and scaling limits in the Consequences section—this approach is an order of magnitude more informative than a simple “We used Postgres”.

3. Six-Step Workflow¶

The Skill defines a standard process:
1. Identify — Recognize the decision being made
2. Research — Investigate at least 2-3 alternative solutions
3. Write — Draft the ADR using the template
4. Review — Get approval via PR or team discussion
5. Merge — Mark as Accepted after review
6. Reference — Link to the ADR in relevant code, e.g. // See ADR-001

4. File Naming and Maintenance Standards¶

The recommended directory structure is:

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

The Skill also includes several writing recommendations:
- Keep the length between 1 and 2 pages
- Use present tense (“We choose X” instead of “We chose X”)
- It’s okay to write the ADR retroactively after the decision
- Superseded ADRs should link to the new ADR instead of being deleted outright
- ADRs record the decision itself, not full design documents

These rules align with community practices from adr.github.io and the spirit of Nygard’s original article: Accepted ADRs should generally not be modified, and changes are made via new ADRs with the status of the old ADR updated accordingly.

Installation and Activation¶

This Skill in the awesome-cursor-skills repository only contains a single SKILL.md file. The installation method is to copy the entire skill directory into the Agent’s skills directory.

Cursor¶

According to the Cursor official documentation, Skills are automatically discovered from these paths:

Recommended installation steps:

# Navigate to your project root directory
cd your-project

# Create the skill directory and download the official 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

You can also manually copy from GitHub:

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

After installation, open Cursor’s sidebar Customize → Skills, and you should see architecture-decision-records in the Agent Decides section. Since user-invocable: true is set, you can also search and manually call it by typing / in an Agent conversation.

Claude Code / Codex CLI¶

Agent Skills is an open standard (see agentskills.io). Cursor documentation states that for compatibility with Claude and Codex, Skills can also be loaded from .claude/skills/, .codex/skills/, and their corresponding user directories. Simply place the same-named directory in these paths, referring to each tool’s official documentation for specific details.

Typical Usage Examples¶

Scenario 1: Database Selection¶

Enter this in an Agent conversation:

/architecture-decision-records

We need to select a primary database for the new order service, with PostgreSQL and MongoDB as candidates.
The data has clear relational structures, the billing module requires ACID transactions, and the team is familiar with Prisma.
Please draft a decision record according to the ADR template and place it in the docs/decisions/ directory.

The Agent will generate a Markdown file containing Context, Options Considered, Decision, and Consequences sections based on the Skill’s template, and suggest an appropriate numbered filename (e.g. 001-use-postgresql-for-orders.md).

Scenario 2: Framework Migration Discussion¶

We are considering migrating our REST API to tRPC. Please help me draft an ADR.
Compare at least three options: REST, tRPC, and GraphQL, and list the impacts on frontend type safety and deployment.

The Skill requires at least 2-3 alternative solutions to be researched during the Research phase, so the Agent will conduct a comparative analysis instead of just writing a single sentence like “We chose tRPC”.

Scenario 3: Retroactive Documentation¶

This PR already switched the package manager from npm to pnpm, but we didn't write an ADR at the time.
Please draft ADR-003 with the status marked as Accepted directly, and include CI cache changes in the Consequences section.

The Skill explicitly allows retroactive documentation, which is especially useful for governing existing projects.

Template Snippet (from official SKILL.md)¶

Below is the official ADR skeleton, which the Agent will populate with project-specific details:

# 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

After review and approval, you can reference the ADR number in code, for example:

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

Applicable Scenarios and Notes¶

Who Should Use This¶

• Tech Leads / Architects: Quickly produce reviewable ADR drafts after major selection discussions
• Small and Medium Teams: Without dedicated architecture documentation roles, but needing searchable decision logs
• Open Source Maintainers: Let contributors understand historical design constraints and reduce repetitive arguments
• AI-assisted Development Users: Want Agents to not only write code but also implement engineering specifications

Usage Restrictions¶

1. Skills are instructions, not decision engines. It will not make technical judgments for you, and the output quality depends on the completeness of the context you provide.
2. Manual review is required. Step 4 of the Skill workflow explicitly requires team review; ADRs generated by Agents should be treated as drafts, not directly marked as Accepted.
3. It does not replace full design documents. Detailed designs for complex systems still require independent documentation; ADRs only capture “what was chosen, why, and what the consequences are”.
4. Directory conventions must be agreed upon separately. The Skill recommends docs/decisions/ or adr/, but will not automatically create them during installation; you can create the directory and submit template.md in the project before first use.
5. Complementary to other Skills like saving-workspace-context. The awesome-cursor-skills repository also includes Skills like saving-workspace-context for persisting context across sessions; architecture-decision-records focuses specifically on “formal decision records”.

Summary¶

Technical debt is not only reflected in messy code, but also in “no one remembers why the system was designed this way originally”. architecture-decision-records packages the decade-proven lightweight ADR practice into an executable Agent Skill: when to write, how to write, and how to review and reference, all follow clear guidelines. For teams already using Cursor for daily development, the installation cost is just copying a single SKILL.md file, but it can significantly reduce the risk of architectural knowledge being lost as personnel turnover.

Official Skill address:

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