skills.rest
MadAppGang
MadAppGangOFFICIAL
Explore all skills by this author →
WebsiteGitHub

adr-documentation

Create Architecture Decision Records with standardized sections for context, decision, consequences, and alternatives.

7|4|Updated Feb 26, 2026
Search Tags:#architecture#decision making#documentation#adr#technical debt#trade-offs
One-click install
npx skills add https://github.com/MadAppGang/magus --skill adr-documentation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-documentation
Source: https://github.com/MadAppGang/magus/tree/main/plugins/dev/skills/adr-documentation
Command: npx skills add https://github.com/MadAppGang/magus --skill adr-documentation

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides a structured and comprehensive approach to documenting architectural decisions, ensuring clarity, context, and historical record-keeping for software projects.

Core Features & Use Cases

  • Standardized ADR Format: Guides users through creating Architecture Decision Records (ADRs) with predefined sections for context, decision, consequences, and alternatives.
  • Decision Lifecycle Management: Explains the process from proposal to acceptance, deprecation, and superseding of ADRs.
  • Integration Guidance: Shows how to reference ADRs within other documentation (like CLAUDE.md) and agent instructions to ensure compliance.
  • Use Case: When making a significant technology choice, like selecting a new database or framework, use this Skill to generate a formal ADR that captures the rationale, trade-offs, and alternatives considered, ensuring the decision is well-understood and recorded for the future.

Quick Start

Use the adr-documentation skill to generate a new Architecture Decision Record for a proposed database change.

Frequently Asked Questions about adr-documentation

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

FAQPage Schema
How do I document architectural decisions to track technical trade-offs and rationale?▼

Document architectural decisions by creating Architecture Decision Records (ADRs) that capture context, decisions, consequences, and alternatives. This structured approach ensures technical trade-offs and rationale are recorded for software development projects.

What is the best way to manage the lifecycle of an Architecture Decision Record?▼

Manage the Architecture Decision Record lifecycle by tracking its status from proposal through acceptance, deprecation, and superseding. This lifecycle management maintains a clear historical record of architectural choices over time.

When do I need to create an ADR for a software development project?▼

Create an ADR when making significant architectural choices, such as selecting a new database or framework. ADRs document the proposed technology choice, rationale, and alternatives considered to prevent technical debt.

Can I reference ADRs within project documentation and agent instructions?▼

Yes, ADRs can be referenced within project documentation like CLAUDE.md and agent instructions. This integration guidance ensures automated tools and team members comply with the documented architectural decisions.

What sections should be included in a standardized ADR template?▼

A standardized ADR template includes predefined sections for context, decision, consequences, and alternatives. These sections enforce best practices to maintain a clear historical record of architectural choices and trade-offs.

Related Skills

Explore More Software Engineering Skills→
adolfoaranaes12adolfoaranaes12
2

create-adr

Create Architecture Decision Records with context, alternatives, rationale, and consequences.

Community
Advanced
simonheimlichersimonheimlicher
1

architecting-typescript

Create Architecture Decision Records for TypeScript architecture decisions.

Community
Advanced
Imad-OuteImad-Oute
2

mh-cto-sdlc-tech-retro

Evaluate architectural decisions against production outcomes to update ADRs and catalog technical debt.

Community
Advanced
richardnpaulrichardnpaul

architecture-decision-records

Capture and organize architectural decisions as ADR documents with context and rationale.

Community
Intermediate