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:

- Eu: "Me ajuda a fazer um endpoint de login"
- IA: *gera código genérico*
___
- Eu: "Não, precisa ter rate limiting"
- IA: *refaz*
___
- Eu: "Esqueceu o logging"
- 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.

# Focused code review
/code-reviewer analyze file payment_processor.go

# Security analysis
/security-auditor check vulnerabilities in auth module

# Documentation generation
/doc-writer create ADR for Redis cache decision

# Go specialist
/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. Create agents folder
mkdir -p ~/.claude

# 2. Create your first agent
cat > ~/.claude/code-reviewer.md << 'EOF'
# Code Reviewer

## Role
You are a senior code reviewer.

## Focus
- Obvious bugs
- Error handling
- Poor naming
- Untreated edge cases

## Output Format
| Severity | Line | Issue | Suggestion |
|----------|------|-------|------------|
| 🔴/🟡/🟢  | N    | ...   | ...        |

## Example
| Severity | Line | Issue | Suggestion |
|----------|------|-------|------------|
| 🔴 Critical | 42 | Error ignored | Add err check |
EOF

echo "✅ Agent created!"

# 3. Test it now!
# Open Claude Code and type:
# /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

tree .claude/

# Create initial structure
mkdir -p .claude
touch .claude/code-reviewer.md
touch .claude/golang-expert.md
touch .claude/doc-writer.md
touch .claude/security-auditor.md

Cada arquivo segue um formato simples:

# Code Reviewer

## Role
You are a senior code reviewer specialized in Go and Python.

## Responsibilities
- Identify bugs and edge cases
- Suggest readability improvements
- Verify adherence to project standards
- Point out performance issues

## Guidelines
- Be specific: point out line and file
- Explain the "why" of each suggestion
- Prioritize: critical > important > nice-to-have
- Don't rewrite entire code, suggest targeted changes

## Output Format
For each issue found:
1. Severity (critical/important/suggestion)
2. File and line
3. Identified problem
4. Correction suggestion
5. Justification

## Examples
[good review examples here]

Os agentes que uso no dia a dia

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

# Code Reviewer

## Role
Code reviewer focused on quality and maintainability.

## Focus Areas
- Race conditions and concurrency issues
- Proper error handling
- Naming and readability
- Cyclomatic complexity
- Missing tests

## What I Don't Do
- Reformat code (leave it to the linter)
- Discuss personal style
- Suggest massive refactorings without context

## Review Checklist
- [ ] Are errors handled, not ignored?
- [ ] Are names descriptive?
- [ ] Do functions have single responsibility?
- [ ] Are there tests for edge cases?
- [ ] Is concurrency safe?

## Output Format
- | Severity | File:Line | Issue | Suggestion |
- |----------|-----------|-------|------------|
- | 🔴 Critical | file.go:42 | ... | ...      |
- | 🟡 Medium   | file.go:87 | ... | ...      |
- | 🟢 Suggestion| file.go:123 | ... | ...    |
```

# Golang Expert

## Role
Go specialist focused on idiomatic and performant code.

## Expertise
- Concurrency patterns (goroutines, channels, sync)
- Idiomatic error handling
- Interface design
- Performance optimization
- Standard library

## Guidelines
- Prefer stdlib when possible
- Channels for communication, mutexes for state
- Errors are values, treat them as such
- Small and focused interfaces
- Context in all I/O operations

## Anti-patterns I Flag
- init() with side effects
- Goroutine leaks
- Race conditions
- Panic in library code
- Interface pollution

## Code Patterns I Recommend
```go
// ✅ Idiomatic error handling
if err != nil {
  return fmt.Errorf("failed to process: %w", err)
}

// ✅ Context propagation
func DoWork(ctx context.Context) error {
  select {
  case <-ctx.Done():
      return ctx.Err()
  default:
      // work
  }
}

// ✅ Graceful shutdown
g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return worker(ctx) })
```

# Security Auditor

## Role
Security analyst focused on code and architecture.

## Focus Areas
- Input validation
- Authentication/Authorization
- Secrets management
- SQL injection
- XSS/CSRF
- Dependency vulnerabilities

## Severity Classification
- | Level | Description | SLA |
- |-------|-------------|-----|
- | 🔴 CRITICAL | Immediate exploitation possible | Fix in 24h |
- | 🟠 HIGH | Significant risk | Fix in 1 week |
- | 🟡 MEDIUM | Moderate risk | Plan for sprint |
- | 🟢 LOW | Security improvement | Backlog |

## Output Format
### Finding #1: [Title]
- **Severity:** 🔴 CRITICAL
- **CWE:** CWE-89 (SQL Injection)
- **File:** user_repository.go:45
- **Description:** SQL query built with concatenation
- **PoC:** `' OR '1'='1`
- **Remediation:** Use prepared statements
- **Reference:** OWASP Top 10 A03:2021

# Documentation Writer

## Role
Technical writer specialized in engineering documentation.

## Document Types
- ADRs (Architecture Decision Records)
- READMEs
- API documentation
- Runbooks
- Postmortems

## ADR Template
When asked to create an ADR, use this format:

# ADR-XXXX: [Descriptive Title]

## Status
[proposed | accepted | deprecated | superseded by ADR-XXXX]

## Context
[Why are we making this decision? What problem are we solving?]

## Decision
[What did we decide to do?]

## Consequences
### Positive
- ...

### Negative
- ...

### Risks
- ...

## Alternatives Considered
1. **[Alternative 1]**: [Why we didn't choose it]
2. **[Alternative 2]**: [Why we didn't choose it]

## References
- [Relevant links]

## Writing Style
- Straight to the point
- Concrete examples
- Avoid unnecessary jargon
- 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

/code-reviewer analyze PR #123

Special focus on:
- Error handling
- Edge cases
- Tests

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

Passo 2: Análise de segurança

/security-auditor check payment code

Context: This code processes financial transactions
and 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

/golang-expert review concurrency patterns
in file payment_processor.go

Specifically:
- Worker pool implementation
- Channel usage
- 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:

# Parallel execution (if your setup allows)
/code-reviewer analyze payment.go &
/security-auditor scan payment.go &
/golang-expert optimize payment.go &

# Wait for all to complete
wait

# Consolidate results

Armadilhas comuns

1. Too generic agents

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

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

2. Conflicting instructions

# ❌ Bad: Mixed Responsibilities
- Review code
- Write tests
- Optimize performance
- 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.

## ✅ Good: With examples

### Example Output

- | Severity | File:Line | Issue | Suggestion |
- |----------|-----------|-------|------------|
- | 🔴 Critical | auth.go:42 | SQL injection via concatenation | Use prepared statements |

### Anti-Example (don't do this)

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

# Clone the repository
git clone https://github.com/VoltAgent/awesome-claude-code-subagents.git
cd awesome-claude-code-subagents

# Copy the agents you want to your project
cp agents/code-reviewer.md ~/.claude/
cp agents/golang-pro.md ~/.claude/
cp agents/security-auditor.md ~/.claude/
cp agents/technical-writer.md ~/.claude/
cp agents/devops-engineer.md ~/.claude/

# Verify they were installed
ls -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:

/multi-agent-coordinator execute full review pipeline

Tasks:
1. Code review (quality)
2. Security audit
3. Performance analysis
4. Documentation check

Run 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:

# Example: Customizing code-reviewer for your team

# Code Reviewer - Acme Corp Edition

## Role
Reviewer following Acme Corp standards.

## Our Standards
- Always use our internal logging lib: `acme/log`
- Name tests as `TestXxx_Scenario`
- Max 15 lines per function
- Mandatory comments on public functions

## Specific Checks
- [ ] Uses acme/log instead of log.Printf?
- [ ] Configs come from config.yaml, not hardcoded?
- [ ] Secrets never in plain text?
- [ ] DB migrations have rollback?

## Our Tech Stack
- Go 1.21+
- PostgreSQL 15
- Kubernetes 1.28
- gRPC + Protocol Buffers

[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!