skills.rest
freedom909
freedom909COMMUNITY
Explore all skills by this author →
GitHub

architecture-decision-records

Captures architectural decisions as structured ADR documents in a docs/adr directory.

Updated Mar 18, 2026
Search Tags:#documentation#markdown#codebase#adr#architecture decisions#decision log#technical rationale
One-click install
npx skills add https://github.com/freedom909/real-estate-saas --skill architecture-decision-records-freedom909
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/freedom909/real-estate-saas/tree/main/.trae/skills/architecture-decision-records
Command: npx skills add https://github.com/freedom909/real-estate-saas --skill architecture-decision-records-freedom909

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architectural decisions made during coding sessions often live only in chat threads, PR comments, or memory, leaving future developers unable to understand why the codebase is shaped the way it is. This Skill records those decisions as structured, versioned ADR documents alongside the code. ## Core Features & Use Cases - Decision Detection: Recognizes explicit signals ("let's record this decision") and implicit signals (choosing between frameworks, databases, or patterns) during conversations. - Structured ADR Format: Generates lightweight Nygard-style ADRs with context, decision, alternatives considered, and consequences sections. - ADR Index & Lifecycle: Maintains a numbered ADR log in docs/adr/ with an index table and status lifecycle (proposed, accepted, deprecated, superseded). - Use Case: After deciding to use PostgreSQL over MongoDB for your primary datastore, ask the assistant to record the decision; it drafts ADR-0002 with rationale and rejected alternatives, then writes it to docs/adr/ after your approval. ## Quick Start Ask the assistant to record the decision we just made about our database choice as an ADR.

Frequently Asked Questions about architecture-decision-records

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I record an architecture decision record during a coding session?▼

Say "record this decision" or "ADR this" when making an architectural choice. The assistant drafts a structured ADR with context, alternatives, and consequences, then writes it to docs/adr/ only after your explicit approval.

What format does an architecture decision record use?▼

It uses the lightweight Nygard ADR format with sections for date, status, deciders, context, decision, alternatives considered with pros and cons, and consequences including risks. Each ADR is a short markdown file readable in about two minutes.

How do I find out why a past technology choice was made?▼

Ask "why did we choose X?" and the assistant scans the docs/adr/README.md index, reads matching ADR files, and presents the Context and Decision sections. If no ADR exists, it offers to record one.

Does the skill create ADR files automatically without asking?▼

No. It requires explicit user consent before creating the docs/adr/ directory and before writing any ADR file. Implicit decision signals only trigger a suggestion to record an ADR, never automatic file creation.

When should I not create an ADR for a decision?▼

Skip ADRs for trivial choices like variable naming or formatting. Reserve them for technology choices, architecture patterns, API design, data modeling, infrastructure, security, and testing strategy decisions with real trade-offs.

Related Skills

Explore More Software Engineering Skills→
Prathmesh2000Prathmesh2000
1

brainstormer

Explore 2-4 design approaches with trade-offs and a recommended plan.

Community
Advanced
zorgentechzorgentech

create-adr

Create Architecture Decision Records from pull request metadata and diffs.

Official
Intermediate
CuriousLearnerCuriousLearner
27

architecture-documenter

Document system architecture and technical decisions with diagrams and ADRs.

Community
Advanced
ThrimbdaThrimbda
13

legion-docs

Classify task information into per-task documents and cross-task wiki.

Community
Intermediate