Mental models for software engineers

The mental models

• Gall’s law

  A complex system that works invariably evolved from a simple system that worked — which is why grand rewrites and designed-from-scratch architectures so rarely do. Ship the simplest working version and grow it; don't design the end state up front.

• Conway’s law

  Your architecture will mirror your org chart: separate teams produce separate services with interfaces shaped like their communication paths. To change the system's structure, you usually have to change who talks to whom.

• Chesterton's fence

  That odd guard clause or "pointless" config was probably put there to stop something you haven't seen yet. Understand why the code exists before deleting it — or you'll rediscover the outage it was preventing.

• Bottleneck

  One constraint — a slow query, a flaky pipeline stage, one overloaded reviewer — caps the whole system's throughput. Profile first: optimizing anything except the bottleneck changes nothing but the code.

• Entropy

  Codebases drift toward disorder by default — dependencies rot, docs go stale, quick fixes accumulate. Maintenance isn't the boring part of engineering; it's the constant energy a working system needs just to stay working.

• Redundancy

  Backups, failover, and retries look like waste until the day they're survival. A system tuned for perfect efficiency has removed exactly the slack that absorbs failures.

• Second-order thinking

  The quick fix compiles today and creates the incident next quarter. Before shipping, trace the "and then what?" — what this change trains callers, teammates, and future code to depend on.

• Local vs global optimum

  Incremental refactors can strand a codebase on a local peak — better than every nearby variant, far below a different design. Sometimes the only path to the better architecture runs through a temporarily worse state.

• Via negativa

  Deleting code is often the highest-value commit: less surface, fewer states, fewer bugs. Knowing what to remove — a dependency, a feature flag, an abstraction — is more reliable than knowing what to add.

• Occam’s razor

  Debug the simple explanation first — the typo, the stale cache, the wrong environment — before the exotic one. The simplest hypothesis isn't always right, but it's the cheapest to rule out.

• The map is not the territory

  The diagram, the docs, and the staging environment are maps; the running production system is the territory. Systems fail precisely in the gaps the map was never drawn to show.

• Goodhart's law

  Make coverage, velocity, or ticket-count a target and engineers will optimize the number, not the quality it was meant to track. Every dashboard you reward eventually measures ingenuity at hitting dashboards.

Biases that trip up software engineers

• The planning fallacy

  Every similar feature ran over, yet this estimate assumes the smooth best case — because from inside a plan, the unknown obstacles are invisible. Estimate from how the last ten tasks actually went, not from the plan.

• Sunk-cost fallacy

  The migration is two quarters in and clearly failing, but abandoning it feels like wasting the work already done. Past effort is gone either way — only the remaining cost and payoff should decide.

• The IKEA effect

  Code you wrote yourself feels worth more than the sturdier library that already exists — the root of not-invented-here syndrome and the in-house tool nobody else can maintain.

• The curse of knowledge

  Once you know how the system works, you can't imagine not knowing — so your API docs, error messages, and onboarding assume context the reader doesn't have.

• Action bias

  Under an outage, doing something — restarting, rolling back, patching live — feels better than reading the logs first. Visible motion beats understanding in the moment, and loses over the incident.

• Optimism bias

  It works on your machine, the migration "should be fine", the edge case "won't happen" — engineers systematically plan for the happy path and are surprised by the ordinary one.

• Hindsight bias

  After the incident, the cause looks like it was obvious all along — which makes post-mortems drift into blame instead of asking why the failure was invisible beforehand.

Mental models for other work