CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md

Read outward from the narrowest scope. A rule in a more specific file wins over a more general one, and a rule the user types in the session wins over every file.

1. What the user says in the session — always wins, including when it contradicts a file.
2. `SKILL.md` — active only while that skill is invoked, and scoped to it.
3. `CLAUDE.md` / tool-specific file — this tool's behaviour in this repo.
4. `AGENTS.md` — the project's rules for any agent.
5. `DESIGN.md` — the visual contract, referenced by the above rather than competing with them.

This is the one to write first. It is read by a growing set of agents, it is not owned by any vendor, and it holds the things that are true regardless of who is doing the work: how to build, how to test, what not to touch, which conventions the codebase actually follows.

The discipline that matters is cost. It loads on every request, so every line is paid forever. A rule earns a place inline only if it changes default behaviour, applies broadly, and is expensive to get wrong. Command catalogues, API schemas and setup procedures belong in a doc with a one-line pointer.

# AGENTS.md

## Build and verify
- `pnpm dev` on :4000. Never run `pnpm build` — it corrupts the shared dev cache.
- Verify with `tsc --noEmit`, not a build.

## Conventions
- Server work goes in `src/server/` as server actions, not API routes.
- Never hardcode theme colors; use the semantic tokens in DESIGN.md.

## Before you act
- Changing the payment flow: read `docs/PRICING.md` first.

The recurring mistake is maintaining CLAUDE.md and AGENTS.md as two full copies. They drift silently, and the drift surfaces as an agent confidently following a rule you deleted two months ago.

# CLAUDE.md

@AGENTS.md

## Claude Code only
- Use the local browser tool for hydration checks; the remote one stalls RSC.
- Slash commands live in `.claude/commands/`.

The distinction that makes skills click: AGENTS.md is *always* in context, and a skill is loaded *when it is relevant*. That difference is a budget decision. A 400-line code-review checklist in AGENTS.md is paid on every request including the ones that change a typo. The same checklist as a skill costs nothing until review actually starts.

So the test is not importance, it is frequency. Rules that apply to almost every request belong in the always-loaded file. Procedures that apply to a specific kind of task — deploying, reviewing, generating a migration — belong in a skill.

Here is the gap. AGENTS.md has no natural home for a colour ramp. CLAUDE.md is about tool behaviour. A skill is invoked, not ambient. So the visual contract ends up nowhere — and an agent with no visual contract falls back to defaults, which is why AI-built sites converge on one look.

A DESIGN.md closes it. At minimum it carries semantic colour tokens for light and dark, the type pairing and scale, the spacing and radius system, and the do's and don'ts that stop an agent inventing a new pattern when it hits an unfamiliar case.

# DESIGN.md

## Color (semantic, light + dark)
--background / --foreground / --card / --primary / --muted-foreground …

## Type
Headings: Fraunces 600, -0.02em. Body: Inter 400, 1.6.
Scale: 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem.

## Motifs
Hairline rules between sections. Radius scales with element size.

## Don't
No gradient text. No shadow on flat surfaces. Never hardcode a hex.

The reason this file works where a prompt does not is unglamorous: it is re-read at the start of every session. Instructions held in conversation degrade as context grows. A file does not.

No, and starting with all four is the wrong move. In rough order of return:

1. `AGENTS.md` first. Highest value per line, works across tools, cheap to write.
2. `DESIGN.md` next, if you ship UI. It is the largest quality gap for the least effort, because nothing else covers it.
3. `CLAUDE.md` as a one-line import, plus a tail only when you genuinely have tool-specific rules.
4. Skills last, once you notice the same long procedure being explained repeatedly.

The files are usually compared on what they are *for*. It is worth knowing how they are used in practice, because the gap between the convention and the practice is where most confusion starts.

We sampled 299 public repository-root DESIGN.md files from GitHub and measured them. The first finding reframes the whole comparison: only 24% of them describe visual design at all. The other 76% are software architecture documents — how a system is built, not how a product looks.

Within the 72 that genuinely describe a visual system, the split of responsibilities argued above is not being honoured. 86% use no semantic colour role names, so the file cannot be applied to any component it did not explicitly describe — which is precisely the job it exists to do. 76% state no prohibitions, and prohibitions are the form of instruction agents follow most reliably. 69% omit dark mode, leaving an entire theme to be invented.

The practical reading: most projects that add a DESIGN.md are writing a document rather than a contract. The difference is whether an agent can resolve a value from it without guessing.