Field guide 01 Software that survives contact with reality
Ten durable ideas from the original twelve. Twelve missing principles for security, reliability, delivery, data, correctness, and sustainability. One opinionated field guide for software people can actually operate.
This is not a vendor checklist. It is a set of architectural pressures: make the right thing easy, make unsafe states hard to reach, and leave enough evidence for the next person to understand what happened.
01 · The argument
Codebase discipline, explicit dependencies, external config, attached services, immutable releases, stateless execution, horizontal scale, disposability, parity, and one-off administration remain excellent constraints. We kept them—and made every page more testable.
Port binding was a useful 2011 deployment contract, but not every modern workload listens on a port. Logs-as-streams was a useful platform rule, but logs are only one observability signal. Their intent now lives in contract-first interfaces and observability with SLOs.
Read the retirement notesHoffman’s Fifteen-Factor App identified interface-first design, telemetry, and identity. Reactive, SRE, Chaos, DORA, secure-by-design, GitOps, privacy, Local-first, FinOps, and sustainable-software work expose the remaining gaps. The new twelve compress those lessons into testable rules.
Follow the research trail02 · The field guide
Each factor starts with one imperative commandment and one boundary that prevents a common over-reading. The article then explains the constraint, names failure modes, and ends with a litmus test. Adopt the pressures as a system; adapt their implementation to context.
Original principles that still earn their place.
Map every deploy to one authoritative source history.
Declare, lock, verify, and isolate every build and runtime dependency.
Build without deploy-specific values; bind validated configuration at release or runtime.
Depend on explicit service contracts; attach and replace implementations through configuration.
Build once, identify every release immutably, and promote the same artifact unchanged.
Keep execution disposable and durable state behind explicit stateful contracts.
Partition work by process type, scale horizontally, and bound every concurrency layer.
Start ready, stop safely, and remain correct when termination is abrupt.
Shorten feedback and test every production-significant difference against the real system.
Run administrative work from the shipped release in a separate trust domain through reviewed, auditable procedures.
Modern obligations the original methodology did not name.
Specify consumer-visible behavior before implementation, then evolve contracts with consumers.
Design the safe path as the default; verify identity, privilege, inputs, abuse cases, and failure behavior.
Define user-visible objectives, instrument causality, and alert only on actionable risk.
Admit only artifacts traceable to reviewed source, declared inputs, and verifiable builds.
Assume components fail; bound time, retries, queues, load, and blast radius, then prove recovery.
Collect only justified data; preserve user agency; govern every copy through verifiable deletion.
Express infrastructure and policy as reviewed desired state, then reconcile drift within explicit safety bounds.
Separate deployment from exposure; expand change only while evidence and abort controls hold.
Change additively; let old and new versions coexist until migration and rollback are proved.
Model critical state transitions explicitly; implement a functional core with pure transformations, immutable values, typed errors, and exhaustive cases.
Prefer memory-safe languages and total types; make absence, failure, and invalid states explicit, and isolate every unsafe boundary.
Deliver useful work with less energy, carbon, water, and hardware—without exporting harm.
03 · Put it to work
The Rust auditor inspects a repository or GitHub organization for factor-scoped evidence, then creates a versioned assessment for the decisions automation cannot make. It never compresses architectural risk into a flattering score.
Locate reviewable evidence without claiming that a filename proves compliance.
Record status, rationale, evidence, owner, review date, and follow-up per factor.
Pin the edition and source release so the decision remains reproducible.
04 · Research trail
The direct extension—and the starting point, not the end, of this revision.
Reactive · SRE · ChaosReliability is a user-visible claim to test under realistic disturbance.
Formal methods · Functional design · Safe languagesModel critical transitions, keep effects explicit, and let types force every case into view.
Local-first · Sustainable · AISpecialized manifestos pressure-test the universal rules without bloating them.
Use it, challenge it, improve it
The original twelve became useful because teams argued with them in public. This project is MIT-licensed and intentionally opinionated. Bring evidence.