the quirks file
Safari ships a file called UserAgentStyleSheets, and that's the polite part. The less polite part is a separate list of domain-specific patches: five lines that make Instagram Reels resize correctly, a fix for a TikTok layout assumption, a Netflix playback workaround. Firefox has one too. These files are not secret, exactly, but no developer shipping a feature checks them. The stated contract is "browsers render to spec." The actual contract is "browsers render to Chrome's bugs, then quietly patch the sites that matter enough for someone to notice."
That's a quirks file. Every system has one.
The browser case is just unusually legible because it's literal source code you can read. Most quirks files aren't written down anywhere. They live in the head of the person who's been on the team longest. They live in the Slack thread from 2021 that nobody has bookmarked. They live in the test that always fails on Tuesdays so the CI config skips it on Tuesdays. They live in the comment that says // don't touch this with no further explanation.
The gap they describe is the same in every case: here is what the system claims to do, and here is what the system actually does, and these two things have drifted.
how the drift happens
Drift is not a failure of discipline. It's a structural property of systems that change over time while their documentation doesn't. A requirement gets added. An edge case gets patched. A dependency upgrades and something upstream compensates silently. The stated contract is expensive to update and nobody's job to maintain, so it stays where it is while the implementation walks away from it.
After long enough, the documentation describes a system that no longer exists. The tests protect behavior that the code doesn't exhibit anymore, or they test the documented behavior rather than the real behavior, which is a different thing. The new engineer reads the spec, builds a mental model, and is surprised by production. The surprise is the gap speaking.
Browser quirks files are interesting because the gap is enormous and managed deliberately. There are probably people at Apple who have never read the entire list. It's archaeology: each entry is a failure that got silently fixed at some point, preserved in amber because removing it might break something and nobody is confident about which something.
the interesting question
The interesting question is not whether your system has a quirks file. It does. The question is whether you know where it is.
Knowing where it is means something specific. It means you can look a new engineer in the eye and say: here are the three places where what I'm about to tell you is wrong. Here's where the API response doesn't match the schema we claim to return. Here's the service that says it's idempotent but isn't if you hit it twice within 500ms. Here's the flag that does nothing but we can't remove because something somewhere depends on it being present.
Systems where nobody knows where the quirks file is are systems that produce surprises in production. The surprise isn't bad luck. It's the gap, expressing itself through the person who encountered it without any map.
Systems where the quirks file is known and maintained are not better-engineered systems. They're more honest ones. The gap still exists. You just have a name for it and a place to write it down.
what maintaining it actually looks like
It doesn't have to be formal. A section in the team wiki called "known deviations from the spec" works. A QUIRKS.md in the repo works. The test that always fails on Tuesdays should have a comment explaining why it fails on Tuesdays and what it would take to fix it, not a CI condition that silently skips it.
The discipline is making the gap visible rather than papering over it. A // don't touch this comment with no explanation is the gap refusing to be named. A // this assumes the upstream service returns 200 for rate-limit errors, which it does despite the docs saying 429; see ticket #4471 for history is the gap being named. The second one is longer. It's also worth the space.
The argument against maintaining it is that it's embarrassing. The gaps are places where the system is wrong, or where some past decision was bad, or where something broke and got fixed in a way that left a scar. Nobody wants to write that down where the new CTO can see it. The argument for maintaining it is that the embarrassment is already there, in the production incidents, in the onboarding confusion, in the engineer who spent a week debugging something that the quirks file would have explained in a paragraph.
Browser vendors maintain their quirks files because the cost of not maintaining them is visible and immediate: the site breaks, users notice, someone gets a call. For internal systems the cost is more diffuse, which is why the file tends not to get written.
But the gap is still there. Naming it doesn't create it. It just makes it legible to the next person through.