Common-Sense Foundations for the Software Factory

What this is, and why it exists

The hard part of building software with agents isn't writing code — agents write code fine. It's keeping the work coherent across weeks of sessions: each session forgets what the last one decided, the codebase grows past what one person can hold in their head, and agents confidently report "done" on things that aren't. Everything below is the practice built around those three problems.

The split: I shape the work and decide; agents execute and produce evidence; I check it; lessons get written down where the next session will find them. The rules, the loop, and the machinery exist to keep that split working under load.

The scope is small things, well-shipped: news aggregators, internal tools, small-business backends, tracking apps for a community or church or neighborhood, content sites for niche audiences — solo-founder work, up to a few thousand daily users. Not enterprise; not trying to be. Read 01–04 for the argument. Skim 05–08 for the machinery, the sources, and blocks worth copying.

None of this was invented in one prompt or copied wholesale from one book. It came out of months of shipping small projects with AI agents, watching them confidently break things, and writing down what stopped the breakage the second time around. The lineage is software craft and indie practice; each rule had to keep earning its place. — Origin note

Thirteen steering rules

The stable rules behind every decision, grouped by what they do. They change slowly; almost everything else is downstream.

The lineage behind the principles

The North Stars aren't original — they're the durable parts of software craft and agentic practice, grouped the same four ways. Lineage, not literature review.

From raw idea to shipped, verified work

The path every task follows from idea to shipped work. The slope model below is the gate: a task crosses into Build only when the path is downhill — scoped, contracted, and verifiable.

• Appetite is a budget, not an estimate. S / M / L fix how much I'll spend; scope flexes to fit.
• The shaped contract is a ceiling. During Build, scope can be cut but never added without re-shaping.
• "Done" means more than "output exists." It means verification ran, the learning got captured, the branch is clean, and the artifact is where it belongs.

Factory-wide abstraction, project-local specificity

Higher layers are factory-wide and slow-changing; lower layers are project-local and concrete. Each layer inherits its parent's rules and specializes them. A conflict between a factory rule and a project's need becomes an explicit local exception with a written reason — never a silent override.

How principles become behavior

A rule that nothing enforces is just a wish. Each mechanism below turns one slice of the rules into something the agent actually does — at a specific moment, with an observable result.

The list below is the same eight mechanisms, framed as definitions for readers who want the categorical shape before the table.

Sources and lineage

Where the ideas come from, with enough context to look up the unfamiliar. Most are useful in parts and overclaim in others — none wholesale.

Blocks you can borrow

Reusable pieces, ready to adapt. Drop them into a project's CLAUDE.md, an agent system prompt, or a rules file; rename to your own. Start-here-at-week-4: if the build already feels noisy, Appetite gates and Shape contract pay back fastest.

SHAPE BEFORE BUILDING
  NS-1  Think before doing — verify assumptions before going deeper
  NS-2  Prototype-first for risk — tracers/spikes; harden or delete
  NS-3 Planning depth scales with risk — appetite=budget, risk=ceremony

KEEP THE CODEBASE HONEST
  NS-4  Verify, don't claim — observed proof, not confidence
  NS-5  Depth over surface — deep modules, narrow interfaces
  NS-6  Loud failure beats silent corruption
  NS-7  Code resists entropy — boring & legible over clever

ALLOCATE ATTENTION
  NS-8  Review capacity is scarce — spend it where it changes outcomes
  NS-9  Anchor decisions to knowledge locality
  NS-10 Cheapest-effective per invocation

COMPOUND WHAT EARNS ITS KEEP
  NS-11  Outcome over output — connect to real signal
  NS-12 Routine work auto-runs — idempotent, observable, reconciled
  NS-13 Compound the substrate — extend/refine/replace, don't balloon

Bench  → capture ideas without interrupting current work
Think  → frame the problem; name the outcome, not a proxy
Shape  → reduce risk to a builder contract  ┐
                                            ├─ SHAPE GATE
Build  → execute inside the contract        ┘
Verify → prove behavior; no claim without proof
Done   → ship boundary + learning capture + cleanup

Feedback: Retro → LEARNED → Vault / Rules / Skills → next loop

S  small   → zero interaction; pick up → verify → auto-ship
M  medium  → draft plan → 1 approval → build → "ready to ship?"
L  large   → co-shape → approve → build → checkpoint → ship

Rule: appetite fixes the budget; if it feels L but scope can be
cut to M, cut it. The shaped contract is a CEILING during build.

Problem               what's broken/missing? (name the outcome)
Appetite              S / M / L
Risk score            novelty + reversibility + deps + interface (0–8)
Solution sketch       rough shape, not a detailed spec
Rabbit holes          what could balloon scope?
No-gos                what we are explicitly NOT doing
Acceptance            checkboxes + verification commands
Verified assumptions  every claim about existing code, grep-checked

  Example row:
    Claim   pipeline.ts caps stories at TARGET_STORIES=7
    Verify  rg -n "TARGET_STORIES\s*=" src/lib/pipeline.ts
    Result  src/lib/pipeline.ts:247:const TARGET_STORIES = 7;