Sometimes you change only the order of values a library function returns, or the wording of an error message, and suddenly a far-off service starts breaking. The documentation never promised those details, yet someone was already relying on that behavior. The observation that sums up this reality in one line is Hyrum’s Law.
Put simply, Hyrum’s Law is the software-engineering rule of thumb that “with enough users of an interface, it no longer matters what the documentation promised: somebody will come to depend on every observable behavior of the system.” Hyrum Wright’s observation, formed while he handled large-scale code changes at Google, was named “Hyrum’s Law” and popularized by his colleague Titus Winters.
In this piece we will look in turn at exactly what Hyrum’s Law means and where it came from, how implicit interfaces arise, the cases developers meet most often, and finally how to respond and where its limits lie.
A Contract Deeper Than the Docs: Hyrum’s Law
What Is Hyrum’s Law?
The law is usually stated like this: with a sufficient number of users of an application programming interface (API), it does not matter what you wrote in the contract—somebody will depend on every observable behavior the system shows. In his own writing, Wright credits Winters with naming the observation “Hyrum’s Law” and spreading it widely.
The same idea also appears as the Law of Implicit Interfaces. As users grow, even implementation details you thought were private become a de facto contract, until even a small change draws demands for bug-for-bug compatibility.
- Explicit Contract: the inputs, outputs, and error conditions written down in docs and specifications.
- Implicit Interface: behavior people come to expect by watching it again and again, even when it is not documented.
- Observable Behavior: every result visible from the outside—response order, latency, error wording, log formats, and the like.
How Implicit Interfaces Form
Hyrum’s Law is not about lazy developers. It is a near-inevitable effect of scale. Even when you believe abstraction has hidden the inside, the outside can still read many signals.
(1) Users watch behavior more than docs
Under a tight deadline, people often check whether things still run as they did yesterday rather than matching the spec line by line. Details that happened to look stable then harden into “obvious promises.”
(2) Dependencies differ, but together they cover the implementation
One team leans on sort order, another on error-code strings, another on average response time. As the user base grows, the sum of those dependencies overlaps almost every face of the implementation.
(3) It meets Joel Spolsky’s leaky abstractions
Joel Spolsky’s Law of Leaky Abstractions says that abstractions never fully hide what lies beneath. Hyrum’s Law adds that those leaked clues, once enough users are watching, harden into contracts too.
Cases You Meet in Day-to-Day Development
It may sound theoretical, but the same pattern repeats in ordinary library and service work. The change you thought was “outside the spec” often shakes the system farthest away.
(1) Order of a returned list
Even when the docs say “order is not guaranteed,” if results always came back in the same order, code tuned to that order piles up. The day you add parallelism and the order shifts, assumptions never covered by tests surface all at once.
(2) Error messages and log lines
Sentences written for humans are sometimes parsed as strings by other programs that branch on them. You only rewrote the wording to be kinder, and automation stops—that is this type.
(3) Performance and timing
Even when the spec promises no latency, a speed that stayed similar for years becomes a de facto expectation. Drop a cache or add a check so things slow a little, and reports arrive that “the feature is the same, but only our side times out.”
How to Respond to Hyrum’s Law, and Its Limits
The law does not mean you should give up on change. It is closer to a warning: treat observable surfaces as potential contracts, and leave yourself room to change on purpose.
- Clear Contract: draw a sharp line, in docs and tests, between what you guarantee and what you do not.
- Intentional Jitter: shuffle order or add a little delay from the start so accidental assumptions never take root.
- Compatibility Testing: before a large change, run real call patterns widely and find the breakages first.
Still, once users are numerous enough, even a tiny edit can break someone. In Software Engineering at Google, the law is treated like entropy—something you cannot erase, yet must keep in mind in design and maintenance. At the same time, beware using the rule as an excuse to put off needed improvements forever.
Hyrum’s Law reminds us that the real interface of a popular system runs far deeper than its documentation. An observation born from large library changes at Google has become a shared language for teams that want APIs and platforms to last.
Before you fix a small behavior, ask once more whether someone is already watching it even though the docs are silent. That is the first step toward using Hyrum’s Law to design change that does not break.
