Architecture and Engineering Principles

Optimise for local reasoning. A developer should be able to find, understand, change and verify a capability by examining a small, obvious part of the codebase, without navigating layers of indirection or hidden dependencies.

Language-independent defaults for small projects maintained by one person and future coding agents. Prefer the simplest coherent design meeting actual requirements. Apply rigour proportionately, never mechanically. See tech-preferences for what to build with, and verifiable-trust for AI risk and permission boundaries.

Justify complexity before implementing it

• Challenge the requirement, not only the code. Before adding a component, behaviour, dependency or defensive mechanism, identify the concrete need and the simplest end-to-end outcome. Deleting an unnecessary requirement is often better than implementing it elegantly.
• Distinguish evidence from hypotheticals. Defend against credible failures according to their likelihood, consequence and recoverability; do not build elaborate machinery for speculative scenarios. Preserve strong safeguards for credentials, permissions and irreversible persistent-state changes.
• Make complexity earn its keep. Each new concept, validation, layer, configuration option or test should reduce a real risk or enable a real capability. Reuse the platform or an existing installer where it removes work, rather than rebuilding its responsibilities.
• Prefer a small complete solution. Avoid temporary compatibility code in inactive replacements when the cutover will remove it, unless a real consumer or migration step needs it. Do not solve duplication by introducing a framework that is harder to navigate than the duplicated code.
• Revisit the finished design. After behaviour works, check whether responsibilities, branches or dependencies can disappear without weakening essential behaviour. Optimise for fewer concepts and faster comprehension, not minimum lines or arbitrary limits.

Structure and navigation