---
title: Architecture Decision Records
category: product
entity_type: skill
price: $15
canonical: https://forgehouse.ai/skills/architecture-decision-records/
lang: en
hreflang_alt: https://forgehouse.ai/tr/skiller/architecture-decision-records/
last_updated: 2026-06-20
---

# Architecture Decision Records

> Write and maintain Architecture Decision Records (ADRs) following best practices for technical…

A complete system for writing and maintaining Architecture Decision Records so significant technical choices are captured at the moment they're made: with context, alternatives, and consequences. It supplies five battle-tested ADR templates, lifecycle management, superseding chains, and a review process, turning scattered tribal knowledge into a searchable decision history.

## Use cases
- Documenting a significant architecture or technology choice
- Recording the alternatives considered and why they were rejected
- Superseding a past decision with a new, properly linked ADR
- Onboarding new engineers by giving them the decision history
- Establishing a lightweight, repeatable decision-making process for a team
- Auditing whether a past architectural choice still holds

## Benefits
- Future engineers can answer why a decision was made without guessing
- Reversibility analysis routes irreversible choices to the right level of review
- Consistent, low-friction documentation people actually keep up
- A clean superseding chain so policies never silently contradict each other

## What’s included
- Five ADR templates: standard MADR, lightweight, Y-statement, deprecation, and RFC
- ADR lifecycle and status model (proposed, accepted, deprecated, superseded)
- A directory structure, index README, and adr-tools automation guide
- A pre-submission and review checklist including reversibility assessment
- Superseding-chain conventions that keep decisions traceable
- Do's and don'ts that keep records honest and short

## Who it’s for
Architects and engineering teams that want to capture and preserve the reasoning behind their technical decisions.

## How it runs
Six months from now, someone will ask why you chose Postgres. ADRs answer that at decision time, and the skill keeps the record honest and lightweight:
1. Filters first: significant decisions (framework adoption, database choice, API patterns, security architecture) get an ADR; bug fixes, minor upgrades and config changes are skipped, so the record stays signal not noise.
2. Writes the record at decision time, never retroactively: Context, Decision Drivers (3-5 bullets), Considered Options with honest pros and cons including the rejected ones, the Decision itself, and Consequences both positive and negative.
3. Classifies reversibility per decision: Type 1 irreversible calls (DB engine change, public API release) require an RFC process and multiple stakeholder approvals; Type 2 reversible calls (library choice, cache strategy) a single engineer can take.
4. Scopes the decision explicitly: the title names where it applies and a does-not-apply-to section prevents the decision from being misused outside its bounded context.
5. Maintains the superseding chain: a new ADR references the old one with Supersedes, the old one gets a Superseded-by note, the index README updates, and orphan ADRs with no links are flagged in audit.
6. Keeps governance lightweight on purpose: MADR format, one page maximum, adr-tools for create, supersede and table-of-contents generation; a process heavier than fifteen minutes per record never gets adopted by a team.

## FAQ
### We already have a year of undocumented decisions, can we start now without backfilling everything?
Yes. ADRs capture choices from the moment you adopt the practice forward, and you only retroactively write up the few past decisions still causing debate. If you ever revisit an old call, the new ADR links back to it through the superseding chain.

### Our wiki pages rot within weeks of being written, what keeps an ADR chain from suffering the same fate?
Each ADR is immutable once accepted; you don't edit it, you supersede it with a linked replacement, so the history of why stays intact. Lifecycle states and a review step keep the chain honest instead of leaving orphaned pages.

### Does this help me decide the architecture, or just write it down?
It's for recording the decision and its alternatives and consequences; the deciding happens elsewhere. Its value is that six months later anyone can read why you chose what you did instead of second-guessing it blind.

## Price
$15, one-time, no subscription. VAT included.

Related guide: [AI code review and developer workflow](https://forgehouse.ai/guides/ai-code-review/)