Engineering Principles
This document defines the core Engineering Principles that govern how we write, review, integrate, and evolve software across the organization. These principles complement the Architecture Principles (which govern system design) and the Quality Principles (which govern the SDLC and testing), and apply to every engineer regardless of stack or domain.
Core Principles
1. Clean Code
Code is read far more often than it is written. Engineers MUST optimize for the reader: clear names, small functions, and obvious control flow over clever shortcuts. This principle is grounded in the practices of *Clean Code* (Robert C. Martin) and *Refactoring* (Martin Fowler), which provide the concrete techniques — naming, function decomposition, refactoring patterns.2. Code Simplicity
The cheapest line of code is the one not written; the second cheapest is the one borrowed from well-tested code. At the implementation level, engineers MUST keep code as simple as the problem allows: prefer the minimal change that solves the problem, avoid speculative abstractions and frameworks added "just in case" (**YAGNI**), and do not reinvent the wheel when a standard library, framework, or internal utility already does the job.3. Small, Incremental Changes
We prefer many small commits and pull requests over large batches. Smaller changes are easier to review, easier to revert, and easier to reason about. Large refactors SHOULD be avoided when not strictly needed; when unavoidable, they MUST be committed separately from behavior-changing work so each step can be reviewed and reverted independently.4. Trunk-Based Development
Engineers work on short-lived branches and integrate to the trunk (main) frequently — ideally multiple times per day. Long-lived branches accumulate merge risk, hide drift between teammates, and conflict with the goal of frequent, low-risk releases.5. Local-First
Engineers MUST be able to build, run, and test the system on their own machine, fast. Slow, fragile, or undocumented local setups are defects to be fixed, not facts of life: one-command setup, fast incremental builds, and fast local test execution are first-class engineering concerns.6. Continuous Integration
Every change MUST be built, tested, and validated by an automated pipeline on every push. Broken builds are stopped at the door, not in production. A red trunk is treated as the highest-priority incident: the team's first responsibility is to get it green again.7. You Build It, You Own It
Engineering ownership means accountability for the quality, evolution, and long-term health of what you ship. The team assigned to the product remains responsible for its design, code quality, dependencies, documentation, observability, and bug fixes for as long as it lives. Ownership is not transferred at the moment of delivery.8. Code Reviews
No change reaches the trunk without review by at least one other engineer. Reviews protect quality, share knowledge, distribute context, and prevent single points of failure. Self-merging is reserved for narrowly defined, pre-approved exceptions (e.g., emergency rollbacks or naive, small-scoped changes).9. Everything as Code
Every artifact under the team's control that defines how our software is built, packaged, deployed, and configured MUST live in version control: application code, Dockerfiles, Helm charts and values, CI/CD pipelines (e.g., GitLab CI), configuration, and schemas. Manual changes applied directly to shared environments are forbidden as they are invisible to the team, untestable, and unreproducible. If it is not in version control, it does not exist.10. Document Decisions, Not Code
Code explains *what* the system does; documents explain *why* it does it that way. Significant decisions MUST be captured in durable artifacts (Architecture ADRs, READMEs, capabilities, foundations, etc) kept close to the code. Decisions outlive the engineers who made them, so they must outlive the conversation in which they were made.Summary Matrix
[!IMPORTANT] When evaluating engineering workflows, pull requests, or team practices, ensure the following alignment:
| Principle | Phase | Target Focus |
|---|---|---|
| 1. Clean Code | Authoring / Review | Clarity over cleverness; clean-code & refactoring habits |
| 2. Code Simplicity | Authoring / Review | KISS & YAGNI; minimal change; don’t reinvent the wheel |
| 3. Small, Incremental Changes | Authoring / Review | Reviewable PR size; revertible units of change |
| 4. Trunk-Based Development | Branching | Short-lived branches; frequent integration to main |
| 5. Local-First | Authoring / Build | Fast local build & test; one-command setup |
| 6. Continuous Integration | Build / CI | Automated build & test on every push; green trunk |
| 7. You Build It, You Own It | Full Lifecycle | End-to-end team ownership: design, run, evolve, retire |
| 8. Code Reviews | Review | No self-merge; reviews as quality and knowledge transfer |
| 9. Everything as Code | Build / Deploy / Config | Versioned Dockerfiles, Helm charts, pipelines, config — no manual env edits |
| 10. Document Decisions, Not Code | Discovery / Design | ADRs and runbooks capturing the why |