arbiter
See the demo

Part 5

Who wins: you, your rules or DESIGN.md?

Your design system is set when the project starts. Your rules change every week you build. When they disagree, or you ask for something they don’t allow, what should the agent do?

Edmond Hua · 14 Oct 2026 · about 5 minutes · follows Part 4: How Vercel teaches its agents design

In part 4, Vercel ranked what wins when an agent’s sources disagree, with the design system above the team’s own decisions.1 Arbiter lands in the same place. The reason comes down to what stays still and what moves.

Static and dynamic

DESIGN.md, pattern docs, component guidelines and the shared components are the foundations. On a team, a design system lead or a design technologist owns them. Working alone, you write them when you set the project up. They change rarely, and on purpose.

Your rules are different. You make them while you build: the undo bar nobody noticed, so removing asks in the row instead; the empty list that should be one grey line. They pile up week by week, and they’re where a project actually shifts. Arbiter keeps them in DECISIONS.md.

So when two of them disagree, the static layer wins by default. A rule can override it, but only by saying so.

You vs your rules

Who wins
You
What the agent does
Asks first: “Do you still want the undo bar?”

Your rules vs DESIGN.md

Who wins
DESIGN.md, unless the rule is written as an exception
What the agent does
Asks which should win. If the rule is an exception, follows it and says so

You vs DESIGN.md, no rule involved

Who wins
Not Arbiter’s call
What the agent does
Works as it would without Arbiter

The foundations win by default. A rule can override them, but only out loud.

Why ask

An order on its own would let the agent pick a winner and move on. But a clash settled silently comes back next session, and in part 3 the agent’s warnings about clashes scrolled away.

So the agent asks once, before it builds, and the answer goes into the record. “Just this once” saves a one-off exception. “Update the rule” replaces it. Choosing DESIGN.md moves the rule to the archive. Every answer changes the dynamic layer and leaves the static one alone: Arbiter never edits DESIGN.md. A change you’d like there is noted for whoever owns it.

What the agent says

Every clash gets the same shape: a heading, the facts, one question, and two options plus Other. This is one reply from the tests below.

The agent’s reply

Before building, Arbiter found a clash.

You asked for a way to remove a guest with an undo bar, which goes against rule D-0001.

D-0001 · When a host clicks Remove, the row asks “Remove Ana Ruiz? Yes · No”, and there’s no undo. An undo bar at the bottom of the page was tried, but hosts didn’t see it and thought nothing had happened. (eddie, 20 Sept)

Do you still want an undo bar?

1. No, follow D-0001: builds Remove so the row itself asks “Remove Ana Ruiz? Yes · No”, with no undo.

2. Yes, just this once: builds the undo bar on this screen only, and D-0001 stays.

3. Other: type something else, or “update the rule” and why.

It states facts, not opinions. The rule’s way comes first. Changing the rule for good sits under Other, because that needs a reason.

Does the agent do it?

I tested it with Claude Code and Opus 5.5, by script, on a small guest-list app and on Evil Martians’ Deploy Board.2

The first version asked first in 1 of 20 clashes. The wording was right, but it sat in a skill the agent opened after building, to record what it had done. And the one line in CLAUDE.md said the design system wins, so the agent built that, then apologised: “I should have asked before building.”

Two sentences fixed it. The skill now says to use it before building, and the CLAUDE.md line says when to ask:

CLAUDE.md

If the request, or the design system (DESIGN.md, design-system or pattern docs, component guidelines, or the shared components), goes against a decision, don’t build yet: ask first, the way the arbiter skill shows. A decision written as an exception (“Exception to the design system: …”) beats the design system without asking: follow it and say so.

Asked before building, when a clash was real

Result
20 of 20 (was 1 of 20)

Followed a rule written as an exception, and said so

Result
10 of 10

Asked when nothing clashed

Result
0 of 25

Recorded the answer the right way

Result
12 of 12

Still asked when the team’s CLAUDE.md said “Don’t stop to ask clarifying questions”, or ran to 34,000–44,000 characters

Result
20 of 20

That’s 142 scripted runs with one model on two demo apps, scored by a script and by me reading every reply. Run by script, the agent shows each question as numbered text rather than Claude Code’s picker. Treat it as a strong signal, not a law.

What we learned

  1. The static layer wins by default. It’s set on purpose and owned by someone. A rule overrides it only by saying it’s an exception.
  2. Ask once, and keep the answer. The answer changes your rules, never the foundations, so the same clash doesn’t come back.
  3. Where an instruction lives decides when it’s read. The line in CLAUDE.md is read every session and decides what happens. The skill decides the wording, but only if it’s opened in time.

Keeping the moving part

Arbiter is for the dynamic layer: it records the rules you make as you build, feeds them back to the agent, and in its next version asks when one clashes with you or with DESIGN.md. The foundations stay with whoever owns them.

  • DESIGN.md and pattern docs are static: set up front and owned. Your rules are dynamic: made while you build.
  • The static layer wins by default. A rule overrides it only when written as an exception.
  • When anything clashes, the agent asks once before building, and the answer goes into your rules.

Sources

  1. John Phamous, Teaching agents product design at Vercel, Vercel, June 2026. vercel.com/blog
  2. Yuri Mandrikov, Deploy Board, the reference app for the ai-design-system skill, Evil Martians, 2026. MIT licence. github.com/ymandrikov/ai-design-system-demo-app