# Doc Adr Architect

> Documenting significant architectural decisions to preserve project context and evolution.

- Skill: `jcorpac/doc-adr-architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jcorpac/doc-adr-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcorpac/doc-adr-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jcorpac (https://skillmd.com/u/jcorpac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jcorpac/doc-adr-architect

---


# ADR Architect

Architecture Decision Records (ADRs) capture the *why* behind significant technical choices.

## Why ADRs?
- **Avoid "Second-Guessing"**: Document why an alternative was rejected.
- **Onboard Newcomers**: Provide historical context for existing designs.
- **Team Alignment**: Ensure everyone understands the rationale for a decision.

## Standard ADR Format

### 1. Title
State the decision clearly (e.g., "ADR-001: Use PostgreSQL for Persistent Storage").

### 2. Status
Proposed, Accepted, Superceded, or Rejected.

### 3. Context
What is the problem? What are the constraints? What alternatives were considered?

### 4. Decision
What choice are we making? Be specific.

### 5. Consequences
What are the positive and negative side effects? What trade-offs were made? (e.g., "Slower writes, but better consistency").

## Best Practices
- **Write them as you decide**: Don't try to reconstruct them months later.
- **Link them**: Show when one ADR supercedes another.
- **Keep them concise**: Focus on the rationale, not the entire meeting transcript.