TL;DR git clone https://github.com/chriscloud27/architecture-decision-record

Architecture Decision Records (ADRs) are short notes that capture important technical choices: what was decided, why it was decided and what trade-offs were accepted.

Write an ADR when a decision will affect future work, team alignment, delivery speed, cost, or risk.

ADRs are not just for documentation. They are shared memory for people and reliable context for LLM tools, so both humans and AI can make better follow-up decisions.

The problem and pain

Teams often move fast, make solid decisions, and then lose the reasoning after a few weeks.

When this happens, the same questions come back again and again:

Why did we choose this approach?

Can we remove this step?

Is this still required?

Who decided this and based on what?

Without clear decision records, teams repeat old debates, onboard slower, and create accidental regressions.

Why teams resist now but appreciate it later

In the moment, ADRs feel optional. Later, they become a superpower.

Teams appreciate ADRs when:

a teammate leaves and context remains

an old decision must be revisited safely

a new engineer asks, "why this way?"

an AI assistant needs project-specific context instead of guessing

Solution approach

The best approach is not heavy process. It is tiny, repeatable habits.

Good atomic habits (very easy step-by-step overview)

Spot one meaningful decision.

Open the ADR template.

Write context in simple language.

Write one clear decision sentence.

List practical consequences and trade-offs.

Set status and date.

Commit the ADR with related changes.

If the direction changes, create a new ADR that supersedes the old one.

Rule of thumb: if the team had a real discussion, write an ADR.

Claude/Copilot instructions (LLM-first)

Use LLMs to reduce writing friction.

Practical flow:

Keep repository ADR rules in CLAUDE.md.

Keep one stable template in docs/adr/0000-template.md.

Ask Claude or Copilot to draft ADR-000X from your decision discussion.

Review for clarity and correctness.

Commit.

Short CLAUDE.md outline:

where ADR files live

when to write one

numbering and naming format

valid status values

required sections: Context, Decision, Consequences

what not to write ADRs for

Ready-to-copy repo with all instructions

If you want this to work consistently, include these basics in any repo:

adr folder and numbering convention

one ADR template

clear assistant instructions (for people and LLMs)

short README section on when ADRs are required

at least two real examples

This turns ADRs from a "maybe later" task into a normal part of delivery.

Examples of good ADRs

Title: ADR-0006: Static HTML Export Deployed to GitHub Pages

Status: accepted

Date: 2026-04-22

## Context

The site is a personal/professional brand site for a solo operator. It has no per-request server-side logic requirements — all content is either static, fetched at build time from Notion, or handled client-side. Two deployment targets were considered:

**Option A — Vercel (Next.js runtime):** Supports full SSR, middleware-based locale redirect, image optimisation, and incremental static regeneration. Requires a paid plan for commercial domains and ongoing vendor dependency.

**Option B — GitHub Pages (static export):** Free, version-controlled deployment via GitHub Actions. Requires `output: "export"`, disables image optimisation (`images.unoptimized: true`), forbids server-side API routes (only edge/external webhooks work), and requires a client-side JavaScript redirect for locale detection at the root path.

The site's content model is compatible with static export: blog posts are fetched from Notion at build time, the Compass scoring feature is a client-side form posting to an external webhook, and no route requires runtime database reads.

## Decision

We use `output: "export"` in `next.config.ts` to pre-render all routes to static HTML at build time and deploy the `out/` directory to GitHub Pages via a GitHub Actions workflow.

## Consequences

- Next.js middleware cannot run — locale detection must be implemented via a JavaScript redirect in the root `index.html`.
- Image optimisation is disabled; all images must be pre-optimised before committing or downloading.
- No server-side API routes are possible. External webhooks (e.g. n8n at `flow.mach2.cloud`) must handle any server-side logic.
- `trailingSlash: true` is required to ensure GitHub Pages serves `page/index.html` correctly for nested routes.
- The GitHub Actions deploy workflow must run `sync:notion-assets` before `next build` to cache Notion-hosted blog images locally.
- Switching to Vercel in future would unlock middleware redirects, image optimisation, and ISR — but the current constraints are acceptable for the site's scale.

Final takeaway

ADRs are small documents with long-term impact.

They reduce repeat debates, preserve team memory, speed onboarding, and improve decision quality over time.

Most importantly, they give both people and LLM assistants the context needed to build and improve systems wisely, not blindly.