code-that-fits-in-your-head

# Code That Fits in Your Head Engineering heuristics for sustainable software, based on Mark Seemann's 2021 book and clearly labelled agent-era amendments. ## 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 | > "The act of describing a program in unambiguous detail and the act of programming are one and the same." — Kevlin Henney **Practical implications for a code agent:** 1. **Successful software endures.** Prefer changes that preserve clear boundaries and keep future change affordable. 2. **Co...