Skip to main content

​
0000. Record architecture decisions

​
Context and problem statement

HAI-Co² is a reference implementation of a published framework. Architectural choices (branching model, agent framework, deployment topology, dual-pathway contribution model) accumulate quickly, and the people who arrive on the project six months from now will not have been present for the original debates. Without a lightweight record, those discussions either die in chat history or have to be reconstructed from PR threads, which is slow and unreliable.

​
Decision drivers

  • Onboarding cost for new contributors must stay low.
  • Decisions that constrain future work need a discoverable rationale.
  • The dual-pathway model (see ADR-0002) uses “does this need an ADR?” as a triage criterion, so the artefact has to exist.
  • Tooling overhead should be zero. We are already comfortable with Markdown in docs/.

​
Considered options

  1. No structured record. Discussions live in PR threads and chat.
  2. A free-form decisions.md file. One growing document of bullets.
  3. MADR-style ADRs under docs/adr/. One short Markdown file per decision, numbered and version-controlled.
  4. An external system (Notion, Confluence). Out-of-repo source of truth.

​
Decision outcome

Chosen option: MADR-style ADRs under docs/adr/, because they keep the record next to the code, require no tooling, version-control naturally, and each file stays small enough that reviewers actually read it.

​
Positive consequences

  • Decisions live alongside the code they justify.
  • ADR existence is itself a signal; see ADR-0002.
  • New contributors can read docs/adr/ top-to-bottom in under an hour.

​
Negative consequences

  • Maintainers have to remember to write an ADR when a decision lands. Reviewers should ask “does this need an ADR?” on architecture-touching PRs.
  • Numbering needs a conflict-resolution step when two ADRs are drafted in parallel; the resolver simply re-numbers the later one before merge.

​
Pros and cons of the options

​
Option 1: No structured record

  • + Zero overhead.
  • − Knowledge evaporates. Hardest option to walk back.

​
Option 2: Free-form decisions.md

  • + Lightweight.
  • − Grows unstructured; either re-litigates or gets ignored.

​
Option 3: MADR ADRs under docs/adr/

  • + Per-decision granularity; small reviewable files; version-controlled.
  • − Mild discipline cost.

​
Option 4: External system

  • + Rich formatting; non-developers can contribute.
  • − Drifts from the code; requires accounts; gone if the SaaS dies.