Proyecto × Global | Subagentes

Ya sabes crear un agente. Ahora la pregunta es: dónde vive? Claude Code lee agentes de dos ubicaciones distintas: la carpeta de proyecto (que va al git, se comparte con el equipo) y la carpeta global (solo tuyo, disponible en cualquier proyecto, nunca se sube al repositorio). La misma lógica se aplica a las skills, los hooks y los servidores MCP: cada uno tiene su propio par de ámbitos.

↑ Proyecto: .claude/agents/ en el repo (va a git). Global: ~/.claude/agents/ en la carpeta principal (no se carga).

Contenido detallado

📁 `.claude/agents/` en el repositorio

Cuando creas un archivo .claude/agents/meu-agente.md dentro del repositorio del proyecto, este agente pertenece a ese proyecto. Cualquier persona que clone el repo y abra Claude Code verá el mismo agente disponible, sin necesidad de configurar nada.

🔀 El agente va junto con el código

O .claude/agents/ vive dentro del repositorio. Esto significa que:

•git add + git push — el agente se incorpora junto con el código.
•git clone — el próximo desarrollador ya lo encuentra en el lugar correcto.
•Pull Requests — los cambios en el agente se revisan como código normal.
•Historial — ves exactamente cuándo y por qué cambió la descripción.

Qué es:

Carpeta .claude/agents/ dentro del repositorio — agentes rastreados por git, visibles para todos los colaboradores del proyecto.

Por qué aprender:

Es la forma correcta de distribuir agentes al equipo. Sin esto, cada desarrollador debe configurar manualmente los mismos agentes en su máquina, lo que puede generar discrepancias.

Conceptos clave:

Alcance del proyecto · control de versiones de los agentes · trazabilidad · incorporación automática.

📁

En el repo

dentro del proyecto

🔀

Versionado

rastreado con git

👥

Compartido

todo el equipo usa

📝

Revisable

mediante PR/code review

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

La carpeta ~/.claude/agents/ está en tu home — fuera de cualquier repositorio. Los agentes que coloques ahí estarán disponibles en todos tus proyectos, en cualquier máquina en la que hayas iniciado sesión, pero nunca se suben a git.

✅ Buenos candidatos para el ámbito global

→Agente con tus preferencias de estilo de código
→Herramientas que usas en todos los proyectos (p. ej., security-auditor)
→Agentes que contienen información sensible (tokens, endpoints internos)
→Flujos de trabajo personales que no tienen sentido para el equipo

❌ Qué NO debe quedar global

→Agentes específicos de un solo proyecto (el equipo no los encontrará)
→Agentes que el equipo debe auditar/versionar
→Cualquier cosa que deba existir en CI/CD (el servidor no tiene tu directorio home)
→Agentes con contexto del dominio del proyecto (arquitectura, reglas de negocio)

Qué es:

Carpeta ~/.claude/agents/ en la carpeta principal del usuario: fuera de cualquier repo, invisible para git y disponible en todos los proyectos que abras.

Por qué aprender:

Evita que herramientas personales o sensibles se incluyan accidentalmente en un commit. Crea un «cajón personal» de agentes reutilizables sin ensuciar el repositorio.

Conceptos clave:

Alcance global · directorio home · invisible para git · varios proyectos · herramientas personales.

🔀 Compartir con el equipo vía git

Agentes en el .claude/agents/ del repo son ciudadanos de primera clase del proyecto. Forman parte del mismo flujo de revisión de código que el código: nadie cambia la descripción de un agente sin que el equipo lo sepa.

Crea el `.md` en la carpeta del proyecto

Nuevo agente → nueva responsabilidad para el equipo.

Ubica en meu-repo/.claude/agents/code-reviewer.md. La carpeta .claude/ ya existe si usas CLAUDE.md o settings.json.

Haz commit y abre un PR

El agente entra en el control de versiones.

El diff del .md aparece en el PR como cualquier cambio de código. La descripción, las herramientas permitidas y el prompt del sistema se pueden revisar línea por línea.

El equipo clona y ya tiene todo

Cero configuración manual para nuevos desarrolladores.

Cualquier colaborador que clone el repositorio encontrará los agentes listos. La configuración de las herramientas es automática —igual que con CLAUDE.md.

💡 Consejo: agrégalo a `.gitignore` los agentes privados

Si tienes agentes de proyecto que no deben salir (p. ej., acceso a staging interno), agrégalos al .gitignore con el patrón .claude/agents/privado-*.md. Así quedan en el repo local, pero nunca se incluyen en un commit.

Qué es: agentes como artefactos versionados — creados, modificados y revisados mediante el mismo flujo que el código del proyecto.

Por qué aprender: garantiza que todos usen la misma versión del agente y que los cambios peligrosos (p. ej., darle al agente acceso a Bash) pasen por revisión.

Conceptos clave: git como fuente de la verdad · revisión de PR por agentes · onboarding automático · .gitignore selectivo.

🔒 Solo tú: el ámbito personal

El ámbito global (~/.claude/agents/) é tu colección privada. No está en ningún repo: nunca aparece en el git status, nunca se sube a GitHub, nunca lo ve tu colega. Ahí están las herramientas que creaste para ti.

🧰 Tu caja de herramientas portátil

Piensa en el ámbito global como la caja de herramientas del carpintero: lo llevas a cada obra, pero es tuyo. El contratista del próximo proyecto no sabe qué herramientas traes.

🏠 Siempre disponible

Abres cualquier proyecto y el agente global está ahí. No necesitas copiarlo ni reinstalarlo.

🔐 Privado por defecto

Nunca aparece en el git status. Los agentes con datos sensibles están seguros aquí.

⚙️ Tus preferencias

Estilo de código, idioma de las respuestas, workflows personales: nada impuesto al equipo.

🚫 No existe en CI/CD

Los servidores de CI no tienen tu directorio home. Los agentes críticos para los pipelines deben estar en el repo.

Qué es: la colección personal y portátil de agentes — disponible en todos los proyectos, pero invisible para git y el equipo.

Por qué aprender: sin el alcance global, te verías obligado a hacer commit de herramientas personales en cada repo — contaminando el historial y exponiendo configuraciones privadas.

Conceptos clave: directorio de inicio · portabilidad · privacidad · no disponible en CI · preferencias personales.

🚚 Mover un agente = mover el `.md`

¿Necesitas promover un agente personal al proyecto del equipo? ¿O privatizar un agente del repo? El proceso es exactamente lo que parece: mueve el archivo .md de una carpeta a otra. No existe "vincular" ni "registrar": el alcance lo determina la ruta del archivo.

⌨️ Los dos movimientos

global → proyecto (promover al equipo)

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

proyecto → global (hacer privado)

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

📊 ¿Por qué es tan simple?

Claude Code no tiene una base de datos de agentes: simplemente lee todos los .md de ambas carpetas al iniciar. El «registro» del agente es la presencia del archivo. Moverlo = cambiar el alcance de inmediato en la próxima sesión.

Qué es: alcance definido por la ruta del archivo — cambiar el alcance es mover el .md, sin configuración adicional.

Por qué aprender: desmitifica el proceso: no hay «instalación» ni «importación»; el agente simplemente existe donde está el archivo.

Conceptos clave: ruta = alcance · lectura directa de archivos · sin base de datos · cambio inmediato.

⚡ Tener el mismo agente en ambos alcances

Nada impide que exista un code-reviewer.md tanto en ~/.claude/agents/ cuánto en .claude/agents/ del proyecto. Claude Code los se une al iniciar — ambos están disponibles. Si tienen el mismo name, la del proyecto tiene precedencia sobre la global.

Ejemplo: el mismo agente en ambos ámbitos 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.

Versión personal — genérica, para varios proyectos

.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

Versión del proyecto — especializada, tiene precedencia

💡 Cuando hay conflictos: prevalece el proyecto

Si ambos tienen name: code-reviewer, Claude usa la versión del proyecto. Esto permite que el equipo "sobrescriba" tu versión global con una adaptada al contexto, sin que tengas que borrar la personal.

Qué es: los dos alcances coexisten: Claude combina el global y el del proyecto al iniciarse, y el del proyecto tiene precedencia si hay nombres duplicados.

Por qué aprender: permite tener una versión genérica global y otra especializada por proyecto, sin conflictos: el patrón más flexible para equipos que también tienen preferencias individuales.

Conceptos clave: precedencia del proyecto · coexistencia de ámbitos · especialización progresiva · override sin eliminación.

🔗 La misma lógica: skills, hooks y MCP

El patrón proyecto × global no es exclusivo de los agentes. Las skills (.claude/skills/), los hooks y los servidores MCP siguen exactamente la misma división. Aprende una vez, aplica en todos los recursos de Claude Code.

Recurso	Alcance del proyecto	Alcance 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 (raíz del repo)	~/.claude/CLAUDE.md

📊 Un modelo mental unificado

La regla es siempre la misma: el proyecto comparte, global es tuyo. Una vez que interiorizas esto para los agentes, ya sabes cómo pensar las skills, los hooks y MCP. Claude Code es coherente: aprende el patrón una vez.

En los hooks y MCP, la lógica de precedencia también se aplica: la configuración del proyecto se combina con la global, pero un hook del proyecto puede sobrescribir uno global con el mismo nombre.

Qué es: el patrón proyecto × global es universal en Claude Code: se aplica de forma consistente a agentes, skills, hooks y MCP.

Por qué aprender: no necesitas aprender un modelo distinto para cada función. Un único modelo mental abarca todo el ecosistema de configuración de Claude Code.

Conceptos clave: modelo unificado · coherencia del ecosistema · el proyecto se comparte, lo global es tuyo · combinación + precedencia.

⌨️

Prompts listos (copia y pega)

Tres prompts para gestionar ámbitos de agentes en Claude Code. Úsalos directamente en la conversación con el maestro.

Prompt 1 — mover un agente del ámbito global al proyecto lo promociona al equipo

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 de ambos alcances auditoría 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 — crear una versión de proyecto de un agente global especialización

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.

🖥️

Pantalla simulada: dos ámbitos en una sesión

Mira cómo Claude Code muestra agentes de ambos alcances en una lista real. El code-reviewer aparece del proyecto (tiene precedencia); los demás agentes vienen del global sin conflictos.

claude code · meu-projeto · agentes disponibles /agents list

# Agentes cargados en la sesión:

# [PROYECTO] .claude/agents/

code-reviewer → .claude/agents/code-reviewer.md [tiene precedencia]

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

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

# [GLOBAL] ~/.claude/agents/

code-reviewer → ~/.claude/agents/code-reviewer.md [sobrepuesto por el proyecto]

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

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

# Total: 5 agentes activos (1 superpuesto, 4 únicos)

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

↑ Recreación ilustrativa. Nota el code-reviewer apareciendo en ambos ámbitos: el del proyecto tiene precedencia.

🎯

Ejercicio — decide el alcance de 4 agentes

Para cada uno de los 4 agentes a continuación, decide si debe quedar dentro del alcance de proyecto o en el global, y justifica con una razón objetiva.

🔍

A) sql-query-expert

Conoce el esquema de la base de datos de este proyecto. Genera consultas optimizadas para las tablas específicas del sistema.

✍️

B) pt-br-writer

Reescribe cualquier texto con mi estilo de escritura en portugués brasileño. Preferencias personales de tono y vocabulario.

🧪

C) e2e-test-runner

Ejecuta las pruebas end-to-end de este proyecto usando Playwright. Conoce los scripts de test:e2e de package.json.

🔐

D) security-scanner

Hace auditorías de seguridad en cualquier código. Busca vulnerabilidades conocidas (OWASP Top 10). Se usa en todos los proyectos.

✅ Criterio de verificación

Para cada agente, tu decisión es correcta si puedes responder sí a la pregunta correspondiente:

A:Proyecto → "¿El equipo necesita este agente para trabajar en este repositorio?" (sí — el schema es del proyecto)
B:Global → "¿Esto es una preferencia personal que no tiene relación con ningún proyecto específico?" (sí — es tu estilo)
C:Proyecto → "¿Este agente falla si se usa fuera de este repositorio específico?" (sí — los scripts son de este proyecto)
D:Global → "¿Este agente es útil en cualquier proyecto, independientemente del contexto?" (sí — la seguridad es universal)

La pregunta que define el alcance

"Este agente funciona fuera de este repositorio?» — Si es así, propónlo para el ámbito global. Si el contexto del proyecto es esencial para que el agente tenga sentido, pertenece al proyecto. Si depende de datos sensibles que no deben incluirse en un commit, debe quedarse en el ámbito global.

✅ Resumen del módulo

✓

.claude/agents/ en el repo — versionado, compartido con el equipo mediante git, pasa por revisión de código.

✓

~/.claude/agents/ global — solo tuyo, disponible en todos los proyectos, nunca se sube a git.

✓

Compartir mediante git — los agentes del proyecto son miembros del repositorio, con historial y revisión de PR.

✓

Solo tú — global es el cajón personal y portátil; no existe en CI/CD ni contamina el repo.

✓

Mover = mover el .md — no hay registro ni instalación; el alcance lo define la ruta del archivo.

✓

Coexistencia — se cargan ambos ámbitos; el del proyecto tiene precedencia si hay nombres duplicados.

✓

Modelo unificado — las skills, los hooks y los MCP siguen la misma lógica: proyecto × global.

Próximo módulo:

2.6 — Creando con /agents + cómo Claude elige. Como el atajo /agents funciona y el criterio que usa el maestro para decidir qué agente activar.

← Módulo 2.4: Herramientas y permisos Próximo módulo →