The 30-second version
Hyrum's Law, named for Google software engineer Hyrum Wright and popularized in the book Software Engineering at Google (2020), states it plainly: "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." It isn't about bad consumers breaking the rules. It's a statement about scale. A documented spec might promise only that a function "returns a list of items" — but if that list has always come back in alphabetical order, some fraction of a large enough user base will quietly write code that assumes alphabetical order, whether or not anyone ever promised it. Change the ordering later for a legitimate performance reason, and you break them anyway. The lesson isn't that those users were wrong to rely on it. It's that at sufficient scale, reliance on undocumented behavior becomes statistically certain, so the real interface of any widely used system is everything it visibly does, not just what its documentation says it does.
Mental Model Compass
Where Hyrum's Law sits next to three other models already in this collection about structure, incentives, and inherited decisions. Click a dot to see why it sits where it does.
Click or focus a dot to read why it sits where it does.
Build the idea, one step at a time
A specification might promise only that a function "returns a list of items," with no guarantee about order. But if the backend has, in practice, always returned the list alphabetically, some share of a large enough user base will write code that silently assumes alphabetical order — not because the documentation told them to, but because that is what the system has always, observably, done. The real interface anyone actually depends on is everything the system visibly does, documented or not.
The law is stated with "a sufficient number of users" deliberately. A small internal tool with three users may never trigger this problem at all — there simply isn't enough surface area of usage for an obscure quirk to matter. A popular, heavily used API with millions of calls a day is a different story: someone, somewhere, is plausibly depending on nearly every observable detail, however minor — an HTTP header's exact letter casing, the precise wording of an error string another program pattern-matches against, even a particular response latency another system's timeout logic has been tuned around.
As a system attracts more users and integrations over time, every detail that once seemed irrelevant becomes, for someone, load-bearing. This is a large part of why long-lived, widely used systems get harder to change the older and more popular they become — not necessarily because the underlying code quality declined, but because reliance quietly accumulated on every corner of it, turning "irrelevant implementation detail" into "thing that will generate a support ticket if it moves."
Teams that take Hyrum's Law seriously respond in specific, deliberate ways: they narrow the observable surface of an interface on purpose, hide internal details behind an abstraction, and sometimes deliberately randomize behavior that was never meant to be guaranteed — Google's own Protocol Buffers library, for instance, intentionally does not guarantee a stable field order in serialized output, specifically so no one can quietly depend on today's ordering. They document more completely, add tests that run against real consumer traffic rather than only the written spec, and treat a complaint about a broken "undocumented" behavior as genuine production signal, not a contractual non-issue to dismiss.
What it looks like in different fields
This is the canonical case the law was coined for. A cloud provider makes what looks like a purely internal change — reordering fields in a JSON response, or tightening a timestamp's precision — and breaks a customer's integration that happened to parse the response positionally or rounded the old precision in a particular way. Google's internal engineering practice takes this seriously enough to design against it directly: the Protobuf serialization format deliberately leaves field order unspecified and unstable release to release, precisely so that no consumer can quietly build a dependency on an ordering the format never promised.
An informal exception process — "just email so-and-so and they'll sort it out," never written into any actual policy — becomes, in practice, how the organization really works for the people who rely on it. No policy document promised that workaround. But when the person who ran it leaves, or the exception finally gets closed in a "policy cleanup," the people who built their routine around it experience it as a broken promise, even though, strictly speaking, nothing written ever promised it to them.
A product ships a quirky, technically unintended behavior — an animation that happens to time out at a convenient moment, a keyboard shortcut that "shouldn't" work but does, a loophole in how a free tier counts usage — and a visible segment of power users builds real workflows around it. When a later "cleanup" release removes the quirk, the backlash is often disproportionate to how official that behavior ever was, because for those users it had become, functionally, a feature.
Users of a public AI model or API quickly learn, and come to depend on, unstated behavioral quirks that sit outside the documented capabilities: a particular phrasing that reliably works around a known limitation, a fairly consistent response length used to budget a downstream process, or a latency pattern a timing-sensitive integration has been tuned around. When the underlying model is updated, those undocumented dependencies can break even though nothing in the actual terms of service changed — a direct, high-stakes, present-day instance of the same dynamic Hyrum's Law describes.
Worked application: planning a breaking-looking change to a widely used interface
- Inventory who actually calls this interface, not just who's supposed to. Pull real traffic and logs rather than relying on a registry of documented consumers, since Hyrum's Law is specifically about undocumented reliance that a consumer list will never capture.
- List every observable behavior of the current system, not only the documented contract — response ordering, timing characteristics, exact error-message text and codes, field presence or absence in edge cases, size limits, letter casing.
- For each behavior you plan to change, assume someone depends on it until you have evidence otherwise, and estimate the blast radius from real traffic: how many callers touch it, how critical are they, how visible would a break be.
- Decouple the risky change from a visible cutover where you can. Ship the new behavior behind a flag, dual-run the old and new paths in parallel against real traffic, and diff the outputs before fully switching over.
- For behavior you specifically don't want to promise going forward, vary it on purpose now — before you ever need to change it for real — so no one can quietly build a dependency on today's exact, unpromised behavior.
- Communicate the change as a production change, not a documentation change. Version it, set a real deprecation timeline, and treat a "that wasn't in the spec" complaint as genuine signal about how the system is actually used, not as a user simply being wrong.
Common mistakes
Treating the written contract as the whole truth
Assuming that because a behavior isn't documented, no one could possibly depend on it. That assumption is exactly what the law says fails once a system has enough users — undocumented is not the same as unrelied-upon.
Blaming the consumer instead of planning for the law
"They shouldn't have relied on that" can be technically correct and still beside the point: the break still happened, the support burden is still real, and the next change still needs a different plan.
Over-applying it as an excuse to never change anything
Hyrum's Law explains why changes carry hidden risk, not that every detail must be frozen forever. The right response is managed change — flags, dual-running, real deprecation windows — not paralysis.
Confusing it with "all software has bugs"
This law is specifically about the social and scale-driven dynamic of reliance on behavior nobody ever promised. It is not a general statement about code quality, and citing it to explain an ordinary regression misses what it actually claims.
When not to use it
- As a justification for never improving, simplifying, or cleaning up an interface — it is a risk-management principle for change, not a mandate to freeze everything in place.
- For systems with genuinely few consumers, where the "sufficient number of users" the law assumes hasn't been reached, and simply talking to the handful of actual consumers beats defensive engineering.
- As a substitute for an actual versioning, deprecation, and communication process — understanding the law doesn't remove the need to give real notice before a real change.
- As a way to blame-shift entirely onto users ("not my problem, it wasn't in the contract") in a way that avoids the genuine engineering and support work a breaking change requires.
- As a universal explanation for every production incident — plenty of outages are ordinary bugs or regressions with nothing to do with undocumented reliance.
Try It Yourself: build your own prompt
Answer three quick questions and get a ready-to-use prompt for applying Hyrum's Law to your own situation.
Your prompt:
Save as Skill
A portable summary of Hyrum's Law you can hand to an AI assistant, a teammate, or your future self, so the model gets applied the same careful way every time.
Preview