---
title: "Guia prático de Rules, Skills e Agents no Claude Code"
locale: pt
category: tutorial
category_name: "Tutorial"
translation_status: reviewed
license: cc_by
author: "injoys"
source_url: https://injoys.com/en/articles/claude-code-rules-skills-agents-guide
published_at: 2026-08-19T16:14:05+09:00
---

# Guia prático de Rules, Skills e Agents no Claude Code

> No Claude Code, Rules, Skills e Agents são responsáveis, respectivamente, por instruções persistentes, procedimentos reutilizáveis e delegação isolada de tarefas. Este guia explica, com exemplos práticos, a estrutura correta dos arquivos, as formas de chamada e os princípios de segurança e gerenciamento de contexto.

## Key Points

- Crie o diretório `.claude` na raiz do projeto e diferencie o escopo das configurações compartilhadas e pessoais.
- Separe os critérios que devem ser sempre seguidos em arquivos Markdown de `.claude/rules` e, se necessário, limite os caminhos aos quais se aplicam.
- Escreva os procedimentos repetitivos em `.claude/skills/<nome>/SKILL.md` e configure a forma de chamada automática ou explícita.
- Delegue tarefas que exijam contexto e função independentes a um subagente em `.claude/agents/<nome>.md`.
- Verifique o carregamento, as permissões das ferramentas e a qualidade dos resultados com pequenas tarefas de validação antes de aplicar as alterações ao repositório da equipe.

As extensões do Claude Code não são todas do mesmo tipo de prompt. **Rules são instruções aplicadas continuamente**, **Skills são procedimentos de trabalho reutilizados repetidamente** e **Agents são executores especializados por função que trabalham em um contexto separado**. Distinguir corretamente os três recursos permite reduzir a repetição de prompts e, ao mesmo tempo, gerenciar com eficiência o contexto da conversa principal.

Este documento explica as configurações no escopo do projeto. Como os metadados ou as telas disponíveis podem variar conforme a versão do Claude Code, os campos que não funcionarem devem ser verificados novamente na documentação oficial da versão instalada.

## Etapa 1: definir o diretório `.claude` e o escopo das configurações

Rules, Skills e Agents compartilhados no projeto geralmente ficam dentro de `.claude`, na raiz do repositório.

```text
my-project/
├── .claude/
│   ├── rules/
│   │   ├── code-style.md
│   │   └── api.md
│   ├── skills/
│   │   └── fix-issue/
│   │       └── SKILL.md
│   └── agents/
│       ├── code-reviewer.md
│       └── test-runner.md
├── src/
└── package.json
```

Os diretórios podem ser criados da seguinte forma.

```bash
mkdir -p .claude/rules
mkdir -p .claude/skills/fix-issue
mkdir -p .claude/agents
```

### Dois equívocos sobre `.claude`

1. `.claude` não é obrigatório para todas as instruções do Claude Code. As instruções do projeto também podem ser gerenciadas no `CLAUDE.md` da raiz ou em `.claude/CLAUDE.md`, enquanto as configurações pessoais do usuário podem ficar em `~/.claude`, dentro do diretório inicial.
2. Dependendo do sistema operacional, nomes de arquivos diferenciam maiúsculas de minúsculas. Para seguir o formato oficial, é mais seguro criar o arquivo de entrada de uma Skill como `SKILL.md`, em letras maiúsculas. Se ele for salvo como `skill.md`, talvez não seja reconhecido.

### Critérios para escolher entre configurações de projeto e pessoais

| Escopo | Conteúdo apropriado | Exemplo |
|---|---|---|
| Compartilhado no projeto | Regras e automações que todos os colaboradores devem seguir da mesma forma | Comandos de teste, estrutura de diretórios, convenções de API |
| Pessoal do usuário | Preferências individuais ou configurações que não devem ser expostas no repositório | Forma pessoal de trabalho, escolha de ferramentas locais |
| Exclusivamente local | Caminhos ou configurações experimentais válidos apenas em um computador específico | Caminho de dados locais, procedimento temporário de depuração |

Faça commit no Git apenas dos arquivos que serão usados em conjunto pela equipe. Não registre chaves secretas, tokens nem senhas de servidores internos em Rules ou Skills.

## Etapa 2: criar instruções contínuas com Rules

Rules é um recurso para gerenciar, em vários arquivos Markdown, as instruções do projeto que Claude deve consultar durante o trabalho. Entre as regras dentro de `.claude/rules`, os arquivos sem a condição `paths` são carregados como instruções do projeto, enquanto os arquivos com condições de caminho são aplicados ao trabalhar com os arquivos relacionados.

### Exemplo de Rule básica

O arquivo `.claude/rules/code-style.md` pode ser escrito da seguinte forma.

```markdown
# Princípios de escrita de código

- Escreva o novo código da aplicação em TypeScript.
- Em funções públicas, explique os valores de entrada, os valores de retorno e as condições de falha.
- Não oculte falhas excluindo testes existentes.
- Após as alterações, execute os testes relacionados e a verificação de tipos.
- Escreva as explicações em coreano, mas siga as convenções de nomenclatura existentes para os identificadores de código.
```

Uma boa Rule pode ser verificada. “Escreva um código elegante” é menos claro do que “Após as alterações, execute `npm test` e `npm run typecheck`”.

### Rule aplicada apenas a caminhos específicos

Se as regras de frontend e backend forem diferentes, é possível restringir o escopo usando `paths` no YAML front matter.

```markdown
---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---

# Regras de API

- Valide todas as entradas da API com um esquema.
- Trate falha de autenticação e falta de permissão como erros diferentes.
- Ao alterar um endpoint, atualize também o teste de API correspondente.
```

Regras por caminho reduzem o problema de instruções desnecessárias ocuparem o contexto de todas as tarefas.

### Conteúdo que não deve ser incluído em Rules

- Procedimentos de migração que serão executados apenas uma vez
- Requisitos detalhados necessários somente para uma issue específica
- Instruções absolutas que entrem em conflito entre si
- Frases longas que repetem conteúdo já imposto pelo código ou pelas configurações do linter
- Dados sensíveis, como senhas, chaves de API e informações de clientes

Rules não são um “mecanismo mágico de garantia que sempre será seguido”. Como instruções ambíguas ou conflitantes podem gerar resultados diferentes, também é necessário usar meios determinísticos de verificação, como testes, linters e controles de permissão.

## Etapa 3: automatizar procedimentos repetitivos com Skills

Uma Skill reúne descrição, procedimento de trabalho, ferramentas necessárias e materiais auxiliares em uma única unidade reutilizável. A estrutura básica de uma Skill de projeto é `.claude/skills/<skill-name>/SKILL.md`. Se necessário, templates ou scripts podem ser adicionados ao mesmo diretório.

Diferentemente de Rules, uma Skill é usada quando necessária para uma tarefa específica. Claude pode selecioná-la automaticamente com base na descrição da Skill, ou o usuário pode chamá-la explicitamente no formato `/<skill-name>`. Ela não funciona necessariamente apenas de forma manual.

### Exemplo de Skill para corrigir uma issue

Um exemplo de `.claude/skills/fix-issue/SKILL.md` é o seguinte.

```markdown
---
name: fix-issue
description: Reproduz o bug, restringe a causa e depois realiza uma correção mínima e um teste de regressão.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)
---

# Procedimento de correção de issue

Issue em questão: $ARGUMENTS

1. Investigue o código relacionado e os testes existentes.
2. Antes da correção, organize as etapas de reprodução e o comportamento esperado.
3. Explique a causa raiz em um parágrafo.
4. Aplique a correção com o menor escopo de impacto.
5. Adicione um teste de regressão ou confirme se os testes existentes verificam o problema.
6. Execute os testes permitidos e resuma os resultados.
7. Informe os arquivos alterados, os riscos restantes e os itens que exigem verificação manual.
```

Essa Skill pode ser chamada da seguinte forma.

```text
/fix-issue Problema em que a foto do perfil não é atualizada após o login
```

`disable-model-invocation: true` é útil para impedir que Claude execute essa Skill por conta própria e limitar sua execução a chamadas diretas do usuário. Os campos de front matter disponíveis podem variar conforme a versão do Claude Code.

### Exemplo de Skill com prioridade para o design

Para criar primeiro um documento de design, em vez de começar a programar imediatamente, o seguinte fluxo pode ser incluído em uma Skill.

1. Separe os requisitos dos pontos ambíguos.
2. Investigue a estrutura existente e os módulos que podem ser reutilizados.
3. Projete o fluxo de dados, as interfaces e as condições de falha.
4. Escreva um documento de design em `docs/design/`.
5. Implemente após confirmar a aprovação do usuário ou as condições de aprovação especificadas.
6. Apresente os testes e o método de rollback.

### Características de uma boa Skill

- A entrada e o resultado final são claros.
- A ordem do procedimento e as condições de interrupção são especificadas.
- Apenas as ferramentas necessárias são permitidas.
- Materiais de referência extensos são separados em arquivos próprios.
- Em caso de falha, ela deve informar o problema em vez de continuar arbitrariamente.
- Uma única Skill não deve ter objetivos demais.

Tarefas repetitivas com início e fim claros, como criação de commits, revisão de código, verificação de releases e design de APIs, são apropriadas para uma Skill.

## Etapa 4: separar funções e contextos com Agents

Os subagentes do Claude Code desempenham funções específicas em contextos separados e retornam os resultados à conversa principal. Eles são úteis quando não se deseja acumular no contexto principal grandes volumes de resultados de busca ou logs de testes.

Os agentes do projeto geralmente são definidos em `.claude/agents/<agent-name>.md`. É possível consultar ou gerenciar agentes com o comando `/agents`, além de solicitar, em linguagem natural, que uma tarefa seja delegada a um agente específico.

### Exemplo de agente de revisão de código

O arquivo `.claude/agents/code-reviewer.md` pode ser escrito da seguinte forma.

```markdown
---
name: code-reviewer
description: Revisor focado em leitura que examina o código alterado em busca de defeitos, riscos de segurança e testes ausentes
tools: Read, Grep, Glob, Bash
model: sonnet
---

Você é um agente dedicado à revisão de código.

Faça a revisão na seguinte ordem de prioridade.

1. Defeitos que possam causar falhas reais ou perda de dados
2. Problemas de segurança relacionados a autenticação, permissões e validação de entradas
3. Problemas de concorrência, transações e tratamento de erros
4. Ausência de testes que validem os requisitos
5. Estruturas que prejudiquem significativamente a manutenibilidade

Em cada descoberta, inclua o caminho do arquivo, as evidências, as condições de ocorrência e a orientação para a correção mínima.
Não informe preferências de estilo sem fundamento como se fossem defeitos.
Não modifique o código diretamente; retorne apenas os resultados da revisão.
```

É possível fazer uma solicitação como esta.

```text
Peça ao agente code-reviewer para revisar as alterações da branch atual.
```

### Diferenças entre Skill e Agent

| Critério | Rules | Skills | Agents |
|---|---|---|---|
| Objetivo principal | Fornecer instruções contínuas | Reutilizar procedimentos repetitivos | Delegar trabalhos por função |
| Momento de aplicação | Sempre ou conforme as condições de caminho | Seleção automática ou chamada explícita | Delegação por Claude ou solicitação do usuário |
| Contexto | Incluído como instrução no trabalho principal | Executado principalmente no fluxo da tarefa atual | Executado em um contexto separado e depois retorna o resultado |
| Exemplo representativo | Padrões de programação | Procedimento de correção de issue | Revisor de código |
| Local de armazenamento | `.claude/rules/*.md` | `.claude/skills/<nome>/SKILL.md` | `.claude/agents/*.md` |

### Agents e Agent Teams são diferentes

O fato de um subagente comum usar um contexto separado não significa que os agentes possam conversar livremente entre si. Em geral, os subagentes seguem uma estrutura de delegação: realizam o trabalho atribuído e retornam o resultado ao agente principal. O recurso Agent Teams, no qual várias sessões independentes trocam mensagens entre si, é um recurso separado, e sua disponibilidade e suas condições de ativação devem ser verificadas na documentação oficial.

Projetar um fluxo de trabalho pressupondo que um agente continuará criando outros agentes em cadeia pode resultar em falhas devido a restrições de versão ou permissões. É mais seguro começar com uma estrutura simples, na qual o agente principal distribui o trabalho entre subagentes especializados por função e consolida os resultados.

## Etapa 5: verificar carregamento, permissões e qualidade

Não se deve presumir que os arquivos de configuração funcionarão conforme o esperado apenas porque foram criados. Verifique cada componente separadamente com uma tarefa pequena.

### Ordem de verificação recomendada

1. **Verificar Rules:** solicite ações em arquivos aos quais a regra se aplica e em arquivos aos quais não se aplica, para confirmar as condições de caminho.
2. **Verificar Skills:** chame explicitamente a Skill e verifique se os argumentos de entrada, os resultados e as condições de interrupção funcionam.
3. **Verificar Agents:** atribua uma tarefa de baixo risco, como uma revisão somente leitura, e verifique o formato do resultado.
4. **Verificar permissões:** confirme se ferramentas capazes de realizar alterações, como Bash e Edit, foram concedidas apenas às configurações que realmente precisam delas.
5. **Verificação automática:** confirme os resultados da AI de forma independente com testes, verificação de tipos, linter e verificações de segurança.

### Itens a verificar em caso de falha

- `.claude` está realmente na raiz do projeto?
- O nome do arquivo da Skill é exatamente `SKILL.md`?
- A Skill está na estrutura `.claude/skills/<nome>/SKILL.md`?
- O arquivo do Agent é um arquivo Markdown localizado diretamente em `.claude/agents`?
- O início e o fim do YAML front matter foram delimitados com `---`?
- `name` e `description` são específicos o suficiente para distinguir a tarefa?
- Os padrões de caminho correspondem à estrutura real do projeto?
- A versão instalada do Claude Code oferece suporte aos metadados utilizados?
- As permissões das ferramentas ou as políticas da organização estão bloqueando a execução?

## Por que o orçamento de contexto e a segurança devem ser projetados em conjunto

O objetivo de Rules, Skills e Agents não é apenas adicionar funcionalidades. Eles também são **meios de engenharia de contexto** que controlam quais informações entram no contexto e em que momento.

Se as regras forem excessivamente longas, instruções irrelevantes para a tarefa atual ocuparão o contexto e aumentarão a possibilidade de conflitos. Por outro lado, ao delegar a exploração e a análise de logs a subagentes, é possível manter apenas as conclusões e as evidências na conversa principal.

Em termos de segurança, os seguintes princípios são importantes.

- Revise Rules e Skills como qualquer outro código do repositório.
- Leia arquivos de Agent ou Skill recebidos de fontes externas antes de executá-los.
- Minimize as permissões para comandos de shell, acesso à rede e modificação de arquivos.
- Não confie incondicionalmente em comandos incluídos na entrada do usuário ou no texto de uma issue.
- Inclua uma etapa de aprovação humana para implantação, exclusão, pagamentos e migração de dados.
- Não armazene informações secretas em arquivos de prompt; use um sistema separado de gerenciamento de segredos.

## Qual recurso escolher

É possível decidir rapidamente com as seguintes perguntas.

- Todas as tarefas relacionadas devem seguir isso? → **Rule**
- É um procedimento repetitivo com início e fim? → **Skill**
- São necessários uma função separada e um contexto independente? → **Agent**
- É necessário executar um comando determinístico antes ou depois de um evento específico? → **Considerar um Hook**

Por exemplo, “usar TypeScript” é uma Rule, enquanto “executar desde a reprodução do bug até o teste de regressão” é uma Skill. “Ler as alterações e informar apenas falhas de segurança” é apropriado para um Agent. Ações vinculadas a eventos específicos, como executar obrigatoriamente um formatador após editar um arquivo, podem ser mais adequadas para Hooks.

A configuração mais estável não considera os três recursos concorrentes, mas os combina. Use uma Rule para fornecer critérios comuns, uma Skill para executar procedimentos padronizados e um Agent para separar tarefas com contextos extensos, como investigação e revisão. Em seguida, complemente a verificação determinística com testes e Hooks.

## FAQ

### A pasta `.claude` é obrigatória no Claude Code?
Ela é usada para gerenciar Rules, Skills e Agents do projeto em uma estrutura padrão, mas não é obrigatória para todas as instruções. As instruções do projeto também podem ser colocadas em `CLAUDE.md` na raiz ou em `.claude/CLAUDE.md`, e as configurações pessoais podem ser gerenciadas em `~/.claude`.

### Qual é a diferença entre Rules e `CLAUDE.md`?
O `CLAUDE.md` é adequado para fornecer as principais instruções do projeto em um único documento. Já `.claude/rules` facilita a separação de arquivos por tema e a aplicação de condições específicas por caminho, ajudando a modularizar as regras à medida que o projeto cresce.

### O nome do arquivo de Skill é `skill.md` ou `SKILL.md`?
O nome do arquivo de entrada compatível com a estrutura oficial de Agent Skills é `SKILL.md`, em letras maiúsculas. É mais seguro colocar a Skill do projeto em `.claude/skills/<skill-name>/SKILL.md`; em sistemas operacionais que diferenciam maiúsculas de minúsculas, `skill.md` é tratado como um arquivo diferente.

### Uma Skill do Claude Code só é executada quando o usuário a chama?
Nem sempre. Claude pode analisar a descrição da Skill e selecioná-la automaticamente para uma tarefa adequada, e o usuário também pode chamá-la com `/<skill-name>`. Se for necessário impedir a chamada automática, é possível considerar a configuração `disable-model-invocation` nas versões compatíveis.

### Devo usar uma Skill ou um Agent?
Uma Skill é adequada para executar procedimentos repetitivos no fluxo de trabalho atual. Um Agent é adequado quando são necessários uma função separada e um contexto isolado, como em pesquisas em grande escala, análise de testes ou revisão de código. Conteúdos que devem ser aplicados continuamente, como padrões comuns de codificação, devem ser separados em uma Rule.

### Os subagentes podem conversar diretamente entre si ou chamar outros agentes?
Os subagentes comuns do Claude Code trabalham em contextos separados e depois retornam os resultados ao agente principal. A colaboração direta entre várias sessões independentes deve ser diferenciada do recurso separado Agent Teams, e é necessário verificar a disponibilidade e as limitações na versão em uso.

### Ao criar Rules, Claude sempre seguirá as instruções perfeitamente?
Não. Rules são instruções fornecidas continuamente, mas não constituem um mecanismo de imposição determinístico. Elas podem ser ignoradas devido a conflitos ou ambiguidades nas instruções, portanto devem ser usadas em conjunto com linters, verificação de tipos, testes, Hooks e revisão de código.

### É seguro usar imediatamente uma Skill ou um Agent obtido externamente?
É melhor não executá-los imediatamente. Primeiro, é necessário revisar as instruções, os comandos de shell, as ferramentas permitidas e o escopo de acesso à rede e aos arquivos incluídos nos arquivos, e testá-los com privilégios mínimos. Também é necessário verificar se não há conteúdo que induza ao envio de informações secretas ou a alterações perigosas em arquivos.

## Sources

- [Documentação do Claude Code: Gerencie a memória do Claude](https://code.claude.com/docs/en/memory)
- [Documentação do Claude Code: Amplie o Claude com habilidades](https://code.claude.com/docs/en/skills)
- [Documentação do Claude Code: Crie subagentes personalizados](https://code.claude.com/docs/en/sub-agents)
- [Documentação do Claude Code: Configurações do Claude Code](https://code.claude.com/docs/en/settings)

## Images

![Pessoa visualizando um painel de fluxo de desenvolvimento em um notebook](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgyOSwicHVyIjoiYmxvYl9pZCJ9fQ==--8ba3d33d24232863ea1d744998bca1e2dbb088c6/ai-7c680af1.webp)
![Diagrama de fluxo com pastas, filtros, automação, ambiente de IA, segurança e validação](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgzNSwicHVyIjoiYmxvYl9pZCJ9fQ==--458d876e5a3cb0d4581f0909c6198e47789eda8b/ai-54d6eb4e.webp)