27 lines
2 KiB
Markdown
27 lines
2 KiB
Markdown
# 0001. Record architecture decisions
|
|
|
|
- **Status:** Accepted
|
|
- **Date:** 2026-06-27
|
|
|
|
## Context
|
|
|
|
The engine makes a number of architectural choices that are hard to reverse and non-obvious from the code alone: the crate boundaries, the determinism stance for worldgen, the server-authoritative simulation model, the content-ID namespacing scheme, and similar. The reasoning behind such choices is valuable to future contributors but does not belong inline in the source, where it would either be lost or bloat a single guidance file.
|
|
|
|
A durable, low-ceremony place is required to record *why* significant choices were made, kept separate from the cross-cutting rules in `AGENTS.md` (which records *what* to follow) and from subsystem implementation docs (which record *how* a system works).
|
|
|
|
## Decision
|
|
|
|
Architecture Decision Records (ADRs), in the lightweight format popularised by Michael Nygard, are used to capture significant, hard-to-reverse decisions.
|
|
|
|
- Each ADR is a single Markdown file in `docs/adr/`, numbered sequentially (`0001-…`, `0002-…`).
|
|
- Each record carries a status (`Proposed`, `Accepted`, `Deprecated`, or `Superseded by …`) and a date.
|
|
- Records are **append-only**: once accepted, an ADR is not edited to reflect a later change of mind. A new ADR is written instead and the old one is marked `Superseded`.
|
|
- New records are started from [`template.md`](template.md).
|
|
|
|
## Consequences
|
|
|
|
- The rationale behind significant choices is preserved with its historical context, independent of how the code later evolves.
|
|
- `AGENTS.md` stays lean: it can state a rule and link to the ADR that explains it, rather than carrying the justification inline.
|
|
- A small, ongoing discipline is required : a contributor making a significant architectural choice is expected to add an ADR for it. Trivial or easily reversible choices do not warrant one.
|
|
- Because records are numbered and append-only, the directory grows monotonically without any single file becoming a bottleneck.
|