{"content_id":"9bufu7fxqw","slug":"claude-code-rules-skills-agents-guide","locale":"pt","schema_type":"HowTo","category":"tutorial","category_name":"Tutorial","title":"Guia prático de Rules, Skills e Agents no Claude Code","summary":"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.","sponsorship_disclosure":null,"author":{"name":"injoys","url":"https://injoys.com/ko/about"},"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/\u003cnome\u003e/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/\u003cnome\u003e.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."],"content_markdown":"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.\n\nEste 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.\n\n## Etapa 1: definir o diretório `.claude` e o escopo das configurações\n\nRules, Skills e Agents compartilhados no projeto geralmente ficam dentro de `.claude`, na raiz do repositório.\n\n```text\nmy-project/\n├── .claude/\n│   ├── rules/\n│   │   ├── code-style.md\n│   │   └── api.md\n│   ├── skills/\n│   │   └── fix-issue/\n│   │       └── SKILL.md\n│   └── agents/\n│       ├── code-reviewer.md\n│       └── test-runner.md\n├── src/\n└── package.json\n```\n\nOs diretórios podem ser criados da seguinte forma.\n\n```bash\nmkdir -p .claude/rules\nmkdir -p .claude/skills/fix-issue\nmkdir -p .claude/agents\n```\n\n### Dois equívocos sobre `.claude`\n\n1. `.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.\n2. 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.\n\n### Critérios para escolher entre configurações de projeto e pessoais\n\n| Escopo | Conteúdo apropriado | Exemplo |\n|---|---|---|\n| 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 |\n| 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 |\n| 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 |\n\nFaç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.\n\n## Etapa 2: criar instruções contínuas com Rules\n\nRules é 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.\n\n### Exemplo de Rule básica\n\nO arquivo `.claude/rules/code-style.md` pode ser escrito da seguinte forma.\n\n```markdown\n# Princípios de escrita de código\n\n- Escreva o novo código da aplicação em TypeScript.\n- Em funções públicas, explique os valores de entrada, os valores de retorno e as condições de falha.\n- Não oculte falhas excluindo testes existentes.\n- Após as alterações, execute os testes relacionados e a verificação de tipos.\n- Escreva as explicações em coreano, mas siga as convenções de nomenclatura existentes para os identificadores de código.\n```\n\nUma 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`”.\n\n### Rule aplicada apenas a caminhos específicos\n\nSe as regras de frontend e backend forem diferentes, é possível restringir o escopo usando `paths` no YAML front matter.\n\n```markdown\n---\npaths:\n  - \"src/api/**/*.ts\"\n  - \"tests/api/**/*.ts\"\n---\n\n# Regras de API\n\n- Valide todas as entradas da API com um esquema.\n- Trate falha de autenticação e falta de permissão como erros diferentes.\n- Ao alterar um endpoint, atualize também o teste de API correspondente.\n```\n\nRegras por caminho reduzem o problema de instruções desnecessárias ocuparem o contexto de todas as tarefas.\n\n### Conteúdo que não deve ser incluído em Rules\n\n- Procedimentos de migração que serão executados apenas uma vez\n- Requisitos detalhados necessários somente para uma issue específica\n- Instruções absolutas que entrem em conflito entre si\n- Frases longas que repetem conteúdo já imposto pelo código ou pelas configurações do linter\n- Dados sensíveis, como senhas, chaves de API e informações de clientes\n\nRules 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.\n\n## Etapa 3: automatizar procedimentos repetitivos com Skills\n\nUma 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/\u003cskill-name\u003e/SKILL.md`. Se necessário, templates ou scripts podem ser adicionados ao mesmo diretório.\n\nDiferentemente 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 `/\u003cskill-name\u003e`. Ela não funciona necessariamente apenas de forma manual.\n\n### Exemplo de Skill para corrigir uma issue\n\nUm exemplo de `.claude/skills/fix-issue/SKILL.md` é o seguinte.\n\n```markdown\n---\nname: fix-issue\ndescription: Reproduz o bug, restringe a causa e depois realiza uma correção mínima e um teste de regressão.\ndisable-model-invocation: true\nallowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)\n---\n\n# Procedimento de correção de issue\n\nIssue em questão: $ARGUMENTS\n\n1. Investigue o código relacionado e os testes existentes.\n2. Antes da correção, organize as etapas de reprodução e o comportamento esperado.\n3. Explique a causa raiz em um parágrafo.\n4. Aplique a correção com o menor escopo de impacto.\n5. Adicione um teste de regressão ou confirme se os testes existentes verificam o problema.\n6. Execute os testes permitidos e resuma os resultados.\n7. Informe os arquivos alterados, os riscos restantes e os itens que exigem verificação manual.\n```\n\nEssa Skill pode ser chamada da seguinte forma.\n\n```text\n/fix-issue Problema em que a foto do perfil não é atualizada após o login\n```\n\n`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.\n\n### Exemplo de Skill com prioridade para o design\n\nPara criar primeiro um documento de design, em vez de começar a programar imediatamente, o seguinte fluxo pode ser incluído em uma Skill.\n\n1. Separe os requisitos dos pontos ambíguos.\n2. Investigue a estrutura existente e os módulos que podem ser reutilizados.\n3. Projete o fluxo de dados, as interfaces e as condições de falha.\n4. Escreva um documento de design em `docs/design/`.\n5. Implemente após confirmar a aprovação do usuário ou as condições de aprovação especificadas.\n6. Apresente os testes e o método de rollback.\n\n### Características de uma boa Skill\n\n- A entrada e o resultado final são claros.\n- A ordem do procedimento e as condições de interrupção são especificadas.\n- Apenas as ferramentas necessárias são permitidas.\n- Materiais de referência extensos são separados em arquivos próprios.\n- Em caso de falha, ela deve informar o problema em vez de continuar arbitrariamente.\n- Uma única Skill não deve ter objetivos demais.\n\nTarefas 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.\n\n## Etapa 4: separar funções e contextos com Agents\n\nOs 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.\n\nOs agentes do projeto geralmente são definidos em `.claude/agents/\u003cagent-name\u003e.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.\n\n### Exemplo de agente de revisão de código\n\nO arquivo `.claude/agents/code-reviewer.md` pode ser escrito da seguinte forma.\n\n```markdown\n---\nname: code-reviewer\ndescription: Revisor focado em leitura que examina o código alterado em busca de defeitos, riscos de segurança e testes ausentes\ntools: Read, Grep, Glob, Bash\nmodel: sonnet\n---\n\nVocê é um agente dedicado à revisão de código.\n\nFaça a revisão na seguinte ordem de prioridade.\n\n1. Defeitos que possam causar falhas reais ou perda de dados\n2. Problemas de segurança relacionados a autenticação, permissões e validação de entradas\n3. Problemas de concorrência, transações e tratamento de erros\n4. Ausência de testes que validem os requisitos\n5. Estruturas que prejudiquem significativamente a manutenibilidade\n\nEm 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.\nNão informe preferências de estilo sem fundamento como se fossem defeitos.\nNão modifique o código diretamente; retorne apenas os resultados da revisão.\n```\n\nÉ possível fazer uma solicitação como esta.\n\n```text\nPeça ao agente code-reviewer para revisar as alterações da branch atual.\n```\n\n### Diferenças entre Skill e Agent\n\n| Critério | Rules | Skills | Agents |\n|---|---|---|---|\n| Objetivo principal | Fornecer instruções contínuas | Reutilizar procedimentos repetitivos | Delegar trabalhos por função |\n| 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 |\n| 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 |\n| Exemplo representativo | Padrões de programação | Procedimento de correção de issue | Revisor de código |\n| Local de armazenamento | `.claude/rules/*.md` | `.claude/skills/\u003cnome\u003e/SKILL.md` | `.claude/agents/*.md` |\n\n### Agents e Agent Teams são diferentes\n\nO 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.\n\nProjetar 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.\n\n## Etapa 5: verificar carregamento, permissões e qualidade\n\nNã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.\n\n### Ordem de verificação recomendada\n\n1. **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.\n2. **Verificar Skills:** chame explicitamente a Skill e verifique se os argumentos de entrada, os resultados e as condições de interrupção funcionam.\n3. **Verificar Agents:** atribua uma tarefa de baixo risco, como uma revisão somente leitura, e verifique o formato do resultado.\n4. **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.\n5. **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.\n\n### Itens a verificar em caso de falha\n\n- `.claude` está realmente na raiz do projeto?\n- O nome do arquivo da Skill é exatamente `SKILL.md`?\n- A Skill está na estrutura `.claude/skills/\u003cnome\u003e/SKILL.md`?\n- O arquivo do Agent é um arquivo Markdown localizado diretamente em `.claude/agents`?\n- O início e o fim do YAML front matter foram delimitados com `---`?\n- `name` e `description` são específicos o suficiente para distinguir a tarefa?\n- Os padrões de caminho correspondem à estrutura real do projeto?\n- A versão instalada do Claude Code oferece suporte aos metadados utilizados?\n- As permissões das ferramentas ou as políticas da organização estão bloqueando a execução?\n\n## Por que o orçamento de contexto e a segurança devem ser projetados em conjunto\n\nO 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.\n\nSe 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.\n\nEm termos de segurança, os seguintes princípios são importantes.\n\n- Revise Rules e Skills como qualquer outro código do repositório.\n- Leia arquivos de Agent ou Skill recebidos de fontes externas antes de executá-los.\n- Minimize as permissões para comandos de shell, acesso à rede e modificação de arquivos.\n- Não confie incondicionalmente em comandos incluídos na entrada do usuário ou no texto de uma issue.\n- Inclua uma etapa de aprovação humana para implantação, exclusão, pagamentos e migração de dados.\n- Não armazene informações secretas em arquivos de prompt; use um sistema separado de gerenciamento de segredos.\n\n## Qual recurso escolher\n\nÉ possível decidir rapidamente com as seguintes perguntas.\n\n- Todas as tarefas relacionadas devem seguir isso? → **Rule**\n- É um procedimento repetitivo com início e fim? → **Skill**\n- São necessários uma função separada e um contexto independente? → **Agent**\n- É necessário executar um comando determinístico antes ou depois de um evento específico? → **Considerar um Hook**\n\nPor 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.\n\nA 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.","content_html":"\u003cp\u003eAs extensões do Claude Code não são todas do mesmo tipo de prompt. \u003cstrong\u003eRules são instruções aplicadas continuamente\u003c/strong\u003e, \u003cstrong\u003eSkills são procedimentos de trabalho reutilizados repetidamente\u003c/strong\u003e e \u003cstrong\u003eAgents são executores especializados por função que trabalham em um contexto separado\u003c/strong\u003e. 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.\u003c/p\u003e\n\u003cp\u003eEste 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.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#etapa-1-definir-o-diret%C3%B3rio-claude-e-o-escopo-das-configura%C3%A7%C3%B5es\" class=\"anchor\" id=\"etapa-1-definir-o-diretório-claude-e-o-escopo-das-configurações\"\u003e\u003c/a\u003eEtapa 1: definir o diretório \u003ccode\u003e.claude\u003c/code\u003e e o escopo das configurações\u003c/h2\u003e\n\u003cp\u003eRules, Skills e Agents compartilhados no projeto geralmente ficam dentro de \u003ccode\u003e.claude\u003c/code\u003e, na raiz do repositório.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003emy-project/\n\u003c/span\u003e\u003cspan\u003e├── .claude/\n\u003c/span\u003e\u003cspan\u003e│   ├── rules/\n\u003c/span\u003e\u003cspan\u003e│   │   ├── code-style.md\n\u003c/span\u003e\u003cspan\u003e│   │   └── api.md\n\u003c/span\u003e\u003cspan\u003e│   ├── skills/\n\u003c/span\u003e\u003cspan\u003e│   │   └── fix-issue/\n\u003c/span\u003e\u003cspan\u003e│   │       └── SKILL.md\n\u003c/span\u003e\u003cspan\u003e│   └── agents/\n\u003c/span\u003e\u003cspan\u003e│       ├── code-reviewer.md\n\u003c/span\u003e\u003cspan\u003e│       └── test-runner.md\n\u003c/span\u003e\u003cspan\u003e├── src/\n\u003c/span\u003e\u003cspan\u003e└── package.json\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eOs diretórios podem ser criados da seguinte forma.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/rules\n\u003c/span\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/skills/fix-issue\n\u003c/span\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/agents\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#dois-equ%C3%ADvocos-sobre-claude\" class=\"anchor\" id=\"dois-equívocos-sobre-claude\"\u003e\u003c/a\u003eDois equívocos sobre \u003ccode\u003e.claude\u003c/code\u003e\n\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003ccode\u003e.claude\u003c/code\u003e não é obrigatório para todas as instruções do Claude Code. As instruções do projeto também podem ser gerenciadas no \u003ccode\u003eCLAUDE.md\u003c/code\u003e da raiz ou em \u003ccode\u003e.claude/CLAUDE.md\u003c/code\u003e, enquanto as configurações pessoais do usuário podem ficar em \u003ccode\u003e~/.claude\u003c/code\u003e, dentro do diretório inicial.\u003c/li\u003e\n\u003cli\u003eDependendo 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 \u003ccode\u003eSKILL.md\u003c/code\u003e, em letras maiúsculas. Se ele for salvo como \u003ccode\u003eskill.md\u003c/code\u003e, talvez não seja reconhecido.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#crit%C3%A9rios-para-escolher-entre-configura%C3%A7%C3%B5es-de-projeto-e-pessoais\" class=\"anchor\" id=\"critérios-para-escolher-entre-configurações-de-projeto-e-pessoais\"\u003e\u003c/a\u003eCritérios para escolher entre configurações de projeto e pessoais\u003c/h3\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eEscopo\u003c/th\u003e\n\u003cth\u003eConteúdo apropriado\u003c/th\u003e\n\u003cth\u003eExemplo\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Escopo\"\u003eCompartilhado no projeto\u003c/td\u003e\n\u003ctd data-label=\"Conteúdo apropriado\"\u003eRegras e automações que todos os colaboradores devem seguir da mesma forma\u003c/td\u003e\n\u003ctd data-label=\"Exemplo\"\u003eComandos de teste, estrutura de diretórios, convenções de API\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Escopo\"\u003ePessoal do usuário\u003c/td\u003e\n\u003ctd data-label=\"Conteúdo apropriado\"\u003ePreferências individuais ou configurações que não devem ser expostas no repositório\u003c/td\u003e\n\u003ctd data-label=\"Exemplo\"\u003eForma pessoal de trabalho, escolha de ferramentas locais\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Escopo\"\u003eExclusivamente local\u003c/td\u003e\n\u003ctd data-label=\"Conteúdo apropriado\"\u003eCaminhos ou configurações experimentais válidos apenas em um computador específico\u003c/td\u003e\n\u003ctd data-label=\"Exemplo\"\u003eCaminho de dados locais, procedimento temporário de depuração\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eFaç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.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#etapa-2-criar-instru%C3%A7%C3%B5es-cont%C3%ADnuas-com-rules\" class=\"anchor\" id=\"etapa-2-criar-instruções-contínuas-com-rules\"\u003e\u003c/a\u003eEtapa 2: criar instruções contínuas com Rules\u003c/h2\u003e\n\u003cp\u003eRules é 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 \u003ccode\u003e.claude/rules\u003c/code\u003e, os arquivos sem a condição \u003ccode\u003epaths\u003c/code\u003e 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.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#exemplo-de-rule-b%C3%A1sica\" class=\"anchor\" id=\"exemplo-de-rule-básica\"\u003e\u003c/a\u003eExemplo de Rule básica\u003c/h3\u003e\n\u003cp\u003eO arquivo \u003ccode\u003e.claude/rules/code-style.md\u003c/code\u003e pode ser escrito da seguinte forma.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e# Princípios de escrita de código\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e- Escreva o novo código da aplicação em TypeScript.\n\u003c/span\u003e\u003cspan\u003e- Em funções públicas, explique os valores de entrada, os valores de retorno e as condições de falha.\n\u003c/span\u003e\u003cspan\u003e- Não oculte falhas excluindo testes existentes.\n\u003c/span\u003e\u003cspan\u003e- Após as alterações, execute os testes relacionados e a verificação de tipos.\n\u003c/span\u003e\u003cspan\u003e- Escreva as explicações em coreano, mas siga as convenções de nomenclatura existentes para os identificadores de código.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eUma boa Rule pode ser verificada. “Escreva um código elegante” é menos claro do que “Após as alterações, execute \u003ccode\u003enpm test\u003c/code\u003e e \u003ccode\u003enpm run typecheck\u003c/code\u003e”.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#rule-aplicada-apenas-a-caminhos-espec%C3%ADficos\" class=\"anchor\" id=\"rule-aplicada-apenas-a-caminhos-específicos\"\u003e\u003c/a\u003eRule aplicada apenas a caminhos específicos\u003c/h3\u003e\n\u003cp\u003eSe as regras de frontend e backend forem diferentes, é possível restringir o escopo usando \u003ccode\u003epaths\u003c/code\u003e no YAML front matter.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003epaths:\n\u003c/span\u003e\u003cspan\u003e  - \"src/api/\u003c/span\u003e\u003cspan\u003e**/\u003c/span\u003e\u003cspan\u003e*.ts\"\n\u003c/span\u003e\u003cspan\u003e  - \"tests/api/\u003c/span\u003e\u003cspan\u003e**/\u003c/span\u003e\u003cspan\u003e*.ts\"\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e# Regras de API\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e- Valide todas as entradas da API com um esquema.\n\u003c/span\u003e\u003cspan\u003e- Trate falha de autenticação e falta de permissão como erros diferentes.\n\u003c/span\u003e\u003cspan\u003e- Ao alterar um endpoint, atualize também o teste de API correspondente.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eRegras por caminho reduzem o problema de instruções desnecessárias ocuparem o contexto de todas as tarefas.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#conte%C3%BAdo-que-n%C3%A3o-deve-ser-inclu%C3%ADdo-em-rules\" class=\"anchor\" id=\"conteúdo-que-não-deve-ser-incluído-em-rules\"\u003e\u003c/a\u003eConteúdo que não deve ser incluído em Rules\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eProcedimentos de migração que serão executados apenas uma vez\u003c/li\u003e\n\u003cli\u003eRequisitos detalhados necessários somente para uma issue específica\u003c/li\u003e\n\u003cli\u003eInstruções absolutas que entrem em conflito entre si\u003c/li\u003e\n\u003cli\u003eFrases longas que repetem conteúdo já imposto pelo código ou pelas configurações do linter\u003c/li\u003e\n\u003cli\u003eDados sensíveis, como senhas, chaves de API e informações de clientes\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eRules 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.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#etapa-3-automatizar-procedimentos-repetitivos-com-skills\" class=\"anchor\" id=\"etapa-3-automatizar-procedimentos-repetitivos-com-skills\"\u003e\u003c/a\u003eEtapa 3: automatizar procedimentos repetitivos com Skills\u003c/h2\u003e\n\u003cp\u003eUma 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 é \u003ccode\u003e.claude/skills/\u0026lt;skill-name\u0026gt;/SKILL.md\u003c/code\u003e. Se necessário, templates ou scripts podem ser adicionados ao mesmo diretório.\u003c/p\u003e\n\u003cp\u003eDiferentemente 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 \u003ccode\u003e/\u0026lt;skill-name\u0026gt;\u003c/code\u003e. Ela não funciona necessariamente apenas de forma manual.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#exemplo-de-skill-para-corrigir-uma-issue\" class=\"anchor\" id=\"exemplo-de-skill-para-corrigir-uma-issue\"\u003e\u003c/a\u003eExemplo de Skill para corrigir uma issue\u003c/h3\u003e\n\u003cp\u003eUm exemplo de \u003ccode\u003e.claude/skills/fix-issue/SKILL.md\u003c/code\u003e é o seguinte.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003ename: fix-issue\n\u003c/span\u003e\u003cspan\u003edescription: Reproduz o bug, restringe a causa e depois realiza uma correção mínima e um teste de regressão.\n\u003c/span\u003e\u003cspan\u003edisable-model-invocation: true\n\u003c/span\u003e\u003cspan\u003eallowed-tools: Read, Grep, Glob, Edit, Bash(npm test:\u003c/span\u003e\u003cspan\u003e*)\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e# Procedimento de correção de issue\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eIssue em questão: $ARGUMENTS\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e1. Investigue o código relacionado e os testes existentes.\n\u003c/span\u003e\u003cspan\u003e2. Antes da correção, organize as etapas de reprodução e o comportamento esperado.\n\u003c/span\u003e\u003cspan\u003e3. Explique a causa raiz em um parágrafo.\n\u003c/span\u003e\u003cspan\u003e4. Aplique a correção com o menor escopo de impacto.\n\u003c/span\u003e\u003cspan\u003e5. Adicione um teste de regressão ou confirme se os testes existentes verificam o problema.\n\u003c/span\u003e\u003cspan\u003e6. Execute os testes permitidos e resuma os resultados.\n\u003c/span\u003e\u003cspan\u003e7. Informe os arquivos alterados, os riscos restantes e os itens que exigem verificação manual.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eEssa Skill pode ser chamada da seguinte forma.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e/fix-issue Problema em que a foto do perfil não é atualizada após o login\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e\u003ccode\u003edisable-model-invocation: true\u003c/code\u003e é ú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.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#exemplo-de-skill-com-prioridade-para-o-design\" class=\"anchor\" id=\"exemplo-de-skill-com-prioridade-para-o-design\"\u003e\u003c/a\u003eExemplo de Skill com prioridade para o design\u003c/h3\u003e\n\u003cp\u003ePara criar primeiro um documento de design, em vez de começar a programar imediatamente, o seguinte fluxo pode ser incluído em uma Skill.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003eSepare os requisitos dos pontos ambíguos.\u003c/li\u003e\n\u003cli\u003eInvestigue a estrutura existente e os módulos que podem ser reutilizados.\u003c/li\u003e\n\u003cli\u003eProjete o fluxo de dados, as interfaces e as condições de falha.\u003c/li\u003e\n\u003cli\u003eEscreva um documento de design em \u003ccode\u003edocs/design/\u003c/code\u003e.\u003c/li\u003e\n\u003cli\u003eImplemente após confirmar a aprovação do usuário ou as condições de aprovação especificadas.\u003c/li\u003e\n\u003cli\u003eApresente os testes e o método de rollback.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#caracter%C3%ADsticas-de-uma-boa-skill\" class=\"anchor\" id=\"características-de-uma-boa-skill\"\u003e\u003c/a\u003eCaracterísticas de uma boa Skill\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eA entrada e o resultado final são claros.\u003c/li\u003e\n\u003cli\u003eA ordem do procedimento e as condições de interrupção são especificadas.\u003c/li\u003e\n\u003cli\u003eApenas as ferramentas necessárias são permitidas.\u003c/li\u003e\n\u003cli\u003eMateriais de referência extensos são separados em arquivos próprios.\u003c/li\u003e\n\u003cli\u003eEm caso de falha, ela deve informar o problema em vez de continuar arbitrariamente.\u003c/li\u003e\n\u003cli\u003eUma única Skill não deve ter objetivos demais.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eTarefas 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.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#etapa-4-separar-fun%C3%A7%C3%B5es-e-contextos-com-agents\" class=\"anchor\" id=\"etapa-4-separar-funções-e-contextos-com-agents\"\u003e\u003c/a\u003eEtapa 4: separar funções e contextos com Agents\u003c/h2\u003e\n\u003cp\u003eOs 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.\u003c/p\u003e\n\u003cp\u003eOs agentes do projeto geralmente são definidos em \u003ccode\u003e.claude/agents/\u0026lt;agent-name\u0026gt;.md\u003c/code\u003e. É possível consultar ou gerenciar agentes com o comando \u003ccode\u003e/agents\u003c/code\u003e, além de solicitar, em linguagem natural, que uma tarefa seja delegada a um agente específico.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#exemplo-de-agente-de-revis%C3%A3o-de-c%C3%B3digo\" class=\"anchor\" id=\"exemplo-de-agente-de-revisão-de-código\"\u003e\u003c/a\u003eExemplo de agente de revisão de código\u003c/h3\u003e\n\u003cp\u003eO arquivo \u003ccode\u003e.claude/agents/code-reviewer.md\u003c/code\u003e pode ser escrito da seguinte forma.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003ename: code-reviewer\n\u003c/span\u003e\u003cspan\u003edescription: Revisor focado em leitura que examina o código alterado em busca de defeitos, riscos de segurança e testes ausentes\n\u003c/span\u003e\u003cspan\u003etools: Read, Grep, Glob, Bash\n\u003c/span\u003e\u003cspan\u003emodel: sonnet\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eVocê é um agente dedicado à revisão de código.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eFaça a revisão na seguinte ordem de prioridade.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e1. Defeitos que possam causar falhas reais ou perda de dados\n\u003c/span\u003e\u003cspan\u003e2. Problemas de segurança relacionados a autenticação, permissões e validação de entradas\n\u003c/span\u003e\u003cspan\u003e3. Problemas de concorrência, transações e tratamento de erros\n\u003c/span\u003e\u003cspan\u003e4. Ausência de testes que validem os requisitos\n\u003c/span\u003e\u003cspan\u003e5. Estruturas que prejudiquem significativamente a manutenibilidade\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003eEm 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\u003c/span\u003e\u003cspan\u003eNão informe preferências de estilo sem fundamento como se fossem defeitos.\n\u003c/span\u003e\u003cspan\u003eNão modifique o código diretamente; retorne apenas os resultados da revisão.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eÉ possível fazer uma solicitação como esta.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003ePeça ao agente code-reviewer para revisar as alterações da branch atual.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#diferen%C3%A7as-entre-skill-e-agent\" class=\"anchor\" id=\"diferenças-entre-skill-e-agent\"\u003e\u003c/a\u003eDiferenças entre Skill e Agent\u003c/h3\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eCritério\u003c/th\u003e\n\u003cth\u003eRules\u003c/th\u003e\n\u003cth\u003eSkills\u003c/th\u003e\n\u003cth\u003eAgents\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Critério\"\u003eObjetivo principal\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003eFornecer instruções contínuas\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003eReutilizar procedimentos repetitivos\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003eDelegar trabalhos por função\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Critério\"\u003eMomento de aplicação\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003eSempre ou conforme as condições de caminho\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003eSeleção automática ou chamada explícita\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003eDelegação por Claude ou solicitação do usuário\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Critério\"\u003eContexto\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003eIncluído como instrução no trabalho principal\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003eExecutado principalmente no fluxo da tarefa atual\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003eExecutado em um contexto separado e depois retorna o resultado\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Critério\"\u003eExemplo representativo\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003ePadrões de programação\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003eProcedimento de correção de issue\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003eRevisor de código\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Critério\"\u003eLocal de armazenamento\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e\u003ccode\u003e.claude/rules/*.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e\u003ccode\u003e.claude/skills/\u0026lt;nome\u0026gt;/SKILL.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003e\u003ccode\u003e.claude/agents/*.md\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003ch3\u003e\n\u003ca href=\"#agents-e-agent-teams-s%C3%A3o-diferentes\" class=\"anchor\" id=\"agents-e-agent-teams-são-diferentes\"\u003e\u003c/a\u003eAgents e Agent Teams são diferentes\u003c/h3\u003e\n\u003cp\u003eO 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.\u003c/p\u003e\n\u003cp\u003eProjetar 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.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#etapa-5-verificar-carregamento-permiss%C3%B5es-e-qualidade\" class=\"anchor\" id=\"etapa-5-verificar-carregamento-permissões-e-qualidade\"\u003e\u003c/a\u003eEtapa 5: verificar carregamento, permissões e qualidade\u003c/h2\u003e\n\u003cp\u003eNã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.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#ordem-de-verifica%C3%A7%C3%A3o-recomendada\" class=\"anchor\" id=\"ordem-de-verificação-recomendada\"\u003e\u003c/a\u003eOrdem de verificação recomendada\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eVerificar Rules:\u003c/strong\u003e 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.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eVerificar Skills:\u003c/strong\u003e chame explicitamente a Skill e verifique se os argumentos de entrada, os resultados e as condições de interrupção funcionam.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eVerificar Agents:\u003c/strong\u003e atribua uma tarefa de baixo risco, como uma revisão somente leitura, e verifique o formato do resultado.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eVerificar permissões:\u003c/strong\u003e confirme se ferramentas capazes de realizar alterações, como Bash e Edit, foram concedidas apenas às configurações que realmente precisam delas.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eVerificação automática:\u003c/strong\u003e confirme os resultados da AI de forma independente com testes, verificação de tipos, linter e verificações de segurança.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#itens-a-verificar-em-caso-de-falha\" class=\"anchor\" id=\"itens-a-verificar-em-caso-de-falha\"\u003e\u003c/a\u003eItens a verificar em caso de falha\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\n\u003ccode\u003e.claude\u003c/code\u003e está realmente na raiz do projeto?\u003c/li\u003e\n\u003cli\u003eO nome do arquivo da Skill é exatamente \u003ccode\u003eSKILL.md\u003c/code\u003e?\u003c/li\u003e\n\u003cli\u003eA Skill está na estrutura \u003ccode\u003e.claude/skills/\u0026lt;nome\u0026gt;/SKILL.md\u003c/code\u003e?\u003c/li\u003e\n\u003cli\u003eO arquivo do Agent é um arquivo Markdown localizado diretamente em \u003ccode\u003e.claude/agents\u003c/code\u003e?\u003c/li\u003e\n\u003cli\u003eO início e o fim do YAML front matter foram delimitados com \u003ccode\u003e---\u003c/code\u003e?\u003c/li\u003e\n\u003cli\u003e\n\u003ccode\u003ename\u003c/code\u003e e \u003ccode\u003edescription\u003c/code\u003e são específicos o suficiente para distinguir a tarefa?\u003c/li\u003e\n\u003cli\u003eOs padrões de caminho correspondem à estrutura real do projeto?\u003c/li\u003e\n\u003cli\u003eA versão instalada do Claude Code oferece suporte aos metadados utilizados?\u003c/li\u003e\n\u003cli\u003eAs permissões das ferramentas ou as políticas da organização estão bloqueando a execução?\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#por-que-o-or%C3%A7amento-de-contexto-e-a-seguran%C3%A7a-devem-ser-projetados-em-conjunto\" class=\"anchor\" id=\"por-que-o-orçamento-de-contexto-e-a-segurança-devem-ser-projetados-em-conjunto\"\u003e\u003c/a\u003ePor que o orçamento de contexto e a segurança devem ser projetados em conjunto\u003c/h2\u003e\n\u003cp\u003eO objetivo de Rules, Skills e Agents não é apenas adicionar funcionalidades. Eles também são \u003cstrong\u003emeios de engenharia de contexto\u003c/strong\u003e que controlam quais informações entram no contexto e em que momento.\u003c/p\u003e\n\u003cp\u003eSe 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.\u003c/p\u003e\n\u003cp\u003eEm termos de segurança, os seguintes princípios são importantes.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eRevise Rules e Skills como qualquer outro código do repositório.\u003c/li\u003e\n\u003cli\u003eLeia arquivos de Agent ou Skill recebidos de fontes externas antes de executá-los.\u003c/li\u003e\n\u003cli\u003eMinimize as permissões para comandos de shell, acesso à rede e modificação de arquivos.\u003c/li\u003e\n\u003cli\u003eNão confie incondicionalmente em comandos incluídos na entrada do usuário ou no texto de uma issue.\u003c/li\u003e\n\u003cli\u003eInclua uma etapa de aprovação humana para implantação, exclusão, pagamentos e migração de dados.\u003c/li\u003e\n\u003cli\u003eNão armazene informações secretas em arquivos de prompt; use um sistema separado de gerenciamento de segredos.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#qual-recurso-escolher\" class=\"anchor\" id=\"qual-recurso-escolher\"\u003e\u003c/a\u003eQual recurso escolher\u003c/h2\u003e\n\u003cp\u003eÉ possível decidir rapidamente com as seguintes perguntas.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eTodas as tarefas relacionadas devem seguir isso? → \u003cstrong\u003eRule\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003eÉ um procedimento repetitivo com início e fim? → \u003cstrong\u003eSkill\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003eSão necessários uma função separada e um contexto independente? → \u003cstrong\u003eAgent\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003eÉ necessário executar um comando determinístico antes ou depois de um evento específico? → \u003cstrong\u003eConsiderar um Hook\u003c/strong\u003e\n\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003ePor 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.\u003c/p\u003e\n\u003cp\u003eA 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.\u003c/p\u003e\n","tags":["Engenharia de contexto","Claude Code","Programação com IA","Habilidades de agentes","Agente de programação"],"faqs":[{"question":"A pasta `.claude` é obrigatória no Claude Code?","answer":"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`."},{"question":"Qual é a diferença entre Rules e `CLAUDE.md`?","answer":"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."},{"question":"O nome do arquivo de Skill é `skill.md` ou `SKILL.md`?","answer":"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/\u003cskill-name\u003e/SKILL.md`; em sistemas operacionais que diferenciam maiúsculas de minúsculas, `skill.md` é tratado como um arquivo diferente."},{"question":"Uma Skill do Claude Code só é executada quando o usuário a chama?","answer":"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 `/\u003cskill-name\u003e`. Se for necessário impedir a chamada automática, é possível considerar a configuração `disable-model-invocation` nas versões compatíveis."},{"question":"Devo usar uma Skill ou um Agent?","answer":"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."},{"question":"Os subagentes podem conversar diretamente entre si ou chamar outros agentes?","answer":"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."},{"question":"Ao criar Rules, Claude sempre seguirá as instruções perfeitamente?","answer":"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."},{"question":"É seguro usar imediatamente uma Skill ou um Agent obtido externamente?","answer":"É 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":[{"url":"https://code.claude.com/docs/en/memory","title":"Documentação do Claude Code: Gerencie a memória do Claude","type":"source"},{"url":"https://code.claude.com/docs/en/skills","title":"Documentação do Claude Code: Amplie o Claude com habilidades","type":"source"},{"url":"https://code.claude.com/docs/en/sub-agents","title":"Documentação do Claude Code: Crie subagentes personalizados","type":"source"},{"url":"https://code.claude.com/docs/en/settings","title":"Documentação do Claude Code: Configurações do Claude Code","type":"source"}],"images":[{"id":767,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgyOSwicHVyIjoiYmxvYl9pZCJ9fQ==--8ba3d33d24232863ea1d744998bca1e2dbb088c6/ai-7c680af1.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"책상에서 노트북의 개발 워크플로 대시보드를 살펴보는 사람","caption":"개발자가 노트북에서 프로젝트 파일과 자동화 작업 상태를 확인하고 있다.","description":null},"en":{"alt":"Person viewing a development workflow dashboard on a laptop at a desk","caption":"A developer reviews project files and automation task statuses on a laptop.","description":null},"ja":{"alt":"デスクでノートパソコンの開発ワークフローダッシュボードを見る人","caption":"開発者がノートパソコンでプロジェクトファイルと自動化タスクの状態を確認している。","description":null},"es":{"alt":"Persona viendo un panel de flujo de desarrollo en un portátil sobre un escritorio","caption":"Un desarrollador revisa archivos del proyecto y estados de tareas automatizadas en un portátil.","description":null},"id":{"alt":"Seseorang melihat dasbor alur kerja pengembangan di laptop pada meja","caption":"Seorang pengembang memeriksa berkas proyek dan status tugas otomatis di laptop.","description":null},"pt":{"alt":"Pessoa visualizando um painel de fluxo de desenvolvimento em um notebook","caption":"Um desenvolvedor verifica arquivos do projeto e o status de tarefas automatizadas no notebook.","description":null},"zh-hant":{"alt":"坐在書桌前查看筆電開發工作流程儀表板的人","caption":"開發者正在筆電上檢查專案檔案與自動化任務狀態。","description":null},"de":{"alt":"Person betrachtet ein Dashboard für Entwicklungsabläufe auf einem Laptop am Schreibtisch","caption":"Ein Entwickler prüft Projektdateien und den Status automatisierter Aufgaben auf einem Laptop.","description":null}}},{"id":768,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgzNSwicHVyIjoiYmxvYl9pZCJ9fQ==--458d876e5a3cb0d4581f0909c6198e47789eda8b/ai-54d6eb4e.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"폴더, 필터, 자동화 단계, AI 작업 공간, 보안 및 검증 흐름을 연결한 워크플로 다이어그램","caption":"규칙과 자동화 단계가 보안 계층을 거쳐 테스트와 검증으로 이어지는 구조를 보여준다.","description":null},"en":{"alt":"Workflow diagram linking folders, filters, automation steps, an AI workspace, security, and validation","caption":"Rules and automated steps flow through a security layer into testing and validation.","description":null},"ja":{"alt":"フォルダー、フィルター、自動化工程、AI作業環境、セキュリティ、検証を結ぶワークフロー図","caption":"ルールと自動化工程がセキュリティ層を経てテストと検証へ進む構成を示している。","description":null},"es":{"alt":"Diagrama de flujo con carpetas, filtros, automatización, espacio de IA, seguridad y validación","caption":"Las reglas y los pasos automatizados pasan por una capa de seguridad hasta las pruebas y la validación.","description":null},"id":{"alt":"Diagram alur folder, filter, tahap otomatisasi, ruang kerja AI, keamanan, dan validasi","caption":"Aturan dan tahapan otomatis mengalir melalui lapisan keamanan menuju pengujian dan validasi.","description":null},"pt":{"alt":"Diagrama de fluxo com pastas, filtros, automação, ambiente de IA, segurança e validação","caption":"Regras e etapas automatizadas passam por uma camada de segurança até os testes e a validação.","description":null},"zh-hant":{"alt":"連結資料夾、篩選器、自動化步驟、AI 工作區、安全與驗證的流程圖","caption":"規則與自動化步驟經過安全層後，進入測試與驗證流程。","description":null},"de":{"alt":"Workflow mit Ordnern, Filtern, Automatisierung, KI-Arbeitsplatz, Sicherheit und Validierung","caption":"Regeln und automatisierte Schritte führen über eine Sicherheitsebene zu Tests und Validierung.","description":null}}}],"published_at":"2026-08-19T16:14:05+09:00","updated_at":"2026-08-19T16:14:05+09:00","license":"cc_by","translation_status":"reviewed","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/en/articles/claude-code-rules-skills-agents-guide"}