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

Leia de fora para dentro, do escopo mais estreito. Uma regra em um arquivo mais específico prevalece sobre uma mais geral, e uma regra digitada pelo usuário na sessão prevalece sobre qualquer arquivo.

1. O que o usuário diz na sessão — sempre vence, inclusive quando contradiz um arquivo.
2. `SKILL.md` — ativo apenas enquanto essa skill é invocada, e limitado ao escopo dela.
3. `CLAUDE.md` / arquivo específico da ferramenta — o comportamento desta ferramenta neste repositório.
4. `AGENTS.md` — as regras do projeto para qualquer agente.
5. `DESIGN.md` — o contrato visual, referenciado pelos itens acima em vez de competir com eles.

Este é o primeiro que você deve escrever. Ele é lido por um conjunto crescente de agentes, não pertence a nenhum fornecedor e contém as verdades independentemente de quem esteja fazendo o trabalho: como buildar, como testar, o que não tocar e quais convenções a base de código realmente segue.

A disciplina que importa aqui é o custo. Ele é carregado em cada requisição, portanto, cada linha é paga para sempre. Uma regra só merece um lugar inline se ela alterar o comportamento padrão, for amplamente aplicável e for caro cometê-la. Catálogos de comandos, schemas de API e procedimentos de configuração devem ficar em um documento com um ponteiro de uma única linha.

# 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.

O erro recorrente é manter o CLAUDE.md e o AGENTS.md como duas cópias completas. Eles divergem silenciosamente, e essa divergência aparece quando um agente segue com confiança uma regra que você deletou dois meses atrás.

# 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/`.

A distinção que faz as skills funcionarem: AGENTS.md está *sempre* no contexto, e uma skill é carregada *quando é relevante*. Essa diferença é uma decisão de orçamento. Um checklist de code-review de 400 linhas no AGENTS.md é pago em cada requisição, inclusive naquelas que corrigem um erro de digitação. O mesmo checklist como uma skill não custa nada até que a revisão realmente comece.

Portanto, o teste não é a importância, mas a frequência. Regras que se aplicam a quase todas as requisições pertencem ao arquivo sempre carregado. Procedimentos que se aplicam a um tipo específico de tarefa — deploy, revisão, geração de migração — pertencem a uma skill.

Aqui está a lacuna. O AGENTS.md não tem um lugar natural para uma rampa de cores. O CLAUDE.md trata do comportamento da ferramenta. Uma skill é invocada, não é ambiente. Portanto, o contrato visual acaba não ficando em lugar nenhum — e um agente sem contrato visual recorre aos padrões, que é por que sites criados por IA convergem para a mesma aparência.

Um DESIGN.md resolve isso. No mínimo, ele contém design tokens semânticos para light e dark, a combinação e escala tipográfica, o sistema de espaçamento e raio, e as recomendações do que fazer e do que não fazer para evitar que um agente invente um novo padrão ao encontrar um caso desconhecido.

# 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.

A razão pela qual este arquivo funciona onde um prompt falha não é glamorosa: ele é relido no início de cada sessão. Instruções mantidas na conversa degradam conforme o contexto cresce. Um arquivo não.

Não, e começar com os quatro é a estratégia errada. Em ordem aproximada de retorno:

1. `AGENTS.md` primeiro. Maior valor por linha, funciona em várias ferramentas, barato de escrever.
2. `DESIGN.md` em seguida, se você entrega UI. É a maior lacuna de qualidade com o menor esforço, porque nada mais a cobre.
3. `CLAUDE.md` como um import de uma linha, com complementos apenas quando você realmente tiver regras específicas de ferramentas.
4. Skills por último, assim que você notar o mesmo procedimento longo sendo explicado repetidamente.

Os arquivos são geralmente comparados pelo que são destinados a fazer. Vale a pena saber como são usados na prática, pois o abismo entre a convenção e a prática é onde começa a maior parte da confusão.

Amostramos 299 arquivos DESIGN.md na raiz de repositórios públicos do GitHub e os medimos. A primeira descoberta reformula toda a comparação: apenas 24% deles descrevem o design visual. Os outros 76% são documentos de arquitetura de software — como um sistema é construído, não como um produto se parece.

Dentro dos 72 que descrevem genuinamente um sistema visual, a divisão de responsabilidades argumentada acima não está sendo respeitada. 86% não utilizam nomes de papéis de cores semânticas, portanto, o arquivo não pode ser aplicado a qualquer componente que não tenha sido explicitamente descrito — que é precisamente a função para a qual ele existe. 76% não estabelecem proibições, e proibições são a forma de instrução que os agentes seguem com mais confiabilidade. 69% omitem o dark mode, deixando um tema inteiro para ser inventado.

A leitura prática: a maioria dos projetos que adicionam um DESIGN.md está escrevendo um documento em vez de um contrato. A diferença é se um agente consegue resolver um valor a partir dele sem precisar adivinhar.