skills.rest
christian-byrne
christian-byrneCOMMUNITY
Explore all skills by this author →
𝕏@c__byrneGitHub

architecture-decision-records

Capture architectural decisions as structured ADR markdown files during coding sessions.

Updated Jul 28, 2026
Search Tags:#architecture#documentation#markdown#adr#decision records#technical decisions
One-click install
npx skills add https://github.com/christian-byrne/comfy-skills --skill architecture-decision-records-christian-byrne
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/christian-byrne/comfy-skills/tree/main/skills/architecture-decision-records
Command: npx skills add https://github.com/christian-byrne/comfy-skills --skill architecture-decision-records-christian-byrne

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Significant technical decisions made during development often disappear into Slack threads or PR comments, leaving future developers wondering why a framework, pattern, or API design was chosen. This Skill documents those decisions as structured Architecture Decision Records so the rationale is preserved alongside the codebase. ## Core Features & Use Cases - Lightweight ADR Format: Uses the Michael Nygard template with Status, Context, Decision, Alternatives Considered, and Consequences sections. - Organized Directory Structure: Creates numbered ADR files (0001-slug.md) under docs/adr/ with an index README table tracking number, title, status, and date. - Approval-Gated Creation: Drafts the ADR first and only writes the file after explicit user approval. - Use Case: While implementing a new service, you choose PostgreSQL over MongoDB. Ask the assistant to record the decision, and it drafts an ADR capturing the context, rejected alternatives, and honest trade-offs. ## Quick Start Ask the assistant to create an ADR documenting the decision to adopt a specific framework or architectural pattern for the current project.

Frequently Asked Questions about architecture-decision-records

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

FAQPage Schema
How do I create an architecture decision record for a project?▼

Create a markdown file in docs/adr/ using the Michael Nygard format: Status, Context, Decision, Alternatives Considered, and Consequences. Number files sequentially (0001-slug.md) and add each entry to an index README table with number, title, status, and date.

When should I write an ADR during development?▼

Write an ADR when making framework or library selections, adopting architectural patterns, designing APIs, choosing data models, or making infrastructure and security decisions. Any choice future developers would question deserves a record.

What is the Michael Nygard ADR format?▼

The Michael Nygard format is a lightweight ADR template with sections for Status (proposed, accepted, deprecated, superseded), Context, Decision, Alternatives Considered, and Consequences. It emphasizes capturing rationale and honest trade-offs in a single short document.

Where should ADR files be stored in a repository?▼

Store ADR files in a docs/adr/ directory with sequentially numbered filenames like 0001-use-postgresql.md. Maintain a README.md index in the same directory listing each ADR's number, title, status, and date.

What are the limitations of lightweight ADRs?▼

Lightweight ADRs capture decisions at a point in time but do not enforce consistency or automatically update when superseded. Teams must manually maintain statuses and the index, and very large organizations may need heavier governance tooling.

Related Skills

Explore More Software Engineering Skills→
evandrodevbrevandrodevbr
1

openspec-explore

Explore and clarify software development problems before implementation.

Community
Intermediate
Amazon-QuickAmazon-Quick
47

architecture-decision-record

Generate structured Architecture Decision Records from design conversations.

Official
Advanced
KevinKE93KevinKE93
42

documentation-and-adrs

Record architectural decisions and supporting documentation for future engineers and AI agents.

Community
Intermediate
GeneralJerelGeneralJerel
6

create-rfc

Create formal RFC documents with standardized sections and review periods.

Community
Advanced