# Software Design > Reducing complexity through thoughtful software design — an AI agent skill based on *A Philosophy of Software Design* by John Ousterhout. Published 2026-02-23 · Updated 2026-08-17 · Code Quality · Free and MIT-licensed Canonical: https://skills.wondel.ai/skills/software-design-philosophy/ Source: https://github.com/wondelai/skills/tree/main/software-design-philosophy **Install:** `npx skills add wondelai/skills/software-design-philosophy --global` ## What is the Software Design skill? One target drives everything in John Ousterhout's A Philosophy of Software Design: reducing complexity. This free skill points your agent at it too, arguing for deep modules behind simple interfaces, for hiding information rather than passing it around, and for spending design effort now instead of paying interest later. ## Key concepts from A Philosophy of Software Design your agent applies - **Deep vs Shallow Modules** — The best modules have simple interfaces that hide significant implementation complexity — depth matters more than number of modules. - **Information Hiding** — Each module should encapsulate design decisions that are likely to change, exposing only what callers need to know. - **Strategic vs Tactical Programming** — Invest time to design clean abstractions upfront (strategic) rather than hacking quick fixes (tactical). - **Define Errors Out of Existence** — Design interfaces so that error conditions cannot occur, rather than handling them after the fact. - **Complexity Signals** — Watch for change amplification, cognitive load, and unknown unknowns — the three manifestations of complexity. ## When to use Software Design — and when not to Reach for it when: - Every new feature touches six files, which is the classic signal that your modules are too shallow. - An interface has more parameters and special cases than the implementation behind it saves you. - You are deciding how much design effort a new component deserves before writing it. - You want error cases designed out of existence rather than handled in every caller. Reach for something else when: - You need naming and function-level style rules — Clean Code is more specific and more prescriptive. - The question is which layer owns a dependency — use Clean Architecture. - You are modelling a complex business domain and its language — Domain-Driven Design fits better. - You want a mechanical, catalogued transformation of existing code — that is Refactoring. ## About John Ousterhout Stanford professor, creator of Tcl/Tk, ACM Software System Award winner. John Ousterhout is a professor at Stanford University and the creator of Tcl/Tk, the Raft consensus algorithm (co-creator), and the RAMCloud storage system. He has been awarded the ACM Software System Award and the UC Berkeley Distinguished Teaching Award. More: https://en.wikipedia.org/wiki/John_Ousterhout · https://www.wikidata.org/wiki/Q92636 The book: https://openlibrary.org/books/OL39808159M/A_Philosophy_of_Software_Design_2nd_Edition ## Example prompts - Evaluate whether these modules are deep or shallow and suggest improvements using software-design-philosophy skill _(Design review)_ - Redesign this API to hide implementation complexity behind a simpler interface using software-design-philosophy skill _(API design)_ - Identify complexity signals in this codebase and propose fixes using software-design-philosophy skill _(Code review)_ - Refactor this error handling to define errors out of existence using software-design-philosophy skill _(Error handling)_ ## Frequently asked questions ### How do I install the Software Design skill? Run `npx skills add wondelai/skills/software-design-philosophy --global`. It takes about 30 seconds and needs no account. The Software Design skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills. ### Which book is the Software Design skill based on? It packages *A Philosophy of Software Design* by John Ousterhout — stanford professor, creator of Tcl/Tk, ACM Software System Award winner. The skill distils the book's method into instructions your agent follows while it works, covering deep vs shallow modules, information hiding and strategic vs tactical programming. It sits in the Code Quality part of the library. ### What makes a module "deep"? A deep module hides a lot of functionality behind a small interface — a garbage collector with no API at all is the extreme case. A shallow module is the opposite: an interface almost as complicated as the implementation, so using it costs about as much as writing it yourself. The skill treats interface-to-implementation ratio as the primary design signal, which is why it will sometimes argue against splitting a class. ### Does this contradict Clean Code on small functions? On one point, yes, and the skill does not pretend otherwise. Ousterhout argues that splitting functions purely to make them short can create shallow modules and spread complexity across more places than it removes. If you install both, expect them to disagree about a long-but-cohesive function; the skill will make the complexity argument so you can decide, rather than applying a rule silently. ### What is "strategic programming" and why does it cost 10-20% more? Strategic programming means the goal of each change is a good design, not just working code — so you spend a little extra on every commit rather than a lot on a rewrite later. Ousterhout puts the overhead at 10-20%, and the skill will flag when a shortcut is being taken tactically so the trade is deliberate rather than accidental. ## Related - All Code Quality skills: https://skills.wondel.ai/skills/code/ - Clean Code: https://skills.wondel.ai/skills/clean-code/ - Pragmatic Programmer: https://skills.wondel.ai/skills/pragmatic-programmer/ - Refactoring: https://skills.wondel.ai/skills/refactoring-patterns/ - Legacy Code: https://skills.wondel.ai/skills/working-with-legacy-code/