architectural-decision-records

Document architecture decisions and blind spots as lightweight ADRs.

Updated Apr 19, 2026

Search Tags:#architecture #documentation #security #adr #resilience #observability #decision-making

Ready to run

npx skills add https://github.com/hoesler/agent-stuff --skill architectural-decision-records-hoesler

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: architectural-decision-records
Source: https://github.com/hoesler/agent-stuff/tree/main/skills/architectural-decision-records
Command: npx skills add https://github.com/hoesler/agent-stuff --skill architectural-decision-records-hoesler

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams turn incomplete architecture discussions into clear ADRs by surfacing missing rationale, alternatives, and risk areas.

Core Features & Use Cases

Decision capture: Records the why behind technology, boundary, and pattern choices.
Gap detection: Checks observability, resilience, security, scalability, consistency, deployment, testing, and performance for missing decisions.
Lightweight ADR generation: Produces brief, sequential ADRs that are easy to maintain and review.
Use case: Use it after an architecture review to document why PostgreSQL, REST, or a service split was chosen and what trade-offs remain.

Quick Start

Ask this skill to review your architecture diagram or system description and draft the first lightweight ADRs from the provided context.

Frequently Asked Questions about architectural-decision-records

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

FAQPage Schema

How do I document architecture decisions and rationale for my system?▼

Document architecture decisions by generating lightweight ADRs that capture context, consequences, and risk tracking. This skill reviews your system descriptions to surface missing rationale and alternatives for technology or pattern choices.

What is the best way to identify missing architecture decisions in a system design?▼

Identify missing architecture decisions by checking your system design for gaps across observability, resilience, security, scalability, consistency, deployment, testing, and performance. This skill analyzes your diagrams to surface undocumented areas and prompt focused questions.

Can I use this to generate an ADR from an existing architecture diagram?▼

Yes, you can generate an ADR from an existing architecture diagram. The skill applies to architecture diagrams, system descriptions, and codebases where rationale or risk areas are missing, producing sequential ADRs by prompting one focused question at a time.

How do I track risk areas and consequences after an architecture review?▼

Track risk areas and consequences by producing lightweight ADRs following an architecture review. The generated ADRs record the trade-offs behind choices like PostgreSQL or REST, documenting what risks remain and why specific boundaries were chosen.

When do I need to create an Architecture Decision Record?▼

You need to create an Architecture Decision Record when you want to capture the why behind technology, boundary, and pattern choices. It is particularly useful after architecture discussions to ensure rationale, alternatives, and trade-offs are formally documented.