architecture-decision-records

Architecture Decision Records (ADRs) provide a structured methodology for documenting significant technical choices throughout a project's lifecycle. By capturing the 'why' behind architectural patterns, technology selections, and design trade-offs, this skill helps teams avoid decision fatigue and 'architectural amnesia.' It is designed for lead developers, software architects, and engineering teams who need to maintain institutional knowledge, facilitate smoother onboarding for new team members, and ensure that historical decisions remain transparent and reviewable.

• Standardized documentation: Includes templates for standard MADR format, lightweight ADRs, Y-statements, and deprecation records.

• Decision lifecycle management: Tracks the evolution of decisions from Proposed to Accepted, Deprecated, or Superseded.

• Strategic clarity: Clearly separates implementation details from significant architectural shifts, helping teams prioritize what requires formal documentation.

• Contextual archiving: Essential for recording trade-offs related to database selection, API design, security architecture, and integration patterns.

• Team alignment: Ensures that all stakeholders understand the reasoning behind complex technical moves, reducing friction during code reviews and future refactoring.

• Use this skill when initiating new projects or making significant shifts in technology stacks (e.g., framework adoption, database migrations, or major security changes).

• Recommended to skip for minor version upgrades, routine configuration changes, or bug fixes.

• Inputs typically involve technical requirements, performance benchmarks, and alternative options considered.

• Outputs consist of a structured Markdown document stored within the repository that serves as a single source of truth for design reasoning.

• Integrates seamlessly with existing repository documentation workflows to maintain a searchable history of technical evolution.