1 open besluit1414 voorstellen

Besluit 1 · werkwijze

De atlas is de bron en wordt bijgehouden via GitOps

De kennis staat als OKF-bundel in Git en is de enige bron; iedere wijziging loopt via een pull request die een architect beoordeelt, en de site wordt uit de atlas gebouwd.
Aanvaard25 september 2026Besloten door vdo89

Context en probleemstelling

Architectuurkennis die in documenten, presentaties en wiki’s staat, loopt uit elkaar: iedere versie is een momentopname, wijzigingen zijn niet te volgen en niemand weet welke versie geldt. De atlas moet één bron zijn die architecten en agents samen bijhouden, met een controleerbare geschiedenis.

Beslisfactoren

  • Eén bron van waarheid, met een volledige geschiedenis van iedere wijziging.
  • Beoordeling door een mens vóór een wijziging geldt.
  • Door agents te lezen en te schrijven, en machinaal te controleren.
  • Open formaat, overdraagbaar naar een ander platform.

Overwogen opties

  1. Kennis als OKF-bundel in Git, bijgehouden via GitOps — één markdownbestand per concept met frontmatter, wijzigingen via pull requests, controles in CI.
  2. Een wiki — snel te bewerken, maar zonder beoordeling vooraf en zonder gestructureerde velden.
  3. Een architectuurtool met eigen database — rijk model, maar gesloten formaat en lastig voor agents.

Besluit

Gekozen optie: “Kennis als OKF-bundel in Git, bijgehouden via GitOps”, omdat alleen die optie een volledige geschiedenis, beoordeling vooraf en een open, machinaal controleerbaar formaat combineert.

  • De kennis staat in kennis/ als bundel volgens het Open Knowledge Format (v0.2): één concept per bestand, met een type, een vaste naam en links naar andere concepten. De atlas verwijst alleen naar zichzelf; externe bronnen komen alleen voor als bron van een feit.
  • Iedere wijziging loopt via een pull request. CI controleert de typecontracten, de links, de relaties en de regels van de status; een architect beoordeelt de inhoud.
  • De site wordt bij iedere wijziging van main uit de atlas gebouwd en gepubliceerd. Teksten van de site en haar vormgeving staan in site/, niet in kennis/.

Gevolgen

  • Goed: iedere uitspraak heeft een geschiedenis; een besluit is terug te vinden in de pull request die het invoerde.
  • Goed: agents werken met dezelfde bestanden en dezelfde controles als mensen.
  • Slecht: wie geen Git kent, bewerkt via de site: die maakt van een reactie of besluit een issue of pull request.