Most CLAUDE.md files are too vague to stop AI from guessing. A concrete, copyable structure for a CLAUDE.md that actually constrains Claude Code.
Claude Code reads your CLAUDE.md before it writes a line. If that file says "follow our brand guidelines and use our design system", you have told it nothing it can execute — and it will do what every agent does with a gap: guess. Confidently, in the right font, with the wrong tokens.
This is the structure we author into client repos. It is short, specific, and it has one job: make the right component and the right token the path of least resistance for an agent.
Most of the ones we audit read like an onboarding doc for a human. They fail in the same four places:
They describe intent, not constraints. "Use semantic colors" is a value. "Components reference semantic tokens only; a raw hex in a component is a bug" is a rule an agent can check itself against.
They don't say where the truth is. No path to the token export, no link to the Figma file, no component index. The agent can't look anything up, so it invents.
They have no component index. This is the single highest-leverage section, and it is almost always missing. Without it, the agent doesn't know Button exists with twelve variants — it writes a thirteenth.
They never say what to do when unsure. So the agent proceeds. The correct instruction is the opposite: stop and ask. An off-system component costs more than a question.
Five things, in this order of value:
Everything else — tone, history, philosophy — belongs in a linked doc, not here. Keep the file under ~200 lines; an agent reads it on every task.
This is the template. Fill the {...}, delete what doesn't apply, and keep the rules verbatim — they are written as constraints on purpose.
# {Client} Design System — agent context
## What this is
The {Client} design system. This file is the source of truth for how to build
on-system UI. When generating components or screens, follow it exactly. If
something here conflicts with code you see, this file wins — surface the conflict.
## Stack
- Figma file: {url} (source of design truth)
- Component library: {path/package}
- Tokens: {path to token export}
- Code Connect: {mapped / partial / path}
## Token system
Three layers — never use a primitive directly in a component.
- Primitives: {path} — raw values, do not reference in UI
- Semantic aliases: {path} — use these (`color-action-primary`, `space-inset-md`)
- Modes: {light/dark/density/brand}
**Rule:** components reference semantic tokens only. A raw value in a component is a bug.
## Components
- Source of truth: {Figma ↔ code mapping via Code Connect}
- Naming convention: {kebab-case / PascalCase}, must match across Figma, code, docs
- To build a screen: resolve each Figma node to its mapped code component; do not
reinvent existing components — search the library first.
### Component index
| Component | Code path | Figma key | Notes |
|-----------|-----------|-----------|-------|
| {Button} | {} | {} | {variants} |
## Conventions
- {File/naming conventions}
- {Where components live, how they're exported}
- {Accessibility baseline}
## Do / Don't
- ✅ {use semantic tokens; reuse library components; match naming}
- ❌ {raw hex values; one-off components; new token names without governance}
## Governance
- Source of truth owner: {name/team}
- How changes propagate: {Figma → tokens → code flow}
- To add/change a token or component: {process}
## When unsure
Don't guess. Surface the gap and ask. An off-system component is worse than a question.
Three notes on the parts people get wrong:
"This file wins — surface the conflict." Your code has drift in it. Without this line the agent treats the drift as the standard and propagates it. With it, the agent reports the inconsistency instead of copying it.
The component index is generated, not written. If you have Code Connect, export the map. If you don't, the index is the audit of what you're missing — every row you can't fill is a component the agent will reinvent.
"A raw value in a component is a bug." Phrase rules as things that are wrong, not things that are preferred. Agents weigh "prefer" loosely and "bug" literally.
A CLAUDE.md is documentation, and documentation drifts. Three habits keep it true:
It lives in the repo, and changes to the system change it in the same PR. A token renamed in Figma and not in this file is a file that now lies.
It is validated the same way you'd validate the system: by running it. Ask an agent to build a known screen from this file and the library alone. Where it guesses, the file has a gap. We call this the consumability test, and every engagement ends with one.
It has an owner. The governance section isn't decoration; it names who approves when someone (or something) proposes a new token.
If you don't know how far your system is from this — whether the tokens are semantic, whether the components map, whether there is anything an agent can read at all — that's what the AI-readiness audit measures: six dimensions, a score, and a live test. The CLAUDE.md is usually the last thing we write, because it can only be as true as the system underneath it.