Subagentes no Claude Code: guia prático para delegar trabalho com segurança

Quando um trabalho no Claude Code fica grande, o primeiro problema normalmente não é o modelo. É a forma de dividir o trabalho. Uma única conversa tentando pesquisar, escrever, traduzir, editar código, rodar verificações e revisar dez arquivos localizados fica pesada rapidamente. O agente relê os mesmos arquivos, os logs ocupam o contexto e o fechamento vira um resumo sem evidência.

Subagentes ajudam porque permitem delegar tarefas bem delimitadas para um contexto separado. Delegar, aqui, não significa “deixe outro agente resolver tudo”. Significa entregar um contrato pequeno: objetivo, arquivos permitidos, arquivos proibidos, critério de conclusão e formato da resposta. Esse contrato impede que trabalho paralelo vire trabalho duplicado.

Este guia usa o fluxo editorial do ClaudeCodeLab como exemplo: escrever um artigo canonical em japonês, localizar para dez idiomas, conferir templates de prompt e revisar riscos antes de publicar. O mesmo padrão funciona para mudanças de código, documentação, migrações e preparação de release.

O que é um subagente

Um subagente é um trabalhador especializado que roda fora do contexto da conversa principal. Contexto é a memória de trabalho que Claude enxerga naquele momento: conversa, arquivos lidos, saídas de comandos, regras do projeto e resumos. Se uma tarefa gera muitas buscas ou logs, o subagente pode fazer a leitura pesada e devolver apenas o resumo útil.

Para referência oficial, veja a documentação do Claude Code sobre subagents, memory e slash commands. Na prática, lembre-se: subagentes começam com contexto isolado, agentes de projeto podem ficar em .claude/agents/, e respostas longas demais ainda consomem o contexto principal quando retornam.

Termo	Significado prático
subagente	Trabalhador especializado para pesquisa, implementação, tradução ou revisão
contexto	Memória de trabalho visível para Claude
disjoint write set	Conjunto de arquivos editáveis que não se sobrepõe ao de outro worker
explorer	Agente de pesquisa em modo somente leitura
worker	Agente que edita apenas os arquivos atribuídos
handoff contract	Contrato com escopo, restrições, conclusão e formato de entrega

Quando delegar

Subagentes não devem ser usados por impulso. Uma alteração pequena pode ficar mais lenta se cada agente precisar reconstruir contexto. A pergunta certa é: separar o contexto traz valor, e a área de escrita pode ser dividida sem sobreposição?

Trabalho	Delegar?	Motivo
Localizar um artigo em dez idiomas	Sim	Cada idioma tem arquivo próprio e critérios claros
Explorar uma base grande em busca de padrões	Sim	A conversa principal precisa do mapa, não de todo resultado
Corrigir um erro de digitação	Não	A coordenação custa mais que a mudança
Refatorar autenticação em vários módulos	Talvez	Primeiro use um explorer para mapear impacto
Criar uma feature com requisitos vagos	Ainda não	Primeiro esclareça a intenção na conversa principal

Minha regra prática: delegue quando a tarefa produz muito material intermediário, quando cada worker pode ser limitado a arquivos explícitos e quando o resultado pode voltar como tabela, checklist ou recibo curto.

Padrão central: explorer, worker, reviewer

Para trabalho relevante, não comece com vários agentes editando. Comece com um explorer. Ele lê em modo somente leitura, identifica arquivos importantes, padrões existentes e riscos, e propõe write sets. Depois os workers editam conjuntos separados. No fim, um reviewer ou verification agent confere tudo sem modificar arquivos.

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"]

Essa ordem evita o erro mais comum: vários agentes lendo e editando os mesmos arquivos porque a instrução era ampla demais.

Caso 1: produção de artigos localizados

No ClaudeCodeLab, o fluxo mais seguro é fechar primeiro o artigo canonical em japonês e depois localizar o guia completo. Se o canonical é raso, todas as traduções ficam rasas. Se ele inclui exemplos, armadilhas, templates e CTA, cada idioma mantém substância sem soar como tradução mecânica.

Papel	Arquivos permitidos	Trabalho
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	Criar estrutura, exemplos, prompts e CTA
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	Localizar naturalmente sem resumir
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	Adaptar termos para leitores locais
review-agent	dez arquivos do slug, somente leitura	Conferir frontmatter, mojibake, links, fences e risco editorial

Prompt 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 exemplos de código no artigo

O autor do artigo e o agente de verificação não devem ter o mesmo papel. O autor constrói a explicação. O verification agent extrai blocos de código, confere sintaxe, valida caminhos e informa o que pode ser copiado com segurança.

---
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.

Esse exemplo pode ficar em .claude/agents/article-reviewer.md. O name precisa ser único, e a description deve explicar quando usar o agente. Evite transformar o prompt em uma política enorme; regras persistentes são mais fáceis de manter em CLAUDE.md ou em uma checklist de equipe. Veja também o guia de gerenciamento de contexto e as boas práticas de CLAUDE.md.

Caso 3: mudanças de código com write sets separados

O mesmo padrão funciona para código. Imagine um site de blog que precisa ajustar cards de artigos, geração de OGP e lógica de posts relacionados. As áreas se conectam, mas os arquivos podem ser separados.

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.

“Melhore a UI em paralelo” é um prompt fraco. Um prompt forte nomeia arquivos permitidos, arquivos proibidos e evidências esperadas.

Caso 4: revisão e verificação somente leitura

O último agente muitas vezes deve ser somente leitura. Um reviewer busca valor para o leitor, lacunas de SEO, conteúdo duplicado e armadilhas ausentes. Um verification agent confere metadata, links, comandos, code fences e risco de build.

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.

Isso é muito útil em publicação multilíngue. Um idioma pode soar natural e ainda ter data antiga, fence aberto ou CTA ausente. Para código, combine com a checklist de code review do Claude Code.

Templates de delegação

Prompt de orquestração:

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 de exploração:

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 worker isolado:

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

Falhas comuns

A primeira falha é paralelizar antes de criar limites. Se três workers recebem “melhore o artigo”, todos mexem em título, introdução, exemplos e CTA. O diff cresce, mas o controle diminui.

A segunda falha é devolver conteúdo demais. O subagente protege o contexto enquanto trabalha, mas o resultado final volta para o thread principal. Peça decisões, tabelas e recibos, não logs inteiros.

A terceira falha é um contrato fraco. “Traduza naturalmente” não basta. Especifique “não resumir”, “preservar frontmatter”, “manter armadilhas”, “usar termos SEO locais” e “apontar frases que precisam de revisão humana”.

A quarta falha é pedir ao implementador que valide as próprias premissas. O reviewer deve ler com ceticismo, comparar o resultado com as restrições e começar pelos riscos.

A quinta falha é esquecer como agents são carregados. Arquivos em .claude/agents/ podem exigir nova sessão para ficarem disponíveis. Para agentes reutilizáveis, uma definição curta em arquivo costuma ser melhor que um prompt enorme de uso único.

Regras de orçamento de contexto

Subagentes só economizam contexto se você limitar o retorno.

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.

O entregável pode ser longo. O handoff deve ser curto. Misturar os dois enche a conversa principal com rascunhos, notas de tradução e logs de verificação.

Subagente revisor pronto para copiar

O primeiro subagente mais seguro é um revisor somente leitura. O script abaixo cria .claude/agents/article-reviewer.md; ele pode inspecionar rascunhos e apontar riscos, mas não editar arquivos. Assim você ganha revisão crítica antes da publicação sem ampliar o risco de escrita.

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 delegação

# 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 na prática

No trabalho editorial do ClaudeCodeLab, o maior ganho não foi traduzir mais rápido. Foi separar o canonical, os workers de idioma e o reviewer somente leitura. Antes era comum terminar com um idioma forte e nove versões rasas. Com regras explícitas contra resumo, write sets fixos e recibo de verificação, a revisão final ficou muito mais concreta.

Se sua equipe está adotando Claude Code, ensine subagentes como técnica de desenho de trabalho, não como botão mágico de automação. O ClaudeCodeLab organiza esses contratos de delegação, rubricas de revisão e hábitos de contexto em training e product templates para equipes.