software-design
Installation
SKILL.md
Software Design
Core Principle
Build the simplest design that faithfully represents the problem's real contracts, responsibilities, and sources of variation. Optimize for a coherent, maintainable system rather than the fewest lines changed or the smallest immediate edit. An abstraction is valuable when it captures a genuine boundary; introducing layers by habit is not an improvement.
Responsibility and Change Boundaries
- One reason to change per responsibility. Group behavior by what it does and why it changes. Separate concerns that evolve independently, even if combining them is initially convenient.
- Reusable definitions versus instance data. Keep stable algorithms, policies, schemas, and instructions separate from invocation-specific values, current state, temporary observations, and environment bindings. Reusable artifacts should not silently capture a snapshot of one use.
- Entry points versus core behavior. CLI commands, notebooks, scheduled jobs, web handlers, and event handlers adapt their environment to reusable operations. Parsing, startup, and I/O orchestration should not be entangled with the processing logic they invoke.
- Information lives at its owning boundary. A value, decision, or rule belongs where its meaning is defined and its lifecycle is managed. Avoid duplicate definitions and hidden assumptions distributed across consumers.
- Dependencies are legible. Callers and maintainers should be able to identify what a component needs, which inputs vary its behavior, and who decides their values. Prefer explicit inputs at meaningful boundaries over implicit state or unrelated hardcoded choices.