| name | architecture-principles |
| description | Define and enforce 8-12 architecture principles with rationale and implications. Use when establishing guardrails for technology choices, ADR reviews, or platform paved roads. |
Architecture Principles
Principles are durable, opinionated statements that constrain design space and accelerate decisions. Done well (TOGAF / Spewak style: statement, rationale, implications) they reduce ADR debate, anchor reviews, and become inputs to fitness functions and policy-as-code.
Stack Baseline (2026)
| Concern | Recommended |
|---|
| Format | TOGAF 10.x principle template (Name, Statement, Rationale, Implications) |
| Storage | Repo-as-source-of-truth (/docs/principles/*.md), rendered via Backstage TechDocs |
| Linkage | ADRs (MADR 4.0), fitness functions, paved-road catalog |
| Decisioning | Lightweight RFC + architecture council (async-first) |
| Enforcement | OPA/Conftest, ArchUnit, Backstage scorecards |
| Reference | TOGAF 10.x; Spewak EAP; Team Topologies |
When to Use
- Establishing a new platform, BU, or modernization program.
- Recurring ADR debates without a shared compass.
- Paved-road definition for a developer platform.
- M&A integration requiring rapid alignment.
Prerequisites
- Business strategy and target operating model understood.
- Stakeholders identified (engineering, security, SRE, product, finance).
- ADR process in place; otherwise establish first.
Instructions
flowchart LR
V[Vision + constraints] --> D[Draft 8-12 principles]
D --> R[Review w/ stakeholders]
R --> P[Publish in repo + Backstage]
P --> E[Enforce: ADRs, fitness, OPA]
E --> M[Measure adherence]
M --> U[Revise yearly]
- Anchor in business outcomes and constraints (compliance, cost, talent). Avoid restating motherhood ("we value quality").
- Limit to 8-12 principles. More than 12 means none are remembered.
- Write each principle with: Name, Statement (imperative), Rationale (why), Implications (what changes, what's harder).
- Tension-check. Each principle should reject some option; if it forbids nothing, delete it. Capture explicit trade-offs.
- Operationalize. Map every principle to at least one mechanism: ADR template prompt, fitness function, OPA policy, or scorecard check.
- Govern. Annual review; principles can be deprecated. Track which ADRs cite which principle.
## P-04: Buy or adopt before build
- Statement: Prefer managed or open-source solutions over bespoke for non-differentiating capabilities.
- Rationale: Engineering capacity is finite; differentiation lives in the domain.
- Implications:
- ADRs must justify build with explicit differentiation hypothesis.
- Vendor and OSS evaluation template required (license, SLSA level, exit cost).
- Platform team curates an approved catalog; off-catalog choices need exception.
# OPA enforcement of P-07: All services emit OpenTelemetry
package paved_road
deny[msg] {
input.kind == "Service"
not input.spec.observability.otel.enabled
msg := "Principle P-07 violation: OpenTelemetry must be enabled"
}
Common Pitfalls
| Pitfall | Mitigation |
|---|
| Vague slogans | Test: does it forbid a real option? If no, rewrite |
| 30+ principles | Cap at 12; archive the rest as guidelines |
| No enforcement | Tie each to ADR prompt, fitness function, or policy |
| Principles ignored in reviews | Add "Principles considered" section to ADR template |
| Static forever | Schedule annual review; allow deprecation |
Output Format
/docs/principles/index.md plus one file per principle.- ADR template referencing principles.
- Mapping table: Principle -> enforcement mechanism (test, policy, scorecard).
Authoritative References
- The Open Group, TOGAF Standard, 10th Edition (2022, updates 2025).
- Steven Spewak, Enterprise Architecture Planning.
- Gregor Hohpe, The Software Architect Elevator, O'Reilly.
- Skelton & Pais, Team Topologies.
- ISO/IEC/IEEE 42010:2022 - architecture description.
