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

Ready to run

npx skills add https://github.com/christian-byrne/comfy-skills --skill architecture-decision-records-christian-byrne

💬 Prompt for ChatGPT / Claude Chat▼

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.