Which trade-offs actually shifted

Most architectural advice survives unchanged. Four trade-offs genuinely moved, and knowing which matters more than any new principle.

There is a temptation to declare that everything about software design has changed. It has not. Cohesion, coupling, clear boundaries and good names are still what makes a system workable, for exactly the same reasons.

Four specific trade-offs have moved, though, and they moved because the cost of writing code fell while the cost of understanding it did not.

1. Duplication versus indirection

Shifted toward tolerating duplication. The classic argument for extracting a shared abstraction was partly that writing the second copy was expensive. It is not any more. Meanwhile the cost of indirection — following an abstraction across five files — is paid by every reader, human and agent, on every visit.

This does not license copy-paste everywhere. It shifts the threshold: three similar-but-not-identical implementations that each read top to bottom are now often better than one parameterised abstraction with five options, where they were previously a clear smell.

2. Explicit versus implicit

Shifted hard toward explicit. Convention-over-configuration frameworks rely on knowledge that exists nowhere in the repository. A human learns the convention once; an agent re-derives it every session from whatever is in context, and gets it wrong when the convention is unusual.

Explicit wiring costs lines and saves an entire category of confident wrong guesses. The same applies to magic: decorators that do three things, metaprogramming, implicit registration by file location.

3. Cleverness versus searchability

Shifted hard toward searchability. An agent finds code by grep. A dynamically constructed method name, a handler registered by convention, a string assembled at runtime — all of these are invisible to search, and therefore effectively invisible.

// invisible: grep for "handleOrderCreated" finds nothing
const handler = handlers[`handle${pascalCase(event.type)}`]

// findable
const handler = {
  'order.created': handleOrderCreated,
  'order.refunded': handleOrderRefunded,
}[event.type]

4. Test coverage versus test quality

Shifted toward quality, sharply. Coverage was always a weak proxy. Now that generating tests is nearly free, coverage is trivially achievable and says almost nothing, while the value of tests that genuinely discriminate correct from incorrect has gone up — because they are what lets you delegate.

What did not shift

• Boundaries and cohesion. Still the main determinant of whether a system stays workable.
• Simplicity. Cheap generation makes complexity cheaper to produce and no cheaper to live with.
• Naming. If anything more important, since names are a large part of what an agent has to reason from.
• The cost of a bad data model. Unchanged and still the most expensive mistake available.
• Deleting code. Still the best refactor, and now more valuable because dead code becomes context.

The one-sentence summary

Optimise for a reader who is fast, tireless, has no memory between visits, and can only see what is in front of them. That description fits an agent, and it also fits a new engineer on their first week — which is why almost everything in this module is good design advice that happens to have become more urgent.

Question: "what happens when an order.refunded event arrives?"

grep -r "order.refunded" .
  -> 3 hits, all in test fixtures and one JSON schema. No handler.

The handler lived in src/events/order/refunded.ts and was registered by
a loader that walked the directory and derived the event name from the
path. The string "order.refunded" appeared nowhere in the handler.

Time for me, knowing the system: 4 minutes.
Time for an agent, no prior knowledge: it never found it. It reported
that no handler existed and proposed writing one.

Three separate sessions in which an agent concluded a handler did not
exist and proposed creating a duplicate. Two were caught in review. One
was not, and shipped a second handler for order.created which ran
alongside the first for nine days, double-sending a customer email.

// src/events/registry.ts - one file, explicit, greppable
export const HANDLERS = {
  'order.created':  handleOrderCreated,
  'order.refunded': handleOrderRefunded,
  'order.shipped':  handleOrderShipped,
  // ... 31 entries
} satisfies Record

The loader was deleted. 31 lines of explicit registration replaced 40
lines of directory-walking magic.

Bonus, unplanned: the `satisfies Record` made it a
compile error to have an event type with no handler. The old system
silently dropped unhandled events, which it turned out had been
happening for one event type for four months.

A course by Pieter Zandbergen