architecture-decision-records

Overview

architecture-decision-records is a project-management skill designed to help teams document, track, and review significant technical and architectural decisions using Architecture Decision Records (ADRs). This skill provides clear patterns and templates for capturing the context, rationale, and consequences of major choices in your software projects. It is ideal for engineering teams, technical leads, and project managers who want to establish a transparent decision-making process and maintain a historical record for onboarding and future reference.

What Problems Does architecture-decision-records Solve?

• Ensures important technical decisions are documented and accessible
• Helps teams review past architectural choices and understand their impact
• Supports onboarding by providing context for why certain decisions were made
• Standardizes the process for recording and managing ADRs

Who Should Use This Skill?

• Teams making significant architectural or technology choices
• Organizations seeking to improve technical documentation and decision transparency
• Projects that need to track design trade-offs and rationale over time

How to Use

Installation Steps

1. Add the skill to your project using the following command:

   npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

2. After installation, start by reading the SKILL.md file for a high-level overview of the workflow and best practices.

Getting Started with ADRs

• Review the included templates and guidance in SKILL.md to understand how to structure your ADRs.
• Use the standard ADR format to capture:
  • Context: Why the decision is needed
  • Decision: What was decided
  • Consequences: The impact and outcomes
• Store ADRs in a dedicated folder within your repository (e.g., /docs/adr/).

Adapting the Workflow

• Customize the templates and processes to fit your team's needs, tools, and repository structure.
• Use the ADR lifecycle (Proposed → Accepted → Deprecated → Superseded) to track the status of each decision.

Key Files to Review

• SKILL.md – Main guide and workflow
• README.md, AGENTS.md, and supporting folders (if present) for additional context

FAQ

When should I write an ADR using architecture-decision-records?

Write an ADR for any significant architectural or technical decision, such as adopting a new framework, choosing a database technology, or designing an API. Routine maintenance, minor upgrades, or bug fixes typically do not require an ADR.

What format does architecture-decision-records recommend?

The skill provides a standard ADR template (MADR format) that captures context, decision, and consequences. You can adapt this template as needed for your project.

Where should I store ADRs in my project?

ADRs are usually stored in a dedicated folder like /docs/adr/ or /architecture/decisions/ within your repository for easy access and version control.

How does this skill support project management?

By documenting decisions and their rationale, architecture-decision-records improves transparency, onboarding, and long-term maintainability for technical teams.

Where can I find more details or templates?

Open the Files tab in the skill directory to explore all available templates, references, and helper scripts included with architecture-decision-records.