A curated collection of battle-tested software design principles for monolith applications, plus an execution-discipline layer for changing code without breaking it — for both AI agents and humans.
SKILL.md ← Navigation hub (progressive disclosure)
├── references/ ← Deep dives for each principle group
│ ├── solid.md — SOLID: SRP, OCP, LSP, ISP, DIP
│ ├── grasp.md — GRASP: 9 responsibility assignment patterns
│ ├── general.md — DRY, KISS, YAGNI, Composition > Inheritance, etc.
│ ├── interface-design.md — Law of Demeter, CQS, Postel, Least Surprise
│ ├── package-design.md — ADP, CCP, SDP
│ ├── architecture.md — Layered, Dependency Rule, Ports & Adapters, Illegal States,
│ │ Parse Don't Validate, Idempotency, Shared State, DDD Lightweight
│ ├── execution-discipline.md — First make it work / Then make it right / Practice
│ └── quality-gates.md — CRAP, duplication, mutation, baseline + ratchet
├── examples/ — Runnable Go examples (before/after)
│ └── go/{illegalstates,parsevalidate,idempotency,sharedstate}
├── scripts/ — Working levers
│ ├── gates.sh — run every gate this machine can run
│ ├── crap-go.py — gocyclo + coverage → CRAP table
│ └── selftest.sh — prove the lever works
├── _zh/ — Chinese version (SKILL.md + references/ only)
│ ├── SKILL.md
│ └── references/
├── README.md
├── README.zh-CN.md
└── CHANGELOG.md
| Group | Principles |
|---|---|
| SOLID | Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion |
| GRASP | Information Expert, Creator, Controller, Low Coupling, High Cohesion, Polymorphism, Pure Fabrication, Indirection, Protected Variations |
| General | DRY, KISS, YAGNI, Composition over Inheritance, Tell Don't Ask, Fail Fast, Separation of Concerns, Information Hiding, Single Level of Abstraction, Boy Scout Rule, Extension over Configuration |
| Interface | Law of Demeter, Command-Query Separation, Postel's Law, Principle of Least Surprise |
| Package | Acyclic Dependencies, Common Closure, Stable Dependencies |
| Architecture | Layered Architecture, Dependency Rule, Ports & Adapters, Illegal States Unrepresentable, Parse Don't Validate, Idempotent Operations, Shared State Ownership, DDD Lightweight (Ubiquitous Language, Package Isolation, Entry Class, Data Access Layer) |
| Execution Discipline | Smallest checkable edit, Data shape before logic, Test first, Aim at a checkable end state, Subtract before you add, Attack the premise, Build the lever, Redesign from first principles, Fix the cause, Sequence into verifiable units, Test behavior not implementation, Refactor in three steps, Keep a log, Guard the context window, Cleanup, Small ordered commits |
| Quality Gates | CRAP (CC² × (1−coverage)³ + CC, threshold 10), structural duplication (Jaccard ≥ 0.8), mutation testing, baseline + ratchet adoption |
- Design principles (the first six groups) — what good design looks like. Static, referenceable, organized by scope.
- Execution discipline (
execution-discipline.md+quality-gates.md) — in what order you change code, and how you prove you did not break it. Procedural, ordered, with numeric exit conditions and a working script behind them.
Load the first layer when you are deciding where something belongs. Load the second when you are about to touch the keyboard.
This skill follows the progressive disclosure pattern:
- SKILL.md — Navigation hub with quick reference and gotchas
- references/ — Deep dives with origin, intent, recognition patterns, before/after examples, and gotchas
- examples/ — Runnable Go examples where a before/after contrast teaches more than prose
- scripts/ — Working levers:
gates.shto run the gates,crap-go.pyto join complexity and coverage,selftest.shto prove the join
Each principle includes:
- Origin — Who proposed it and when
- Intent — What problem it solves
- Recognition — How to spot violations
- Before/After — Concrete code examples
- Gotchas — Common mistakes even experienced developers make
MIT
中文版位于 _zh/ 目录（含 SKILL.md + references/），从 _zh/SKILL.md 开始阅读。