architecture-decision-recorder_skill

Overview

This skill creates and manages Architecture Decision Records (ADRs) to capture important architectural decisions, tradeoffs, and rationale. It provides a consistent ADR template, enforces best practices like immutability and version control, and helps teams maintain an accessible architectural history. Use it to improve transparency and onboarding across engineering and product teams.

How this skill works

The skill scaffolds ADRs using a standard template with sections for context, decision, rationale, consequences, alternatives, and implementation actions. It automates numbering, date stamping, status tracking, and linking of related ADRs, and generates Markdown files ready for version control. You can create, view, and supersede ADRs while preserving previous records.

When to use it

• Before making or formalizing any major architectural or technology choice
• When evaluating tradeoffs between frameworks, services, or system designs
• To capture decisions that affect multiple teams or long-term maintenance
• When onboarding new engineers who need historical context
• During architecture reviews, design docs, or roadmap planning

Best practices

• Create ADRs for decisions that change system shape, dependencies, or costs
• Keep ADRs immutable: supersede older records instead of editing them
• Store ADRs in the repository and link them from design docs and tickets
• Include measurable data and clear mitigation strategies for risks
• Review ADRs periodically (quarterly) to validate status and relevance

Example use cases

• Choosing between self-hosted services and managed cloud offerings
• Selecting a TypeScript architecture pattern or module boundary approach
• Documenting the decision to adopt or deprecate a third-party library
• Recording migration plans and tradeoffs when refactoring core systems
• Capturing cross-team API contract decisions and rollout strategies