guardrails

Poka-Yoke Guardrails

Design-time devices protect the code you are writing now. Guardrails protect the code everyone writes later, including the version of you who is in a hurry. They are Shingo's successive check: the next station refuses to accept bad work.

The reason this mode exists as its own thing: the most common failure in software quality is agreeing on a rule and then writing it down. A rule in a wiki has a half-life of about one onboarding. The same rule wired into a gate applies itself and costs nothing to remember.

Building, not reviewing

Most of the time this mode is reached while someone is building the thing, not afterwards. That changes the deliverable. They asked for the config, so produce the config, working, complete, in their stack. Do not hand back a severity table when the person is mid-feature; a list of findings about code they have not written yet is not useful to them.

Then add a short closing note, three or four lines, covering:

• which misuses the shape you chose makes impossible, and at which rung,
• what you left possible on purpose, and why that tradeoff is the right one here.

That closing note is what stops the device being undone in six months by someone who cannot see why it is there. It is also the difference between mistake-proofing and a code generator: the reasoning travels with the code.

When the code already exists and they are asking what is wrong with it, switch to the audit voice, ranked findings with the mistake, the consequence, and the device. Match the mode to where they are in the work, not to this file's default.

Pick the earliest gate that can hold the rule

The same rule can live at several points in the lifecycle. Earlier is better, feedback is faster, cheaper, and lands while the author still has the context in their head. But earlier is also easier to bypass. The resolution is to place the device early and back it with a gate that cannot be skipped.

Gate	Feedback speed	Bypassable?	Best for
Type system / compiler	instant	no	anything the types can express, always first choice
Editor + lint	seconds	yes (ignore comment)	style, banned APIs, unsafe patterns
Pre-commit hook	seconds	yes (--no-verify)	fast checks: secrets, formatting, obvious footguns
Pre-push hook	~a minute	yes	medium checks you don't want to wait for on every commit
CI required check	minutes	no, with branch protection	the real enforcement, everything that must not merge
Database constraint	instant, at write	no	data invariants, across every service and every script
Runtime assertion	at execution	no	invariants no earlier gate can see