skills.rest
iCesofT
iCesofTCOMMUNITY
Explore all skills by this author →
Website𝕏@fjahijadoGitHub

architecture-decision-records

Document architectural decisions as ADRs with context, alternatives, and rationale.

1|1|Updated Apr 16, 2026
Search Tags:#architecture#documentation#codebase#adr#traceability#design-decision
One-click install
npx skills add https://github.com/iCesofT/awesome-ai --skill architecture-decision-records-icesoft
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: architecture-decision-records
Source: https://github.com/iCesofT/awesome-ai/tree/main/skills/01-planning-architecture-adrs
Command: npx skills add https://github.com/iCesofT/awesome-ai --skill architecture-decision-records-icesoft

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Architectural decisions are often scattered across chats, PR comments, and memory. This skill captures them as structured ADR documents, keeping rationale, context, and alternatives in a centralized, codified log.

Core Features & Use Cases

  • Auto-detect decision moments during development and record the context, decision, alternatives considered, and rationale.
  • Maintain an ADR log alongside the codebase (docs/adr) so future developers understand why the architecture is the way it is.
  • Support quick reference in architecture reviews and planning sessions to accelerate onboarding and governance.

Quick Start

Record a new ADR by prompting the agent with "ADR this decision" and confirm the ADR file path as docs/adr/NNNN-title.md.

Frequently Asked Questions about architecture-decision-records

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

FAQPage Schema
How do I document architecture decisions to keep design rationale traceable?▼

Document architecture decisions by capturing context, alternatives, and rationale as structured ADR files. This skill auto-detects decision moments during development sessions and logs them in a standardized format under docs/adr.

What is an ADR and when do I need to record one in my codebase?▼

An ADR is an Architecture Decision Record that codifies a design decision. You record one whenever a significant architectural choice is made during development to maintain traceability and context for future architecture reviews.

How to start logging architecture decisions during a development session?▼

Start logging architecture decisions by prompting the agent with a command like "ADR this decision". The skill then records the context and rationale, saving the new ADR file as docs/adr/NNNN-title.md.

Why does my codebase lack traceability for past architecture design decisions?▼

Your codebase lacks traceability because architectural decisions are often scattered across chats and PR comments. Centralizing these into a structured ADR log alongside your code provides the missing rationale and context.

Can I use a lightweight ADR format for architecture reviews across different projects?▼

Yes, you can use a lightweight ADR format across projects. This skill applies a standardized template to capture decisions, supporting quick reference during governance and accelerating onboarding.

What is the best way to maintain an ADR log for future architecture reviews?▼

The best way to maintain an ADR log is to store standardized markdown files under docs/adr. This keeps decision rationale centralized and codified alongside the codebase for quick reference.

Related Skills

Explore More Software Engineering Skills→
cliveportmancliveportman
1

docs-conventions

Define and enforce documentation conventions for the docs/ directory.

Community
Intermediate
DavidROliverBADavidROliverBA
49

ADR Report Skill

Generate markdown reports of ADR activity categorized by status and project.

Community
Intermediate
kanade0404kanade0404

adr-writer

Evaluate architecture decisions and generate ADR records in Nygard format.

Community
Advanced
agentpatternsagentpatterns
5

adr

Create and manage Architecture Decision Records with structured YAML frontmatter.

Official
Intermediate