Can I use this to search existing decisions?

Yes, you can ask Claude 'why did we choose X?' and the skill will scan your existing ADR index to provide the documented rationale.

How does the skill handle superseded decisions?

The skill manages a lifecycle for ADRs; when a new decision replaces an old one, it marks the previous record as 'superseded' and provides a link to the new record.

What is an Architecture Decision Record (ADR)?

An ADR is a short document that captures a significant architectural decision, the context in which it was made, and the consequences it has for the project.

Does Claude create ADRs automatically?

Claude will detect decision moments and propose a draft, but it will always ask for your explicit approval before writing files to your repository.

Where does this skill store the ADR files?

Files are stored directly in your project repository under the `docs/adr/` directory, ensuring they version-controlled alongside your source code.

Architecture Decision Records (ADR)

Name: Architecture Decision Records (ADR)
Author: hieuck

byhieuck

0•

Learning & Documentation

Captures and documents architectural decisions as structured ADR files to maintain a clear history of technical choices and trade-offs.

The Architecture Decision Records skill empowers Claude Code to identify critical decision moments during development, such as selecting frameworks, designing APIs, or choosing databases. It automates the creation of structured ADR documents using the Michael Nygard format, ensuring that the rationale, alternatives considered, and long-term consequences are preserved directly within your repository. This turns ephemeral chat discussions into a permanent, searchable knowledge base that helps prevent architectural drift and streamlines developer onboarding.

Key Features

01Standardized ADR formatting including context, rationale, and consequences

02Context-aware retrieval to explain past architectural choices to the team

03Support for decision lifecycle tracking (proposed, accepted, superseded)

04Automatic detection of architectural decision signals in conversation

050 GitHub stars

06Automatic indexing and management of the docs/adr/ directory

Use Cases

01Recording data modeling decisions and schema design trade-offs

02Documenting the rationale for choosing a specific tech stack or library over alternatives

03Maintaining a historical log of why specific infrastructure or API patterns were adopted

Key Features

01Standardized ADR formatting including context, rationale, and consequences

02Context-aware retrieval to explain past architectural choices to the team

03Support for decision lifecycle tracking (proposed, accepted, superseded)

04Automatic detection of architectural decision signals in conversation

050 GitHub stars

06Automatic indexing and management of the docs/adr/ directory

Use Cases

01Recording data modeling decisions and schema design trade-offs

02Documenting the rationale for choosing a specific tech stack or library over alternatives

03Maintaining a historical log of why specific infrastructure or API patterns were adopted