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.

FileKindSize
SKILL.mdskill md1.7 KB
reference.mdmarkdown677 B
---
name: architecture-decision-records
description: "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."
allowed-tools: Read, Glob, Grep
---

# Architecture decision records

## When to write an ADR

| Write ADR | Skip ADR |
|-----------|----------|
| New framework or major dependency | Minor version bump |
| Database or storage choice | Bug fix |
| API or integration pattern | Config-only change |
| Security or auth architecture | Routine 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

```markdown
# 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](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: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated 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: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall