First Principles of Software Design

<!-- Copyright (c) 2026 Todd Levy. Licensed under MIT. SPDX-License-Identifier: MIT -->

First Principles of Software Design

The foundational axioms of quality software, traced to their intellectual origins.

"First Principles" carries a deliberate double meaning:

1. Epistemological — Reasoning from irreducible truths rather than by analogy
2. Historical — The first people who articulated these principles; the founders

This skill provides the why behind best practices by connecting modern conventions to their intellectual lineage.

When to Use

• Making architectural decisions with trade-offs
• Evaluating whether code violates design principles
• Understanding why a pattern exists, not just how
• Teaching or explaining software design
• Code review with principled reasoning

Principles Index

Founders Index

How to Use This Skill

For Decision-Making

When evaluating a design choice, identify which principles are at stake:

"Should we duplicate this validation logic in both services?"

→ Principle: Single Source of Truth (Hunt & Thomas)
→ Risk: Drift when one copy changes but the other doesn't
→ Decision: Extract to shared module or single service

For Code Review

Cite the principle and its lineage when explaining why something matters:

"This component fetches data AND renders AND handles errors.
 That's three concerns in one place.

→ Principle: Separation of Concerns (Dijkstra, 1974)
→ Why it matters: Each concern changes for different reasons
→ Suggestion: Extract data fetching to a hook"

For Learning

Trace modern patterns back to their origins:

React hooks → Composition over Inheritance → GoF (1994)
TypeScript interfaces → Contracts → Hoare (1969), Liskov (1987)
Redux single store → SSOT → Hunt & Thomas (1999)
Microservices → Information Hiding → Parnas (1972)

Convergence Map

These principles emerged from different lineages but converge on the same goal: managing complexity in systems that must change over time.

                         ┌─────────────────────────────────────┐
                         │   MANAGING COMPLEXITY IN SYSTEMS    │
                         │       THAT MUST CHANGE OVER TIME    │
                         └───────────────┬─────────────────────┘
                                         │
          ┌──────────────┬───────────────┼───────────────┬──────────────┐
          ▼              ▼               ▼               ▼              ▼
   ┌─────────────┐ ┌───────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐
   │ MODULARITY  │ │ LEGIBILITY│ │ ABSTRACTION │ │  INTEGRITY  │ │ FEEDBACK │
   │   Parnas    │ │  Dijkstra │ │Liskov/​Hoare │ │   Brooks    │ │ Hamilton │
   └─────────────┘ └───────────┘ └─────────────┘ └─────────────┘ └──────────┘
          │              │               │               │              │
          ▼              ▼               ▼               ▼              ▼
   Information     Separation      Contracts &     Conceptual      Fail Fast
     Hiding        of Concerns    Substitution      Integrity
          │              │               │               │              │
          └──────────────┴───────────────┴───────────────┴──────────────┘
                                         │
                         ┌───────────────┼───────────────┐
                         ▼               ▼               ▼
                  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
                  │    SOLID    │ │     DRY     │ │   PATTERNS  │
                  │ Uncle Bob   │ │ Hunt/​Thomas │ │     GoF     │
                  └─────────────┘ └─────────────┘ └─────────────┘
                         │               │               │
                         └───────────────┼───────────────┘
                                         ▼
                         ┌─────────────────────────────────────┐
                         │        MODERN PRACTICE              │
                         │  Clean Architecture, Microservices, │
                         │  Functional Core, React Composition │
                         └─────────────────────────────────────┘

Primary Sources

See sources/​primary-sources.md for annotated bibliography with links to original papers and books.

---

Decision Heuristics

When principles appear to conflict, use these heuristics:

Information Hiding vs Explicitness

SRP vs DRY

YAGNI vs Extensibility

Scale Considerations

---

Anti-Pattern Catalog

Diagnostic Questions

• Does this change for multiple reasons? → SRP violation
• Could I swap this implementation? → Information Hiding check
• Is this fact represented once? → DRY/​SSOT check
• Can I test this in isolation? → Coupling smell
• Does the name explain the purpose? → Abstraction quality

---

Principle Interactions

Reinforcing Relationships

graph LR
    SoC[Separation of Concerns] --> SRP[Single Responsibility]
    SRP --> Testability
    InfoHide[Information Hiding] --> Abstraction
    Abstraction --> Substitutability
    Testability --> SRP
    DI[Dependency Injection] --> Testability

Tension Relationships

---

Related Skills

This skill provides the theory. For practice, see:

---

References

Quilted Skills

• sickn33/​software-architecture — Architecture patterns
• athola/​code-quality-principles — KISS, YAGNI
• ramziddin/​solid-skills — SOLID principles

First-Party Academic Sources

• Parnas 1972 — On the Criteria To Be Used in Decomposing Systems into Modules
• Dijkstra — On the Role of Scientific Thought (EWD447)
• Liskov 1987 — Data Abstraction and Hierarchy
• Brooks 1975 — The Mythical Man-Month

Modern Interpretation

• Martin Fowler's Bliki — Contemporary patterns
• Clean Coder Blog — Robert Martin on SOLID
• Refactoring.Guru — Pattern explanations

Books

• Clean Architecture (Martin)
• Domain-Driven Design (Evans)
• Patterns of Enterprise Application Architecture (Fowler)

Skill References

• sources/​primary-sources.md — Annotated bibliography
• principles/ — Individual principle deep-dives
• founders/ — Biographical context for key figures