Piensa en una bóveda con varias capas de seguridad. Qué puede hacer el agente puede hacer
está determinado por las herramientas que enumeras en el campo tools
— no por el texto del prompt. El prompt dice "qué hacer"; las herramientas dicen "con qué".
Mezclar ambos es el error más común al crear subagentes.
Contenido detallado
🎯 Dar solo lo necesario
El principio del mínimo privilegio es simple: un agente que no necesita escribir no debe tener permiso para escribir. Parece obvio, pero se viola constantemente. El costo de ser demasiado generoso con las herramientas no aparece en el primer uso; aparece cuando el agente toma una decisión inesperada en producción.
Principio del mínimo privilegio aplicado a subagentes
Cada herramienta que agregas al campo tools
amplía el alcance de acción del agente. Expándelo solo cuando el agente necesite la herramienta para cumplir
el objetivo específico. Si tienes dudas, empieza sin ella: puedes agregarla después; reparar daños en
producción es mucho más costoso.
Borrador — sin restricción
Incluyes todo: Read, Write, Bash, WebSearch. El agente funciona, pero no es auditable.
Refinamiento — solo lo que usa
Observas qué herramientas llamó realmente el agente. Elimina las demás.
Producción — mínimo validado
Solo las herramientas necesarias. El comportamiento es predecible y el riesgo, controlado.
📖 Agentes de solo lectura: Read, Grep, Glob
La mayoría de los agentes de análisis, revisión e investigación no necesitas escribir nada.
El trío Read, Grep
e Glob cubre prácticamente todos los casos de uso de lectura —
inspeccionar archivos, buscar patrones, listar la estructura. Con solo estas tres, creas un agente
que puede aprender todo sobre el repositorio sin cambiar un byte.
✓ Qué abarca el trío
- ✓Read — leer cualquier archivo del proyecto, incluidos configs y secretos (cuidado al informar)
- ✓Grep — buscar patrones en texto, ideal para encontrar funciones, TODOs, imports
- ✓Glob — listar archivos de forma predeterminada, mapear la estructura de carpetas
- ✓Combinados: mapeo completo + búsqueda semántica + lectura de contexto
✗ Qué no hacen
- ✗Crear o modificar archivos (Write)
- ✗Ejecutar comandos del sistema (Bash)
- ✗Hacer requests HTTP (WebFetch, WebSearch)
- ✗Interactuar con servidores MCP externos
Consejo: Glob + Read en secuencia
Un patrón muy útil: usa Glob para descubrir qué archivos existen y luego Read para leer solo los relevantes. Eso es mucho más eficiente que pedirle al agente que "lea todo": priorizará según el patrón que definiste en el Glob.
⚖️ Permitido x no permitido — la lista concreta
El archivo .md de un subagente tiene un campo
tools que recibe una lista. Todo lo que está en la lista
está permitido — todo lo que queda fuera se bloquea automáticamente, sin ninguna configuración adicional.
No existe "negar explícitamente": tú incluye lo que puede, el resto no existe para el agente.
| Herramienta | Categoría | Riesgo si se incluye sin necesidad | Incluir cuando... |
|---|---|---|---|
| Read | Lectura | Bajo (puede leer secretos) | Necesita inspeccionar el contenido de los archivos |
| Grep | Búsqueda | Bajo | Necesita buscar patrones en el codebase |
| Glob | Listado | Bajo | Necesita mapear la estructura de archivos |
| Write | Escritura | Medio (modifica archivos) | El agente necesita generar o editar artefactos |
| Edit | Escritura | Medio (parche en archivos) | El agente necesita hacer ediciones precisas |
| Bash | Ejecución | Alto (ejecuta cualquier comando) | El agente necesita ejecutar scripts/pruebas |
| WebFetch | Red | Alto (acceso externo) | El agente necesita buscar datos externos |
🔌 MCP permitidos — acceso al mundo externo
Herramientas MCP (Model Context Protocol) dan al agente acceso a sistemas externos: bases de datos, APIs, navegadores, servicios. Son más poderosas — y más riesgosas — que las herramientas nativas. La decisión de incluir un MCP en un subagente debe ser intencional y específica: ¿el agente necesita este servidor MCP para completar su función?
Cómo se heredan los MCP servers
Por defecto, los subagentes heredan los servidores MCP del contexto principal. Esto significa que si tienes
un servidor de base de datos configurado globalmente, el agente hijo también puede acceder a él
— a menos que lo restrinjas explícitamente con mcpServers: []
(lista vacía = ningún MCP) o enumera solo los permitidos.
- →Herencia predeterminada: todos los MCP del contexto principal están disponibles
- →Restricción total:
mcpServers: []— sin acceso a ningún MCP - →La lista especifica: solo están disponibles los servidores incluidos en la lista
✓ Los MCP suelen ser seguros para subagentes
- ✓MCP de lectura de la base de datos (solo SELECT)
- ✓MCP de búsqueda (Brave, tavily) con límite de solicitudes
- ✓MCP de acceso a la documentación interna (solo lectura)
- ✓MCP de GitHub para leer PR y issues
✗ MCP que requieren una revisión cuidadosa
- ✗MCP que puede enviar correos electrónicos o mensajes
- ✗MCP con acceso de escritura a la base de datos
- ✗MCP para ejecutar deploys o tareas de infraestructura
- ✗MCP de pagos o facturación
🛡️ El permiso real supera el prompt «no lo hagas»
Una de las trampas más comunes: incluir en el prompt instrucciones como «nunca elimines archivos»
o «no ejecutes comandos del sistema» mientras el campo tools
todavía incluye Bash.
El prompt es orientación; el campo tools es ley.
Las instrucciones en lenguaje natural pueden malinterpretarse, ignorarse bajo presión o evadirse; la lista de herramientas, no.
No confíes solo en el prompt para la seguridad
El agente recibe el prompt como contexto de alto nivel, pero el LLM es un sistema probabilístico. En escenarios de mucha presión, instrucciones ambiguas o cadenas largas, puede:
- —Razonar que "la excepción se aplica a este caso específico"
- —Interpretar una instrucción vaga de manera inesperada
- —Ser manipulado por prompt injection en el contenido que procesa
Elimina la herramienta. No le indiques al agente que no la use.
Regla práctica: las herramientas como contrato, el prompt como estilo
Usa el campo tools para definir lo que el agente puede hacer (contrato inmutable). Usa el prompt / description para definir como debe hacer (tono, formato, criterios). Mezclar ambos — usar el prompt para prohibir lo que permite el tools — es una falsa seguridad.
👁️ "Si puede leerlo, asume que lo hará"
Cuando incluyes Read en el campo tools,
el agente puede leer cualquier archivo accesible en el proyecto — incluso .env,
claves SSH, tokens en configuraciones. Esto es esperado y útil, pero exige que sepas qué hace el agente
puede hacer y que los informes que genera no filtren datos sensibles.
✗ Malo: el agente leyó y reprodujo los valores en el informe
Indica al agente que no reproduzca datos sensibles
Para agentes con acceso de lectura en proyectos reales, incluye en el prompt: "Nunca reproduzcas valores de variables de entorno, claves, tokens ni contraseñas en los informes. Menciona solo que existen y si están configurados correctamente." Aquí sí es el prompt y el lugar correctos: no estás prohibiendo una herramienta, estás orientando el comportamiento dentro de lo permitido.
🔬 Granularidad — Bash y el caso especial
Bash y la herramienta más poderosa y la que
exige más cuidado. Con Bash, el agente puede ejecutar cualquier comando del sistema: instalar paquetes,
eliminar archivos, hacer solicitudes con curl, iniciar procesos. Cuando Bash sea necesario,
la granularidad viene de la descripción precisa en el prompt sobre
cuáles comandos se esperan, combinada con allowedTools en settings.json
del proyecto para restringir qué binarios se pueden llamar.
---
name: code-reviewer
description: |
Revisor de codigo que analisa qualidade, padroes e problemas potenciais.
Leia arquivos .ts, .js e .py no caminho indicado. Reporte: (1) problemas
criticos, (2) sugestoes de melhoria, (3) pontos positivos. Nao altere
nenhum arquivo. Nao execute comandos. Entregue um relatorio estruturado.
tools:
- Read
- Grep
- Glob
# Sem Write, sem Edit, sem Bash, sem WebFetch
# Nenhum MCP server necessario para este agente
---Prompts listos
"Crea un subagente llamado doc-auditor que sea completamente de solo lectura. Debe leer archivos Markdown en el directorio /docs, verificar si cada uno tiene frontmatter con 'title', 'date' y 'author', y generar un informe de compliance. Enumera las herramientas necesarias y explica por qué no necesita Write ni Bash."
"Lee el archivo .claude/agents/meu-agente.md y evalúa si todas las herramientas enumeradas en tools son necesarias para la tarea descrita en description. Para cada herramienta, indica: necesaria, innecesaria o depende. Sugiere una versión más concisa de la lista de tools."
"Quiero un agente que verifique si el archivo package.json tiene la dependencia X. Explica cómo hacerlo solo con Read (sin Bash) y cuándo sería necesario agregar Bash. ¿Cuál es el riesgo de cada enfoque?"
Ejercicio
Crea el archivo .claude/agents/log-analyzer.md
para un agente que analiza archivos de log (.log, .txt) en busca de errores críticos
y genera un informe con: cantidad de errores por nivel (ERROR, WARN, FATAL), los 5 errores más frecuentes,
y una línea de recomendación. El agente no puede modificar ningún archivo.
Pasos
- 1Define el campo
tools— enumera ÚNICAMENTE las herramientas necesarias para leer y buscar en archivos de texto. - 2Escribe el campo
descriptioncon instrucciones claras sobre cómo informar los resultados (sin reproducir líneas completas del log). - 3Verifica: ¿el agente necesita Bash? ¿Necesita Write? Si no, elimínalo.
- 4Prueba invocando: «usa el agente log-analyzer para inspeccionar los archivos en /tmp/logs»
Criterio de verificación: cómo saber si lo hiciste bien
El agente está correcto si cumple con todos los criterios a continuación:
- ✓Mínimo necesario: tools contienen solo Read, Grep y Glob; sin Write, Edit, Bash ni herramientas de red.
- ✓Description precisa: el campo description especifica los tres elementos del informe (recuento, top-5, recomendación).
- ✓Sin falsa seguridad: no hay ninguna instrucción en el prompt que prohíba Write; simplemente, Write no está en tools.
- ✓Datos sensibles: description orienta a no reproducir líneas completas de stack trace con datos de usuarios.
- ✓Comprobable: al invocar al agente, este completa la tarea sin solicitar permisos adicionales y sin intentar editar archivos.
Próximo módulo:
2.5 — Proyecto x Global. Cuándo colocar el agente en .claude/agents/ del proyecto frente a la carpeta global del usuario.