Hyrum's Law: With Enough Users, Even Bugs Get Depended On
Someone is depending on your bug right now. Coined by Google engineer Hyrum Wright, Hyrum's Law states: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." The documented contract is not the interface. The observed behavior is — bugs, timing quirks, error message wording, and undocumented side effects included.
The implicit interface
Every system grows a second, invisible spec. Your docs promise a return type; your users also depend on the exact ordering, the millisecond latency, the field that's always present "by accident," and the error string they regex against. Wright's own summary of the effect: eventually "the implementation has become the interface." This is why teams end up shipping bug-for-bug compatibility — the old bug is now load-bearing.
The classic illustration is xkcd 1172: a user emails that the spacebar heats their coffee, and it turns out an app deliberately reboots when a key is held. Fix the "bug" and you break a real workflow. With enough users, there is no change so small that nobody depends on it.
Deprecation is a migration, not a memo
The trap is treating removal as an announcement. Software Engineering at Google is blunt: "It is often tempting to simply put a deprecation warning on an old system and walk away without any further effort." It rarely works. The book splits deprecation into two kinds:
| Type | What it is | What actually happens |
|---|---|---|
| Advisory | A warning with no enforcement | "We hope that clients move, but can't force them to" — it slows new usage but "rarely leads to teams actively migrating away." |
| Compulsory | A hard removal deadline with teeth | Works only when a team is staffed to do the migration work for consumers. |
The reason "just announce it" fails: users literally cannot switch when they depend on behavior the replacement doesn't replicate. And an unfunded compulsory deprecation, the book warns, "can come across to customer teams as mean spirited." The scalable pattern is to localize the migration expertise in the team that owns the removal — you migrate them, then you delete.
Design for deletion up front
The cheapest deprecation is the one you planned before shipping. The book's advice: "deprecation of a software system can be planned as those systems are first built." Ask the question at design time, not three years in:
- "How would I delete this in three years?" If the answer is "I can't," you're designing a permanent dependency.
- Minimize observable surface. Randomize what shouldn't be relied on (iteration order, spare latency) so nobody can depend on it — the same logic behind Go's randomized map ordering.
- Version and gate. New behavior behind a flag or a new endpoint, so the old path can be measured and drained rather than yanked.
For power users
- Instrument before you deprecate. You can't migrate a dependency you can't see. Add logging/metrics on the old path first, so removal is driven by a usage graph trending to zero — not a calendar date.
- Deprecation warnings need an escape hatch. A warning with no documented migration path just trains users to filter it out. Ship the replacement and the codemod together.
- This applies to AI systems too. A model's tone, its exact output format, even a quirk in how it structures JSON becomes a de-facto contract the moment agents and downstream parsers depend on it. Pin model versions, freeze output schemas, and treat a model swap as a migration — not a config change.
Resources
- Hyrum's Law — the canonical statement and origin
- Software Engineering at Google, Ch. 15: Deprecation (advisory vs compulsory, active migration)
- xkcd 1172: Workflow ("spacebar heating")
Shipping systems people build on? Yeda AI designs, audits, and migrates production software and LLM systems — with deletion planned from day one.