Prove It Works
“It works” is a claim, and an engineer is someone who can back it up. Running the happy path once on your machine is where amateurs stop. A world-class engineer isn’t done when the code runs; they’re done when they can prove it does what it should, see it doing it in production, and know the instant it stops. Everything in this group so far is about building the right thing well. This doc is about the other half of the job: making sure, and staying sure.
The bar is a question you should be able to answer at any moment, about anything you’ve shipped: “how do you know it works?” If the honest answer is “it did when I tried it,” you don’t know. Here’s how to actually know.
Correct, Not Just Running#
What’s expected: The behavior is pinned by tests, the edges as well as the happy path, so “it works” survives the next change.
Running once proves the code can work, not that it does work, and definitely not that it will still work after someone refactors near it next month. That’s what tests are for, and specifically the edge-case tests: the empty input, the over-limit value, the failure path. A feature with only a happy-path test is a feature you’re hoping is correct. The edges are where “works” actually gets decided, and a test is the only thing that keeps a future change from silently undoing your decision. A change without a test is not finished; it’s a hope with a green checkmark.
See It in Production#
What’s expected: You can watch your change behaving in production, not just infer that it’s fine because nobody complained.
The most dangerous state is a change that’s broken and quiet, silently failing for 3% of users, or working but ten times slower than it should. You cannot fix what you cannot see, and “no one has complained” is not the same as “it works.” Before you call something done, make sure you can observe it:
- A trace shows the path your change took and how long each step spent (Observability instruments this for free, every request and query is already a span).
- A metric shows how often and how much, the count, the rate, the duration you’ll want to chart (Metrics vs Traces vs Logs).
- A log records the specific decisions and failures, structured and tied to the trace (How to Log).
The habit: when you build something that matters, add the one signal you’d want at 2am while you’re building it, not after the incident. If you can’t answer “is my thing working right now?” from a dashboard, you haven’t finished instrumenting it.
Measure, Don’t Guess#
What’s expected: When something is slow or wrong, you find the cause with a measurement, not a hunch.
Engineers waste enormous time optimizing the thing they assume is slow, and it’s almost never the thing. The rule is absolute: measure first. Reach for the number before you touch the code (the full loop is in How to Debug Performance). The single most common culprit in a web backend is the database, a missing index turning a lookup into a full scan, or an N+1 quietly firing one query per row, so when a request is slow, look at its queries first. EXPLAIN the slow one and read what the database is actually doing before you change anything. A fix aimed by measurement lands; a fix aimed by hunch usually just moves the problem.
Know the Moment It Breaks#
What’s expected: The few signals that mean a user is being hurt are alerted on; the rest are not.
You will not be watching the dashboard when it breaks. Something has to tell you. But an alert on every metric trains everyone to ignore alerts, which is worse than none, so point alarms only at the handful of signals that mean a user is actually hurting: error rate, latency, saturation. An alert should mean “a human needs to look now,” the same promise as an error log level. Everything else is a dashboard you consult, not a page that wakes you.
Close the Loop#
What’s expected: After it ships, you check that it did what you set out to do, not just that it deployed.
Shipping is not the finish line; the finish line is impact. The change went out to move something, a metric, a user outcome, so after it’s live, you go back and check whether it moved. This is where engineering meets Learn and the product goal: a change that deployed cleanly but didn’t move the number it was meant to move is not a success, it’s a lesson. “Done” is the number moving, not the PR merging.
The Standard#
At any point, for anything you’ve built, you should be able to answer four questions with evidence, not vibes: Is it correct? (tests, including the edges). Is it working right now? (a trace, a metric, a log you can point at). Is it fast enough? (a measurement, not a guess). Will I know when it breaks? (an alert on the signals that matter). An engineer who can answer those four, every time, is one you can trust with production. That’s the whole difference between code that runs and a system you can stand behind.