Subagentes de Claude Code: guía práctica para delegar trabajo de forma segura

Cuando un trabajo en Claude Code crece, lo primero que suele fallar no es el modelo. Falla la forma en que dividimos el trabajo. Si una sola conversación intenta investigar, escribir, traducir, editar código, ejecutar comprobaciones y revisar diez archivos localizados, el contexto se llena de ruido. El agente vuelve a leer los mismos archivos, los logs ocupan espacio y el cierre termina siendo demasiado vago.

Los subagentes ayudan porque permiten delegar tareas acotadas en un contexto separado. Delegar no significa “que otro agente lo resuelva todo”. Significa entregar un contrato pequeño: objetivo, archivos permitidos, archivos prohibidos, criterio de finalización y formato de respuesta. Ese contrato evita que el trabajo paralelo se convierta en trabajo duplicado.

Esta guía usa ejemplos del flujo de ClaudeCodeLab: crear un artículo canonical en japonés, localizarlo a diez idiomas, comprobar prompts reutilizables y revisar riesgos antes de publicar. El mismo patrón sirve para cambios de código, documentación, migraciones y preparación de releases.

Qué es un subagente

Un subagente es un trabajador especializado que se ejecuta fuera del contexto de la conversación principal. Contexto significa la memoria de trabajo que Claude ve en ese momento: chat, archivos leídos, salidas de comandos, reglas del proyecto y resúmenes. Si una tarea genera muchas búsquedas o logs, conviene que un subagente haga la lectura pesada y devuelva solo lo útil.

Para la referencia oficial, consulta la documentación de Claude Code sobre subagents, memory y slash commands. En la práctica, recuerda esto: los subagentes arrancan con contexto aislado, los agentes de proyecto pueden vivir en .claude/agents/, y una respuesta final demasiado larga también consume contexto al volver al hilo principal.

Término	Significado práctico
subagente	Trabajador especializado para investigar, implementar, traducir o revisar
contexto	Memoria de trabajo visible para Claude
disjoint write set	Conjunto de archivos editables que no se solapa con otro trabajador
explorer	Agente de investigación en modo solo lectura
worker	Agente que edita solo los archivos asignados
handoff contract	Contrato de alcance, restricciones, finalización y formato de entrega

Cuándo delegar

No uses subagentes por costumbre. Una tarea pequeña puede volverse más lenta si cada agente tiene que reconstruir contexto. La pregunta correcta es doble: si vale la pena separar el contexto y si el área de edición se puede dividir sin solapamientos.

Trabajo	¿Delegar?	Motivo
Localizar un artículo a diez idiomas	Sí	Cada idioma tiene archivo propio y criterios claros
Explorar un código grande para encontrar patrones	Sí	El hilo principal necesita el mapa, no todos los resultados
Corregir una errata en un archivo	No	La coordinación pesa más que el trabajo
Refactor de autenticación en varios módulos	Depende	Primero conviene usar un explorer
Nueva función con requisitos confusos	Todavía no	Primero hay que aclarar la intención en el hilo principal

Mi regla práctica: delega si la tarea produce mucho material intermedio, si puedes limitar a cada worker a archivos concretos y si el resultado puede volver como tabla, checklist o recibo breve.

Patrón base: explorer, worker, reviewer

Para trabajos importantes, no empieces con varios agentes editando. Primero usa un explorer. Lee en modo solo lectura, identifica archivos relevantes, convenciones y riesgos, y propone write sets. Luego los workers editan rangos separados. Al final, un reviewer o verification agent revisa el resultado sin tocar archivos.

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

Este orden evita el fallo más común: varios agentes editan los mismos archivos porque la instrucción inicial era demasiado amplia.

Caso 1: producción de artículos localizados

En ClaudeCodeLab, el flujo más seguro es cerrar primero el artículo canonical en japonés y después localizar la guía completa. Si el canonical es superficial, las traducciones también lo serán. Si incluye ejemplos, fallos, plantillas y CTA, cada idioma puede mantener sustancia sin sonar mecánico.

Rol	Archivos permitidos	Trabajo
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	Crear estructura, ejemplos, prompts y CTA
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	Localizar de forma natural sin resumir
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	Adaptar términos a lectores locales
review-agent	los diez archivos del slug, solo lectura	Revisar frontmatter, mojibake, enlaces, fences y riesgo editorial

Prompt listo para copiar:

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

Caso 2: verificar ejemplos de código dentro del artículo

El autor del artículo y el agente de verificación no deben cumplir la misma función. El autor construye la explicación; el verification agent extrae bloques de código, comprueba sintaxis, valida rutas y dice qué se puede copiar con confianza.

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

Este ejemplo puede vivir como .claude/agents/article-reviewer.md. El name debe ser único y la description debe explicar cuándo usarlo. Evita convertir el prompt en una política enorme; las reglas persistentes encajan mejor en CLAUDE.md o en una checklist de equipo. Para más contexto, consulta la guía de gestión de contexto y las buenas prácticas de CLAUDE.md.

Caso 3: cambios de código con write sets separados

El mismo patrón funciona para código. Imagina un sitio de blog donde hay que tocar las tarjetas de artículos, la generación de OGP y la lógica de posts relacionados. Están conectados, pero se pueden editar por separado.

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

“Mejora la UI en paralelo” es un prompt débil. Un prompt fuerte nombra los archivos permitidos, los archivos prohibidos y la evidencia que debe volver.

Caso 4: revisión y verificación en modo solo lectura

El último agente muchas veces debe ser de solo lectura. Un reviewer busca valor para el lector, huecos SEO, contenido duplicado y riesgos de publicación. Un verification agent revisa metadata, enlaces, comandos, code fences y señales de build roto.

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

Esto es muy útil en publicaciones multilingües. Un idioma puede sonar natural pero tener una fecha antigua, un fence sin cerrar o un CTA ausente. Para código, combínalo con la checklist de revisión de Claude Code.

Plantillas de delegación

Prompt de orquestación:

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

Prompt para investigación:

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

Prompt para implementación aislada:

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

Fallos frecuentes

El primer fallo es paralelizar antes de crear límites. Si tres workers reciben “mejora el artículo”, todos tocarán título, introducción, ejemplos y CTA. Hay más diffs, pero menos control.

El segundo fallo es devolver demasiado contenido. El subagente protege el contexto mientras trabaja, pero su resultado final vuelve al hilo principal. Pide decisiones, tablas y recibos, no logs completos.

El tercer fallo es un contrato pobre. “Traduce natural” no basta. Especifica que no debe resumir, que debe preservar frontmatter, mantener los fallos, usar términos SEO locales y señalar frases que requieran revisión humana.

El cuarto fallo es dejar que el implementador valide sus propias suposiciones. El reviewer debe leer con escepticismo y empezar por los hallazgos.

El quinto fallo es olvidar cómo se cargan los agentes. Los archivos en .claude/agents/ pueden requerir una sesión nueva para quedar disponibles. Para agentes reutilizables, una definición breve en archivo suele ser más mantenible que un prompt de CLI enorme.

Reglas de presupuesto de contexto

Los subagentes solo ahorran contexto si limitas lo que devuelven.

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

El producto final puede ser largo; el handoff debe ser corto. Si mezclas ambos, la conversación principal se llena de borradores, notas de traducción y logs de verificación.

Subagente revisor listo para copiar

El primer subagente más seguro es un revisor de solo lectura. El script crea .claude/agents/article-reviewer.md; puede inspeccionar borradores y señalar riesgos, pero no editar archivos, así que añade revisión crítica sin aumentar el riesgo de escritura.

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

Checklist de delegación

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

Resultado al probarlo

En el trabajo editorial de ClaudeCodeLab, la mayor mejora no fue traducir más rápido. Fue separar el canonical, los workers de idioma y el reviewer de solo lectura. Antes era fácil terminar con un idioma sólido y nueve versiones delgadas. Con reglas explícitas de “no resumir”, write sets fijos y recibos de verificación, la revisión final se vuelve mucho más concreta.

Si tu equipo está adoptando Claude Code, enseña los subagentes como una técnica de diseño del trabajo, no como un interruptor mágico de automatización. ClaudeCodeLab organiza estos contratos de delegación, rúbricas de revisión y hábitos de contexto en training y product templates para equipos.