A Philosophy of Software Design-Inspired Guide
Behavioral guidelines for AI coding agents inspired by A Philosophy of Software Design, 2nd Edition by John Ousterhout (Yaknyam Press, 2021).
Designed for Claude Code, OpenCode, Cursor, and any AI coding agent.
The Problem
Software complexity is the fundamental challenge in writing programs. As systems grow, complexity accumulates and makes code harder to understand, modify, and extend. Most programmers focus on getting code working quickly ("tactical programming") without investing in design quality, which accelerates the accumulation of complexity.
"The greatest limitation in writing software is our ability to understand the systems we are creating."
Ousterhout identifies three symptoms of complexity:
| Symptom | Description |
|---|
| Change amplification | A single change requires edits in many places |
| Cognitive load | How much a developer must hold in their head to make a change |
| Unknown unknowns | You don't know what code to change or what to consider |
Every principle and red flag in this skill traces to one of these three.
The Solution
Fifteen behavioral rules in one CLAUDE.md file that make agents design software strategically, not tactically:
| Rule | Addresses |
|---|
| Strategic Over Tactical | Design debt, "just make it work" pressure |
| Design Deep Modules | Shallow interfaces, classitis |
| Information Hiding | Leaky abstractions, exposed internals |
| Design General-Purpose Modules | Special-purpose code, narrow interfaces |
| Different Layer, Different Abstraction | Pass-through methods and variables |
| Pull Complexity Downward | Complex callers, simple implementations |
| Comments First | Missing or useless documentation |
| Choosing Names | Vague names, inconsistent conventions |
| Design for Reading | Obscure code, cognitive load |
| Define Errors Out of Existence | Error-handling duplication |
| Better Together or Better Apart | Wrong module boundaries |
| Design It Twice | First-design bias |
| Design for the Future | Unencapsulated volatility |
| Increments Are Abstractions | Feature-driven decomposition |
| Modify Strategically | Code rot during maintenance |
Plus two on-demand analysis commands:
| Command | Purpose |
|---|
aposd critique [target] | Evaluate design against 18 principles + dual-persona assessment (Strategic Thinker + Tactical Tornado). P0–P3 severity tagging. Results saved to .aposd/critique/ for trend tracking. Suppress recurring findings in .aposd/critique/ignore.md. |
aposd audit [target] | Countable design audit: 5 dimensions scored 0–4, total /20. Tactical Tornado risk assessment. P0–P3 severity tagging. |
See docs/output-interpretation.md for how to interpret scoring, severity, personas, and snapshot persistence.
Install
Option A (Recommended): npx skills
npx skills add mhenke/john-ousterhout-skills
Option B: Claude Code Plugin
From within Claude Code, add the marketplace and install:
/plugin marketplace add mhenke/john-ousterhout-skills
/plugin install john-ousterhout-skills@aposd-skills
Option C: Cursor
Copy .cursor/rules/aposd-guidelines.mdc into your project's .cursor/rules/ directory. See CURSOR.md.
Option D: OpenCode
Clone the repo and symlink skills into ~/.config/opencode/skills/:
git clone https://github.com/mhenke/john-ousterhout-skills.git
cd john-ousterhout-skills
ln -s $(pwd)/skills/aposd ~/.config/opencode/skills/aposd
ln -s $(pwd)/skills/aposd-critique ~/.config/opencode/skills/aposd-critique
ln -s $(pwd)/skills/aposd-audit ~/.config/opencode/skills/aposd-audit
How to Know It's Working
These guidelines are working if you see:
- Fewer pass-through chains and shallow classes — Modules have simple interfaces and substantial implementations
- Comments written before code — Interface documentation precedes implementation
- Errors eliminated, not handled — Interfaces designed so common errors can't happen
- Design discussed before implementation — "Design it twice" becomes a natural habit
- Cleaner diffs during maintenance — Code improves with each modification instead of accumulating debt
Key Insight
From Ousterhout:
"The overall goal is to reduce complexity; this is more important than any particular principle or idea you read here."
When principles conflict, the one that better reduces cognitive load wins. Every red flag traces to one of the three complexity symptoms. If a principle isn't reducing complexity, don't apply it dogmatically.
Customization
These guidelines are designed to be merged with project-specific instructions. Add them to your existing CLAUDE.md or create a new one.
