Govern architectural decisions across repositories by keeping repository-specific decisions close to their code and distributing organisation-level decisions as versioned, read-only dependencies. Define scope and precedence explicitly, resolve the final decision set at a pinned revision, and require local exceptions or overrides to cite the higher-level record and receive appropriate approval.
Do not centralise every decision
A single catalogue improves discovery but can separate local choices from the code and teams that own them. Purely local records preserve context but make cross-cutting constraints hard to distribute. A layered model keeps authority at the narrowest sensible level.
Organisation decisions may govern security, data residency or interoperability. Domain decisions may govern shared APIs. Repository decisions should cover implementation choices whose effects stay local. Each layer needs an owner and a declared scope.
Distribute versioned authority
Repositories should consume a pinned release or commit of shared decisions rather than an unversioned live feed. This makes agent retrieval and CI reproducible and allows teams to review upgrades. A central index can improve discovery, but retrieved content should resolve to the authoritative reviewed source.
- Global: regulatory, security and company-wide platform constraints.
- Domain: contracts and boundaries shared by related services.
- Repository: implementation choices owned with the code.
- Exception: narrow, approved deviation with an expiry or review date.
Make precedence deterministic
Define what happens when records conflict. A narrower decision should not silently override a mandatory higher-level control. Require an explicit exception or supersession relationship, and return the conflict to the agent and reviewer rather than selecting whichever document ranks highest semantically.
Use stable IDs across repositories and qualify them with an authority or namespace where collisions are possible. Preserve the source revision in citations so a merged change can be reconstructed later.
Roll out by risk and reuse
Begin with a small set of cross-repository decisions that teams already need repeatedly. Measure retrieval, citation accuracy, enforcement coverage and exception volume. Add federation only when ownership, update cadence and migration behaviour are clear.
AsDecided's repository-native format and deterministic interfaces provide a local foundation. A federated catalogue, organisation resolver and central exception service are additional architectural components, not prerequisites for gaining value in one repository.