Core Principles

These principles guide every technical decision. They're not rules to follow blindly, but lenses through which to evaluate choices.

KISS: Keep It Simple, Stupid

The simplest solution that works is usually the right one. Complexity is a tax paid every time someone reads, modifies, or debugs the code.

In practice:

• Prefer obvious code over clever code
• Avoid abstractions until you need them (rule of three)
• Question every dependency added

DRY: Don't Repeat Yourself

Every piece of knowledge should have a single, unambiguous representation. But beware the wrong abstraction—duplication is cheaper than the wrong abstraction.

In practice:

• Extract when you see the same logic three times
• Don't DRY across unrelated domains
• Configuration is knowledge too

YAGNI: You Aren't Gonna Need It

Build for today's requirements, not imaginary future ones. The future you're predicting probably won't happen, and you'll carry the complexity cost regardless.

In practice:

• Skip the config file until you need runtime changes
• Don't build the plugin system until the second plugin
• Delete speculative code

Explicit Over Implicit

Code should say what it does. Magic is for stage shows.

In practice:

• Prefer explicit dependencies over global state
• Name things by what they do, not implementation details
• Make the happy path obvious

Fail Fast, Fail Loud

Errors should be caught early and reported clearly. Silent failures are debugging nightmares.

In practice:

• Validate inputs at boundaries
• Use assertions for invariants
• Log with context

The Boy Scout Rule

Leave the code better than you found it. Small, continuous improvements compound.

In practice:

• Fix the naming while you're there
• Add the missing test
• But don't refactor the whole file on an unrelated PR