architecture-decision-records

The architecture-decision-records skill captures architectural decisions made during Claude Code sessions in a structured, persistent format known as Architecture Decision Records (ADRs). It addresses the common problem where decisions about frameworks, patterns, databases, and APIs are scattered across Slack threads, pull request comments, or developers’ memories, making it difficult for teams to understand why the codebase is shaped a certain way. By producing ADRs as part of the code repository, this skill ensures that architectural rationale, context, and alternatives are documented and accessible for future developers.

This skill automatically detects decision moments and guides users through a structured workflow to document each decision. It supports initializing an ADR directory, gathering context, recording alternatives with pros and cons, stating consequences, assigning sequential numbers, confirming drafts with the user, and updating an ADR index. The ADRs follow a lightweight format proposed by Michael Nygard, including sections for context, decision, alternatives considered, and consequences. Users can also query existing ADRs to understand prior architectural choices, and the skill will present the relevant context and decisions from the ADR log.

Typical use cases include recording framework choices, database selections, API design decisions, or any significant architectural trade-offs during planning or coding sessions. Target users are software developers, architects, and teams who want to maintain a transparent, well-documented rationale behind their system architecture. It is particularly useful for onboarding new team members, auditing architectural evolution, or ensuring consistency in decision-making across distributed teams.