Architecture Decision Records

An Architecture Decision Record (ADR) is a short document that captures a single architectural decision along with its context and consequences. ADRs answer two questions: why was this decision made, and what are its trade-offs? The practice is well established — teams have long documented decisions like “we use Hono for the backend” or “API routes must validate input at the boundary.”

Traditionally, ADRs are passive. Developers read them (sometimes) and follow them (hopefully). Archgate’s core insight is that an ADR should not just describe a rule — it should enforce it.

Two expressions of one decision

Every ADR in Archgate has two expressions:

1. A human-readable document — Markdown with YAML frontmatter, written so that both developers and AI agents understand the intent, context, and rationale.
2. Machine-checkable rules — an optional companion file that verifies compliance automatically.

When an AI agent works in an Archgate-governed project, both expressions act at once:

• The agent reads the ADR document as context, shaping what it generates — this is prevention.
• The automated rules validate the output, catching what the agent missed — this is detection.

Not every ADR needs rules

Some decisions are best enforced through code review and human judgment alone. An ADR can be pure documentation (rules: false) or carry an executable companion file (rules: true). The two expressions are independent — a decision is valuable as a record even when no automated check is practical.

What lives in an ADR

Each ADR document follows a consistent structure so that humans and agents always know where to look:

• Frontmatter — machine-readable metadata: a unique id (such as BE-003), a title, a domain, whether it has rules, and optional files globs that scope which files its rules check.
• Context — the problem that prompted the decision and the alternatives that were considered and rejected.
• Decision — the decision itself, stated prescriptively. This is the section AI agents pay the most attention to when deciding how to write code.
• Do’s and Don’ts — concrete, verifiable guidance that acts as a quick-reference checklist for developers and agents.
• Consequences — the positive outcomes, the trade-offs accepted, and the risks (each with a mitigation).
• Compliance and Enforcement — how the decision is enforced, both through automated rules and through manual review.
• References — links to related ADRs and external sources.

ADRs are grouped into domains (backend, frontend, data, architecture, general, plus any custom domain a project registers). The domain determines the ID prefix — a backend ADR is BE-001, an architecture ADR is ARCH-001 — and lets the reviewer skill and archgate review-context scope ADR briefings to only the domains a change touches.

How ADRs reach your AI agent

The editor plugins load the applicable ADRs into your agent automatically before every coding task — no copy-pasting decisions into prompts. The plugin asks the CLI which ADRs apply to the files being changed, receives condensed briefings (the Decision and Do’s and Don’ts of each), and the agent writes code against those constraints. The governance loop explains how this fits together end to end.

Starting from proven decisions

You do not have to write every ADR from scratch. The ADR packs registry provides curated, tested collections of ADRs — TypeScript strictness, testing standards, security baselines, and more — that you import and adapt to your project.

The CLI is the authoritative reference

This page explains the ADR concept. For the exact frontmatter schema, field-by-field reference, naming conventions, and the archgate adr command set (create, list, show, import, domain), see the authoritative CLI documentation at cli.archgate.dev. We deliberately do not duplicate the schema here — the CLI docs are the single source of truth and stay in sync with each release.

Related concepts

Rules The executable companion that enforces an ADR automatically.

Packs Import curated ADR collections instead of starting blank.

The Governance Loop How ADRs drive prevention, detection, and learning.

ADR authoring The skill that writes and edits ADRs to project standard.