← Problem log

Agent rule changes kept clashing

Last verified Nov 1
By the Bluhook team · Updated Nov 8, 2026
Version 1
Exact text to search:
AI agents rule changes conflict review CLAUDE.md

1What happened

we run a large team of AI agents. Each one has a rules file that tells it how to work. Agents propose changes to these files all day.

Each change looked fine by itself. Together, they kept clashing. One agent's new rule was stricter than the owner's own words. Another cut a line that a second agent still relied on. Two changes merged a minute apart each fit a size limit, and together they broke the build for every agent.

In the week of Oct 26, 100 of the 216 rule changes we reviewed had a clash on their first review.

2What we did

  1. One agent does just one job: it reviews every change to a rules file before the change merges. It doesn't write rules for others, and it doesn't merge.

  2. Every review asks the same 8 questions: what problem does this fix, which agents does it touch, does it clash with an existing rule or the owner's words, what could it break, which old lines should go, how will we know it worked, did the agent simply lack the information, and is this a duplicate that pushes the file over its size limit.

  3. The owner's exact words live in one file, each with its date and time. A rule that quotes the owner gets checked against that file, not against memory.

  4. The answer is PASS or the clash, plus a pick for the fix. It goes on the change itself. The owning agent decides.

  5. A PASS names the exact commit it was given for. A merge hold reads it. If the change gets one more commit, the hold comes back until there's a new review.

    For buildersthe verdict's first line is PASS at <40-character commit hash>, and the hold compares that hash to the head of the change.
  6. Tests run on the commit that was actually pushed, not on the local copy. We learned this when a fix passed every test locally but was pushed without its last edit.

3How we checked

the reviewer agent is checked by a second agent (our security lead) on its own changes.

216 changes reviewed in the week of Oct 26, with 512 reviews in all, counting re-checks after a fix. No change with an open clash was merged.

The hold caught changes that got a new commit after their PASS (for example, a rebase that grew a size count by 5 words and failed a test).

4Try it

when agents can edit their own rules, the rules drift. Put one reviewer in the path, tie each PASS to an exact commit, and keep the owner's words in one file to check against.

AI agentsprocesscode reviewPublished Nov 1

Your free AI evaluation

17 free questions, a few minutes. Your top 3 jobs for AI arrive by email.

Show me my top 3 jobs

Questions people ask

Why do AI agents editing their own rules files break each other?

Each change looked fine alone, but together they clashed. One new rule was stricter than the owner's own words, another cut a line a second agent relied on. In one week, 100 of 216 rule changes had a clash on their first review.

How do I review changes to CLAUDE.md files across many agents?

Send every change through one reviewer agent that only reviews. It asks the same 8 questions each time and answers PASS or names the clash with a pick for the fix. The owner's exact words live in one dated file to check against.

How do I stop a rule change from merging after a new commit?

Tie each PASS to the exact commit it was given for. A merge hold compares that commit hash to the head of the change. If a new commit lands, the hold comes back until there's a new review.

Keep reading

Robb Lejuwaan

Every practical lesson, the wins and the flops, goes into Robb on AI, a free email newsletter.

Robb Lejuwaan, writer of Robb on AI
Get Robb on AI, free

Every lesson, win and flop, by email. Opens Substack.

Robb on AI is our free newsletter, written by Robb Lejuwaan.

We'll add you to Robb on AI, our free newsletter on Substack. Unsubscribe anytime. Privacy policy