Quick reference for core engineering principles. For detailed standards, see standards/.
- Clarity over cleverness: Optimize for readability and explicitness
- Small, safe changes: Incremental delivery with tests and feature flags
- Separation of concerns: Isolate domains, interfaces, and implementations
- Defensive boundaries: Validate inputs at edges; trust internal invariants
- Observability-first: Logs, metrics, traces are first-class citizens
- Consistency across teams: Shared practices, vocabulary, and decision-making
- Data-driven decisions: Objective criteria, ADRs, and metrics over opinions
- Quality & security are everyone's responsibility: Shift-left; built in, not bolted on
- Living documentation: Auto-generated from code; manually document only ADRs and context
- Continuous learning: Retrospectives, post-mortems, evolving standards
- Composable Architecture & DDD - Bounded contexts, ubiquitous language
- API-First & Contract-Driven - Independent services with clear contracts
- Cloud Portability - Avoid vendor lock-in, use open standards
- Observability - Tracing, logging, metrics, alerting
- Zero Trust Security - Authenticate, authorize, encrypt all flows
- Performance Optimization - Caching, compression, efficient algorithms
- High Availability - Redundancy, failover, graceful degradation
- Reliability & Resilience - Fault tolerance, chaos engineering
- Cost Optimization - Right-sizing, auto-scaling, FinOps
- Automation First - CI/CD, automated testing, security scanning
- Infrastructure as Code - Version-controlled, repeatable deployments
- AI-Native Design - Prompt-driven interfaces, RAG over fine-tuning, agentic orchestration, evaluation-as-code, and human-in-the-loop guardrails from inception
- Open Source & Open Standards - Prefer OAUTH, OpenTelemetry, Kubernetes over proprietary
| Decision |
Guidance |
| Performance vs Maintainability |
Prefer maintainable; optimize proven hotspots |
| Consistency vs Local Optimization |
Favor org-wide conventions |
| Abstraction vs Simplicity |
Abstract only repeated patterns (Rule of Three) |
- Open standards preferred
- Libraries with zero critical/high vulnerabilities
- Active maintenance and community support
- Clear licensing compatible with commercial use
- Performance characteristics matching requirements
- LLM frameworks with structured output, tool use, and observability (e.g., LangChain, Claude SDK, OpenAI SDK)
- Evaluation and guardrail tooling for prompt regression testing and safety