Jon Chery
176 lines
10 KiB
Markdown
176 lines
10 KiB
Markdown
# 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 | |