architecture-decision-record_skill

Overview

This skill helps teams create and maintain Architecture Decision Records (ADRs) using the Nygard format. It provides ready-to-use templates, examples, and a checklist so teams can capture context, decisions, consequences, and alternatives. The goal is to preserve architectural memory and make reasoning about backend, API, database, and infrastructure choices explicit.

How this skill works

The skill generates ADR templates numbered sequentially and pre-populates sections for Title, Status, Context, Decision, Consequences, Alternatives, and References. It enforces writing guidance (present tense, immutable accepted records, at least two alternatives) and supplies examples and a quick-start checklist to integrate ADRs into your workflow. It also maps ADR lifecycle states and recommended storage/location conventions.

When to use it

• Making significant technology choices (databases, frameworks, cloud providers)
• Designing or changing system architecture or major components
• Establishing team-wide patterns, conventions, or standards
• Documenting trade-offs that affect future development and onboarding
• Linking design rationale to implementation PRs or rollout plans

Best practices

• Keep accepted ADRs immutable; create a new ADR to supersede older ones
• Write ADRs in present tense and focus on the rationale (why) rather than implementation details (how)
• Include at least two alternatives with pros/cons and reasons for rejection
• Capture both positive and negative consequences; be honest about trade-offs and risks
• Number ADRs sequentially using zero-padded 4-digit IDs and store in version control alongside code

Example use cases

• Choose database technology for a new microservice and record trade-offs and constraints
• Select an API versioning strategy and document consumer impact and migration plan
• Decide on an infrastructure change (Kubernetes adoption, serverless) and list operational consequences and rollout responsibility
• Document why a monolith will be optimized vs migrated to microservices, including alternatives considered
• Record a deprecated decision and link it to the ADR that supersedes it