Code That Fits in Your Head

Engineering heuristics for sustainable software, based on Mark Seemann's 2021 book and clearly labelled agent-era amendments.

Code examples are C#-first; every rule and the tooling tables are language-neutral.

Philosophy (Why This Skill Exists)

Software development is principally a design activity, not construction. An agent may produce most of the text, but people still review, operate, extend, and own the resulting system. These heuristics make software sustainable: understandable, resistant to architectural erosion, and cheap to change after thousands of decisions.

Core mental model from Chapter 1:

Metaphor	What it gets right	What it misses
Building a house	Plans, structure	Software endures; there's no construction phase (compiling is free); dependencies can start anywhere
Growing a garden	Pruning, refactoring, tending	Code does not improve by itself; generated code still needs stewardship
Art / craft	Skill, mastery, situational knowledge	Doesn't scale; leaves newcomers without guidance
Engineering (the target)	Heuristics, review, sign-off, checklists	We're not there yet — physical-construction calculations don't apply

code-that-fits-in-your-head

Code That Fits in Your Head

Philosophy (Why This Skill Exists)