architecture-decision-records

This skill provides a structured framework for teams to capture the context, rationale, and consequences of significant architectural decisions. By using standardized formats like MADR (Markdown Architecture Decision Records) or Y-Statements, teams can effectively communicate technical strategies, ensure consistency across projects, and provide historical transparency for onboarding new members or reviewing past design choices. It is designed to act as a living repository of project knowledge, preventing the loss of critical design context that often occurs in long-running development efforts.

• Standardized Templates: Includes support for MADR (Markdown ADR), Lightweight, Y-Statement, and Deprecation-focused templates to suit various project complexities.

• Lifecycle Management: Facilitates tracking of decisions through Proposed, Accepted, Deprecated, and Superseded states.

• Decision Drivers: Helps explicitly define requirements like ACID compliance, scalability, security, and developer experience (DX).

• Consequence Analysis: Encourages thoughtful evaluation of positive outcomes, negative impacts, and inherent risks associated with every chosen technical path.

• Documentation Best Practices: Provides clear guidelines on when to write an ADR (e.g., framework adoption, API design) versus when to skip it (e.g., bug fixes, minor updates).

• Best for: Lead developers, system architects, and engineering managers overseeing complex system designs or team-wide technology shifts.

• Typical usage: Run this skill during design review meetings or when planning major infrastructure changes to ensure all stakeholders align on the 'why' behind the 'what'.

• Inputs: Requires project requirements, constraints, and candidate technologies; outputs a structured markdown file that integrates directly into your version-controlled documentation folder.

• Integration: Designed for seamless usage within the Claude Code environment alongside other project management and development tools, helping maintain a high-integrity architectural history.