30 Principles That Actually Change How You Code

Distilled from 249 principles in learning.db — the ones that earn their keep

1. The Problem: Principles Nobody Reads

You've accumulated 249 principles from hundreds of coding sessions. Each one was hard-earned — a bug that burned you, a design that crumbled, a pattern that saved hours. They live in learning.db, materialized to ~/.claude/principles/, and are automatically retrieved when they seem relevant.

But 249 is too many to hold in your head. The truly transformative ones — the seven that should run in your background process on every task — get buried alongside niche observations about SQLite triggers and Gradio CSS.

This presentation ranks the top 30 by a single criterion: how much damage does violating this principle cause, and how broadly does it apply?

2. How These 30 Were Selected

Selection criteria, in order of weight:

Here's how the data backs these rankings. The top 30 were selected from 249 active principles in learning.db, supported by 6,130 instances and 3,644 tracked applications. The evidence is not uniform — some principles (#15 Verify Action: 353 applications) are battle-tested across dozens of sessions, while others (#21 Map Boundaries: 0 applications) are conceptual frameworks that haven't yet been tracked in production. Both are valuable, but the ranking weights empirical evidence.

3. Tier 1: Change How You Think About Every Task

4. Tier 2: Save You From the Most Common Mistakes

5. Tier 3: Make Design Decisions Sharper

6. Tier 4: Domain-Specific but High-Impact

7. Principles in Action

Example 1: The frac() Refactor (Principles #27, #9, #7)

Vario's Budget had a binary exhausted() method. Eight callsites checked it. The problem: binary signals can't enable proportional decisions.

if ctx.budget.exhausted():
    # stop everything
    return

if ctx.budget.frac() >= 1.0:
    return  # same behavior
# BUT now you can also:
if ctx.budget.frac() > 0.8:
    # throttle, reduce effort
    n = max(1, round(5 * remaining))

Principles applied: #27 (continuous > discrete), #9 (simplify — exhausted() was eliminated, not kept alongside), #7 (trace to action — frac() feeds actual allocation decisions).

Example 2: The "Flatten Everything" Design Session (Principles #21, #28, #4)

Vario's Item uses a generic props dict. Context uses named fields (budget, hooks). The inconsistency seemed like a design flaw.

Extreme probe (#21): "Make Context generic like Item — everything is dict[str, Any]." Ran it through 3-model adversarial review.

What broke: Engine boundaries need validation. limit.usd as a string key means a typo silently removes your budget cap. Concurrency safety requires encapsulation, not raw dicts.

Synthesis (#28): The metaphor (both hold metadata) was shared, but the mechanics (extension vs engine control) were different. Result: "unopinionated at extension boundaries, opinionated at engine boundaries."

Example 3: The Silent Batch Failure (Principles #12, #15, #24)

A YouTube channel download pipeline processed 2,000 videos. Two hours in, it silently failed at item 847 — but reported overall "success" because the orchestrator only checked the final HTTP status, not per-item outcomes.

result = batch.run(urls)
# returns 200 OK even when
# 40% of items failed silently
if result.status == 200:
    log("batch complete")

for url in urls:
    result = process(url)
    report.record(result)
# End-of-batch reconciliation
assert report.succeeded >= report.expected * 0.95

Principles applied: #12 No Silent Failures (256 applications — the most-evidenced principle in the system) → per-element error tracking. #15 Verify Action (353 applications) → end-of-batch reconciliation. #24 Fail Per-Element → individual failures don't kill the batch.

Example 4: The 50-Column Dashboard (Principles #18, #7, #6)

A Gradio monitoring dashboard displayed 50+ metrics in a data table. Users couldn't find what mattered — every metric competed equally for attention. Worse: Unicode zero-width spaces used for column alignment caused silent query failures when the data was parsed back from the UI.

Less Is More (#18): Reduced visible metrics from 50 to 5 — the ones that drive actual decisions. Trace the Chain (#7): For each remaining metric, identified the specific action it informs. Metrics with no consumer were hidden. Minimize Blast Radius (#6): Hidden metrics moved to an expandable section, not deleted. Previous users can still find them.

Result: dashboard load time dropped 4x, and the Unicode bug surfaced immediately because the parsing layer now handled fewer, well-defined fields.

Example 5: The Flaky Integration Test (Principles #17, #3, #15)

An integration test failed intermittently — sometimes on CI, never locally. The instinct was to add retries and increase timeouts.

# Reaching behind the API to check DB directly
items = db.query("SELECT * FROM items")
assert len(items) == 3  # race with async write

# Verify through the same API the user sees
resp = client.get("/api/items")
assert len(resp.json()) == 3  # waits for commit

Principles applied: #17 Treat Symptoms as Signals — the flakiness was the bug signal, not the specific assertion. #3 Respect Abstraction Boundaries — the test reached behind the HTTP layer to query the database directly, creating a race condition. #15 Verify Action — replaced with end-to-end verification through the API the user actually calls.

8. How to Use These

For daily coding

Internalize Tier 1. These 7 should be reflexive — you shouldn't have to think about them. Print them on a card. If you can only remember one: Fail Loud, Never Fake.

For design decisions

Consult Tier 2–3 when designing. Before committing to an architecture, check: Am I decomposing orthogonally? Did I simplify after designing? Am I building when I should be adopting?

For domain work

Tier 4 activates contextually. Starting a batch pipeline? Scan #24–26. Designing a data structure? Check #27–28. The /recall command does this automatically.

For the full 303

They live in learning.db, materialized to ~/.claude/principles/. The /recall skill searches them semantically before any design decision. You don't need to memorize them — the system surfaces them when relevant.

9. Quick Reference Card

All 30 principles on one sheet. Print it. Pin it.

How the System Works