Skip to content

ciembor/agent-rules-books / a-philosophy-of-software-design

a-philosophy-of-software-design

Verified

Apply John Ousterhout-inspired software design rules when reducing complexity, designing module boundaries, or reviewing APIs and abstractions.

a-philosophy-of-software-design.nano.md

View on GitHub
# 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?
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall