π 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
βοΈ 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
2. Criar arquivo do agente com frontmatter YAML
3. Invocar subagente
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)
π§ͺ 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.
π 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
"doc-writer: gere JSDoc para todas funcoes em src/utils/"
π 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.
π― 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
Proximo Modulo:
3.6 - Orquestracao Multi-Agente - coordenando multiplas instancias trabalhando em paralelo