pragmatic-programmer

# The Pragmatic Programmer Framework

A systems-level approach to software craftsmanship from Hunt & Thomas' "The Pragmatic Programmer" (20th Anniversary Edition). Apply these meta-principles when designing systems, reviewing architecture, writing code, or advising on engineering culture -- how to think about software, not just how to write it.

## Core Principle

**Care about your craft.** Software development demands continuous learning, disciplined practice, and personal responsibility -- pragmatic programmers think beyond the immediate problem to context, trade-offs, and long-term consequences. Great software comes from great habits: avoid duplication ruthlessly, keep components orthogonal, and treat every line of code as a living asset that must earn its place. The goal is not perfection -- it is systems that are easy to change, easy to understand, and easy to trust.

## Scoring

**Goal: 10/10.** Score against the seven Quick Diagnostic rows: award ~1.4 points per row answered "yes" (7 yes = 10). Then band the result:
- **9-10**: every principle holds -- DRY knowledge, orthogonal layers, a working tracer slice, contracts at boundaries, no broken windows, reversible vendor/DB choices, ranged estimates.
- **5-6**: 1-2 violations that cost real change-effort (e.g. business logic coupled to the DB, single-point estimates).
- **<=3**: pervasive duplication, global state, or accumulated broken windows -- entropy is winning.

Always state the score, name the failing diagnostic rows, and give the specific fix from the Action column to reach 10/10.

## The Seven Meta-Principles

Seven principles for building software that lasts:

### 1. DRY (Don't Repeat Yourself)

**Core concept:** Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. DRY is about knowledge, not code -- duplicated logic, business rules, or configuration are far more dangerous than duplicated syntax.

**Why it works:** Duplicated knowledge must be changed in multiple places; eventually one gets missed, introducing inconsistency. DRY reduces the surface area for bugs and makes systems easier to change.

**Key insights:**
- DRY applies to knowledge and intent, not textual similarity -- two identical code blocks serving different business rules are NOT duplication
- Four types of duplication: imposed (environment forces it), inadvertent (developers don't realize), impatient (too lazy to abstract), inter-developer (multiple people duplicate)
- Comments that restate the code violate DRY -- explain *why*, not *what*
- Database schemas, API specs, and documentation duplicate knowledge unless generated from a single source
- The opposite of DRY is WET: "Write Everything Twice" or "We Enjoy Typing"

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Config values** | Single source of truth | DB connection in one env file, referenced everywhere |
| **Validation rules** | Shared schema | One JSON Schema or Zod schema for client and server |
| **API contracts** | Generate from spec | OpenAPI spec generates types, docs, and client code |

See: [references/dry-orthogonality.md](references/dry-orthogonality.md) when classifying a specific duplication or deciding whether two code blocks are truly the same knowledge -- per-type examples and mitigations for the four duplication types.

### 2. Orthogonality

**Core concept:** Two components are orthogonal if changes in one do not affect the other. Design systems where components are self-contained, independent, and have a single, well-defined purpose.

**Why it works:** Decoupling localizes change -- a fix in one module can't ripple into unrelated ones, so blast radius stays bounded. Change the database layer and the UI should not break; change the auth provider and business logic should not care.

**Key insights:**
- Ask: "If I dramatically change the requirements behind a function, how many modules are affected?" The answer should be one
- Eliminate effects between unrelated things -- a logging change should never break billing
- Layered architectures promote orthogonality: presentation, domain logic, data access
- Avoid global data -- every consumer of global state is coupled to it
- Frameworks that force you to inherit from their classes reduce orthogonality

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **Architecture** | Layered separation | Controller -> Service -> Repository, each replaceable |
| **Dependencies** | Dependency injection | Pass a `Notifier` interface, not a `SlackClient` concrete class |
| **Testing** | Isolated unit tests | Test business logic without database, network, or filesystem |

See: [references/dry-orthogonality.md](references/dry-orthogonality.md) when measuring coupling or refactoring toward decoupled layers -- the change-impact and stranger tests, layered-architecture diagram, and the helicopter analogy.

### 3. Tracer Bullets and Prototypes

**Core concept:** Tracer bullets are end-to-end implementations connecting all layers of the system with minimal functionality. Unlike prototypes (which are throwaway), tracer bullet code is production code -- thin but real.

**Why it works:** Tracer bullets give immediate end-to-end feedback before you invest in filling out every feature. Users see something real, developers have a framework to build on, and integration issues surface early.

**Key insights:**
- Tracer bullet: thin but complete path through the system (UI -> API -> DB) -- you keep it
- Prototype: focused exploration of a single risky aspect -- you throw it away
- Use tracer bullets when "shooting in the dark" -- vague requirements, unproven architecture
- If a tracer misses, adjust and fire again -- the cost of iteration is low
- Label prototypes clearly as throwaway -- never let one become production code

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **New project** | Verti