Lição 7 de 10: Rules e skills

Esta lição é decisão antes de código.

Duas coisas concretas pra ancorar antes do modelo mental

Antes do mapa de 4 buckets, olha uma rule realArquivo na pasta .claude/rules/ que descreve uma constraint sempre-ligada (ex: nunca commitar .env). Vale em toda sessão, sem precisar invocar. Diferente de skill, que é workflow condicional. e uma skill realArquivo SKILL.md numa subpasta de .claude/skills/ que descreve um workflow reutilizável (ex: como fazer deploy). O Claude carrega e usa quando reconhece o trigger no description:. Diferente de rule, que vale sempre. do Starter.

A rule starter/.claude/rules/no-secrets-in-claude-md.md abre assim:

Secrets em arquivos versionados é um vazamento permanente — Git history nunca esquece. Esta rule existe porque um projeto real vazou um Upstash token em .claude/settings.local.json antes desta rule existir. Não repita.

Quatro coisas a notar: (1) frase única de contexto, (2) seção ## What NEVER goes ... listando o anti-padrão, (3) seção ## Where secrets DO go listando o padrão correto, (4) rule curta, de uma página. Ela vale em toda sessão, sem você precisar invocar.

A skill starter/.claude/skills/plan-then-work/SKILL.md abre com este frontmatter:

---
name: plan-then-work
description: The Builder OS signature workflow. Write a markdown plan
  in plans/ first, then execute it. Use whenever the user asks for a
  non-trivial change — anything touching ≥2 files, introducing a new
  dependency, changing a schema, or adding a new route. Do NOT plan
  one-line tweaks.
---

O description: é o triggerA frase que faz o Claude reconhecer quando uma skill se aplica e decidir carregá-la naquela conversa. Trigger ruim = skill que dispara na hora errada ou nunca dispara.: a frase que o Claude lê e usa pra decidir se carrega a skill naquela conversa. Skills só rodam quando o trigger bate. Rules valem o tempo todo.

Essa é a categoria-mãe: rules são sempre-ligadas; skills são condicionais.

Mapa de decisão 2x2: política vs procedimento × sempre-ligado vs condicional, com os 4 buckets resultantesGrid 2x2 mostrando 4 buckets de configuração do Claude Code: Rule (política sempre-ligada), Skill (procedimento condicional), e os 2 quadrantes auxiliares. Cada bucket tem nome + descrição curta + exemplo de arquivo real.

Os 4 buckets: onde cada decisão mora

O template já vem com 3 rules e 5 skills

Antes de criar uma rule nova, vale ver o que o template já trouxe. Assim você não duplica nada e já pega o estilo certo.

Cole no Claude:

Liste em duas colunas: as rules em `.claude/rules/` e as skills em `.claude/skills/` deste projeto. Pra cada uma, dê uma frase explicando o que ela define.

A resposta deve mencionar:

• Rules (3): bilingual-content (idiomas por superfície), no-secrets-in-claude-md (sem secrets em arquivos versionados), plan-lifecycle (fluxo de planos).
• Skills (5): commit-and-pr, getting-started, nextjs-react, plan-then-work, ui-design.

Pede o conteúdo completo de uma delas pra pegar o estilo:

Mostre o conteúdo completo de `.claude/rules/no-secrets-in-claude-md.md` aqui no chat pra eu ver a forma de uma rule do template.

Repare na anatomia que já vimos no abre da lição: contexto curto, ## What NEVER goes ..., ## Where ... DO go, e, quando faz sentido, o incidente real que motivou a rule.

Crie sua primeira rule custom

Agora você vai adicionar uma rule própria. Três candidatas que valem pra quase todo produto brasileiro:

Preencha o campo abaixo com a rule que você escolheu:

Crie uma nova rule em `.claude/rules/[NOME_DO_ARQUIVO].md` que codifica esta decisão:

> [REGRA_QUE_VOU_ADICIONAR]

Siga o estilo das rules existentes em `.claude/rules/`:
- Título H1 curto.
- 1-2 frases de contexto explicando o que a rule define.
- Seção `## What NEVER goes ...` ou equivalente listando o anti-padrão.
- Seção `## Where it DOES go` listando o padrão correto, com exemplo de código quando fizer sentido.
- Seção `## Why this matters` (opcional, se houver razão concreta — incidente, custo, regulação).

Mantenha curto: máximo 1 página. Mostre o diff antes de criar o arquivo.

O Claude vai propor o conteúdo num diff. Aprova com y se o estilo bate; refina se não bater.

Faça um commit que usa a rule

Uma rule que nenhum commit referencia não tem como provar que está moldando o trabalho. Agora você vai fazer um trabalho invocando a rule que acabou de criar.

Implemente um helper pequeno que aplica a rule que acabamos de adicionar em `.claude/rules/[NOME_DO_ARQUIVO].md`.

Decida onde o helper mora (provavelmente `src/lib/`), use TypeScript strict, e exporte uma função pequena. Adicione 2-3 exemplos de uso no final do arquivo, em comentários (`// formatBrDate(new Date('2026-01-15')) → '15/01/2026'`).

Depois faça commit em duas etapas separadas:

Etapa 1 — só a rule:
`git add .claude/rules/[NOME_DO_ARQUIVO].md` + commit com mensagem `feat(rules): add [NOME_DO_ARQUIVO] rule`.

Etapa 2 — só o código:
`git add` do código + commit cuja mensagem referencia a rule explicitamente no body. A mensagem deve ser uma linha de subject (`feat(lib): add formatBrDate helper`), uma linha em branco, e o body (`Applies .claude/rules/[NOME_DO_ARQUIVO].md.`).

Mostra o diff e os comandos antes de executar cada etapa.

O Claude vai pedir aprovação pra cada git add e cada git commit. Aprova passo a passo.

A prova: pergunte ao Claude qual rule vale

Mesma estrutura da lição 05: fecha o Claude (Ctrl+D no terminal, ou fecha o painel/janela). Reabre. Cola:

Estou prestes a implementar uma feature que envolve [REGRA_QUE_VOU_ADICIONAR]. Qual rule deste projeto eu preciso respeitar?

A resposta deve referenciar .claude/rules/{{NOME_DO_ARQUIVO}}.md pelo nome, porque o Claude releu as rules na nova sessão e a sua acabou de entrar no conjunto.

E as skills?

Você não vai criar uma skill nesta lição, porque skills são mais difíceis de escrever bem que rules. O description: do frontmatter funciona como gatilho: ele precisa descrever quando a skill é relevante de um jeito que dispare nos pedidos certos sem disparar em todos. O Módulo 5 trata disso ao empacotar suas skills num plugin, onde o namespace (/<plugin>:<skill>) resolve a colisão de nomes que antes você contornava na mão.

Por enquanto, fica com o exercício mental: olhe as 5 skills do template que você listou no início. Pra cada uma, identifique:

• Qual é o trigger (o description: do frontmatter)?
• Qual é o trabalho que ela executa (as etapas concretas)?

Se você notar um workflow que repete em prompts seus ("toda vez que adiciono uma tabela no Postgres, sempre preciso de migration + seed + zod schema juntos"), anota. Vai virar sua primeira skill custom no Módulo 5.

Takeaways

• Rules são sempre-ligadas; skills são condicionais (o description: do frontmatter é o trigger).
• 4 buckets pra decidir onde decisão mora: rule (constraint), skill (workflow com trigger), CLAUDE.md (contexto/domínio), comentário no código (decisão local).
• Anatomia de rule curta: contexto de 1 frase, ## What NEVER ..., ## Where ... DO go, e, quando houver, o incidente real que motivou.
• O commit em duas etapas (rule, depois código que a aplica) prova que a rule já está moldando o trabalho, em vez de só existir no diretório.

Confirma que deu certo