---
name: book--a-philosophy-of-software-design--nano
description: >-
  Philosophy of Software Design (John Ousterhout) — Minimal rules — essential one-liners only. Use when asked to apply Philosophy of Software Design principles or review code against Philosophy of Software Design standards.
origin: "github.com/ciembor/agent-rules-books (MIT)"
license: MIT
version: "1.0.0"
compatibility: "yamtam-engine >= 0.14.0"
---

# OBEY A Philosophy of Software Design by John Ousterhout

## When to use

Use when the main risk is accidental complexity, shallow abstractions, leaky interfaces, or tactical patches.

## Primary bias to correct

Working code, small pieces, and familiar wrappers are not automatically simple.

## Decision rules

- Optimize for lower cognitive load and local understandability, not shorter files, familiar patterns, fewer lines, or clever compactness.
- Prefer deep modules; reject wrappers, layers, helpers, facades, and split-outs that do not hide real complexity.
- Hide volatile decisions, representations, storage, protocol facts, workflow bookkeeping, and messy edge handling in one owning module.
- Make interfaces caller-centered and semantic; avoid staged APIs, flags, setup sequences, and mechanism leakage when the module can provide the right operation.
- If a change feels awkward or spreads widely, improve ownership and abstraction instead of adding tactical special cases.
- Combine or split by total complexity: keep shared knowledge together and split only at independently understandable boundaries.
- Treat names and comments as design signals: precise abstraction names, explicit contracts, and no comments that compensate for bad decomposition.
- Add complexity for performance, trends, patterns, frameworks, tests, or exception handling only when evidence or caller needs justify it.

## Trigger rules

- When adding a helper, layer, option, callback, pattern, or abstraction, prove it removes complexity for callers.
- When an API requires sequencing, representation, storage, transport, caching, protocol, or file-format knowledge, redesign the boundary.
- When naming is hard, comments get long, or reviewers are surprised, treat it as design evidence.
- When one change spreads widely, look for duplicated knowledge, hidden dependencies, temporal coupling, or the wrong owner.
- When optimizing or adding exception paths, keep the common path simple and require evidence or a stronger invariant.

## Final checklist

- Fewer concepts to hold?
- More complexity hidden below the right boundary?
- Fewer special cases, knobs, leaks, and call-order traps?
- Better names, contracts, ownership, and evidence for any added complexity?