Skip to main content

Context​

With the org and the docs repo already in place (ADRs 0001 and 0002), the first truly architectural decisions emerge: hosting, authentication, versioning format, branching strategy. Without a formal mechanism, those decisions would be captured as Slack messages, PR comments, or the individual memory of whoever made them. That is fragile: when someone leaves, when an AI agent takes over a module, or simply when six months pass, the "why" is lost.

The Architecture Decision Record format (Michael Nygard, 2011) already solved this problem for many teams. The question is not whether to adopt it, but how much ceremony to apply.

Decision​

Every significant architectural or organizational decision is documented as an Architecture Decision Record (ADR) inside internal-docs/docs/adrs/, sequentially numbered, immutable once accepted, and discussed in advance via GitHub Discussions when applicable.

Consequences​

  • Institutional memory: decisions (and the reasoning behind them) survive changes in people, AI agents, or tools.
  • Change traceability: if a decision is reversed, it is made explicit through a new ADR that supersedes the previous one.
  • Simpler onboarding: new contributors read the ADRs and understand the rationale behind the current state without having to ask.
  • Discipline when proposing large changes: requiring an ADR forces the evaluation of alternatives and consequences before implementing.
  • Process overhead: every "big" decision adds overhead (writing, reviewing, merging). Mitigated by scoping to decisions that cross repos, modules, or people.
  • Risk of obsolescence: if no one reviews old ADRs, contradictions can accumulate; mitigated by the immutability + supersede rule.

Alternatives considered​

  • Freeform documentation in READMEs or wikis: faster to write but lacks structure and immutability; decisions dilute and no one knows which version is current.
  • Issues labeled decision: leverages GitHub's UI but issues get closed and drop out of the main flow; there is no stable numbering or renderable content either.
  • Slack/Notion for decisions: ephemeral or disconnected from the code; decisions are lost or inaccessible to agents that only read the repo.
  • MADR format vs. Nygard plain: we chose a simple variant (Context / Decision / Consequences / Alternatives / References) that prioritizes brevity over exhaustiveness; we can enrich the template later if needed.

References​