Engineering Principles

These principles apply to contributions — human and AI alike. Prefer them when implementing features, reviewing design choices, or writing CONTRIBUTING.md.

Explain the why briefly when a principle changes a decision; do not lecture on every edit.

YAGNI — You Aren't Gonna Need It

Implement only what the current task demands. Build for today's requirements; future requirements arrive with future context.

Use trusted libraries over reinventing

Reach for a well-maintained dependency before writing your own crypto, HTTP client, or token parser. The goal is a working solution, not a showcase of custom implementations. When a library exists and is maintained, use it.

Deep modules over shallow ones

Prefer a module with a small surface area and rich internals over a sprawl of thin wrappers. A single cohesive client that handles a concern cleanly beats a dozen one-method classes. More files is not more modular.

Single responsibility and separation of concerns