skills.rest
ibytechaos
ibytechaosCOMMUNITY
Explore all skills by this author →
GitHub

architecture-decision-records

Captures architectural decisions as structured ADR documents in a docs/adr directory.

1|Updated Oct 11, 2025
Search Tags:#architecture#documentation#markdown#codebase#adr#technical design#decision records
One-click install
npx skills add https://github.com/ibytechaos/claude --skill architecture-decision-records-ibytechaos
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/ibytechaos/claude/tree/main/plugins/everything-claude-code/skills/architecture-decision-records
Command: npx skills add https://github.com/ibytechaos/claude --skill architecture-decision-records-ibytechaos

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 Architecture Decision Records (ADRs) 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 ADRs following the Michael Nygard format with Context, Decision, Alternatives Considered, and Consequences sections. - ADR Log Management: Maintains a numbered ADR directory (docs/adr/) with an index README, lifecycle states (proposed, accepted, deprecated, superseded), and a reusable template. - Use Case: After choosing PostgreSQL over MongoDB for a project, the Skill drafts 0002-postgres-over-mongo.md documenting the rationale and rejected alternatives, then updates the index after your approval. ## Quick Start Ask the assistant to record the database decision we just discussed as an ADR in this 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 my project?▼

State the decision in conversation, such as "we decided to use REST over GraphQL", 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 the lightweight Michael Nygard format with sections for Context, Decision, Alternatives Considered, and Consequences. Each record also includes a date, status (proposed, accepted, deprecated, or superseded), and deciders.

Where are ADR files stored in a repository?▼

ADRs are stored in a docs/adr/ directory containing numbered Markdown files like 0001-use-nextjs.md, an index README.md listing all records, and a blank template.md for manual use. The directory is only created after explicit user confirmation.

Can I look up why a past architectural decision was made?▼

Yes, asking "why did we choose X?" triggers a search of the docs/adr/ index and matching ADR files. The Skill presents the Context and Decision sections, or offers to record a new ADR if no match exists.

When should I not write an ADR?▼

Skip ADRs for trivial choices like variable naming or formatting. Reserve them for decisions with real trade-offs: technology selection, architecture patterns, API design, data modeling, infrastructure, security, and testing strategy.

Related Skills

Explore More Software Engineering Skills→
riftzen-bitriftzen-bit

architecture-decision-records

Capture architectural decisions as structured ADR documents during design discussions and coding sessions.

Community
Intermediate
farzanmrzfarzanmrz
6

documentation-and-adrs

Record architecture decisions and rationale in structured ADR templates.

Community
Intermediate
b12consultingb12consulting
2

specs-review

Audit spec-driven documentation health and detect code-spec drift.

Official
Intermediate
snoodleboot-iosnoodleboot-io

team-collaboration

Applies structured practices for code ownership, onboarding, handoffs, and written disagreement in engineering teams.

Official
Intermediate