Principle: Design for replaceability, not reusability

Over-engineering for reusability creates complex abstractions that are never actually reused and are hard to change.

Instead of making components reusable, make them replaceable:

Reusability-focused (over-engineered):

• Generic interfaces for hypothetical future uses
• Plugin architectures for one implementation
• Configuration-driven behavior for two cases
• Abstract base classes with one concrete class

Replaceability-focused (pragmatic):

• Clear boundaries between components
• Small, focused modules with explicit dependencies
• Simple interfaces at module boundaries
• No shared mutable state between modules

Test: Can you rewrite this module from scratch in a day?

• If yes: it's replaceable - good
• If no: it's too coupled to too many things - simplify

Practical rules:

1. Write concrete code first. Extract abstractions when you have 3+ concrete cases
2. Prefer duplication over the wrong abstraction
3. Keep modules small enough to throw away
4. Depend on interfaces at boundaries, concrete types internally
5. If you wouldn't open-source it as a library, don't engineer it like one

Software requirements change constantly. Replaceable components adapt to change cheaply. Reusable components often resist change because modifying them affects all users.

Making architectural decisions about code organization and abstraction