Clear ideas for complex systems
Latest posts
Technology and Infrastructure

Hyrum’s Law and Implicit Interfaces: Why Every Observable Behavior Becomes a Dependency

Hyrum's Law explains why every observable behavior of a system can become an implicit dependency, even when it was never intended as an interface.

Table of ContentsNavigate this article

    Last updated: 3 November 2026.

    Hyrum’s Law is a warning about interfaces: with enough users of a system, every observable behavior will be depended on by somebody. The official API may be small, but real dependencies grow around timing, ordering, defaults, error messages, resource use and other behaviors that were never promised.

    Key takeaways

    • The effective interface is larger than the documented interface.
    • Consumers create dependencies through observation, testing and adaptation.
    • Safe change requires discovering behavior, classifying dependencies and offering migration paths.

    The documented interface is only the center

    A service may promise a JSON field and a status code. Consumers may also rely on field order, response latency, retry behavior, pagination quirks, log text or the exact way a failure is represented. They do not necessarily do this carelessly. They are responding to what the system exposes.

    At small scale, a team can know which behaviors matter. At larger scale, the dependency graph becomes partly invisible. A behavior that looks accidental to the producer can be essential to a downstream client.

    Observable behavior becomes an implicit interfaceA documented interface sits inside a wider set of observable behaviors, and different consumers depend on different parts of that wider surface.Observable systemdocs + timing + defaultsdocumented APIclient Aclient Bclient Cclient D

    Why implicit dependencies appear

    Software consumers optimize for the system they can observe, not the system designers intended. A client may use an undocumented sort order because it makes a report stable. A test may freeze a timestamp format because a parser depends on it. An operator may build a runbook around a retry window.

    As the behavior is repeated, the dependency becomes stronger. The producer may not know who relies on it until a change breaks something. This is a version of emergence: the interface emerges from many interactions rather than from one specification.

    The system cost of compatibility

    Compatibility is not free. Supporting every accidental behavior can make the code harder to change, increase testing cost and preserve defects. But ignoring observed dependencies can cause outages. The systems problem is to distinguish safe freedom to change from behavior that has become part of the operating environment.

    Useful practices include contract tests, deprecation windows, telemetry on behavior, explicit compatibility tiers and documentation of known quirks. The point is not to promise everything forever. It is to make the change surface visible enough that people can adapt.

    How to apply Hyrum’s Law

    1. List what users can observe, not only what the documentation promises.
    2. Instrument usage before changing behavior.
    3. Classify behaviors as guaranteed, tolerated or internal.
    4. Communicate changes with examples and migration dates.
    5. Keep compatibility shims at boundaries while consumers move.

    Teams should also examine organizational interfaces. A dashboard’s refresh time, a queue’s escalation rule or a meeting’s decision format can become an implicit contract. Removing it may change behavior even when no policy document changes.

    Common mistakes

    • Assuming undocumented means unused.
    • Using a major version number as a substitute for migration evidence.
    • Testing only the happy path and ignoring timing or failure behavior.
    • Keeping every behavior forever without identifying its cost.

    Examples beyond APIs

    A software service is an obvious case, but Hyrum’s Law applies to any system that can be observed and used repeatedly. A team may depend on the time a report arrives, the order in which a queue is processed or the exact phrase used in an escalation email. A city may depend on the opening hours of an office even if those hours were never promised as a public service level.

    These dependencies are often rational adaptations. People build tools around stable behavior because stability is useful. The producer may call the behavior accidental, but the consumer experiences it as part of the environment.

    Why tests discover the interface

    Tests are not only verification. They are records of what a consumer considers important. When a test asserts response ordering, timeout behavior or a default value, it is documenting a dependency whether or not the API specification mentions it.

    Producers should inspect downstream tests, examples and support cases before changing a mature system. Consumers should avoid relying on accidental behavior when a documented alternative exists, but they may not know the difference until it is explained.

    Versioning is a social process

    Semantic versioning and deprecation notices help, but compatibility is ultimately negotiated with users. A breaking change can be technically correct and still operationally unsafe if consumers cannot find the change, understand its impact or migrate in time.

    Good change management includes a clear before-and-after example, telemetry showing remaining usage, a migration guide, an overlap period and a person or team responsible for difficult cases. Compatibility shims are often cheaper than forcing every consumer to move at once.

    Discovering accidental contracts

    • Search code repositories for fields, defaults and error values.
    • Inspect logs for parsing, retry and timing assumptions.
    • Review support tickets that mention “unexpected” changes.
    • Compare real traffic with the documented contract.
    • Ask operators which workarounds they teach new staff.

    Discovery should happen before the design is frozen. If the system is already changing, create a temporary compatibility layer while the dependency map is built.

    When to break the behavior

    Not every accidental dependency deserves preservation. A security flaw, unsafe default or impossible performance cost may justify a rapid change. The decision should still identify who will be affected, what protection they need and how the system will detect migration failure.

    Hyrum’s Law is not an argument for never improving a system. It is an argument for respecting the fact that an observable system is already part of other systems. Change should be designed as a transition, not imagined as a private edit.

    Operational contracts

    Teams can reduce surprise by publishing operational contracts: expected latency ranges, retry behavior, error semantics, data freshness and support channels. These contracts need not promise every implementation detail. They define which properties matter to users and which are deliberately free to change.

    That distinction creates a healthier boundary. Users know what to depend on, producers know what to protect and both sides have a shared vocabulary for discussing exceptions.

    Designing a change-safe interface

    A change-safe interface has three layers. The first layer is the documented contract that consumers can rely on. The second is observable behavior that is tolerated but may change with notice. The third is implementation detail that the producer actively tries not to expose. The boundary is imperfect, but naming the layers helps teams decide where to invest compatibility effort.

    Telemetry is important because it turns invisible dependency into evidence. Before removing a default, measure how often it is used. Before changing a timeout, inspect retries and downstream load. Before altering ordering, find consumers that parse the output. A small amount of observation can prevent a large migration surprise.

    The organizational version

    Teams also create implicit interfaces with each other. A finance report delivered every Monday, a product escalation channel or an on-call handoff becomes part of the environment. When changing it, communicate the new behavior, provide an overlap period and name the owner of exceptions. Hyrum’s Law is a reminder that coordination creates dependencies even when no code is involved.

    Interface discovery is ongoing work

    New consumers appear after an interface is released. A behavior that was internal may become relied on after a new integration, tutorial or automation script spreads. Periodic dependency discovery is therefore part of maintenance, not a one-time migration task.

    Teams can publish a compatibility budget: a short list of behaviors they will protect, behaviors they will deprecate with notice and behaviors that may change without guarantee. The budget keeps the interface from expanding silently while still respecting the system’s real users.

    When a change breaks an unplanned consumer, treat the incident as evidence about the interface boundary. Fix the immediate problem, then update the contract or the discovery process so the same dependency is not invisible again.

    Change management is interface management

    When a mature system changes, the producer should communicate not only the new feature but the old behavior that may disappear. Give consumers a way to test against the new version, publish a migration example and monitor the old path until usage falls. A warning in documentation is rarely enough when the dependency is implicit.

    Consumers also have a responsibility. Prefer documented contracts, isolate integrations behind adapters and avoid turning every observation into a permanent assumption. Both sides reduce accidental coupling when they make the boundary explicit.

    Compatibility without paralysis

    The practical balance is to protect the behaviors that users need while refusing to let every historical accident expand the interface forever. Publish a clear compatibility policy, measure actual dependence and retire behavior through a visible transition. This gives the system room to evolve without pretending that its current users do not exist.

    When a dependency is discovered late, treat the incident as a discovery failure. Add the missing telemetry or contract test so the next change starts with better knowledge.

    What producers and consumers owe each other

    Producers should publish stable contracts, measure usage and communicate deprecations. Consumers should isolate integrations, avoid undocumented behavior where possible and report dependencies before a breaking change. The law is most useful when both sides treat the interface as a shared environment rather than a private implementation detail.

    That attitude reduces accidental coupling without denying that coupling exists. It also makes the system easier to evolve because the cost of change is visible before the change is shipped.

    A final test before release

    Ask a consumer who did not design the system to describe what they believe is stable. Compare that answer with the documentation. The gap is the practical interface that users are already learning. Close the gap with a contract, a migration note or a deliberate decision to change the behavior with support.

    That final comparison is often where a hidden dependency becomes visible. It turns a surprising breakage into a documented choice about compatibility.

    In that sense, compatibility is a relationship to manage, not a promise to freeze the system forever.

    Documented contracts make the system legible to the people who must change it, support it and depend on it.

    That discipline preserves room for innovation while respecting the dependencies that already make the system useful.

    Frequently asked questions

    Does Hyrum’s Law mean APIs cannot change?

    No. It means change must account for the real dependency surface. Versioning, telemetry, compatibility layers and migration support make change safer.

    Is this only a software problem?

    No. Any system with observers can develop implicit interfaces. People depend on institutional routines and infrastructure behavior as well as code.

    What is the first practical step?

    Before a change, measure who uses the behavior and how. Search code, logs, support tickets and operational workarounds.

    Conclusion

    Hyrum’s Law turns observation into structure. Every visible behavior offers a place for a dependency to form. Good engineering does not pretend that only the documented interface exists. It discovers the wider surface, chooses what to support and gives the surrounding system a path to change.

    Sources and further reading

    About the publisher

    Systems Thinking Hub

    We are experts in delivering clear, practical knowledge about systems thinking, complexity, and better decision-making.

    Discussion

    Join the discussion

    Your email address will not be published. Required fields are marked.