Can I search through existing architectural decisions?

Yes, you can ask Claude questions like 'Why did we choose PostgreSQL?' and it will scan the ADR index to provide the recorded context and rationale.

Where are the ADR files stored?

Files are stored directly in your project repository under 'docs/adr/', ensuring your documentation lives alongside the source code it describes.

What is an Architecture Decision Record (ADR)?

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

How does this skill detect decision moments?

The skill monitors conversations for signals like comparing frameworks, choosing between libraries, or explicit phrases such as 'let's go with X over Y'.

Does Claude create ADR files automatically?

No. The skill identifies a decision moment and drafts the content, but it will always ask for your explicit approval before writing files to your disk.

Architecture Decision Records (ADRs)

Name: Architecture Decision Records (ADRs)
Author: affaan-m

byaffaan-m

•

172,009

•

Learning & Documentation

Captures and organizes architectural decisions into structured ADR documents during AI-assisted development sessions.

The Architecture Decision Records skill enables Claude Code to automatically identify pivotal architectural moments—such as choosing a database, framework, or API pattern—and document the rationale behind them. By maintaining a structured log of context, alternatives, and consequences within your repository, it ensures that the 'why' behind your codebase is preserved for future developers. It manages the full lifecycle of ADRs, from initial proposal to supersession, integrating seamlessly into your development workflow to transform ephemeral chat decisions into permanent documentation.

Key Features

01Contextual retrieval of existing decisions to answer 'why' questions

02172,009 GitHub stars

03Automatic detection of architectural decision points during conversation

04Full lifecycle tracking for decisions (proposed, accepted, deprecated, or superseded)

05Standardized Michael Nygard ADR format including context, alternatives, and consequences

06Automated directory management (docs/adr/) and searchable index updates

Use Cases

01Onboarding new team members by providing a historical record of technical rationale

02Recording the selection of specific libraries or database technologies for a project

03Documenting architectural trade-offs during a transition from monolith to microservices

Key Features

01Contextual retrieval of existing decisions to answer 'why' questions

02172,009 GitHub stars

03Automatic detection of architectural decision points during conversation

04Full lifecycle tracking for decisions (proposed, accepted, deprecated, or superseded)

05Standardized Michael Nygard ADR format including context, alternatives, and consequences

06Automated directory management (docs/adr/) and searchable index updates

Use Cases

01Onboarding new team members by providing a historical record of technical rationale

02Recording the selection of specific libraries or database technologies for a project

03Documenting architectural trade-offs during a transition from monolith to microservices