Jon Chery
10 KiB
10 KiB
Principles Matrix
Maps every domain principle to the core principle(s) it derives from. Used to verify that no domain rule is orphaned and to resolve conflicts.
Core principles key: C1=Correctness · C2=Clarity · C3=Simplicity · C4=Locality · C5=Reversibility · C6=Composability · C7=Observability · C8=Economy
UI / UX
| UI/UX Principle | Core | Why |
|---|---|---|
| P1 User Primacy | C2 | Clarity serves the user |
| P2 Accessibility | C1 | Correctness for all abilities |
| P3 Clarity | C2 | Direct derivation |
| P4 Feedback | C7 | Observability for humans |
| P5 Forgiveness | C5 | Reversibility of user actions |
| P6 Performance | C1 | Correctness includes temporal correctness |
| P7 Hierarchy | C2 | Clarity of priority |
| P8 Consistency | C2 | Clarity through uniformity |
| P9 Simplicity | C3 | Direct derivation |
| P10 Reversibility | C5 | Direct derivation |
API Design
| API Principle | Core | Why |
|---|---|---|
| P1 Contract Fidelity | C1 | Correctness of the public contract |
| P2 Clarity | C2 | Direct derivation |
| P3 Predictability | C3 | Simplicity of mental model |
| P4 Composability | C6 | Direct derivation |
| P5 Versioning | C5 | Reversibility for consumers |
| P6 Idempotency | C1 | Correctness under retry |
| P7 Performance | C1 | Correctness includes latency |
| P8 Security | C1 | Correctness includes safety |
| P9 Error Transparency | C7 | Observability of failures |
| P10 Stability | C5 | Reversibility of changes |
Security
| Security Principle | Core | Why |
|---|---|---|
| P1 Zero Trust | C1 | Correctness requires no false trust |
| P2 Least Privilege | C3, C8 | Simplicity of access; economy of trust |
| P3 Defense in Depth | C1 | Correctness under partial failure |
| P4 Input Validation | C1 | Correctness of inputs |
| P5 Output Safety | C1 | Correctness of outputs |
| P6 Crypto Correctness | C1 | Crypto failures = correctness failures |
| P7 Auditability | C7 | Observability of security events |
| P8 Fail Securely | C1 | Correctness of failure modes |
| P9 Secret Hygiene | C6, C7 | Composability of secrets; observability |
| P10 Surface Minimization | C3, C8 | Simplicity; economy of code |
Data
| Data Principle | Core | Why |
|---|---|---|
| P1 Truth | C1 | Schema must match domain |
| P2 Normalization | C1, C3 | Correctness without duplication; simplicity |
| P3 Invariants in Schema | C1 | Correctness enforced |
| P4 Migration Safety | C5 | Reversibility of changes |
| P5 Indexing with Intent | C7 | Observability of query patterns |
| P6 Naming Consistency | C2 | Direct derivation |
| P7 Type Fidelity | C1, C2 | Correctness; clarity |
| P8 Lifecycle Awareness | C1 | Correctness includes lifecycle |
| P9 Referential Integrity | C1 | Correctness of relationships |
| P10 Performance Awareness | C1 | Correctness includes cost |
Testing
| Testing Principle | Core | Why |
|---|---|---|
| P1 Tests as Specification | C2 | Tests document intent |
| P2 Independence | C4 | Locality of test execution |
| P3 Determinism | C1 | Correctness is reproducible |
| P4 Fast Feedback | C3, C8 | Simplicity; economy of time |
| P5 Coverage of Behavior | C1 | Correctness of behavior |
| P6 Failure Specificity | C7 | Observability of failures |
| P7 Realism | C1 | Correctness in real conditions |
| P8 Maintainability | C3, C8 | Simplicity; economy of maintenance |
| P9 Edge Case Coverage | C1 | Correctness at boundaries |
| P10 No Test Theater | C1, C8 | Correctness; economy of test code |
Performance
| Perf Principle | Core | Why |
|---|---|---|
| P1 Measure First | C7 | Observability precedes optimization |
| P2 Critical Path Focus | C3 | Simplicity of scope |
| P3 Complexity Awareness | C1 | Correctness includes cost |
| P4 Resource Bounds | C1, C8 | Correctness; economy of resources |
| P5 Caching with Intent | C3, C6 | Simplicity; composability |
| P6 Lazy by Default | C8 | Economy of computation |
| P7 Async When Independent | C3 | Simplicity of flow |
| P8 Budget Discipline | C8 | Economy of resources |
| P9 Perceived Performance | C1 | Correctness from user's view |
| P10 Regression Prevention | C7 | Observability of regressions |
Observability
| Obs Principle | Core | Why |
|---|---|---|
| P1 Structured by Default | C2, C7 | Clarity; observability |
| P2 Correlation | C7 | Direct derivation |
| P3 Sufficient Context | C7, C2 | Observability; clarity |
| P4 Cardinality Discipline | C8 | Economy of storage/cost |
| P5 Sampling with Intent | C8 | Economy of observability budget |
| P6 No Secrets in Obs | C1, C6 | Correctness; composability |
| P7 Actionable Alerts | C7, C8 | Observability; economy of attention |
| P8 SLI/SLO Awareness | C1 | Correctness defined |
| P9 Cost Awareness | C8 | Direct derivation |
| P10 Debuggability | C2, C7 | Clarity; observability |
Errors
| Error Principle | Core | Why |
|---|---|---|
| P1 Errors are Data | C2, C7 | Clarity; observability |
| P2 Fail Loudly | C7 | Direct derivation |
| P3 Fail Specifically | C2, C7 | Clarity; observability |
| P4 Preserve Context | C7 | Direct derivation |
| P5 Recoverable When Possible | C1, C5 | Correctness; reversibility |
| P6 Unrecoverable Means Stop | C1 | Correctness of failure mode |
| P7 Errors are Boundaries | C6 | Composability |
| P8 User-Facing Errors are UX | C2 | Clarity for users |
| P9 Errors are Logged | C7 | Direct derivation |
| P10 Errors Don't Lie | C1, C2 | Correctness; clarity |
Documentation
| Doc Principle | Core | Why |
|---|---|---|
| P1 Documentation is Code | C3, C8 | Simplicity; economy of process |
| P2 Audience Awareness | C2 | Direct derivation |
| P3 Examples are Mandatory | C2 | Direct derivation |
| P4 Currency | C1 | Correctness of docs |
| P5 Discoverability | C2 | Direct derivation |
| P6 Conciseness | C3, C2 | Simplicity; clarity |
| P7 Structure | C2 | Direct derivation |
| P8 Why Over What | C2 | Direct derivation |
| P9 Living Documents | C1, C5 | Correctness; reversibility |
| P10 Public by Default | C6 | Composability |
Concurrency
| Concurrency Principle | Core | Why |
|---|---|---|
| P1 Immutability by Default | C1, C3 | Correctness; simplicity |
| P2 Single Responsibility | C3, C6 | Simplicity; composability |
| P3 Boundaries are Locks | C4, C6 | Locality; composability |
| P4 Determinism Over Speed | C1 | Correctness precedes performance |
| P5 Lock Minimization | C3 | Simplicity |
| P6 No Silent Races | C7 | Observability of races |
| P7 Cancellation Support | C5 | Reversibility of work |
| P8 Timeout Discipline | C1 | Correctness of blocking |
| P9 Bounded Queues | C1, C8 | Correctness; economy of memory |
| P10 Test for Races | C1 | Correctness verification |
DevOps
| DevOps Principle | Core | Why |
|---|---|---|
| P1 Reproducibility | C1 | Correctness of environments |
| P2 Automation | C3, C8 | Simplicity; economy of effort |
| P3 Observability | C7 | Direct derivation |
| P4 Rollback First | C5 | Direct derivation |
| P5 Progressive Delivery | C5, C1 | Reversibility; correctness gradually |
| P6 Configuration as Code | C1, C3 | Correctness; simplicity |
| P7 Immutability | C1 | Correctness of deploys |
| P8 Security at Every Layer | C1 | Correctness includes security |
| P9 Documentation in Pipeline | C2 | Clarity of operations |
| P10 Failure as Expected | C1, C7 | Correctness; observability |