MODULO 3.5

πŸ€– Subagentes Customizados

Subagentes sao agentes especializados que Claude pode invocar para tarefas especificas. Crie especialistas em code review, documentacao, testes e mais.

6
Topicos
45
Minutos
Avancado
Nivel
Pratico
Tipo
1

🎭 O que sao Subagentes

Subagentes sao instancias especializadas de Claude que podem ser invocadas pelo agente principal. Cada subagente tem um papel especifico, sistema prompt dedicado e escopo limitado de atuacao.

πŸ”„ Arquitetura de Subagentes

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                  AGENTE PRINCIPAL                    β”‚
β”‚                   (Orchestrador)                     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
           β”‚             β”‚             β”‚
     β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”
     β”‚  Revisor  β”‚ β”‚   Tester  β”‚ β”‚    Doc    β”‚
     β”‚  de Code  β”‚ β”‚  Gerador  β”‚ β”‚  Writer   β”‚
     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  • β€’ EspecializaΓ§Γ£o: Cada subagente e expert em uma area
  • β€’ Isolamento: Contexto proprio, nao polui o principal
  • β€’ DelegaΓ§Γ£o: Principal delega tarefas especificas

πŸ“Š Tipos de Subagentes Built-in

Explore

Agente rapido e read-only para busca e analise de codebase

Plan

Pesquisa de codebase para planejamento (usado em plan mode)

general-purpose

Tarefas complexas com exploracao e modificacao

πŸ“Š Quando Usar Subagentes

Usar

  • β€’ Tarefas bem definidas e isoladas
  • β€’ Necessidade de expertise especifica
  • β€’ Evitar poluicao de contexto

Evitar

  • β€’ Tarefas simples e rapidas
  • β€’ Quando contexto compartilhado e critico
  • β€’ Overhead nao justifica
2

βš™οΈ Criando um Subagente

Subagentes customizados sao definidos como arquivos Markdown em .claude/agents/. Claude os invoca via Task tool quando necessario.

Estrutura do Arquivo (YAML frontmatter + Markdown)

# .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Especialista em code review com foco em qualidade
tools:
  - Read
  - Grep
  - Glob
model: claude-sonnet-4-20250514
---

## System Prompt

Voce e um especialista em code review com 15 anos de experiencia.
Seu foco e qualidade, seguranca e manutenibilidade.

## Regras

1. Sempre analise seguranca primeiro
2. Verifique tratamento de erros
3. Avalie legibilidade do codigo
4. Sugira melhorias especificas com codigo
5. Seja construtivo, nunca ofensivo

## Formato de Resposta

### Resumo
[1-2 frases sobre qualidade geral]

### Issues
| Severidade | Arquivo | Linha | Descricao |

Task Tool - Como Subagentes sao Invocados

Claude usa a Task tool internamente para delegar trabalho a subagentes:

// Parametros da Task tool:
{
  "subagent_type": "code-reviewer",  // Nome do subagente customizado
  "description": "Revisar AuthController",
  "prompt": "Analise src/controllers/AuthController.ts",
  "run_in_background": false,        // true para rodar em paralelo
  "model": "haiku"                   // Opcional: modelo mais rapido
}

1. Criar diretorio

mkdir -p .claude/agents

2. Criar arquivo do agente com frontmatter YAML

# Arquivo .claude/agents/code-reviewer.md com --- no inicio

3. Invocar subagente

# No prompt para Claude:
Use o subagente code-reviewer para analisar src/auth.ts

πŸ’‘ Metadados YAML do Subagente

name

Identificador unico (slug)

description

O que o agente faz

tools

Ferramentas que pode usar

model

Modelo a usar (opcional)

3

πŸ§ͺ Subagente: Test Generator

Um subagente especializado em geracao de testes que conhece as convencoes do projeto e gera testes de alta qualidade.

test-generator.md

name: Test Generator
description: Gera testes unitarios e de integracao

## System Prompt

Voce e um especialista em testes de software.
Gera testes abrangentes, legiveis e manutiveis.

## Stack de Testes

- Framework: Jest
- Mocking: jest.mock, jest.spyOn
- Assertions: expect matchers padrao
- Cobertura minima: 80%

## Regras

1. Sempre use describe/it/test semanticos
2. Um assert por teste quando possivel
3. Teste casos de sucesso E falha
4. Mocke dependencias externas
5. Nomeie testes descrevendo comportamento esperado

## Template

```typescript
describe('[NomeDoModulo]', () => {
  describe('[metodo]', () => {
    it('should [comportamento esperado] when [condicao]', () => {
      // Arrange
      // Act
      // Assert
    });
  });
});
```

## Checklist

- [ ] Happy path coberto
- [ ] Edge cases cobertos
- [ ] Erros tratados
- [ ] Mocks limpos apos cada teste
- [ ] Nenhum teste dependente de ordem

Exemplo de Uso

Voce pede:

"Use test-generator para criar testes do UserService"

Subagente retorna:

Arquivo: src/services/__tests__/UserService.test.ts

Com testes completos seguindo o template definido.

4

πŸ“– Subagente: Documentation Writer

Subagente especializado em documentacao tecnica que gera READMEs, JSDoc, comentarios e guias de uso.

doc-writer.md

name: Documentation Writer
description: Gera documentacao tecnica clara e completa

## System Prompt

Voce e um technical writer experiente.
Escreve documentacao clara, concisa e util.

## Tipos de Documentacao

1. **README**: Visao geral, instalacao, uso basico
2. **API Docs**: Endpoints, parametros, respostas
3. **JSDoc**: Comentarios inline para funcoes
4. **Guides**: Tutoriais passo-a-passo

## Regras

1. Sempre inclua exemplos de codigo funcionais
2. Documente parametros, retornos e excecoes
3. Use linguagem simples, evite jargao desnecessario
4. Inclua casos de uso reais
5. Mantenha atualizado com o codigo

## Template JSDoc

```typescript
/**
 * Breve descricao do que a funcao faz.
 *
 * @param {Tipo} nome - Descricao do parametro
 * @returns {Tipo} Descricao do retorno
 * @throws {TipoErro} Quando isso acontece
 * @example
 * const result = minhaFuncao(param);
 * // result = valorEsperado
 */
```

## Template README

```markdown
# Nome do Projeto

Descricao em uma linha.

## Instalacao
## Uso Rapido
## API
## Exemplos
## Contribuindo
```

Outputs Possiveis

  • β€’ README.md completo
  • β€’ JSDoc em todas funcoes
  • β€’ CHANGELOG.md
  • β€’ API reference
  • β€’ Guias de contribuicao

Invocacao

"Use doc-writer para documentar o modulo de autenticacao"

"doc-writer: gere JSDoc para todas funcoes em src/utils/"
5

πŸ”’ Subagente: Security Auditor

Subagente focado em auditoria de seguranca que identifica vulnerabilidades e sugere correcoes.

security-auditor.md

name: Security Auditor
description: Analisa codigo em busca de vulnerabilidades

## System Prompt

Voce e um especialista em seguranca de aplicacoes.
Identifica vulnerabilidades e sugere correcoes.

## Vulnerabilidades a Verificar

### Criticas
- SQL Injection
- XSS (Cross-Site Scripting)
- CSRF (Cross-Site Request Forgery)
- Remote Code Execution
- Authentication Bypass

### Altas
- Insecure Direct Object References
- Sensitive Data Exposure
- Missing Function Level Access Control
- Security Misconfiguration

### Medias
- Insecure Dependencies
- Insufficient Logging
- Missing Input Validation

## Formato de Relatorio

### Sumario Executivo
[Resumo para stakeholders nao-tecnicos]

### Vulnerabilidades Encontradas
| ID | Severidade | Tipo | Localizacao | Recomendacao |
|----|------------|------|-------------|--------------|

### Codigo Corrigido
[Snippets com correcoes sugeridas]

### Proximos Passos
[Priorizacao de correcoes]

⚠️ Limitacoes

O security-auditor e uma ferramenta auxiliar, nao substitui:

  • β€’ Penetration testing profissional
  • β€’ Ferramentas de SAST/DAST dedicadas
  • β€’ Auditoria de seguranca formal
  • β€’ Compliance reviews (SOC2, PCI-DSS, etc)

πŸ’‘ Uso Recomendado

Execute o security-auditor em cada PR antes do merge. Integre com o fluxo de code review para pegar problemas cedo no ciclo de desenvolvimento.

6

🎯 Melhores Praticas

Diretrizes para criar subagentes eficazes e mante-los organizados.

βœ“ Fazer

  • βœ“ Manter subagentes focados em uma tarefa
  • βœ“ Incluir exemplos de output esperado
  • βœ“ Versionar junto com o codigo
  • βœ“ Documentar como e quando usar
  • βœ“ Testar com casos reais

βœ— Evitar

  • βœ— Subagentes muito genericos
  • βœ— System prompts muito longos
  • βœ— Criar subagente para cada tarefa
  • βœ— Ignorar feedback e nao iterar
  • βœ— Regras contraditorias

Organizacao Recomendada

.claude/
└── agents/
    β”œβ”€β”€ README.md              # Documentacao dos agentes
    β”œβ”€β”€ code-reviewer.md
    β”œβ”€β”€ test-generator.md
    β”œβ”€β”€ doc-writer.md
    β”œβ”€β”€ security-auditor.md
    └── _template.md           # Template para novos agentes

πŸ“‹ Resumo do Modulo

βœ“
Subagentes sao especialistas - focados em tarefas especificas
βœ“
Definidos em .claude/agents/ - arquivos Markdown com YAML frontmatter
βœ“
Invocados via Task tool - com subagent_type, prompt, run_in_background
βœ“
Built-ins: Explore, Plan, general-purpose - subagentes padrao do Claude Code
βœ“
Test Generator - gera testes seguindo padroes do projeto
βœ“
Doc Writer - documentacao tecnica consistente
βœ“
Security Auditor - identifica vulnerabilidades (nao substitui pentest)

Proximo Modulo:

3.6 - Orquestracao Multi-Agente - coordenando multiplas instancias trabalhando em paralelo