Claude Sub-Agents: Como parei de conversar com IA e comecei a delegar trabalho

TL;DR

Depois de meses usando Claude Code, percebi que a maioria das pessoas usa IA como um chat glorificado. A virada de chave acontece quando você para de conversar e começa a delegar. Sub-agents são a forma de fazer isso de forma estruturada.

O que são: Agentes especializados com responsabilidades bem definidas, invocados via / no Claude Code.

Por que usar: Consistência, qualidade e contexto limpo. Cada agente é expert em uma coisa e roda em seu próprio contexto.

O ganho oculto: Seu contexto principal não satura. Sub-agents rodam isolados, preservando a "memória de trabalho" da conversa principal.

Resultado: Code reviews melhores, documentação consistente, conversas mais longas sem degradação, e menos retrabalho.

Tempo de leitura: ~20 minutos.

A evolução: chat → prompt → agente → sub-agent

Quando comecei a usar IA para programação, minha interação era assim:

1- Eu: "Me ajuda a fazer um endpoint de login"
2- IA: *gera código genérico*
3___
4- Eu: "Não, precisa ter rate limiting"
5- IA: *refaz*
6___
7- Eu: "Esqueceu o logging"
8- IA: *refaz de novo*

Isso é usar IA como um estagiário confuso que precisa de microgerenciamento constante.

A próxima fase foi criar prompts melhores - instruções mais detalhadas, contexto mais rico. Funcionava melhor, mas ainda era uma conversa de ida e volta.

Agentes foram o próximo salto. Um agente tem:

• Goal: O que ele precisa alcançar
• Context: Informações que ele precisa saber
• Constraints: Limites do que ele pode/deve fazer
• Tools: O que ele tem disponível para usar

Mas quando você tem múltiplas responsabilidades diferentes, um agente único vira um monstro cheio de instruções conflitantes. É aí que entram os sub-agents.

O que são sub-agents no Claude Code

Sub-agents são agentes especializados que você pode invocar dentro do Claude Code usando o comando /. Cada um tem uma responsabilidade única e bem definida.

A analogia que funciona pra mim: pense em um time de engenharia. Você não pede pro mesmo dev fazer code review, escrever documentação, otimizar performance E configurar infra. Você tem especialistas.

Sub-agents são esses especialistas. O code-reviewer só faz review. O doc-writer só escreve docs. O security-auditor só analisa segurança.

1# Focused code review
2/code-reviewer analyze file payment_processor.go
3
4# Security analysis
5/security-auditor check vulnerabilities in auth module
6
7# Documentation generation
8/doc-writer create ADR for Redis cache decision
9
10# Go specialist
11/golang-expert optimize ProcessBatch function to reduce allocations

A mágica não está na tecnologia, está na separação de responsabilidades. Cada agente pode ter instruções específicas, exemplos específicos, e constraints específicas para seu domínio.

Quick Start: Seu primeiro sub-agent em 5 minutos

Quer testar agora antes de continuar lendo? Faça isso:

1# 1. Create agents folder
2mkdir -p ~/.claude
3
4# 2. Create your first agent
5cat > ~/.claude/code-reviewer.md << 'EOF'
6# Code Reviewer
7
8## Role
9You are a senior code reviewer.
10
11## Focus
12- Obvious bugs
13- Error handling
14- Poor naming
15- Untreated edge cases
16
17## Output Format
18| Severity | Line | Issue | Suggestion |
19|----------|------|-------|------------|
20| 🔴/🟡/🟢  | N    | ...   | ...        |
21
22## Example
23| Severity | Line | Issue | Suggestion |
24|----------|------|-------|------------|
25| 🔴 Critical | 42 | Error ignored | Add err check |
26EOF
27
28echo "✅ Agent created!"
29
30# 3. Test it now!
31# Open Claude Code and type:
32# /code-reviewer analyze [your file]

Funcionou? Ótimo! Agora continue lendo para entender como isso funciona e como criar agentes mais sofisticados.

Não funcionou? Verifique:

• O arquivo está em ~/.claude/code-reviewer.md (caminho absoluto)
• O arquivo tem extensão .md
• Claude Code está aberto (reinicie se necessário)

O ganho oculto: preservação de contexto

Aqui está algo que pouca gente fala, mas que faz uma diferença enorme na prática: sub-agents rodam em contextos isolados.

O problema do contexto saturado

Toda conversa com IA tem um limite de contexto (a "janela" de tokens que ela consegue processar). Quando você usa um único agente para tudo, cada interação consome parte desse contexto:

Conforme a conversa avança, o contexto vai enchendo. Quando atinge o limite:

• A IA começa a "esquecer" partes antigas da conversa
• Respostas ficam menos precisas
• Você precisa repetir contexto que já deu antes
• Eventualmente precisa começar uma conversa nova

A solução: contextos isolados

Com sub-agents, cada agente roda em seu próprio contexto. O contexto principal só guarda o essencial: o resultado final de cada sub-agent, não todo o processo.

Impacto real na prática

Exemplo concreto: Em um projeto grande, depois de ~40 interações com agente único, comecei a notar que o Claude "esquecia" decisões anteriores. Com sub-agents, cheguei a 150+ interações na mesma sessão sem degradação perceptível.

O motivo é simples: cada sub-agent processa sua tarefa em isolamento, e só o resultado condensado volta pro contexto principal. É como ter uma equipe que te entrega relatórios executivos ao invés de te incluir em todas as reuniões.

Por que isso importa: o princípio da responsabilidade única

Se você trabalha com arquitetura de software, conhece o SRP (Single Responsibility Principle). Um módulo deve ter apenas um motivo para mudar.

O mesmo princípio se aplica a agentes de IA:

É a diferença entre um monolito e microserviços, mas para IA.

Quando não usar sub-agents

Sub-agents não são silver bullet. Tem situações onde não fazem sentido:

Configurando sub-agents no Claude Code

O Claude Code permite configurar sub-agents através de arquivos markdown na pasta .claude/. Cada arquivo define um agente com suas instruções.

Estrutura básica

1tree .claude/
2
3# Create initial structure
4mkdir -p .claude
5touch .claude/code-reviewer.md
6touch .claude/golang-expert.md
7touch .claude/doc-writer.md
8touch .claude/security-auditor.md

Cada arquivo segue um formato simples:

1# Code Reviewer
2
3## Role
4You are a senior code reviewer specialized in Go and Python.
5
6## Responsibilities
7- Identify bugs and edge cases
8- Suggest readability improvements
9- Verify adherence to project standards
10- Point out performance issues
11
12## Guidelines
13- Be specific: point out line and file
14- Explain the "why" of each suggestion
15- Prioritize: critical > important > nice-to-have
16- Don't rewrite entire code, suggest targeted changes
17
18## Output Format
19For each issue found:
201. Severity (critical/important/suggestion)
212. File and line
223. Identified problem
234. Correction suggestion
245. Justification
25
26## Examples
27[good review examples here]

Os agentes que uso no dia a dia

Vou compartilhar os principais sub-agents que configuro em projetos Go/Python.

1# Code Reviewer
2
3## Role
4Code reviewer focused on quality and maintainability.
5
6## Focus Areas
7- Race conditions and concurrency issues
8- Proper error handling
9- Naming and readability
10- Cyclomatic complexity
11- Missing tests
12
13## What I Don't Do
14- Reformat code (leave it to the linter)
15- Discuss personal style
16- Suggest massive refactorings without context
17
18## Review Checklist
19- [ ] Are errors handled, not ignored?
20- [ ] Are names descriptive?
21- [ ] Do functions have single responsibility?
22- [ ] Are there tests for edge cases?
23- [ ] Is concurrency safe?
24
25## Output Format
26- | Severity | File:Line | Issue | Suggestion |
27- |----------|-----------|-------|------------|
28- | 🔴 Critical | file.go:42 | ... | ...      |
29- | 🟡 Medium   | file.go:87 | ... | ...      |
30- | 🟢 Suggestion| file.go:123 | ... | ...    |
31```

1# Golang Expert
2
3## Role
4Go specialist focused on idiomatic and performant code.
5
6## Expertise
7- Concurrency patterns (goroutines, channels, sync)
8- Idiomatic error handling
9- Interface design
10- Performance optimization
11- Standard library
12
13## Guidelines
14- Prefer stdlib when possible
15- Channels for communication, mutexes for state
16- Errors are values, treat them as such
17- Small and focused interfaces
18- Context in all I/O operations
19
20## Anti-patterns I Flag
21- init() with side effects
22- Goroutine leaks
23- Race conditions
24- Panic in library code
25- Interface pollution
26
27## Code Patterns I Recommend
28```go
29// ✅ Idiomatic error handling
30if err != nil {
31    return fmt.Errorf("failed to process: %w", err)
32}
33
34// ✅ Context propagation
35func DoWork(ctx context.Context) error {
36    select {
37    case <-ctx.Done():
38        return ctx.Err()
39    default:
40        // work
41    }
42}
43
44// ✅ Graceful shutdown
45g, ctx := errgroup.WithContext(ctx)
46g.Go(func() error { return worker(ctx) })
47```

1# Security Auditor
2
3## Role
4Security analyst focused on code and architecture.
5
6## Focus Areas
7- Input validation
8- Authentication/Authorization
9- Secrets management
10- SQL injection
11- XSS/CSRF
12- Dependency vulnerabilities
13
14## Severity Classification
15- | Level | Description | SLA |
16- |-------|-------------|-----|
17- | 🔴 CRITICAL | Immediate exploitation possible | Fix in 24h |
18- | 🟠 HIGH | Significant risk | Fix in 1 week |
19- | 🟡 MEDIUM | Moderate risk | Plan for sprint |
20- | 🟢 LOW | Security improvement | Backlog |
21
22## Output Format
23### Finding #1: [Title]
24- **Severity:** 🔴 CRITICAL
25- **CWE:** CWE-89 (SQL Injection)
26- **File:** user_repository.go:45
27- **Description:** SQL query built with concatenation
28- **PoC:** `' OR '1'='1`
29- **Remediation:** Use prepared statements
30- **Reference:** OWASP Top 10 A03:2021

1# Documentation Writer
2
3## Role
4Technical writer specialized in engineering documentation.
5
6## Document Types
7- ADRs (Architecture Decision Records)
8- READMEs
9- API documentation
10- Runbooks
11- Postmortems
12
13## ADR Template
14When asked to create an ADR, use this format:
15
16# ADR-XXXX: [Descriptive Title]
17
18## Status
19[proposed | accepted | deprecated | superseded by ADR-XXXX]
20
21## Context
22[Why are we making this decision? What problem are we solving?]
23
24## Decision
25[What did we decide to do?]
26
27## Consequences
28### Positive
29- ...
30
31### Negative
32- ...
33
34### Risks
35- ...
36
37## Alternatives Considered
381. **[Alternative 1]**: [Why we didn't choose it]
392. **[Alternative 2]**: [Why we didn't choose it]
40
41## References
42- [Relevant links]
43
44## Writing Style
45- Straight to the point
46- Concrete examples
47- Avoid unnecessary jargon
48- Links to references

Exemplo prático: workflow de code review

Vou mostrar como uso sub-agents em um workflow real de code review.

Cenário: Recebi um PR com uma nova feature de processamento de pagamentos.

Passo 1: Review geral

1/code-reviewer analyze PR #123
2
3Special focus on:
4- Error handling
5- Edge cases
6- Tests

O code-reviewer retorna uma lista estruturada de issues, priorizadas por severidade.

Passo 2: Análise de segurança

1/security-auditor check payment code
2
3Context: This code processes financial transactions
4and interacts with Stripe external API.

O security-auditor foca em vulnerabilidades específicas: validação de input, secrets, logging de dados sensíveis.

Passo 3: Verificação Go-específica

1/golang-expert review concurrency patterns
2in file payment_processor.go
3
4Specifically:
5- Worker pool implementation
6- Channel usage
7- Error propagation

O golang-expert encontra um potencial goroutine leak e sugere usar errgroup.

Resultado: Três perspectivas diferentes, cada uma focada no que faz melhor. E o mais importante: meu contexto principal não saturou com os detalhes de cada análise - recebi apenas os resultados condensados.

Arquitetura de sub-agents: design patterns

Depois de usar sub-agents por alguns meses, identifiquei alguns patterns que funcionam bem.

Pattern 1: Orquestrador + Especialistas

Pattern 2: Pipeline de Validação

Pattern 3: Especialistas em Paralelo

Quando as análises são independentes, rode em paralelo:

1# Parallel execution (if your setup allows)
2/code-reviewer analyze payment.go &
3/security-auditor scan payment.go &
4/golang-expert optimize payment.go &
5
6# Wait for all to complete
7wait
8
9# Consolidate results

Armadilhas comuns

1. Too generic agents

1# ❌ Bad: General Helper
2You help with anything programming related.

This is basically having no agent at all. The more specific, the better.

2. Conflicting instructions

1# ❌ Bad: Mixed Responsibilities
2- Review code
3- Write tests
4- Optimize performance
5- Document APIs

Each of these should be a separate agent.

3. Lack of examples

Agents learn a lot from examples. An agent with zero examples produces inconsistent output.

1## ✅ Good: With examples
2
3### Example Output
4
5- | Severity | File:Line | Issue | Suggestion |
6- |----------|-----------|-------|------------|
7- | 🔴 Critical | auth.go:42 | SQL injection via concatenation | Use prepared statements |
8
9### Anti-Example (don't do this)
10
11"The code has some security issues you should look at."

4. Not iterating

Your first agent draft will be bad. The second too. Iterate based on real output until the agent consistently produces what you expect.

Métricas que observo

Como saber se sub-agents estão funcionando? Algumas métricas que acompanho:

O ecossistema: awesome-claude-code-subagents

Se você não quer criar tudo do zero, existe um repositório da comunidade com sub-agents prontos: VoltAgent/awesome-claude-code-subagents.

126 agentes especializados, prontos para usar.

Categorias principais

O repositório organiza os agentes em 10 categorias:

Agentes que uso frequentemente

Dos 126 disponíveis, alguns se tornaram essenciais no meu workflow:

1# Clone the repository
2git clone https://github.com/VoltAgent/awesome-claude-code-subagents.git
3cd awesome-claude-code-subagents
4
5# Copy the agents you want to your project
6cp agents/code-reviewer.md ~/.claude/
7cp agents/golang-pro.md ~/.claude/
8cp agents/security-auditor.md ~/.claude/
9cp agents/technical-writer.md ~/.claude/
10cp agents/devops-engineer.md ~/.claude/
11
12# Verify they were installed
13ls -la ~/.claude/

Top 10 agentes que mais uso:

1. code-reviewer - Review automático de PRs
2. golang-pro - Expert em Go idiomático
3. security-auditor - OWASP top 10, CVEs
4. technical-writer - Docs, ADRs, READMEs
5. devops-engineer - CI/CD, Docker, K8s
6. refactoring-specialist - Limpeza de código técnico debt
7. database-optimizer - Query optimization, indexes
8. performance-engineer - Profiling, bottlenecks
9. git-workflow-manager - Branching, merging, conflicts
10. prompt-engineer - Otimizar prompts de outros agentes

Agentes Meta: orquestrando outros agentes

Uma categoria interessante são os Meta & Orchestration agents - agentes que coordenam outros agentes:

1/multi-agent-coordinator execute full review pipeline
2
3Tasks:
41. Code review (quality)
52. Security audit
63. Performance analysis
74. Documentation check
8
9Run in parallel where possible.

O multi-agent-coordinator decide:

• Quais agentes invocar
• Ordem de execução (paralelo vs sequencial)
• Como consolidar resultados
• Onde há dependências entre agentes

É como ter um "orquestrador de orquestradores".

Customização e extensão

Os agentes do repositório são pontos de partida, não soluções finais. Você deve adaptá-los ao seu contexto:

1# Example: Customizing code-reviewer for your team
2
3# Code Reviewer - Acme Corp Edition
4
5## Role
6Reviewer following Acme Corp standards.
7
8## Our Standards
9- Always use our internal logging lib: `acme/log`
10- Name tests as `TestXxx_Scenario`
11- Max 15 lines per function
12- Mandatory comments on public functions
13
14## Specific Checks
15- [ ] Uses acme/log instead of log.Printf?
16- [ ] Configs come from config.yaml, not hardcoded?
17- [ ] Secrets never in plain text?
18- [ ] DB migrations have rollback?
19
20## Our Tech Stack
21- Go 1.21+
22- PostgreSQL 15
23- Kubernetes 1.28
24- gRPC + Protocol Buffers
25
26[rest of agent...]

Vale a pena usar agentes prontos?

Minha recomendação: Comece com agentes prontos, use por 1-2 semanas, anote o que funciona e o que não funciona, então customize. Não tente criar tudo do zero - você vai reinventar a roda.

Próximos passos

Se você quer começar com sub-agents:

1. Identifique tarefas repetitivas O que você faz toda semana que poderia ser delegado?

2. Comece com um agente Não tente criar 10 de uma vez. Comece com o code-reviewer ou equivalente.

3. Itere baseado em uso real Use por uma semana, anote o que funciona e o que não funciona, ajuste.

4. Expanda gradualmente Adicione novos agentes conforme identificar necessidades.

Referências

• VoltAgent/awesome-claude-code-subagents - Coleção de sub-agents prontos
• Claude Code Documentation - Documentação oficial
• Architecture Decision Records - Padrão de ADRs
• Single Responsibility Principle - Uncle Bob sobre SRP

Usa sub-agents no seu workflow? Tem algum agente customizado que funciona bem? Me conta no X!