Skip to content

charlieviettq/awesome-agent-skill / .claude/skills/architecture-decision-records

architecture-decision-records

Verified

Create and maintain Architecture Decision Records (ADRs) for significant technical choices—frameworks, data stores, API shapes, ML platform decisions. Use when documenting a decision, onboarding, or superseding a prior approach.

Architecture decision records

When to write an ADR

Write ADRSkip ADR
New framework or major dependencyMinor version bump
Database or storage choiceBug fix
API or integration patternConfig-only change
Security or auth architectureRoutine maintenance

Lifecycle

Proposed -> Accepted -> Deprecated -> Superseded

Do not rewrite accepted ADRs; add a new ADR that supersedes the old one.

Required sections

  1. Context — problem and constraints
  2. Decision — what was chosen (one clear statement)
  3. Consequences — positive, negative, risks and mitigations
  4. Status and date

Optional (recommended for significant decisions)

  • Decision drivers (numbered)
  • Considered options with honest pros/cons
  • Related ADRs / links

Lightweight template

# ADR-NNNN: Title

**Status:** Accepted | **Date:** YYYY-MM-DD

## Context
[Why we needed to decide]

## Decision
[What we decided]

## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... **Mitigation:** ...

Full MADR-style templates

See reference.md for extended templates (standard, Y-statement, deprecation).

Practices

  • Write before implementation starts when possible.
  • Keep ADRs short (1-2 pages); link deep dives elsewhere.
  • Be honest about trade-offs.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall