Philosophy of Software Design

Apply John Ousterhout's "A Philosophy of Software Design" (2018; 2nd ed. 2021) — design as the fight against complexity. Covers complexity's symptoms (change amplification, cognitive load, unknown unknowns) and causes (dependencies, obscurity), strategic vs tactical programming, deep vs shallow modules, information hiding and leakage, temporal decomposition, somewhat-general-purpose interfaces, different layer different abstraction, pass-through methods, pulling complexity downwards, defining errors out of existence, design it twice, comments as design, and the red-flags catalogue. Adds the de

5 stars 2 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add vnovakovits/claude-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add vnovakovits/claude-skills --skill philosophy-of-software-design
Manual install
git clone --depth 1 https://github.com/vnovakovits/claude-skills.git /tmp/claude-skills
mkdir -p ~/.claude/skills
cp -r /tmp/claude-skills/plugins/engineering-practices/skills/philosophy-of-software-design ~/.claude/skills/philosophy-of-software-design

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# A Philosophy of Software Design (John Ousterhout)

Apply this skill when designing or reviewing the *shape* of code: what a module exposes, what it hides, where one module ends and the next begins, and how errors cross its interface. Ousterhout's single theme is **complexity**: every design decision either adds to it or removes it, and good design is the steady removal of it. The skill also carries a few sharpening ideas from Matt Pocock's `codebase-design` skill (the deletion test, depth as leverage, the adapter rule for seams).

## Core Philosophy

**Complexity is the enemy.** Complexity is anything about a system's structure that makes it hard to understand or change. It isn't measured by size: a large system can be simple to work in, and a small one can be miserable. What counts is the complexity of each part weighted by how much time developers spend in it.

**Complexity is incremental.** No single shortcut makes a system complex; hundreds of small ones do. That is why "it's only a little hack" is the most expensive sentence in software, and why removing complexity needs a standing habit rather than a cleanup sprint.

**Modules should be deep.** The best modules hide a lot of functionality behind a simple interface. The interface is a cost every caller pays; the functionality is the benefit. Design to maximise the benefit per unit of cost.
Read the full skill on GitHub

Details

Skill name
philosophy-of-software-design
Path
plugins/engineering-practices/skills/philosophy-of-software-design/SKILL.md
License
MIT
Repo updated
16 November 2026

FAQ

What does the Philosophy of Software Design skill do?

Apply John Ousterhout's "A Philosophy of Software Design" (2018; 2nd ed. 2021) — design as the fight against complexity. Covers complexity's symptoms (change amplification, cognitive load, unknown unknowns) and causes (dependencies, obscurity), strategic vs tactical programming, deep vs shallow modules, information hiding and leakage, temporal decomposition, somewhat-general-purpose interfaces, different layer different abstraction, pass-through methods, pulling complexity downwards, defining errors out of existence, design it twice, comments as design, and the red-flags catalogue. Adds the de

How do I install the Philosophy of Software Design skill?

Claude Code plugin: /plugin marketplace add vnovakovits/claude-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Philosophy of Software Design popular?

It lives in vnovakovits/claude-skills, which has 5 GitHub stars and 2 forks.

Related skills

Accidental Cio

5

vnovakovits/claude-skills

Apply Scott Millett's "The Accidental CIO — A Lean and Agile Playbook for IT Leaders" (Wiley, 2024) when designing or reviewing how a technology organisation decides, funds, governs and delivers work. Covers the five components of an adaptive IT operating model (organised, work, govern, talent, lead) and its four themes (outcomes over output, intrinsic motivation, being not doing agile, manage flow not people); matching method and governance to context via Cynefin and Wardley evolution; governance as demand management + funding + measurement + decision rights, shifting from project funding to

Frontend & Design

Agent Retro

5

vnovakovits/claude-skills

Run a retrospective on a coding-agent session and improve the agent's environment, not the code. Combines Derby & Larsen's five-stage retrospective, Shigeo Shingo's poka-yoke (turn a mechanical mistake into a check that makes it impossible), and Matt Pocock's retro categories — navigation, automated checks, coding standards, steering files, tool economy, information access. Covers mining the session transcript for corrections, wrong turns and slow searches; deciding where each fix belongs (analyzer, hook, CI, reviewer standards, CLAUDE.md pointer, skill, doc or memory); the no-op test for stee

AI, LLMs & Agents

API Design

5

vnovakovits/claude-skills

Design APIs that are clear, evolvable, and idiomatic to their protocol — covering REST (Fielding, Richardson Maturity Model, Massé), GraphQL, gRPC/protobuf, versioning strategies, pagination, error responses (RFC 7807 Problem Details), idempotency, authentication, documentation (OpenAPI), and the pragmatic trade-offs between RESTful purity and developer ergonomics. Use when designing a new endpoint, choosing between REST/GraphQL/gRPC, defining versioning, structuring error responses, deciding pagination strategy, or evaluating an existing API's evolvability.

Software Development

Pi Extension Dev

5

bolasblack/claude-skills

End-to-end workflow for developing, debugging, configuring, and shipping pi-coding-agent extensions and pi packages. Use when building or maintaining extensions, skills, prompt templates, themes, settings.json setups, provider integrations, or when updating this skill after pi releases. Do NOT use for general coding questions unrelated to pi extension development.

Software Development

Pattern Extraction

8

Freddy-CHEN-ux/00_claude_skills

Three-tier system for documenting code patterns to optimize token usage

Software Development

Plugin Developer

8

Freddy-CHEN-ux/00_claude_skills

Create and maintain Claude Code plugins following established patterns

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.