The House Rules Beat The Helpful Default

If you build an automated reviewer, make it read the repository's own written rules before it applies any of its own. A bot's built-in convention is a fallback for when nobody has said anything, not an opinion that outranks the people who live in the codebase. I was reminded of this recently when a review bot I run asked for a branch name in one shape while the repository's own guidance, sitting in plain sight at the root, asked for another. The bot was confident. The repo was right. Confident and wrong is the worst combination a reviewer can have.

Why the default felt reasonable

Nobody wrote that default out of malice or laziness. When you build a reviewer you need it to say something useful on day one, in a repository it has never seen. A naming convention is an easy, checkable thing to enforce, so it goes in. It was tidy, consistent and sensible in isolation.

The trouble is that "sensible in isolation" describes almost nothing in real software. Teams accrete conventions for reasons that never make it into a tool's design: a ticketing system that wants a particular prefix, a deployment pipeline that parses branch names, a habit that survived because it made someone's Tuesday easier two years ago. A generic rule can't know any of that. When it meets a local rule, one of them has to win, and a tool that always picks itself is quietly claiming it understands the codebase better than the people who wrote the guidance.

What the mismatch actually costs

The obvious cost is a wasted round trip: the author renames a branch to satisfy the bot, then a human points out the repository wanted something else. That's irritating but cheap.

The expensive cost is trust. Each time a reviewer is wrong with confidence, people learn a little more about how to treat it. The first conflicting comment gets investigated. The third gets skimmed. By the tenth, the whole bot sits in the same mental bucket as a linter nobody configured, and the one time it flags a real problem, a missing authorisation check or a migration that can't be rolled back, the comment lands in a thread already trained to scroll past it. Noise isn't free. It spends the credibility you need later.

There's a human cost too, and it's easy to miss. Written conventions in a repository are usually a small act of care by whoever took the time to write them down. A tool that ignores them tells that person their effort didn't register. People rarely say so, but they remember.

The ordering that works

The fix is a simple precedence, and it's mostly a matter of being honest about what each source of rules is. The repository's own guidance is authoritative for that repository, because it was written by people who carry its consequences. The tool's built-in convention is a default, useful precisely when the repository is silent. So the reviewer reads local guidance first, applies it where it speaks, and falls back to its own opinion only where it doesn't.

That ordering has a pleasant side effect. It makes the tool more useful in repositories where nobody has written anything down, because it still behaves sensibly there, and more respectful in repositories where somebody has. It also means the tool can be dropped into a new codebase without a negotiation about whose naming scheme is correct.

It's worth being clear about what this doesn't mean. It doesn't mean the bot should be silent about everything local rules don't mention, and it doesn't mean local rules are always good. A repository's guidance can be stale, contradictory or simply wrong, and a reviewer that quietly obeys a bad rule is no better than one that quietly overrides a good one. The useful behaviour in that case is to follow the local rule and say plainly that it did, so a human can decide whether the rule deserves revisiting. Deference with visibility beats both obedience and defiance.

The wider pattern

I think this generalises well beyond bots. Any time a newcomer, a contractor, a framework or a clever assistant arrives with its own idea of how things are done, the useful question is the same: has this place already told me? Reading before acting is a sign of respect, and it's also just cheaper. The few seconds it takes to look at what's written down are nothing next to the cost of confidently reorganising someone else's house.

With AI-assisted tooling this matters more, not less. These tools are fluent, and fluency reads as authority. A model that produces a crisp, well-argued instruction about branch naming sounds like it knows something, even when it has never looked at the repository it's talking about. The discipline has to come from how we build around it: make it find the local rules first, make it say which rule it applied, and treat its own preferences as the fallback they are.

There's a commercial angle as well. A reviewer people trust gets used, and used tools find real defects. One people have learned to ignore costs the same to run and delivers nothing. Teaching a bot some manners looks like polish, but it's really what decides whether the thing earns its keep.

So the change I made was small: read the repository's guidance first, use the built-in convention only when there's nothing to read, and be explicit about which one applied. It took far less effort than the comment threads it prevents, and it moved the tool from telling people how their house should work to working inside the house they already built.