Regras de design no Claude Code: skill ou CLAUDE.md?

Tua regra de espaçamento tá no CLAUDE.md, a paleta tá numa skill que nunca dispara e o resto tá na tua cabeça, aparecendo só quando o Claude entrega uma tela feia 🙂

O Claude Code oferece lugares diferentes pra guardar instrução de design, e eles NÃO são equivalentes

Tem o CLAUDE.md do projeto (em ./CLAUDE.md ou ./.claude/CLAUDE.md), tem skill em .claude/skills/ ou ~/.claude/skills/, e tem regra com escopo de caminho em .claude/rules/

A escolha não é estética, ela muda o que entra no contexto e QUANDO entra

Bora comparar?

CLAUDE.md x skill x regra por caminho: o que muda na prática

Repara na coluna do meio, porque é ela que decide o custo

CLAUDE.md é presença permanente, skill é presença condicional, regra por caminho é presença localizada

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Quando a regra de design pertence a cada lugar

Convenção curta que vale em qualquer tarefa:

A orientação oficial é reservar o CLAUDE.md pro que vale em toda sessão: comandos de build, convenções, layout do projeto e regras do tipo sempre faça X

Então "os componentes de UI ficam em src/components" e "nunca escreva estilo inline" são candidatos naturais

São fatos, não procedimento

O que a doc manda mover pra fora dali é justamente o que é procedimento de vários passos ou o que só importa em parte do código: isso vai pra skill ou pra regra com escopo de caminho

Guia de estilo com julgamento, vários passos:

A recomendação é usar skill quando o Claude precisa DECIDIR como aplicar os passos, ou quando o conteúdo é conhecimento, tipo um guia de estilo

O exemplo público mais fácil de olhar é a skill frontend-design, publicada no repositório anthropics/skills, com o objetivo de gerar interfaces distintas e de qualidade, fugindo da estética genérica de IA

Ela manda definir contexto e direção estética ANTES de escrever código (do minimalismo radical ao maximalismo, retrofuturista, orgânico, luxo) e desaconselha fontes genéricas como Inter, Roboto e Arial, além de clichês tipo gradiente roxo em fundo branco

Isso é exatamente o tipo de coisa que morre no CLAUDE.md: é longo, é procedimento, e só faz sentido quando tem interface na mesa

Dois detalhes que valem ouro aqui

Se você quer que a skill seja acionada só na mão, o campo disable-model-invocation: true no frontmatter impede que o Claude acione ela sozinho

E quando existe skill de mesmo nome em escopos diferentes, uma definição vence por prioridade: no exemplo da documentação, com uma skill deploy em ~/.claude/skills/ e outra no .claude/skills/ do projeto, roda a pessoal

Ou seja: cuidado com nome genérico tipo design, porque a tua versão pessoal pode estar mandando na do time sem você perceber 😛

Ah, e o campo allowed-tools no SKILL.md vale no Claude Code via CLI, no SDK o controle de ferramentas é feito pela opção allowedTools da configuração da query

Regra que só importa numa área do código:

Se a instrução visual só vale pros arquivos de UI, ela não precisa estar aberta a sessão inteira

Em .claude/rules/, o campo paths do frontmatter aceita padrões glob e a regra só entra no contexto quando um arquivo correspondente é aberto

É o meio termo perfeito pra aquela regra chata de acessibilidade que só interessa em src/**/*.{ts,tsx}

Tome cuidado com um detalhe: regra SEM paths carrega no início da sessão, virando um CLAUDE.md disfarçado

Como consolidar regras espalhadas sem inchar o contexto

1. Separe fato de procedimento. Passe o olho no teu CLAUDE.md e marque cada linha: é uma verdade curta do projeto ou é um passo a passo? Fato fica, procedimento sai. O erro comum deste passo é tentar decidir por tamanho em vez de natureza: linha curta que exige julgamento continua sendo procedimento

2. Deixe no CLAUDE.md só o que vale em toda sessão. Comandos de build, convenções, layout do projeto e regras do tipo sempre faça X. O erro comum aqui é quebrar o arquivo em imports @caminho achando que isso alivia o contexto: os arquivos importados também são expandidos e carregados na abertura, junto com o CLAUDE.md que os referencia. Dividir organiza, não reduz. (A recursão dos imports vai até quatro saltos, e escrever o caminho entre crases evita o import)

3. Crie a skill. A doc usa a criação do diretório assim:

mkdir -p ~/.claude/skills/design-do-projeto

Se a regra é do time e você quer que ela chegue a quem clona o repositório, o lugar é .claude/skills/ dentro do projeto

4. Escreva o SKILL.md com frontmatter. Frontmatter YAML entre os marcadores ---, com name e description, e o corpo em markdown com as instruções:

---
name: design-do-projeto
description: Guia de estilo visual do produto. Use ao criar ou redesenhar telas, componentes de interface, escolher tipografia, cores e espaçamento.
---

# Direção estética

Defina a intenção visual antes de escrever qualquer código
...

5. Trate a description como gatilho, não como enfeite. É por ela que o Claude decide sozinho quando acionar o conteúdo, por correspondência semântica. O erro comum deste passo é description vaga ("regras de design") que nunca dispara: descreva as SITUAÇÕES em que a skill deve entrar, com as palavras que aparecem no teu pedido do dia a dia

6. Mova a regra de área específica pra .claude/rules/. Crie o arquivo com paths no frontmatter apontando pro glob da área. O erro comum é esquecer o paths e achar que ganhou economia de contexto quando a regra tá carregando desde o início

Se você tá começando do zero e quer ver formato de skill funcionando antes de escrever a tua, dá pra estudar um repositório de skills prontas só pra pegar o padrão, beleza?

O que eu aprendi usando skills em todos os meus projetos

No vídeo abaixo eu gero um projeto do zero com as skills de planejamento e execução, abro o app no navegador e dou de cara com uma interface padrão, genérica, sem identidade nenhuma

Eu chamo isso de projeto sem alma haha

Antes de chegar no visual, aliás, o app funcional saiu com erro de cadastro e login, e eu resolvi do jeito mais bobo possível: colando a mensagem de erro no chat pro Claude Code analisar e corrigir

Pro redesign eu ativei a skill frontend-design e escrevi um prompt descrevendo a INTENÇÃO visual, não só o componente: visual clean e moderno, sensação de confiança financeira, modo escuro, e o usuário sentindo controle das finanças sem sobrecarga

No fim, o Claude Code listou o que tinha mudado: modo escuro, tipografia, cor de acento, cards, barra de navegação e animações

Abrindo o app de novo, a tipografia mudou bastante, o estilo ficou mais sofisticado e os elementos ficaram mais consistentes entre si

Agora a parte honesta: o resultado varia, e nem sempre a mudança é significativa

Boa parte das reclamações de "resultado ruim" que eu vejo tem mais a ver com prompt mal escrito do que com a ferramenta em si (e isso vale pra qualquer modelo, inclusive quando a gente compara projetos visuais e interativos entre um e outro)

Esse tipo de conteúdo, com direção estética e decisão de gosto, é onde a skill brilha: ele é grande, ele é situacional, e ficaria ocupando espaço à toa se morasse no CLAUDE.md desde o boot

O que sobra pro CLAUDE.md é o esqueleto: onde as coisas ficam, o que rodar, o que nunca fazer

Eu cito a UI UX Pro Max como outra opção conhecida pra design de front end, mas prefiro a skill de design da própria Claude, que já resolve muito caso, em vez de sair instalando pacote de terceiro

E quando o projeto tem tecnologia ou regra própria, aí sim eu monto skill customizada, tipo uma skill de segurança com as regras que só valem ali

No vídeo você vê o fluxo inteiro na prática: o app genérico, o prompt de intenção visual, o que o Claude Code diz ter mudado e o resultado na tela

Veredito: onde colocar suas regras visuais

Sem ficar em cima do muro

CLAUDE.md pro pouco que é permanente e curto: comandos de build, convenções, layout do projeto, regra do tipo sempre faça X. Se cabe em uma linha e não exige julgamento, é aqui

Skill pro guia de estilo: direção estética, tipografia, o que evitar, os passos que o Claude precisa decidir COMO aplicar. Carrega só nome e descrição no startup, e o corpo entra quando faz sentido

Regra em .claude/rules/ com paths pro que é local, aquilo que só vale nos arquivos de UI e é ruído no resto do repositório

E sim, muitas vezes a resposta é usar mais de um ao mesmo tempo: o CLAUDE.md diz que existe um guia de estilo e onde as telas moram, a skill carrega o guia quando tem interface na mesa, e a regra por caminho reforça o detalhe fino quando o arquivo abre

Tem um quarto caso que o pessoal insiste em enfiar em skill e não é skill: quando a ação precisa acontecer SEMPRE igual, sem o modelo pensar, o lugar dela é um hook

Skill é conhecimento e passos com julgamento, hook é ação determinística

Rodar o formatador depois de editar arquivo não é decisão estética, é hook 🙂

Conclusão

Se teu projeto já tem instrução visual espalhada, o próximo passo é bem concreto: abre o CLAUDE.md HOJE e tira dele tudo que é procedimento de vários passos

Esse pedaço vira a tua primeira skill de design, com mkdir -p ~/.claude/skills/nome-da-skill (ou dentro de .claude/skills/ se o time precisa herdar) e um SKILL.md com name e description bem escritos

O que sobrar no CLAUDE.md, sobra por mérito: fato curto, comando, convenção

Pra ter referência de formato, vale abrir a frontend-design no repositório anthropics/skills e ler o SKILL.md inteiro, ou instalar a versão empacotada como plugin pelo comando /plugin, que funciona no terminal e no VS Code (plugin é a camada que reúne skills, hooks, subagentes e servidores MCP numa unidade instalável, com as skills ganhando prefixo do plugin pra não conflitar)

Ah, e se você usa a gestão de memória da sessão, o comando /memory é onde dá pra ligar ou desligar a memória automática, que grava autoMemoryEnabled em ~/.claude/settings.json

Organiza uma vez, colhe em toda sessão…

até o próximo post!