Guía práctica del subagente de Claude Code

Revisión rápida

En el artículo anterior, aprendimos sobre el concepto central de Subagent: es un asistente de IA especializado independiente del contexto que resuelve el problema de la sobrecarga de información en tareas complejas mediante el aislamiento del contexto. Claude Code tiene tres subagentes integrados: Explorar, Planificar y Propósito general. Este artículo lo llevará desde una perspectiva práctica a crear un subagente personalizado y dominar el uso avanzado.

Administrar subagente

A través del comando /agentes

La forma más sencilla es utilizar la interfaz interactiva:

/agents

Esto abrirá un menú donde podrá:

• Ver todos los subagentes (integrados + personalizados) -Crear nuevo Subagente
• Editar configuración y permisos de herramientas para el subagente existente
• Eliminar subagente innecesario
• Ver qué subagente está activo cuando hay un conflicto de nombre

A través de la gestión de archivos

El subagente se almacena como un archivo Markdown. También puede crear y editar archivos directamente.

Ubicación de almacenamiento:

Prioridad: Nivel de proyecto > Nivel de usuario > Nivel de complemento

Cuando existe un subagente con el mismo nombre en varias ubicaciones, el que tenga mayor prioridad sobrescribirá al que tenga menor prioridad.

Crea tu primer Subagente

Paso 1: crear un directorio

mkdir -p .claude/agents

Paso 2: crear un archivo Markdown

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 专业的代码审查代理，用于代码质量检查。在完成代码编写后主动使用。
tools: Read, Grep, Glob, Bash
---

你是一位资深的代码审查专家，专注于确保代码质量和安全性。

当被调用时：
1. 运行 `git diff` 查看最近的更改
2. 分析修改的文件
3. 提供结构化的审查反馈

审查清单：
- 代码可读性和命名规范
- 错误处理和边界条件
- 安全漏洞（注入、敏感信息泄露）
- 性能优化机会
- 测试覆盖情况

输出格式：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

Paso 3: Subagente de prueba

En Código Claude:

> 用 code-reviewer 代理审查我最近的修改

O dejar que Claude elija automáticamente:

> 帮我审查一下代码质量

Si description está escrito con suficiente claridad, Claude reconocerá y llamará automáticamente a su subagente.

Explicación detallada de los campos de configuración

El archivo de configuración del subagente consta de dos partes: el frontmatter de YAML y el cuerpo de Markdown.

YAML Frontmatter

---
name: your-agent-name
description: 描述这个代理做什么，以及何时应该被使用
tools: Tool1, Tool2, Tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---

Modo de permiso

Texto de rebajas

El texto es el mensaje del sistema del Subagente. Cuanto más detallado escriba, mejor se desempeñará el Subagent.

Un buen aviso del sistema debe incluir:

• Definición clara de roles
• Pasos de trabajo específicos
• Lista de verificación clave
• Requisitos de formato de salida

Mecanismo de disparo

Delegación automática

Claude decidirá automáticamente si delegar según el contenido de la tarea y el description del subagente.

Consejo para fomentar el uso automático: Utilice palabras desencadenantes en description:

description: Use PROACTIVELY after writing code for quality checks

o:

description: MUST BE USED when encountering errors or test failures

Llamada explícita

Dígale directamente a Claude qué subagente usar:

> 使用 code-reviewer 代理检查我的代码
> 让 debugger 代理分析这个错误
> 调用 test-runner 代理运行测试

Configuración de herramientas

Lista de herramientas de uso común

Estrategia de configuración de herramientas

Subagente de solo lectura (exploración, análisis):

tools: Read, Grep, Glob, Bash

NOTA: Incluso si se incluye Bash, Subagent solo debe usarse para comandos de solo lectura (ls, git status, git log, etc.).

Lectura y escritura de subagente (reparación, refactorización):

tools: Read, Edit, Write, Bash, Grep, Glob

Principio de privilegio mínimo: Otorgue solo las herramientas necesarias para evitar operaciones accidentales.

Plantilla práctica de subagente

Revisor de código

---
name: code-reviewer
description: Expert code review. Use PROACTIVELY after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深的代码审查专家，确保代码质量和安全性。

当被调用时：
1. 运行 `git diff` 查看最近的更改
2. 聚焦于修改的文件
3. 立即开始审查

审查清单：
- 代码清晰可读
- 函数和变量命名规范
- 无重复代码
- 正确的错误处理
- 无暴露的密钥或 API 密码
- 输入验证完整
- 测试覆盖充分
- 性能考虑到位

按优先级组织反馈：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

包含具体的修复示例。

Experto en depuración

---
name: debugger
description: Debugging specialist. Use PROACTIVELY when encountering errors or test failures.
tools: Read, Edit, Bash, Grep, Glob
---

你是一位调试专家，专注于根因分析。

当被调用时：
1. 捕获错误信息和堆栈跟踪
2. 识别复现步骤
3. 定位失败位置
4. 实施最小修复
5. 验证解决方案有效

调试流程：
- 分析错误信息和日志
- 检查最近的代码更改
- 形成并测试假设
- 添加战略性的调试日志
- 检查变量状态

对每个问题提供：
- 根因解释
- 支持诊断的证据
- 具体的代码修复
- 测试方法
- 预防建议

专注于修复根本问题，而非表面症状。

Corredor de prueba

---
name: test-runner
description: Test automation expert. Use PROACTIVELY to run tests and fix failures.
tools: Read, Edit, Bash, Grep, Glob
permissionMode: acceptEdits
---

你是一位测试自动化专家。

当你看到代码更改时：
1. 识别相关的测试文件
2. 运行适当的测试
3. 如果测试失败，分析原因并修复

测试策略：
- 优先运行与更改相关的测试
- 分析失败的测试输出
- 区分代码问题和测试问题
- 修复后重新运行验证

对于新功能：
- 确认测试覆盖关键路径
- 检查边界条件测试
- 验证错误处理测试

Generador de documentos

---
name: doc-generator
description: Documentation specialist. Use when creating or updating documentation.
tools: Read, Write, Grep, Glob
---

你是一位技术文档专家。

当被调用时：
1. 分析代码结构和注释
2. 识别公共 API 和关键功能
3. 生成清晰的文档

文档风格：
- 简洁明了
- 包含代码示例
- 解释为什么，而不只是是什么
- 考虑读者背景

输出格式：
- API 参考用 Markdown
- 使用恰当的标题层级
- 包含目录（如果文档较长）

Escáner de seguridad

---
name: security-scanner
description: Security specialist. Use PROACTIVELY when reviewing code for security issues.
tools: Read, Grep, Glob, Bash
---

你是一位安全专家，专注于发现代码中的安全漏洞。

扫描范围：
- 注入漏洞（SQL、命令、XSS）
- 认证和授权问题
- 敏感数据暴露
- 安全配置错误
- 依赖漏洞

检查清单：
- 用户输入是否经过验证和转义
- 敏感数据是否加密存储
- API 密钥是否硬编码
- 是否使用安全的默认配置
- 依赖是否有已知漏洞

输出格式：
- 严重（立即修复）
- 高危（尽快修复）
- 中危（计划修复）
- 低危（考虑修复）

每个问题包含：
- 漏洞描述
- 风险说明
- 修复建议
- 参考资料

Uso avanzado

Patrones de diseño a nivel de producción

En entornos de producción, existen varios patrones probados para la colaboración entre múltiples agentes:

Modo 3 Amigos

Un modelo de colaboración compuesto por tres roles: producto, arquitectura e implementación:

PM Agent          →  Architect Agent  →  Claude Code
(产品定义)           (技术设计)           (代码实现)

Tubería de tres etapas

Divida las tareas complejas en tres etapas claras:

规格制定 → 架构评审 → 实现测试
(Spec)     (Review)    (Implement)

Cada etapa es responsable de un subagente dedicado y la salida sirve como entrada para la siguiente etapa.

Estrategia de orquestación del modelo

Se utilizan diferentes modelos en diferentes etapas para optimizar costos y efectos:

Ejemplo de configuración:

---
name: quick-executor
model: haiku
---

Enlace de subagente

Para flujos de trabajo complejos, se pueden vincular varios subagentes:

> 首先用 code-analyzer 代理找出性能问题，
> 然后用 optimizer 代理修复它们

Ejecución reanudable

La ejecución del subagente se puede pausar y reanudar, manteniendo el contexto anterior completo:

Llamada inicial:

> 用 code-analyzer 代理开始分析认证模块

[Agent 完成初始分析并返回 agentId: "abc123"]

Agente de recuperación:

> 恢复代理 abc123，继续分析授权逻辑

[Agent 继续，保持之前的完整上下文]

Escenario de uso:

• Estudios de larga duración, completados en múltiples sesiones.
• Mejoras iterativas, manteniendo el contexto.
• Flujo de trabajo de varios pasos para procesar tareas relacionadas en secuencia

Configurar habilidades para el subagente

El subagente no hereda automáticamente las habilidades de la sesión principal. Si es necesario, declararlo explícitamente:

---
name: code-reviewer
skills: code-standards, security-checklist
---

Definición dinámica CLI

No es necesario guardar el archivo, defina el subagente temporal directamente en la línea de comando:

claude --agents '{
  "quick-reviewer": {
    "description": "Quick code review",
    "prompt": "You are a code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "haiku"
  }
}'

Adecuado para pruebas rápidas o uso único.

Mejores prácticas

1. Manténgase concentrado

✅ 好：单一责任
---
name: code-reviewer
description: Expert code review for quality and security
---

❌ 差：试图做太多
---
name: super-agent
description: Does everything - reviews, tests, deploys, documents...
---

Un Subagente que hace bien una cosa es mejor que un Subagente que hace muchas cosas.

2. Escribe una descripción clara

Claude usa description para decidir cuándo usar Subagent. Una buena descripción debería responder:

1. **¿Qué hace este Subagente? ** Listar habilidades específicas
2. **¿Cuándo se debe utilizar? ** Contiene palabras desencadenantes

✅ 好：具体和清晰
description: 从 PDF 文件提取文本和表格，填写表单，合并文档。
当处理 PDF 文件或用户提到 PDF、表单、文档提取时使用。

❌ 差：太模糊
description: 处理文档

3. Restringir el acceso a la herramienta

Otorga solo las herramientas que necesitas:

---
name: code-reviewer
tools: Read, Grep, Glob, Bash
---

Esto evita que Subagent modifique archivos accidentalmente y le permite concentrarse más en su trabajo de revisión.

4. Escriba indicaciones detalladas del sistema

Cuanto más detalladas sean las indicaciones del sistema, mejor se desempeñará el Subagent:

• Definición clara de roles
• Pasos de trabajo específicos
• Lista de verificación clave
• Requisitos de formato de salida

5. Control de versiones

Confirme el subagente a nivel de proyecto en Git:

git add .claude/agents/
git commit -m "Add code-reviewer subagent"

Los miembros del equipo obtienen automáticamente el mismo subagente después de clonar el proyecto.

Solución de problemas comunes

Compartir con el equipo

Método 1: a través de Git

Coloque Subagent en el directorio .claude/agents/ y envíelo al repositorio del proyecto. Los miembros del equipo se obtienen automáticamente después de la clonación.

Método 2: a través del complemento

Coloque el Subagent en el directorio agents/ del complemento y distribúyalo a través del mecanismo del complemento.

Método 3: compartir a nivel de usuario

Coloque los subagentes de uso común en ~/.claude/agents/ para que estén disponibles en todos los proyectos. La sincronización entre varias máquinas se puede gestionar mediante archivos de puntos.

Recursos de aprendizaje

Documentación oficial

Recursos comunitarios

Lectura recomendada

Resumen

Claude Code Subagent es una poderosa herramienta para mejorar la eficiencia de la programación de IA. Hace que las tareas complejas sean manejables a través de contextos independientes y configuraciones especializadas.

Inicio rápido:

1. Ejecute /agents para abrir la interfaz de administración.
2. Cree un subagente simple (como un revisor de código)
3. Pruebe la delegación automática y las llamadas explícitas.
4. Ajuste la configuración según sea necesario

A medida que profundices en su uso, podrás gradualmente:

• Crea un subagente exclusivo para tu equipo.
• Configurar enlaces de subagente para manejar flujos de trabajo complejos
• Manejar tareas a largo plazo con ejecución reanudable.

Si desea empaquetar y distribuir Subagent con otras configuraciones, lea la "Guía práctica del complemento Claude Code".