# Documentation Architectural Decision Records Adr

> Imported TRAE skill from documentation/Architectural_Decision_Records_ADR.md Use when this capability is needed.

- Skill: `tomevault-io/documentation-architectural-decision-records-adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-architectural-decision-records-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-architectural-decision-records-adr/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-architectural-decision-records-adr

---


# Skill: Architectural Decision Records (ADR)

## Purpose
To document the "Why" behind significant architectural decisions in a way that is easily searchable and immutable over time. ADRs provide context for future developers about the constraints, trade-offs, and rationale that led to a specific system design, preventing "architectural amnesia."

## When to Use
- When choosing a primary database (e.g., PostgreSQL vs. MongoDB)
- When adopting a new framework or major library (e.g., React vs. Vue, Next.js)
- When defining a communication protocol between services (e.g., REST, GraphQL, gRPC)
- When implementing a core design pattern (e.g., CQRS, Event Sourcing)

## Procedure

### 1. The Structure of an ADR
An ADR should be a short, focused Markdown file (usually stored in a `/docs/adr/` folder).

**ADR Template**:
- **Title**: Short and descriptive (e.g., `ADR 001: Use PostgreSQL for User Data`)
- **Date**: YYYY-MM-DD
- **Status**: `Proposed`, `Accepted`, `Deprecated`, or `Superseded` (by ADR XXX)
- **Context**: What is the problem we are solving? What are the constraints?
- **Decision**: What did we decide to do?
- **Consequences**: What are the trade-offs? What is the impact (positive and negative)?

### 2. Format Example

```markdown
# ADR 005: Use GraphQL for Frontend-Backend Communication

**Status**: Accepted  
**Date**: 2023-10-27

## Context
Our current REST API requires multiple round-trips to fetch data for the dashboard, leading to high latency on mobile devices. Frontend developers are frequently blocked waiting for new REST endpoints to be created.

## Decision
We will use GraphQL (Apollo Server/Client) as the primary communication layer between our web/mobile apps and our microservices.

## Consequences
- **Positive**: Frontend can query exactly what they need, reducing payload size.
- **Positive**: Schema introspection provides better documentation and type safety.
- **Negative**: Increased complexity in handling caching (N+1 problem).
- **Negative**: Steep learning curve for the team compared to REST.
```

### 3. Managing ADRs
- **Immutable**: Once an ADR is `Accepted`, it should not be edited. If the decision changes later, create a *new* ADR that `Supersedes` the old one.
- **Sequential Numbering**: Use a 3-digit prefix (e.g., `001`, `002`) to maintain order.
- **Git Flow**: ADRs should be submitted as Pull Requests. This allows the team to discuss and refine the decision before it's officially accepted.

## Best Practices
- **Focus on the "Why"**: Don't just document the decision; document the *alternatives* that were rejected and the specific reasons why.
- **Keep it Short**: An ADR should be readable in 5 minutes. If it's too long, it might be a Technical Spec instead.
- **One Decision Per ADR**: Don't bundle unrelated decisions (e.g., "Use React and PostgreSQL") into one file.
- **Visible to All**: Store ADRs in the main repository so every developer can find them.
- **Refer to ADRs in PRs**: When a PR implements a major decision, link to the relevant ADR in the description.

---
> Source: [Ditto190/crispy-nextjs-turborepo-monorepo](https://github.com/Ditto190/crispy-nextjs-turborepo-monorepo) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->