skills.rest
Femad-6
Femad-6COMMUNITY
Explore all skills by this author →
WebsiteGitHub

architecture-decision-records

Captures architectural decisions as structured ADR documents with context, alternatives, and rationale.

Updated Mar 25, 2026
Search Tags:#architecture#documentation#adr#software architecture#technical design#engineering workflow#decision records
One-click install
npx skills add https://github.com/Femad-6/my-skills --skill architecture-decision-records-femad-6
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/Femad-6/my-skills/tree/main/.github/skills/architecture-decision-records
Command: npx skills add https://github.com/Femad-6/my-skills --skill architecture-decision-records-femad-6

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Architectural decisions made during coding sessions often live only in chat threads, PR comments, or memory, leaving future developers unable to understand why the codebase is shaped the way it is. This Skill records those decisions as structured ADR documents stored alongside the code. ## Core Features & Use Cases - Decision Detection: Recognizes explicit signals ("let's go with X", "record this as an ADR") and implicit signals (framework comparisons, database choices) during conversations. - Structured ADR Format: Generates Nygard-style ADRs with context, decision, alternatives considered, consequences, and lifecycle status (proposed, accepted, deprecated, superseded). - ADR Index Maintenance: Maintains a numbered log in docs/adr/ with an index README so past decisions are searchable when someone asks "why did we choose X?". - Use Case: During a session you decide to use PostgreSQL over MongoDB. The Skill drafts ADR-0002 with the rationale and rejected alternatives, asks for your approval, writes it to docs/adr/, and updates the index. ## Quick Start Tell the assistant to record the decision we just made about our database choice as an ADR.

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?▼

State your decision in conversation, such as "we decided to use PostgreSQL over MongoDB", and the Skill drafts a structured ADR with context, alternatives, and consequences. After your approval, it writes the file to docs/adr/ with a sequential number and updates the index.

What format does an ADR document use?▼

The ADRs follow Michael Nygard's lightweight format with sections for Context, Decision, Alternatives Considered, and Consequences. Each record also includes a date, status (proposed, accepted, deprecated, or superseded), and the deciders involved.

Where are ADR files stored in a project?▼

ADRs are stored in a docs/adr/ directory at the project root, named with sequential numbers like 0001-use-nextjs.md. The directory also contains a README.md index table and a blank template.md for manual use.

Does the skill create ADR files automatically without asking?▼

No. The Skill requires explicit user confirmation before creating the docs/adr/ directory or writing any ADR file. Implicit decision signals only trigger a suggestion to record an ADR, never automatic file creation.

When should I not record an ADR?▼

Skip ADRs for trivial decisions like variable naming, formatting choices, or minor implementation details. ADRs are meant for significant choices such as technology selection, architecture patterns, API design, data modeling, and security strategy.

Related Skills

Explore More Software Engineering Skills→
mikecubedmikecubed

brainstorm

Run a Socratic ideation session to surface constraints, risks, and trade-offs.

Community
Advanced
sparkfabriksparkfabrik
3

adr-creator

Creates Architecture Decision Records using adr-tools or manual templates.

Official
Advanced
zorgentechzorgentech

create-adr

Create Architecture Decision Records from pull request metadata and diffs.

Official
Intermediate
billlzzz18billlzzz18

notion-knowledge-capture

Extract key concepts and create structured Notion pages with templates.

Community
Advanced