Architecture Decision Records
Capture significant technical choices as Architecture Decision Records with context, options, rationale, and consequences for future you and collaborators.
Overview
Architecture Decision Records is an agent skill most often used in Build (also Validate scope, Operate iterate) that documents significant technical decisions with context, options, rationale, and consequences in ADR for
Install
npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill architecture-decision-recordsWhat is this skill?
- Four-step process: context and drivers → options and tradeoffs → decision and rationale → link ADRs and update status
- Defines when to write vs skip ADRs (framework adoption vs minor version bumps)
- Captures context, decision, and consequences—the ADR triad—for architectural choices
- Supports onboarding, historical review, and formal decision-making processes
- Community-sourced patterns for maintaining ADR libraries over time
- 4-step ADR instruction workflow in SKILL.md
- ADR triad: context, decision, and consequences
Adoption & trust: 633 installs on skills.sh; 40.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You made a major stack or design call but only left a commit message, so future you cannot reconstruct tradeoffs or onboard anyone quickly.
Who is it for?
Solo builders adopting new frameworks, splitting services, or standardizing how architectural choices are recorded in the repo.
Skip if: Minor patches, routine dependency bumps, or changes with no architectural decision to capture—as the skill’s anti-patterns state.
When should I use this skill?
Making significant architectural decisions, documenting technology choices, recording design trade-offs, onboarding teammates, or reviewing historical decisions.
What do I get? / Deliverables
You produce a maintained ADR set with linked records and updated status that preserves why decisions were made and what they cost.
- ADR documents with context, options, decision, and consequences
- Linked ADR index with status updates
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/docs is the canonical home because ADRs document how the product is shaped while you are still making structural technology calls. docs subphase matches decision logs and onboarding artifacts rather than runtime monitoring or marketing copy.
Where it fits
Record why you chose Postgres over SQLite before building the MVP schema.
Write an ADR when adopting a new frontend framework mid-product.
Supersede an old ADR when migrating auth providers and link the successor record.
How it compares
Structured decision log templates—not a linter, deploy skill, or automatic architecture generator.
Common Questions / FAQ
Who is architecture-decision-records for?
Indie developers and small teams who want lightweight, searchable records of meaningful technical decisions without a heavyweight governance process.
When should I use architecture-decision-records?
During Validate when framing scope and technology bets, during Build when adopting frameworks or recording design tradeoffs, and during Operate when reviewing or superseding past decisions.
Is architecture-decision-records safe to install?
It is documentation guidance with no inherent runtime risk—still review Security Audits on this Prism page for the parent skill package source.
SKILL.md
READMESKILL.md - Architecture Decision Records
# Architecture Decision Records Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions. ## Use this skill when - Making significant architectural decisions - Documenting technology choices - Recording design trade-offs - Onboarding new team members - Reviewing historical decisions - Establishing decision-making processes ## Do not use this skill when - You only need to document small implementation details - The change is a minor patch or routine maintenance - There is no architectural decision to capture ## Instructions 1. Capture the decision context, constraints, and drivers. 2. Document considered options with tradeoffs. 3. Record the decision, rationale, and consequences. 4. Link related ADRs and update status over time. ## Core Concepts ### 1. What is an ADR? An Architecture Decision Record captures: - **Context**: Why we needed to make a decision - **Decision**: What we decided - **Consequences**: What happens as a result ### 2. When to Write an ADR | Write ADR | Skip ADR | |-----------|----------| | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes | ### 3. ADR Lifecycle ``` Proposed → Accepted → Deprecated → Superseded ↓ Rejected ``` ## Templates ### Template 1: Standard ADR (MADR Format) ```markdown # ADR-0001: Use PostgreSQL as Primary Database ## Status Accepted ## Context We need to select a primary database for our new e-commerce platform. The system will handle: - ~10,000 concurrent users - Complex product catalog with hierarchical categories - Transaction processing for orders and payments - Full-text search for products - Geospatial queries for store locator The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID compliance for financial transactions. ## Decision Drivers * **Must have ACID compliance** for payment processing * **Must support complex queries** for reporting * **Should support full-text search** to reduce infrastructure complexity * **Should have good JSON support** for flexible product attributes * **Team familiarity** reduces onboarding time ## Considered Options ### Option 1: PostgreSQL - **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text search, PostGIS for geospatial, team has experience - **Cons**: Slightly more complex replication setup than MySQL ### Option 2: MySQL - **Pros**: Very familiar to team, simple replication, large community - **Cons**: Weaker JSON support, no built-in full-text search (need Elasticsearch), no geospatial without extensions ### Option 3: MongoDB - **Pros**: Flexible schema, native JSON, horizontal scaling - **Cons**: No ACID for multi-document transactions (at decision time), team has limited experience, requires schema design discipline ## Decision We will use **PostgreSQL 15** as our primary database. ## Rationale PostgreSQL provides the best balance of: 1. **ACID compliance** essential for e-commerce transactions 2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce infrastructure complexity 3. **Team familiarity** with SQL databases reduces learning curve 4. **Mature ecosystem** with excellent tooling and community support The slight complexity in replication is outweighed by the reduction in additional services (no separate Elasticsearch needed). ## Consequences ### Positive - Single database handles transactions, search, and geospati