⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
a-philosophy-of-software-design
Apply John Ousterhout-inspired software design rules when reducing complexity, designing module boundaries, or reviewing APIs and abstractions.
// RATINGS
// README
About
MIT licensed universal project rules for coding agents.
This repository contains ready-to-use rule sets inspired by well-known books on software design, architecture, refactoring, legacy code, reliability, and data-intensive systems.
For editor-specific setup in Codex, Claude Code, and Cursor, see USAGE.md. It covers always-on vs on-demand usage, skills, scoped rules, and the preferred setup for each editor.
Each rule set is released in three tool-agnostic Markdown versions:
mini: the recommended version for most real task usenano: the compact fallback for very tight context budgetsfull: the canonical complete source and reference version
For constructive criticism from Reddit, see CRITICISM.md.
For release history, see CHANGELOG.md.
Installation as Skills
Prerequisite: install Node.js with npm. You can run the Skills CLI through npx without installing skills separately.
Install all book skills with the open Agent Skills CLI:
npx skills add ciembor/agent-rules-books --all
List available skills without installing:
npx skills add ciembor/agent-rules-books --list
Install one selected skill:
npx skills add ciembor/agent-rules-books --skill refactoring
Every book directory contains a standard SKILL.md entrypoint. The skill loads the corresponding mini rule set by default and keeps the full file available as deeper reference material.
If you prefer another setup, see USAGE.md for manual, scoped, always-on, and editor-specific installation patterns.
Release Matrix
Metrics:
lines: physical line count fromwc -lrules: Markdown list items counted with the deterministic release conventionsize: raw bytes fromwc -c
| Rule Set | Full file | Full lines | Full rules | Full size | Mini file | Mini lines | Mini rules | Mini size | Nano file | Nano lines | Nano rules | Nano size |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| A Philosophy of Software Design | full | 370 | 177 | 13561 B | mini | 46 | 28 | 5774 B | nano | 35 | 17 | 2258 B |
| Clean Architecture | full | 515 | 289 | 17782 B | mini | 49 | 31 | 5486 B | nano | 36 | 18 | 2254 B |
| Clean Code | full | 297 | 220 | 13851 B | mini | 47 | 29 | 3804 B | nano | 32 | 14 | 1235 B |
| Code Complete | full | 354 | 180 | 12407 B | mini | 56 | 38 | 6717 B | nano | 41 | 23 | 2544 B |
| Designing Data-Intensive Applications | full | 393 | 205 | 16084 B | mini | 55 | 37 | 6949 B | nano | 34 | 16 | 2575 B |
| Domain-Driven Design | full | 979 | 523 | 42424 B | mini | 48 | 30 | 5683 B | nano | 39 | 21 | 2266 B |
| Domain-Driven Design Distilled | full | 317 | 158 | 11351 B | mini | 56 | 38 | 6438 B | nano | 41 | 23 | 2535 B |
| Implementing Domain-Driven Design | full | 337 | 177 | 12848 B | mini | 57 | 39 | 7333 B | nano | 37 | 19 | 2723 B |
| Patterns of Enterprise Application Architecture | full | 404 | 196 | 15501 B | mini | 54 | 36 | 8099 B | nano | 35 | 17 | 2823 B |
| Refactoring | full | 433 | 242 | 17866 B | mini | 49 | 31 | 5167 B | nano | 37 | 19 | 1986 B |
| Release It! | full | 382 | 204 | 13542 B | mini | 48 | 30 | 6372 B | nano | 38 | 20 | 2205 B |
| The Pragmatic Programmer | full | 359 | 179 | 13398 B | mini | 65 | 47 | 7165 B | nano | 44 | 26 | 2263 B |
| Working Effectively with Legacy Code | full | 371 | 193 | 13817 B | mini | 50 | 32 | 5707 B | nano | 35 | 17 | 1792 B |
| Refactoring.Guru | full | 765 | 478 | 62561 B | mini | 64 | 46 | 6287 B | nano | 41 | 23 | 2593 B |
Books List
A Philosophy of Software Design
Author: John Ousterhout
The book focuses on fighting complexity through deep modules, simple interfaces, information hiding, and design choices that reduce cognitive load. This rule set is especially useful for API design, modul
// HOW IT'S BUILT
KEY FILES