---
title: "Write and Maintain Architecture Decisions | Agent Barn"
canonical: "https://agentbarn.dev/guides/architecture-decision-records"
pubDate: "2026-08-25T00:00:00.000Z"
updatedDate: "2026-08-29T16:41:32.000Z"
author: Agent Barn
description: "Capture hard-to-reverse technical choices, their trade-offs, consequences, and later supersession."
tags: [Engineering guide, Maintainers and technical leads, Agent Barn]
categories: [Guides]
---

# Write and Maintain Architecture Decisions

Use an ADR for a consequential choice that is difficult to reverse, surprising without context, and based on a real trade-off. Keep current behavior in architecture and feature guides.

## Guide details

- Reference: GD-18
- Type: Engineering guide
- Audience: Maintainers and technical leads

## When an ADR qualifies

Create an ADR only when the choice is hard to reverse, surprising without context, and the result of alternatives worth preserving. Establish rationale from maintainers, issues, plans, commits, or other historical evidence. Mark retrospective records clearly.

## Smallest complete format

Use a stable `YYYY-MM-DD-descriptive-slug.md` filename, then state the decision title, status, date, optional origin, context, choice, and reason. Add alternatives, consequences, and revisit conditions only when they help future maintainers preserve or challenge the choice.

## Supersede instead of rewriting history

Accepted ADR filenames remain stable. When a decision changes, create a new ADR and mark the old one superseded. Feature and architecture docs must still describe the current system, because an ADR explains why rather than serving as a live product manual.