Hyrum’s Law

Here is a release note of a kind many teams have shipped:

v4.2.0
Fixed: search results are now returned in a consistent order.

And here are the tickets that could follow it inside a week:

#2291  Our nightly export lists customers in a new order, so the
       finance diff now flags every row as changed.
#2304  The support macro grabs the first search result and assumes
       it's the newest ticket. Since Tuesday it's the oldest.
#2310  Our dashboard's "latest activity" panel shows last year's
       records. It never sorted anything. It relied on the old order.

The tickets are invented, and the pattern is not. The old order was never documented, and the fix was a reasonable one. Every ticket is still a real customer whose work broke.

Hyrum's Law is the observation that once enough people use a system, they will depend on every behavior they can observe, including behavior the system never promised, so almost any change to what users can see will break somebody.

Where the law comes from

Hyrum Wright spent years as a software engineer at Google working on large-scale code change tooling and Google's core C++ libraries. He says the observation "grew out of experiences when even the simplest library change caused failures in some far off system." On the page he keeps for it, hyrumslaw.com, he states it this way: "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." He credits Titus Winters with "actually naming it as 'Hyrum's Law' and popularizing the concept more broadly."

Wright's explanation is about the gap between an interface and its implementation. An interface is meant to separate the people who use a system from the people who build it. In practice, users come to rely on details "intentionally exposed through the interface, or which they divine through regular use." His shorter version: "Given enough use, there is no such thing as a private implementation."

Two features of his account matter for anyone who has to change a system later. The first is that it happens quietly: "The creation of the implicit interface usually happens gradually, and interface consumers generally aren't aware as it's happening." His example is performance. An interface may promise nothing about speed, and users come to expect a certain speed anyway. The second is where it ends. Given enough users, the implicit interface "will eventually exactly match the implementation," and at that point, he writes, "the implementation has become the interface."

Winters made the law a fixture of Software Engineering at Google (2020), where his opening chapter calls it "a dominant factor in any discussion of changing software over time" and compares it to entropy: "We can mitigate it, but we know that it can never be eradicated." His example is the order in which a hash table returns its items, which most programmers know isn't guaranteed. Even so, "programmers will write programs that depend on the order in which a hash table is traversed, if they have the ability to do so." Some languages now shuffle that order on purpose to stop people relying on it, and the chapter notes that even this produced a surprise: "there is code that uses hash iteration ordering as an inefficient random-number generator."

Products have implicit interfaces too

The law was written about APIs, and it applies to anything people can see. A product's interface with its customers is every behavior they can see, and only a few of those were ever written down as promises.

• The columns in a CSV export, and their order, which someone's spreadsheet formula now assumes.
• The hour the weekly summary email goes out, which a customer's team has built a Monday meeting around.
• A free plan that never actually enforced its seat limit, which three customers have grown past.
• An endpoint that has always answered in under a second, so a partner set their timeout at one.

None of these were decided in the sense that a product decision is decided. Each was a side effect of building something else, and each became a commitment the day enough people started relying on it.

The question the law makes expensive

When one of those behaviors has to change, the first question is whether it was ever promised. The code can't answer that. The implementation shows what the system does, and it treats a behavior somebody chose exactly the same as one that happened by accident. The answer, if it exists, is usually in the head of whoever built the feature, if they're still around, or in a Slack thread nobody can find.

Without that answer, teams tend toward one of two bad defaults. They treat everything as promised and stop changing anything, which is what Wright calls "bug-for-bug compatibility." Or they treat nothing as promised and find out from tickets like the ones above. Tests help less than they seem to. In Wright's words, widespread automated testing "can detect these new expectations but not ameliorate them."

Coding agents add pressure from both sides. An agent working in a codebase sees the implementation and nothing else, so by the law's own logic it will build on whatever behavior it can observe. And agents produce a lot of new observable behavior: every default an agent picks without comment is something a customer can start depending on next month.

Where Brief fits: a record of what was promised

Hyrum's Law can't be repealed, but the question it makes expensive can be made cheap. What a team needs is a list of the behaviors somebody actually chose, with the reasons, kept somewhere both people and agents look before they change something. That list is a set of decisions, and keeping decisions is what Brief does.

Run the release note again with that record in place.

The chosen behavior gets recorded when it's chosen. Say the team agreed months ago that search results in the support view come back newest first. If that was settled in a Slack thread, mentioning @Brief in the thread has Brief read the surrounding conversation, propose a structured decision, and show a preview to confirm or edit. From the terminal it's brief decisions create --decision "Search results in the support view return newest first" --rationale "Support macros act on the top result and need it to be the latest ticket". Ticket #2304's behavior is now on the promised list. The export's row order never got a record, and that absence is information too.

The change gets checked before it ships. The engineer or agent making the "consistent order" fix runs brief ask --mode check "We plan to return search results in a stable alphabetical order", and Brief validates the approach against the decisions already on record. The newest-first decision comes up before the release note is written instead of after the ticket is filed. Coding agents connected through Brief's MCP server are told to call brief_get_onboarding_context at the start of every session, which loads the team's decisions along with features, personas and recent work, so an agent knows which behaviors are commitments before it writes code that leans on them.

An accident can be promoted on purpose. After #2291, the team might decide the export's row order should stay stable from now on, because finance diffs it every night. That's a new decision, and recording it turns an accidental behavior into an intentional one, with a reason a future engineer can read. If the order has to change two years later, the new decision supersedes the old one: Brief tracks that one replaced the other, keeps the original as history, and marks which one now governs. The supersession post covers how that works.

The code and the promises sit side by side. Brief's GitHub integration analyzes the codebase to tell what's actually built from what's only planned. Decisions add the piece code can't show: which parts of what's built anyone meant to commit to.

Hyrum's Law still holds with all of this in place. A record tells you what was promised. It can't tell you who depends on a behavior that wasn't, and only usage data, telemetry and customers can. It also holds only what the team captured, so a behavior that was chosen in a hallway and never written down still looks like an accident. What the record does give you is the answer to the first question every breaking change raises. When ticket #2310 arrives, the team knows it broke an accident, not a promise, and that changes both the fix and the conversation with the customer.

Of the behaviors your customers relied on this month, how many could you point to a decision for?

Objections