Hyrum’s Law
With enough people relying on a system, every observable behavior of it becomes something somebody depends on, whether or not it was ever promised.
What Is It?
Hyrum’s Law states that with a sufficient number of users of an API, it doesn’t matter what the contract promises: all observable behaviors of the system will be depended on by somebody. Google engineer Hyrum Wright noticed the pattern doing years of software maintenance work, where changes to code that should have been invisible kept breaking projects that had quietly come to rely on some undocumented quirk.
Every system has two versions: the one it promises, and the one people actually depend on. The second is usually larger, and nobody has a full map of it.
Why Does It Matter?
Organizations gradually acquire a second operating system made up of habits, exceptions, shortcuts, and unofficial practices, running underneath the official one. Nobody emails Mary directly, but everyone knows to. The form has a field everyone’s told to ignore, except the one team that quietly reads it. The report isn’t due until Friday, but everyone actually sends it Thursday, because someone downstream needs the extra day and nobody wrote that down either. None of it is official. All of it is load-bearing.
Hyrum’s Law is why removing any one piece of that second system is riskier than the documentation suggests. Formal documentation, official policy, or a stated process defines what’s supposed to be safe to change. It was never a map of what’s actually depended on. “Cleaning it up” without accounting for who’s using it breaks something real, and the break often lands on people nobody thought to check with, because their dependency was never written down anywhere.
What Changes Once You See It?
Before removing an undocumented workaround, an informal exception, or a quirky process shortcut, you check who’s actually depending on it instead of trusting the official policy to tell you what’s safe. The official contract was never a complete map of the dependency surface. It was only ever the part someone bothered to write down.
You also start reading “nobody uses that anymore” with more suspicion. The people relying on an undocumented behavior are often the ones least likely to have flagged it, precisely because it was never supposed to be something they needed.
Common Misunderstandings
- Hyrum’s Law isn’t a claim of certainty at any scale. It’s a statement about probability that grows with the number of users. One person relying on a quirk is a manageable risk. A thousand people quietly relying on the same quirk is a different situation entirely.
- It doesn’t mean nothing can ever be cleaned up or changed. It means the cleanup needs to account for real usage, not just the documented contract.
- It isn’t specific to software. Any organizational process with enough users, an approval workflow, a reporting template, an informal escalation path, accumulates the same kind of invisible dependency over time.
Diagnostic Question
Before we remove this undocumented shortcut, do we actually know who’s quietly depending on it, or are we only checking what it was officially supposed to do?
Explore Further
Field Notes
None yet.
Related Field Guide
Origin
Hyrum Wright observed the pattern during years of software maintenance work at Google around 2011 and 2012. His colleague Titus Winters named it “Hyrum’s Law” in recognition of the observation, and it’s documented in the book Software Engineering at Google, co-authored by Winters, Tom Manshreck, and Wright.