adr

Create architecture decision records with frontmatter and body for documentation.

1|Updated Mar 29, 2026

Search Tags:#architecture #documentation #adr #rationale #software-design #decision-record

Ready to run

npx skills add https://github.com/HeyItsGilbert/marketplace --skill adr-heyitsgilbert

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: adr
Source: https://github.com/HeyItsGilbert/marketplace/tree/main/plugins/architecture-decisions/skills/adr
Command: npx skills add https://github.com/HeyItsGilbert/marketplace --skill adr-heyitsgilbert

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Create lightweight decision records that explain why a design choice was made and capture the rationale for future engineers, ensuring decisions travel with the codebase.

Core Features & Use Cases

Create ADRs after significant decisions to document context, alternatives considered, and the final decision.
Backfill undocumented decisions or convert RFCs into ADRs for traceability and historical insight.
Maintain ADRs in docs/decisions/ to provide a living record that accompanies the codebase.

Quick Start

Draft an ADR for the latest architectural decision by summarizing the problem, the options considered, and the chosen solution, then commit it to docs/decisions/.

Frequently Asked Questions about adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I document architectural decisions to explain why a software design choice was made?▼

To document architectural decisions, create architecture decision records that capture the context, alternatives considered, and the final choice. This ensures your design rationale travels with the codebase for future engineers.

What is the best way to convert an existing RFC into a decision record?▼

The best way to convert an RFC into a decision record is to extract the problem context and proposed solution, then map them into an ADR format. This backfills undocumented decisions for better historical traceability.

What should be included in architecture decision record frontmatter?▼

Architecture decision record frontmatter should include id, status, date, related links, tags, and superseded-by fields. The body must capture the context, decision, and consequences of the software design choice.

Where should I store ADR files in my repository?▼

You should store ADR files in a docs/decisions/ directory within your repository. This creates a living record of architectural decisions that directly accompanies the codebase.

When do I need to create an architecture decision record?▼

You need to create an architecture decision record after making significant architectural choices. Documenting these design decisions provides historical insight and explains the rationale to future engineers.

Can I backfill undocumented software design decisions across multiple repositories?▼

Yes, you can backfill undocumented decisions across repositories by summarizing the historical context and final choice. Converting these into ADRs establishes traceability for past architectural decisions.