code-that-fits-in-your-head

# Code That Fits in Your Head

Engineering heuristics for sustainable software, based on Mark Seemann's 2021 book.

## Philosophy (Why This Skill Exists)

Software development is principally a **design activity**, not construction. Code is written by people, read by people, and endures far longer than any "project". These heuristics are rules of thumb (not scientific laws) that make software sustainable — that is, cheap to change and resilient to the next 10,000 small 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 doesn't grow by itself — someone writes it |
| **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 don't lock the future; avoid "finish-and-forget" thinking.
2. **Heuristics, not laws.** Every rule in this skill has context. Understand *why* before deviating. When the user asks to break a rule, check if their reason addresses the rule's rationale.
3. **Design = typing code.** Code review, naming, function size, and API shape are the primary design surfaces.
4. **The future is unevenly distributed.** Techniques described here (CI, tests, checklists, STRIDE) exist today — adopt them per-context rather than arguing for greenfield-only use.

See `references/foundations/` for more on sustainability, readability, and brain-limited design.

## How to Use This Skill

1. Identify the user's task (writing, reviewing, debugging, security review, setting up, etc.)
2. Read `guidelines.md` — it maps tasks and symptoms to specific reference files
3. Load only the reference files relevant to the current task (progressive disclosure)
4. Apply the rules; when in doubt, consult `references/practices-glossary/` for cross-references

## Chapter Index

| Topic | Use when... |
|-------|-------------|
| `references/foundations/` | Understanding why code should fit in head; sustainability, readability, humane code |
| `references/codebase-setup/` | Starting or inheriting a code base — git, build automation, warnings-as-errors |
| `references/outside-in-tdd/` | Writing new features test-first; walking skeleton, AAA, triangulation, devil's advocate, editing tests |
| `references/encapsulation/` | Designing types with invariants; DTO vs Domain Model, always-valid, Postel's law, parse-don't-validate |
| `references/decomposition/` | Splitting a function/class; cyclomatic complexity, 80/24 rule, cohesion, feature envy, fractal architecture, composition |
| `references/api-design/` | Designing a public API; affordance, poka-yoke, CQS, hierarchy of communication, naming over comments |
| `references/separation-of-concerns/` | Adding cross-cutting concerns; Decorator pattern, logging, what to log, performance vs legibility |
| `references/teamwork-git/` | Writing commits, reviewing PRs; 50/72 rule, small commits, continuous integration, pair/mob, code review |
| `references/evolution/` | Changing running systems; feature flags, Strangler pattern, versioning, regular dependency updates, Conway's law |
| `references/troubleshooting/` | Debugging a defect; scientific method, rubber ducking, reproduce-as-test, bisection, non-deterministic defects |
| `references/security/` | Threat modelling; STRIDE (spoofing, tampering, repudiation, info disclosure, DoS, elevation) |
| `references/code-navigation/` | Onboarding to a code base; big picture, file organisation, cycles, property-based testing, behavioural code analysis |
| `references/practices-glossary/` | Looking up a named practice by name (28 entries: 50/72, 80/24, AAA, Bisection, CQS, Strangler, etc.) |

### ⚠️ Editorial amendments (NOT from the book)

The folder below is NOT content from Seemann's book. It contains our own additions covering agent-specific concerns the 2021 book does not address. Do not attribute these files to Seemann. See `references/agent-native/knowledge.md`.

| Topic | Use when... |
|-------|-------------|
| `references/agent-native/` | The question is specifically about how a code agent should do something differently from Seemann's 2021 guidance — tight verification loops, hallucination debugging, strict types as primary guardrails, reviewable vs readable code |

## Workflows

Composite step-by-step processes live in `workflows/`:

| Task | Workflow |
|------|----------|
| Review a pull request / piece of code | `workflows/review-code.md` |
| Add a new feature from scratch | `workflows/add-feature-outside-in.md` |
| Investigate and fix a defect | `workflows/debug-defect.md` |
| Threat-model a new endpoint | `workflows/threat-model.md` |

See `guidelines.md` for the full routing layer (task → file, symptom → file, decision tree).