Building Like Claxx

A claim without a receipt is indistinguishable from a guess. The discipline of producing evidence is the same discipline that produces correct work — you cannot fake a passing test you didn’t run, but you can write any words you want about it. We bias our processes toward verifiable truth over the appearance of it.

No author audits their own output. The reviewer is always someone — or something — with no stake in the original answer. The bias of authorship is universal; the cost of a second look is small.

Any single safeguard will eventually be misconfigured, bypassed, or revoked. We design assuming that. The same constraint enforced at three layers is not redundancy — it is how we survive the single failure that’s already in our future.

The first miss is a learning moment. The second is a missing control. We don’t rely on remembering, on documentation, or on willpower. In the moment of a deadline, willpower loses every time.

Mass-blocking on subjective issues stalls work without improving outcomes. Hard blocks are reserved for actions you can’t take back. Everything else is ratcheted toward better, never enforced as an emergency.

The cost of a defect compounds with every minute it lives undetected. Errors at write-time are cheaper than errors at push, which are cheaper than errors at review, which are cheaper than errors in production. We invest at the front of that curve.

Local tooling exists to make the right thing easy in the moment of writing it. Centralized tooling exists to make the wrong thing impossible to ship. They run the same rules at different cadences and are not interchangeable.

Default to scoping checks to the diff. Pay the cost of a whole-system pass only when the rules themselves changed. Engineers shouldn’t pay full cost for work prior commits already paid for — doing so trains them to find ways around the system.

Once shipped, history is read-only. We correct forward, never erase. Lost work is the worst kind of failure because it’s invisible to everyone except the person who lost it — and rewriting history is the same failure in slow motion.

Don’t run subjective review on a broken build. Don’t ask for human attention before machine attention has had its turn. Cheap signals filter the work that deserves expensive ones — the wrong order means we burn the most expensive resource on problems the cheapest one would have caught.

New active integrations start off. Activation requires intent, an owner, and a documented reason. Surface area is a tax paid in cognitive load and operational complexity — not a free gift to the future.

Every active integration has a documented purpose and a named owner. No drive-by additions. The reason field is what turns a permission into a contract.

If a pattern matters, the machine checks it. Humans drift; tools forget nothing. We pair every “you should” with a check that fires when you didn’t.

Every enforcement we add began as a real bug, a real review comment, or a real incident. We don’t enforce what we wish were true. We enforce what proved itself necessary.

Names and diffs show what; commit messages, design docs, and recorded decisions explain why. The why survives refactoring, language migrations, and team turnover.

Standards live in one place; every tool, environment, and team member reads from it. Differences between surfaces are bugs to close, not preferences to indulge.

A check that didn’t run is failed, not missing. A reviewer who couldn’t reach an answer says so loudly. Ambiguity in the user-facing state is itself a failure mode — silence trains people to ignore the system rather than trust it.

A “looks good” is bound to a specific state of the work, not to a person’s general opinion. When the work changes, the approval expires. Treating approvals as transferable creates a polite fiction that protects no one.

Working code that no consumer has seen and accepted is not done. We define “done” as demonstrated and approved in an environment as close to production as practical. This inverts the traditional shipping order: consumer acceptance happens before code review, not after.

A reviewer reading the code should be certain that the form of the work is correct — the only remaining question is whether the implementation is correct. Reviewing the polish on a feature the user will reject is wasted attention.

It is an admission that a behavior claim was made about a system the speaker cannot fully reproduce. Local environments are development tools, not authoritative records of correctness. The minimum standard for “it works” is “it works in a shared environment whose differences from production are documented and small.”

A built artifact is immutable. Behavior changes require new artifacts. Configuration may differ between deploys; the artifact may not. This separates what the code does from where it runs.

Code shall not contain environment-specific values. Everything that varies between deploys is externalized — to environment variables, secrets stores, or configuration services. The codebase is identical in every environment; only the configuration changes.

Databases, queues, caches, blob stores, and external APIs are referenced by handle resolved from configuration at runtime. Code shall not assume which provider supplies a backing service.

Application processes shall not store state across requests in process memory or local disk. State required across requests must live in a named backing service. A process must be safely killable at any time without data loss.

Application code emits structured logs as events to stdout. Routing, aggregation, retention, and search are the platform’s concern, not the application’s.

Development, staging, and production shall differ in the smallest practical number of dimensions. Each remaining difference must be documented with the reason it cannot be removed.