Referencia del sistema de herramientas

file_read

Capacidades:

• Leer el contenido completo de archivos o rangos de líneas específicos
• Esencial para entender el código antes de modificarlo
• Manejo eficiente de archivos grandes mediante la especificación de rangos

Casos de uso:

• Leer archivos de configuración antes de editarlos
• Entender patrones de implementación existentes
• Revisar archivos de prueba para comprender la cobertura

Ejemplo:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Capacidades:

• Reemplazo preciso de texto mediante coincidencia exacta de cadenas
• Varias operaciones de reemplazo con la opción multiple
• Conserva la estructura y el formato del archivo

Casos de uso:

• Actualizar implementaciones de funciones
• Modificar valores de configuración
• Refactorizar nombres de variables en varios archivos

Práctica recomendada: Úsala para cambios específicos. Para reescrituras completas, usa file_write en su lugar.

file_write

Capacidades:

• Crear archivos nuevos desde cero
• Reemplazar por completo el contenido de archivos existentes
• Manejar cualquier formato basado en texto

Casos de uso:

• Generar nuevos componentes o módulos
• Crear archivos de configuración
• Escribir archivos de prueba

Advertencia: Sobrescribe por completo los archivos existentes. Usa file_edit para modificaciones parciales.

glob

Capacidades:

• Encontrar archivos que coincidan con patrones: **/*.ts, src/**/*.js
• Filtrar por ruta de directorio
• Patrones de exclusión para acotar resultados
• Controlar el número de resultados

Casos de uso:

• Encontrar todos los componentes de un proyecto
• Localizar archivos de prueba
• Identificar archivos de configuración en varios directorios

Patrones de ejemplo:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Capacidades:

• Buscar contenido de archivos usando patrones regex
• Mostrar líneas de contexto antes/después de las coincidencias (opciones -B, -A)
• Búsqueda sin distinción de mayúsculas
• Filtrar por tipo de archivo mediante patrones glob

Casos de uso:

• Encontrar definiciones de funciones
• Localizar implementaciones de endpoints de API
• Buscar mensajes de error específicos
• Identificar patrones de seguridad

Ejemplo:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Capacidades:

• Listar archivos que contienen coincidencias de patrón
• Más rápida que grep_content cuando solo necesitas las ubicaciones de los archivos
• Compatible con patrones regex
• Filtrado glob por tipos de archivo

Casos de uso:

• Identificar qué archivos necesitan refactorización
• Encontrar archivos que importan módulos específicos
• Localizar archivos con patrones obsoletos

Práctica recomendada: Usa primero grep_file para identificar archivos relevantes y luego file_read para un examen detallado.

list_dir

Capacidades:

• Mostrar la jerarquía de directorios
• Controlar la profundidad con el parámetro max_depth
• Patrones de exclusión para filtrar la salida

Casos de uso:

• Entender la estructura del proyecto
• Verificar la organización de directorios
• Encontrar subdirectorios específicos

bash

Capacidades:

• Ejecutar comandos de shell
• Tiempo de espera máximo: 120 segundos (2 minutos, límite estricto)
• Encadenar comandos con && para dependencias
• Proporcionar resúmenes descriptivos para mayor claridad

Casos de uso:

• Ejecutar pruebas
• Construir proyectos
• Instalar dependencias
• Operaciones de Git
• Migraciones de bases de datos

Ejemplo:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Seguridad: Los comandos se ejecutan con los permisos del usuario. Revisa los comandos en Manual Accept Mode.

spawn_subagent

Capacidades:

• Lanzar subagentes especializados con contextos aislados
• Tipos: explorer, verifier, code-reviewer
• Delegar tareas complejas sin contaminar el contexto principal
• Ejecución de subagentes en paralelo para mayor eficiencia

Casos de uso:

• explorer: Buscar patrones en bases de código grandes
• verifier: Validar la lógica de implementación
• code-reviewer: Evaluación de seguridad y calidad

Práctica recomendada: Delega la investigación exploratoria en el subagente Explorer para preservar el contexto de la conversación principal.

todo_update

Capacidades:

• Crear y gestionar listas de tareas
• Actualizar el estado de las tareas (pending, in_progress, completed)
• Seguir el progreso en implementaciones complejas

Casos de uso:

• Desglosar funciones de varios pasos
• Seguir el progreso de la refactorización
• Gestionar tareas de migración

web_search

Capacidades:

• Consultar motores de búsqueda de internet
• Controlar el número de resultados
• Filtrar por actualidad (días recientes)

Casos de uso:

• Encontrar documentación de APIs desconocidas
• Investigar mensajes de error
• Comprobar las prácticas recomendadas actuales

web_fetch

Capacidades:

• Recuperar el contenido de páginas web
• Analizar contenido con consultas específicas
• Extraer información estructurada

Casos de uso:

• Leer páginas de documentación
• Analizar la documentación de API
• Extraer ejemplos de tutoriales

Formatos de datos

Archivos de compilación y paquetes

Eficiencia de file_read

Prácticas recomendadas:

• Usa rangos de líneas para archivos de más de 500 líneas y evita saturar el contexto
• Lee solo las secciones relevantes para la tarea
• Para archivos grandes, usa primero grep_content para identificar los números de línea relevantes

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

Precisión de file_edit

Prácticas recomendadas:

• Asegura coincidencias exactas de cadenas para evitar ediciones fallidas
• Para varios cambios similares, usa la opción multiple=true
• Verifica las rutas de los archivos antes de editar

Seguridad de file_write

Prácticas recomendadas:

• Verifica dos veces las rutas para evitar sobrescrituras accidentales
• Úsala solo para archivos nuevos o reescrituras completas
• Para modificaciones, prefiere file_edit por seguridad

Especificidad de los patrones glob

Prácticas recomendadas:

• Usa patrones específicos para acotar el alcance: src/**/*.ts en lugar de **/*
• Excluye directorios con patrones de exclusión: !**/node_modules/**
• Limita los resultados para evitar una salida abrumadora

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

Estrategia de grep

Flujo de trabajo recomendado:

1. Usa grep_file para identificar archivos relevantes
2. Lee archivos específicos con file_read
3. Usa grep_content cuando necesites el contexto circundante

Consejos de rendimiento:

• Los patrones regex pueden tardar más que las cadenas literales
• Las búsquedas sin distinción de mayúsculas son más lentas
• Limita las líneas de contexto (-A, -B) a lo necesario

Prácticas recomendadas de bash

Ejecución segura de comandos:

• Proporciona resúmenes claros para las descripciones de los comandos
• Establece tiempos de espera apropiados para operaciones de larga duración
• Encadena comandos dependientes con &&
• Revisa con cuidado los comandos destructivos (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Consideraciones de seguridad

Reglas de seguridad críticas:

• Los comandos se ejecutan con los permisos del usuario
• Nunca ejecutes comandos no confiables
• Usa Manual Accept Mode para revisión en bases de código compartidas
• Evita comandos que expongan credenciales o datos sensibles

Eficiencia en la delegación a subagentes

Cuándo usar subagentes:

• Explorer: Búsquedas en la base de código, preguntas de arquitectura (ahorra contexto principal)
• Verifier: Comprobaciones rápidas de validación (verificación aislada)
• Code-reviewer: Revisiones de seguridad y calidad (análisis detallado)
• General: Tareas complejas de varios pasos (ejecución en paralelo)

Práctica recomendada: Delega tareas exploratorias y de investigación en subagentes para preservar el contexto de la conversación principal para el trabajo de desarrollo activo.

Gestión del contexto

Uso estratégico de las herramientas:

• Lee archivos de forma estratégica: solo lo necesario
• Usa subagentes para investigación en segundo plano
• Monitorea el consumo de contexto durante sesiones largas
• Divide operaciones complejas en pasos con todo_update

Flujos de trabajo eficientes:

1. Planificación: Usa glob/grep para identificar el alcance
2. Lectura: Lee solo los archivos/secciones relevantes
3. Ejecución: Delega en subagentes cuando sea apropiado
4. Verificación: Comprobaciones rápidas con el subagente Verifier

Límites de tamaño de archivo

Manejo de archivos grandes: Los archivos muy grandes (>10.000 líneas) deben leerse en secciones para evitar:

• Agotamiento de la ventana de contexto
• Tiempos de respuesta lentos
• Problemas de memoria

Tiempos de espera predeterminados de las herramientas

Límites de las herramientas:

• Tiempo de espera de Bash: 120 segundos (2 minutos) como máximo
• Operaciones con archivos: Sin límites de tamaño (los archivos grandes se leen automáticamente por lotes)
• Manejo de archivos grandes: Los archivos >256KB devuelven solo los primeros 256KB de contenido
• Resultados de búsqueda: Sin límites en los resultados de glob o grep_content
• Subagentes concurrentes: Sin límites en la ejecución en paralelo

Configuración de tiempo de espera:

• Establece tiempos de espera explícitos para operaciones de larga duración
• Monitorea posibles procesos colgados
• Los comandos que superen el tiempo de espera de 2 minutos se terminarán

Operaciones concurrentes

Ejecución en paralelo: Varios subagentes pueden ejecutarse en paralelo para acelerar operaciones complejas. El agente principal gestiona la coordinación automáticamente.

Beneficios de rendimiento:

• Reducción del tiempo total de ejecución en tareas de varios pasos
• Utilización eficiente de los recursos
• Orquestación automática de tareas
• Sin límites en el número de subagentes concurrentes