Projeto × Global | Subagentes

Você já sabe criar um agente. Agora a pergunta é: onde ele mora? O Claude Code lê agentes de dois locais distintos — a pasta do projeto (que vai pro git, compartilha com o time) e a pasta global (só sua, disponível em qualquer projeto, nunca sobe pro repositório). A mesma lógica se aplica a skills, hooks e servidores MCP: cada um tem o seu par de escopos.

↑ Projeto: .claude/agents/ no repo (vai pro git). Global: ~/.claude/agents/ na home (não sobe).

Conteúdo detalhado

📁 `.claude/agents/` no repositório

Quando você cria um arquivo .claude/agents/meu-agente.md dentro do repositório do projeto, esse agente pertence àquele projeto. Qualquer pessoa que clonar o repo e abrir o Claude Code vai ver o mesmo agente disponível — sem precisar configurar nada.

🔀 O agente vai junto com o código

O .claude/agents/ vive dentro do repositório. Isso significa que:

•git add + git push — o agente sobe junto com o código.
•git clone — o próximo dev já o encontra no lugar certo.
•Pull Requests — mudanças no agente são revisadas como código normal.
•Histórico — você vê exatamente quando e por que a descrição mudou.

O que é:

Pasta .claude/agents/ dentro do repositório — agentes rastreados pelo git, visíveis a todos os colaboradores do projeto.

Por que aprender:

É a forma correta de distribuir agentes para o time. Sem isso, cada dev precisa configurar manualmente os mesmos agentes na máquina deles — propenso a divergências.

Conceitos-chave:

Escopo de projeto · controle de versão dos agentes · rastreabilidade · onboarding automático.

📁

No repo

dentro do projeto

🔀

Versionado

rastreado por git

👥

Compartilhado

todo o time usa

📝

Revisável

via PR/code review

🏠 `~/.claude/agents/` — escopo global

A pasta ~/.claude/agents/ fica na sua home — fora de qualquer repositório. Agentes colocados aí ficam disponíveis em todos os seus projetos, em qualquer máquina em que você esteja logado, mas nunca sobem para o git.

✅ Bons candidatos ao global

→Agente com suas preferências de estilo de código
→Ferramentas que você usa em todos os projetos (ex.: security-auditor)
→Agentes que contêm informação sensível (tokens, endpoints internos)
→Workflows pessoais que não fazem sentido para o time

❌ O que NÃO deve ficar global

→Agentes específicos de um único projeto (o time não vai encontrar)
→Agentes que devem ser auditados/versionados pelo time
→Qualquer coisa que precise existir na CI/CD (o servidor não tem sua home)
→Agentes com contexto de domínio do projeto (arquitetura, regras de negócio)

O que é:

Pasta ~/.claude/agents/ na home do usuário — fora de qualquer repo, invisível ao git, disponível em todos os projetos que você abrir.

Por que aprender:

Evita que ferramentas pessoais ou sensíveis sejam acidentalmente commitadas. Cria uma "gaveta pessoal" de agentes reutilizáveis sem poluir o repositório.

Conceitos-chave:

Escopo global · home directory · invisível ao git · multi-projeto · ferramentas pessoais.

🔀 Compartilhando com o time via git

Agentes no .claude/agents/ do repo são cidadãos de primeira classe do projeto. Eles participam do mesmo fluxo de code review que o código: ninguém muda a descrição de um agente sem que o time saiba.

Crie o `.md` na pasta do projeto

Novo agente → nova responsabilidade para o time.

Coloque em meu-repo/.claude/agents/code-reviewer.md. A pasta .claude/ já existe se você usa CLAUDE.md ou settings.json.

Commite e abra PR

O agente entra no controle de versão.

O diff do .md aparece no PR como qualquer mudança de código. A descrição, as tools permitidas e o system prompt são revisáveis linha a linha.

O time clona e já tem tudo

Zero configuração manual para novos devs.

Qualquer colaborador que clonar o repositório encontra os agentes prontos. O onboarding de ferramentas é automático — o mesmo que acontece com CLAUDE.md.

💡 Dica: adicione ao `.gitignore` os agentes privados

Se você tem agentes de projeto que não devem sair (ex.: acesso a staging interno), adicione-os ao .gitignore com o padrão .claude/agents/privado-*.md. Assim eles ficam no repo local mas nunca são commitados.

O que é: agentes como artefatos versionados — criados, modificados e revisados pelo mesmo fluxo que o código do projeto.

Por que aprender: garante que todos usem a mesma versão do agente e que mudanças perigosas (ex.: dar ao agente acesso a Bash) passem por revisão.

Conceitos-chave: git como fonte da verdade · PR review de agentes · onboarding automático · .gitignore seletivo.

🔒 Só você — o escopo pessoal

O escopo global (~/.claude/agents/) é sua coleção particular. Ele não está em nenhum repo — nunca aparece no git status, nunca sobe para o GitHub, nunca é visto pelo seu colega. É onde ficam as ferramentas que você construiu para si mesmo.

🧰 Sua caixa de ferramentas portátil

Pense no global como a carteira de ferramentas do carpinteiro: você leva para todo canteiro de obra, mas é seu. O empreiteiro do próximo projeto não sabe quais ferramentas você traz.

🏠 Sempre disponível

Você abre qualquer projeto e o agente global está lá. Não precisa copiar ou reinstalar.

🔐 Privado por padrão

Nunca aparece no git status. Agentes com dados sensíveis ficam seguros aqui.

⚙️ Suas preferências

Estilo de código, idioma de respostas, workflows pessoais — nada imposto ao time.

🚫 Não existe em CI/CD

Servidores de CI não têm sua home. Agentes críticos para pipelines devem ficar no repo.

O que é: a coleção pessoal e portátil de agentes — disponível em todos os projetos, mas invisível ao git e ao time.

Por que aprender: sem o escopo global, você seria forçado a commitar ferramentas pessoais em cada repo — poluindo o histórico e expondo configurações privadas.

Conceitos-chave: home directory · portabilidade · privacidade · não disponível em CI · preferências pessoais.

🚚 Mover um agente = mover o `.md`

Precisa promover um agente pessoal para o projeto do time? Ou privatizar um agente do repo? O processo é exatamente o que parece: mova o arquivo .md de uma pasta para outra. Não existe "vincular" ou "registrar" — o escopo é determinado pelo caminho do arquivo.

⌨️ Os dois movimentos

global → projeto (promover para o time)

mv ~/.claude/agents/meu-agente.md \
   meu-projeto/.claude/agents/meu-agente.md

projeto → global (privatizar)

mv meu-projeto/.claude/agents/meu-agente.md \
   ~/.claude/agents/meu-agente.md

📊 Por que é tão simples?

O Claude Code não tem banco de dados de agentes — ele simplesmente lê todos os .md das duas pastas na inicialização. O "registro" do agente é a presença do arquivo. Mover = mudar o escopo imediatamente na próxima sessão.

O que é: escopo definido pelo caminho do arquivo — mudar o escopo é mover o .md, sem configuração adicional.

Por que aprender: desmistifica o processo: não há "instalação" ou "importação" — o agente simplesmente existe onde o arquivo está.

Conceitos-chave: caminho = escopo · leitura direta de arquivos · sem banco de dados · mudança imediata.

⚡ Ter o mesmo agente nos dois escopos

Nada impede que exista um code-reviewer.md tanto em ~/.claude/agents/ quanto em .claude/agents/ do projeto. O Claude Code os une na inicialização — ambos ficam disponíveis. Se tiverem o mesmo name, o do projeto tem precedência sobre o global.

Exemplo: o mesmo agente nos dois escopos code-reviewer.md

~/.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revisa qualquer código que eu
  peça, com foco em legibilidade e segurança.
  Use em qualquer projeto.
model: claude-sonnet-4-5
tools: Read, Glob, Grep
---

Você é um revisor de código sênior.
Analise o código fornecido e aponte:
1. Problemas de segurança
2. Código difícil de manter
3. Sugestões de simplificação

Seja direto. Máximo 10 pontos por revisão.

Versão pessoal — genérica, multi-projeto

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Revisa código deste projeto
  seguindo nossas convenções internas
  (ESLint config, naming patterns do time).
model: claude-sonnet-4-5
tools: Read, Glob, Grep
---

Você é um revisor sênior deste projeto.
Siga RIGOROSAMENTE as convenções em
CLAUDE.md antes de qualquer sugestão.
Verifique também conformidade com:
- Padrões do ESLint do projeto
- Convenção de nomear hooks com useX
- Não usar any no TypeScript

Versão do projeto — especializada, tem precedência

💡 Quando conflitam: o projeto ganha

Se ambos têm name: code-reviewer, o Claude usa a versão do projeto. Isso permite que o time "sobrescreva" sua versão global com uma adaptada ao contexto — sem você precisar deletar a pessoal.

O que é: os dois escopos coexistem — o Claude une global + projeto na inicialização, com o projeto tendo precedência em caso de nome duplicado.

Por que aprender: permite ter uma versão genérica global e uma especializada por projeto, sem conflito — o padrão mais flexível para times que também têm preferências individuais.

Conceitos-chave: precedência de projeto · coexistência de escopos · especialização progressiva · override sem deleção.

🔗 A mesma lógica: skills, hooks e MCP

O padrão projeto × global não é exclusivo dos agentes. Skills (.claude/skills/), hooks e servidores MCP seguem exatamente a mesma divisão. Aprender uma vez, aplicar em todos os recursos do Claude Code.

Recurso	Escopo projeto	Escopo global
Agentes	.claude/agents/	~/.claude/agents/
Skills	.claude/skills/	~/.claude/skills/
Hooks	.claude/settings.json	~/.claude/settings.json
MCP servers	.claude/settings.json	~/.claude/settings.json
CLAUDE.md	CLAUDE.md (raiz do repo)	~/.claude/CLAUDE.md

📊 Um modelo mental unificado

A regra é sempre a mesma: projeto compartilha, global é seu. Uma vez que você internalizou isso para agentes, já sabe como pensar skills, hooks e MCP. O Claude Code é consistente — aprenda o padrão uma vez.

Nos hooks e MCP, a lógica de precedência também se aplica: settings de projeto mesclam com o global, mas um hook de projeto pode sobrescrever um global de mesmo nome.

O que é: o padrão projeto × global é universal no Claude Code — aplica-se a agentes, skills, hooks e MCP de forma consistente.

Por que aprender: você não precisa aprender um modelo diferente para cada recurso. Um único padrão mental cobre todo o ecossistema de configuração do Claude Code.

Conceitos-chave: modelo unificado · consistência do ecossistema · projeto compartilha, global é seu · mesclagem + precedência.

⌨️

Prompts prontos (copie e cole)

Três prompts para gerenciar escopos de agentes no Claude Code. Use diretamente na conversa com o maestro.

Prompt 1 — mover agente de global para o projeto promove para o time

Mova o agente "code-reviewer" do meu escopo global
(~/.claude/agents/) para este projeto (.claude/agents/).
Depois me mostre o caminho final e confirme que o arquivo
saiu do global.

Prompt 2 — listar agentes dos dois escopos auditoria rápida

Liste todos os agentes disponíveis nesta sessão,
separando os que vêm do escopo do projeto
(.claude/agents/) dos globais (~/.claude/agents/).
Mostre o nome e o caminho de cada um.

Prompt 3 — criar versão de projeto de um agente global especialização

Leia o meu agente global "code-reviewer"
(~/.claude/agents/code-reviewer.md) e crie uma versão
especializada para este projeto em .claude/agents/,
adicionando as convenções do CLAUDE.md deste repo.
Mantenha o mesmo name para que o projeto tenha
precedência sobre o global.

🖥️

Tela simulada: dois escopos em uma sessão

Veja como o Claude Code exibe agentes de ambos os escopos em uma listagem real. O code-reviewer aparece do projeto (tem precedência); outros agentes vêm do global sem conflito.

claude code · meu-projeto · agentes disponíveis /agents list

# Agentes carregados na sessão:

# [PROJETO] .claude/agents/

code-reviewer → .claude/agents/code-reviewer.md [tem precedência]

test-runner → .claude/agents/test-runner.md

doc-writer → .claude/agents/doc-writer.md

# [GLOBAL] ~/.claude/agents/

code-reviewer → ~/.claude/agents/code-reviewer.md [sobreposto pelo projeto]

security-audit → ~/.claude/agents/security-audit.md

meu-setup → ~/.claude/agents/meu-setup.md

# Total: 5 agentes ativos (1 sobreposto, 4 únicos)

maestro · Sonnet | contexto 8% | meu-projeto/

↑ Recriação ilustrativa. Note o code-reviewer aparecendo nos dois escopos — o do projeto tem precedência.

🎯

Exercício — decida o escopo de 4 agentes

Para cada um dos 4 agentes abaixo, decida se ele deve ficar no escopo do projeto ou no global, e justifique com uma razão objetiva.

🔍

A) sql-query-expert

Conhece o schema do banco de dados deste projeto. Gera queries otimizadas para as tabelas específicas do sistema.

✍️

B) pt-br-writer

Reescreve qualquer texto no meu estilo de escrita em português brasileiro. Preferences pessoais de tom e vocabulário.

🧪

C) e2e-test-runner

Executa os testes end-to-end deste projeto usando Playwright. Conhece os scripts de test:e2e do package.json.

🔐

D) security-scanner

Faz auditoria de segurança em qualquer código. Busca vulnerabilidades conhecidas (OWASP Top 10). Uso em todos os projetos.

✅ Critério de verificação

Para cada agente, sua decisão está correta se você consegue responder sim à pergunta correspondente:

A:Projeto → "O time precisa desse agente para trabalhar neste repositório?" (sim — o schema é do projeto)
B:Global → "Isso é uma preferência pessoal que não tem relação com nenhum projeto específico?" (sim — é seu estilo)
C:Projeto → "Esse agente quebra se for usado fora deste repositório específico?" (sim — scripts são deste projeto)
D:Global → "Esse agente é útil em qualquer projeto, independente do contexto?" (sim — segurança é universal)

A pergunta que decide o escopo

"Este agente funciona fora deste repositório?" — Se sim, candidate ao global. Se o contexto do projeto é essencial para o agente fazer sentido, ele pertence ao projeto. Se ele depende de dados sensíveis que não devem ser commitados, ele deve ficar no global.

✅ Resumo do módulo

✓

.claude/agents/ no repo — versionado, compartilhado com o time via git, passa por code review.

✓

~/.claude/agents/ global — só seu, disponível em todos os projetos, nunca sobe pro git.

✓

Compartilhar via git — agentes de projeto são cidadãos do repositório, com histórico e PR review.

✓

Só você — global é a gaveta pessoal e portátil; não existe em CI/CD, não polui o repo.

✓

Mover = mover o .md — não há registro ou instalação; o escopo é definido pelo caminho do arquivo.

✓

Coexistência — ambos os escopos são carregados; projeto tem precedência em nome duplicado.

✓

Modelo unificado — skills, hooks e MCP seguem a mesma lógica projeto × global.

Próximo módulo:

2.6 — Criando com /agents + como o Claude escolhe. Como o atalho /agents funciona e o critério que o maestro usa para decidir qual agente acionar.

← Módulo 2.4: Ferramentas e permissões Próximo módulo →