brogeby
c48b6e9c94
Add AGENTS.md, CLAUDE.md, and the agents-docs/ tree (workflow, lessons, engineering standards, context map, ADR seed, feature template) plus a domain-bearing CONTEXT.md for each of the six subdomains: toju-app, electron, server, e2e, website, docs-site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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
|
||
|
||
```markdown
|
||
# 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.
|