The handbook problem

If you’ve built anything with Claude Code, Cursor, Lovable, v0 or Figma Make, you’ve probably written notes for the agent. A rules file, a project knowledge box, a list of things to always do and never do. And you’ve probably watched it ignore some of them.

I’m building Arbiter, a tool that records the design decisions made while an agent builds UI. To build it, I read what the AI labs, the coding tools and design system teams have published about getting agents to follow what a team decided. Engineers call this context management. Most of it turned out to be information design.

The new hire with a 500-page handbook

Picture a new hire. On day one you hand them a 500-page handbook. They skim it, remember a fraction, and apply the wrong rule in the wrong place. It’s how most of us onboard agents.

Space isn’t the problem, because modern models can hold a lot of text. Attention is. In one study, the best model followed about 98% of 100 simple instructions and 69% of 500, and most misses were silent skips.¹ In another, a focused 300-token prompt beat the full 113,000-token version of the same material for every model tested.² Irrelevant text gets in the way.

The tools know this. Claude Code suggests keeping its main instruction file under 200 lines, Cursor under 500, and GitHub Copilot no more than two pages.³ In my own project, a typography rule written for one screen started showing up on another, because nothing told the agent where it applied.

Everyone landed on the same answer

Anthropic, OpenAI, Cursor, GitHub, Figma and Storybook arrived at roughly the same setup. Designers will recognise it as progressive disclosure.

1. 01
   A cheat sheet that’s always visible. A short list of one-line rules. OpenAI’s team tried one big instruction file first. It crowded out the task and went stale, so they replaced it with a 100-line map pointing to detailed docs.⁴
2. 02
   The full chapter when you enter that area. Most tools can now load a set of rules only when the agent works on one part of the product.
3. 03
   A spellchecker for anything mechanical. If a rule can be checked automatically, make it a check, and make the error message explain the fix.

Above all, don’t rely on the agent to go and look. When Vercel made their docs available on request, the agent didn’t ask for them in 56% of runs and did no better than with no help at all. A small index that was always present scored 100%.⁵

A tap on the shoulder beats a handbook on a shelf.

Put each kind of knowledge where it belongs

A rules file is the weakest home for design knowledge, because it depends on the agent reading and remembering. Most knowledge has a better home.

Examples come with a warning, because agents copy mistakes too. In a small test, two of three agents working without the team’s rules copied a hard-coded colour from the existing code. With the rules, none did.⁶ And training a model on your design system is the wrong fit for team decisions. It’s like hiring from a great design school: good instincts, but no idea what your team decided last Tuesday.

The reason is the first thing to go

This surprised me most. Almost every system that learns on its own keeps the rule and drops the reason. Review bots from GitHub, Cursor and CodeRabbit save what to do, often before anyone approves it. Visual review tools record a yes or a no on a screenshot. AI builders’ notes boxes fill up with lines like “feel: calm, dense”, with no reason, date or owner.

A rule without a reason gets applied mechanically, including in places it was never meant for. Nobody can tell when it’s fine to break it, or which rules depended on thinking the team has since changed.

A few teams keep the reason. GitHub’s Spec Kit makes you justify any departure from the project’s principles.⁷ Evil Martians require a written reason for every component override.⁸ Vercel’s design team goes furthest: each decision is written up with its status, reasoning, evidence and exceptions, and a person reviews new evidence every week.⁹

One caution. Agents will happily write the reason for you, and it will sound plausible. A reason the agent inferred is a guess. A reason the designer gave is a decision.

Team decisions are case law

Your design system is the written law: tokens and components, enforced. Your team’s decisions are case law: precedent that guides the next person, who can depart from it if they say why.

Case law needs upkeep, because a wrong rule is worse than no rule. Models tend to trust what’s in front of them over their own better judgment.¹⁰

• Retire rules instead of deleting them, with the date and what replaced them.
• Check rules against the product. GitHub Copilot’s memory only uses facts it can still find in the code.¹¹
• Keep a person in charge of what becomes a rule. Cursor removed its automatic memory and told people to write rules instead.
• Say who wins in a clash. “Exception to the design system: 12px corners on payment cards, because…”

What you can do this week

Here’s a rule written the way the research suggests, taken apart.

1. 01
   Test your rules. Ask the agent for something a rule forbids. Does it push back, name the rule, or quietly comply? Testing and fixing a rules file measurably improves results.¹²
2. 02
   One rule per line, under about 25 words, naming the option that lost.
3. 03
   Say where it applies, grouped by area of the product.
4. 04
   Only write what the agent wouldn’t do anyway. Rule files help most with things the model can’t work out for itself.¹³
5. 05
   Hand checkable rules to engineering. In 481 public Claude Code instruction files, only 4 to 16% of the “do not” rules about security were enforced by anything.¹⁴

It was a design problem all along

Context management sounds like an engineering topic. Most of it is information design: what to show, when, and to whom.

This week, ask your agent for something your rules forbid. What it does next will tell you more than your rules file does.