Files

brogeby c48b6e9c94 docs: scaffold agent instruction tree

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>

2026-05-20 00:02:02 +02:00

1.2 KiB

Raw Blame History

ADR-0001: Record Architectural Decisions

Status

Accepted

Context

We need a lightweight way to record architectural decisions so that future agents and engineers can understand why the system looks the way it does, not just what it does. Without ADRs, decisions live in PR descriptions, chat logs, or nowhere — and get re-litigated on every refactor.

Decision

We use Architecture Decision Records (ADRs) in the Nygard short form. Each ADR lives at agents-docs/adr/NNNN-slug.md with a 4-digit zero-padded number, monotonically increasing. The minimum content is a title plus 1–3 sentences each for Context, Decision, and Rationale. Add Status, Considered Options, or Consequences only when they genuinely help.

Rationale

Nygard short form is the lowest-friction format that still captures the why. Heavier templates (MADR, full IEEE 1471) routinely don't get written — the bar to start one is too high. ADRs are append-only: a superseded decision gets a new ADR with a Supersedes ADR-NNNN note while the old one stays in place. The 3-criteria gate (hard to reverse, surprising without context, genuine trade-offs) keeps the directory from filling with trivia. See agents-docs/AGENTS_ADRS.md for the full contract.

1.2 KiB Raw Blame History Unescape Escape