Toju/agents-docs/AGENTS_ADRS.md

Agent Instructions: Architecture Decision Records (ADRs)

Architectural decisions live in agents-docs/adr/ as numbered Markdown files (NNNN-slug.md).

This document defines how agents must detect, document, and maintain architectural decisions as the codebase grows.

This file is part of the agent instruction infrastructure. Do NOT create, delete, or modify this file unless explicitly instructed.

---

What an ADR is

A short record of an architectural decision that future engineers (and agents) will need context for. The format is Nygard short form:

• Title and number (ADR-NNNN: <slug>).
• Required: 1–3 sentences each covering Context (why this came up), Decision (what was chosen), and Rationale (why this option over alternatives).
• Conventional: Status (usually Accepted for new ADRs; Superseded by ADR-MMMM once overturned).
• Optional: Considered Options, Consequences — add only when they genuinely help. Most ADRs won't need them.

See agents-docs/adr/0001-record-architectural-decisions.md for the canonical example — a minimal four-section ADR that matches the typical shape.

The value is in recording that a decision was made and why — not in completing formal sections.

---

ADR Contract (MANDATORY)

When to write an ADR

The canonical criteria — the 3-criteria gate — live in agents-docs/AGENT_WORKFLOW.md § 5 ADR upkeep. Read those before writing. In short: write an ADR only when the decision is hard to reverse, surprising without context, and the result of genuine trade-offs. If any of the three is missing, don't.

Suitable topics: architectural patterns, integration approaches, significant technology selections, scope boundaries, intentional deviations from standard practices, non-obvious rejections of alternatives.

Read before crossing decision boundaries

Before non-trivial changes in an area, scan agents-docs/adr/ for decisions that touch it. If your work would contradict an existing ADR:

• Surface it explicitly, don't silently override. Phrase it as: "Contradicts ADR-NNNN (slug) — but worth reopening because…"
• If the contradiction is intentional, write a new ADR that supersedes the old one (see below).

Write the ADR in the same turn as the decision

When the 3-criteria gate is met, write the ADR before reporting the task done. The AGENTS.md completion checklist has a line for this; don't tick the box without it.

Numbering

Scan agents-docs/adr/ for the highest existing number; the new ADR is NNNN+1. Use 4-digit zero-padded numbers (0001, 0002, …).

Slugs are kebab-case and describe the decision concisely: 0042-postgres-for-write-model.md, 0043-event-sourced-orders.md.

Supersede, don't delete

ADRs are append-only:

• When a decision is overturned, write a new ADR. The old one stays.
• Add Superseded by ADR-NNNN near the top of the old ADR.
• Add Supersedes ADR-MMMM near the top of the new one.
• Never delete or rewrite history.

---

Format

# ADR-NNNN: <Slug Title>

## Status
<Proposed | Accepted | Superseded by ADR-MMMM>

## Context
<1–3 sentences: what prompted this decision, what constraint or fork was hit.>

## Decision
<1–3 sentences: what was chosen, plainly stated.>

## Rationale
<1–3 sentences: why this option over the alternatives.>

<!-- Optional sections, only when they help: -->

## Considered Options
<bullet list of alternatives evaluated and rejected>

## Consequences
<bullet list of follow-on effects, especially constraints this locks in>

Keep ADRs short. Three sentences per section beats three paragraphs.