Engineering Standards¶
🧩 Principle: boring, dependable engineering beats clever engineering. Optimize for the next person reading the code, not for showing skill.
Code & Repo Conventions¶
| Area | Standard |
|---|---|
| Version control | Git, trunk-based or short-lived feature branches; no long-lived divergent branches |
| Commits | Small, descriptive commits; explain why in the message when not obvious |
| Code review | All non-trivial changes reviewed before merge, even solo projects (self-review checklist if no second reviewer) |
| Testing | Critical paths covered by automated tests; manual test notes for anything untested |
| Secrets | Never committed to git; environment variables or a secrets manager only |
| Naming | Consistent, descriptive naming for repos, branches, and environments (see Tools & Tech Stack) |
Definition of Done¶
A task is "done" when:
- It meets the agreed success criteria, not just "it runs"
- It has been tested (automated where practical, manual otherwise) and results noted
- It is documented (README, inline comments only where the why isn't obvious)
- It has been reviewed by at least one other person, or self-reviewed against this checklist
- Monitoring/logging exists for anything running in production
- A runbook exists (deploy, rollback, alerts) for anything deployed to production
Code Review¶
Reviewers check, in order: correctness (does it solve the problem?), readability (can someone else maintain it?), security (does it introduce risk?), performance (obvious bottlenecks?), and test coverage (are critical paths covered?).
Pull request checklist:
- Clear title and description
- Linked issue/task, if applicable
- Tests added or updated
- Docs updated (README / runbook)
- No secrets in the diff
Testing¶
| Layer | Goal | Examples |
|---|---|---|
| Unit | Fast feedback | Pure functions, validators |
| Integration | Validate components together | DB + API, queues |
| End-to-end | Validate the user-facing flow | Critical journeys |
Minimum standard: unit tests for core logic, integration tests for integrations, smoke tests for deployments.
Architecture Decisions¶
- Record any non-obvious technical decision (framework choice, data model, model/approach selection) as a short ADR: context → decision → tradeoffs considered → outcome.
- Store ADRs alongside the project's code, not only in chat history.