New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Design principles from John Ousterhout's book, distilled into a guide for reviews, module splits, and API design.

skills.sh installs
261
GitHub stars
359
last updated
Aug 21, 2026
View on GitHub

What it does

  • Covers complexity analysis, strategic versus tactical programming, and deep versus shallow module design
  • Includes checklists for information leakage, pass-through methods and variables, and pulling complexity downward
  • Provides a strategy for defining errors out of existence, plus guidance on designing two alternatives before committing
  • Designed for code reviews, architecture discussions, and refactoring where design quality feedback is requested

Install

$ npx -y skills add luoling8192/software-design-philosophy-skill --skill software-design-philosophy -y

Installs into .agents/skills for every agent it finds here, and .claude/skills for Claude Code.

Files

A Philosophy of Software Design — Distilled Guide

Source: John Ousterhout, A Philosophy of Software Design Central thesis: The core challenge of software design is managing complexity.


I. Complexity: Know the Enemy

Definition

Complexity is anything related to the structure of a software system that makes it hard to understand and modify. Complexity is not the same as system size — a small system can be complex, and a large well-designed system can be manageable.

Three Symptoms of Complexity

  1. Change Amplification: A seemingly simple change requires code modifications in many different places.
  2. Cognitive Load: Developers must absorb a large amount of information to complete a task safely. Note: fewer lines of code ≠ simpler — sometimes more code is actually simpler because it reduces cognitive load.
  3. Unknown Unknowns: It's unclear which code must be modified or what information is needed to complete a task. This is the most dangerous symptom.

Two Root Causes

Details

Repository
github.com/luoling8192/software-design-philosophy-skill
Categories
Backend & APIs, Git & Pull Requests, Documentation, Code Review & Quality, Debugging, Design & UI/UX
First seen
Jun 3, 2026

Similar to Software Design Philosophy

More Backend & APIs