Software Design Philosophy

luoling8192/software-design-philosophy-skill

This distills John Ousterhout's "A Philosophy of Software Design" into actionable guidance for code reviews and architecture decisions. It's built around managing complexity through deep modules (simple interfaces hiding rich implementations), information hiding, and pulling complexity down into modules rather than pushing it to callers. The most immediately useful parts are the red flags: pass-through methods, information leakage, and shallow modules that do too little behind complex interfaces. Invoke it when debating how to split modules, whether to add configuration parameters, or how to handle errors. The "define errors out of existence" section alone will change how you think about exception handling.

skills.sh installs: 256
GitHub stars: 356
last updated: Aug 21, 2026

View on GitHub

Install

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

Installs into .claude/skills of the current project.

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

Change Amplification: A seemingly simple change requires code modifications in many different places.
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.
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.