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

Leia de fora para dentro, partindo 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 universais, 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 estar inline se alterar o comportamento padrão, for amplamente aplicável e for caro cometê-la. Catálogos de comandos, esquemas 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 critério não é a importância, mas a frequência. Regras que se aplicam a quase todas as solicitações pertencem ao arquivo carregado permanentemente. 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. Assim, 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 mode, a combinação e escala tipográfica, o sistema de espaçamento e raio, e as diretrizes de 'faça e não faça' que impedem um agente de inventar 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 diversas ferramentas, fácil 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 da ferramenta.
4. Skills por último, assim que você notar o mesmo procedimento longo sendo explicado repetidamente.

Os arquivos geralmente são comparados com base na sua *finalidade*. Vale a pena saber como são usados na prática, pois a lacuna entre a convenção e a prática é onde a maioria das confusões começa.

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

Entre os 72 que genuinamente descrevem um sistema visual, a divisão de responsabilidades discutida acima não está sendo respeitada. 86% não usam nomes de funções de cores semânticas, portanto, o arquivo não pode ser aplicado a nenhum componente que não tenha sido explicitamente descrito, que é precisamente a função para a qual ele existe. 76% não declaram proibições, e as proibições são a forma de instrução que os agentes seguem com mais precisão. 69% omitem o modo escuro, deixando um tema inteiro para ser inventado.

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