Pular para o conteúdo principal

Fase 3 — Avançado: estendendo o agente

Duração: 4 semanas · Dedicação: 10–12h/semana · Trilhas: essencial para 🔵🟣 · opcional para 🟢 Pré-requisito: Fase 2 concluída (você é fluente no uso diário do Claude Code). Foco principal: Claude Code · Conceitos transferíveis: marcados com 🌐.

Objetivo da fase​

Sair de "uso Claude Code do jeito que vem na caixa" para "customizo e estendo Claude Code para o meu contexto". Você vai aprender a estender a ferramenta com os 7 mecanismos de extensão do Claude Code:

MecanismoLançadoO que estende
MCPNov/2024Acesso a ferramentas externas (DBs, APIs, etc.)
SubagentesJul/2025Especialização e isolamento de contexto
HooksSet/2025Ações deterministicas em eventos
PluginsOut/2025Empacotamento e distribuição
SkillsOut/2025Workflows repetíveis (substituem slash commands antigos)
Agent TeamsFev/2026Orquestração multi-agente nativa
Sandbox2025/26Isolamento de filesystem/rede

Ao final desta fase você consegue:

  • Rodar Claude Code em modo headless integrado a CI/CD
  • Criar servidores MCP customizados para o seu contexto
  • Definir subagentes especializados que economizam contexto
  • Escrever hooks para ações automáticas em eventos
  • Criar slash commands e Skills customizadas e empacotá-las como plugin
  • Publicar (ou usar) plugins via marketplace
  • Operar Claude Code em modo seguro com sandbox e proteção contra prompt injection

Convenções​

  • Tipo: 📚 Doc oficial · 📖 Artigo/Paper · 🎓 Curso · 🎬 Vídeo/Podcast · 🛠️ Hands-on/Repositório
  • Idioma: [PT] português · [EN] inglês
  • Custo: [Grátis] · [Pago] · [Freemium]
  • ⭐ essencial · 🌐 conceito universal (transferível para qualquer agente)

M12 · Modo headless e CI/CD com Claude Code

Por que este módulo​

Modo headless é o que transforma Claude Code em ferramenta de pipeline — não interativo, scriptável, executável em CI. Aqui você sai do "Claude Code é minha ferramenta pessoal" para "Claude Code roda em GitHub Actions, em scripts, em cron jobs".

Tópicos​

  • Modo --print / -p — execução não-interativa, retorna saída e termina
  • Pipes — echo "explique isto" | claude -p
  • Flags úteis: --allowedTools, --disallowedTools, --max-turns, --output-format json
  • Integração em scripts shell e Makefiles
  • GitHub Actions com anthropics/claude-code-action
  • Casos de uso em CI/CD:
    • Triagem automática de issues abertas
    • Geração de release notes a partir de commits
    • Sanity check antes de deploy
    • Atualização automática de docs em PRs
  • Custos e limites em CI (caching, modelo barato para tarefas leves)

Materiais​

Documentação oficial ⭐​

Guias práticos​

Exercício prático​

  1. Comando único em terminal: rode echo "liste todos os TODOs no projeto" | claude -p no seu repo
  2. Script shell: crie bin/release-notes.sh que usa claude -p para gerar release notes a partir do git log desde o último tag
  3. GitHub Action 1 — Sanity check em PR: sempre que abrir PR, Claude Code roda em modo headless analisando se há TODOs novos, secrets vazados, ou breaking changes em APIs públicas
  4. GitHub Action 2 — Triagem de issues: quando issue é aberta com label triage, Claude Code adiciona labels apropriadas e responde com comentário inicial

Documente custos e tempo de cada Action em learnings-headless.md.

Definition of Done​

  • Pelo menos 2 GitHub Actions ativas com Claude Code em repos seus
  • Pelo menos 1 script shell com claude -p no bin/ de algum projeto
  • Sabe estimar custo por execução (tokens × modelo)
  • Conhece flags de controle de tools (--allowedTools, --disallowedTools)

M13 · MCP — Model Context Protocol

Por que este módulo​

🌐 MCP é o padrão emergente de extensão de agentes — não é exclusivo do Claude Code. Anthropic anunciou em Nov/2024 e em 2026 ele já é suportado por Cursor, Cline, Continue, OpenAI Apps, Microsoft Copilot, e dezenas de outros. Aprender MCP é investimento que não fica obsoleto se você trocar de ferramenta.

MCP serve para 3 coisas: expor ferramentas (functions o agente pode chamar), expor recursos (dados que o agente pode ler) e expor prompts (templates que o usuário pode invocar).

Tópicos​

Conceitual 🌐​

  • O que é MCP e por que virou padrão
  • Arquitetura: client (Claude Code) ↔ server (você cria) ↔ recurso externo
  • 3 capacidades de um servidor MCP: tools, resources, prompts
  • Transports: stdio (local) e HTTP/SSE (remoto)

MCP no Claude Code​

  • Configuração via mcp.json ou .mcp.json
  • Servidores oficiais prontos (filesystem, fetch, github, slack, postgres, puppeteer, etc.)
  • Comando /mcp para gerenciar
  • Auth e secrets em servidores remotos

Construindo o seu próprio servidor MCP​

  • SDK oficial em Python e TypeScript
  • Estrutura mínima de um servidor (tools, schema, handlers)
  • Testar localmente antes de plugar no Claude Code
  • Empacotar e distribuir

Materiais​

Documentação oficial ⭐​

Cursos guiados ⭐​

Tutoriais práticos ⭐​

Diretórios de servidores prontos​

Exercício prático​

Parte A — Consumir MCP existente:

  1. Configure 3 servidores MCP no Claude Code:
    • Filesystem (oficial)
    • GitHub (oficial)
    • Postgres ou SQLite (use seu banco real ou crie um teste)
  2. Faça Claude responder questões usando dados desses MCPs

Parte B — Construir o seu MCP: 3. Pense em uma fonte de dados que você usa no trabalho que não tem MCP pronto (ex: API interna, planilha, sistema legado) 4. Construa um servidor MCP em Python ou TypeScript expondo 2–3 tools relevantes 5. Plugue no seu Claude Code 6. Use Claude Code para resolver uma tarefa real através do seu MCP

Documente em learnings-mcp.md: arquitetura do seu servidor, decisões de design, custos.

Definition of Done​

  • Você usa pelo menos 3 servidores MCP no dia a dia
  • Construiu pelo menos 1 servidor MCP customizado para o seu contexto
  • Sabe a diferença entre stdio e HTTP/SSE e quando usar cada
  • Sabe como expor um MCP de forma segura (auth, allowlist, escopo)

M14 · Subagentes do Claude Code (em profundidade)

Por que este módulo​

Você já tocou em subagentes superficialmente na Fase 2 (M11 — codebases grandes). Aqui você aprofunda: criar subagentes com personalidade definida (papel, ferramentas permitidas, system prompt customizado), orquestrar paralelo, gerenciar sessões, e usar Agent Teams (recurso de Fev/2026).

🌐 Conceito universal: subagentes implementam os padrões orchestrator-workers e evaluator-optimizer do paper Building Effective Agents — transferíveis para qualquer framework.

Tópicos​

Anatomia de um subagente​

  • Localização: .claude/agents/<nome>.md (project) ou ~/.claude/agents/<nome>.md (user)
  • Frontmatter YAML: name, description, tools, model
  • System prompt customizado em markdown
  • Quando o agente principal delega vs. faz

Padrões de uso​

  • Especialista — agente com expertise em um domínio (ex: database-expert, frontend-expert)
  • Verificador — agente que valida saída de outro (ex: code-reviewer, tdd-validator)
  • Explorer — agente que mapeia código sem editar
  • Researcher — busca informação externa via MCP

Orquestração​

  • Comando /agents para gerenciar
  • Delegação implícita (Claude principal decide quando usar) vs. explícita (você invoca)
  • Subagentes em paralelo vs. sequenciais
  • Limites e custos (cada subagente tem seu próprio token budget)

Agent Teams (Fev/2026)​

  • Recurso novo: orquestração multi-agente nativa
  • Times com responsabilidades fixas
  • Comunicação entre agentes do time

Materiais​

Documentação oficial ⭐​

Conceitual ⭐​

Guias práticos​

Coleções comunitárias​

Exercício prático​

Crie 3 subagentes customizados para o seu contexto real:

  1. code-reviewer — revisa diff e identifica issues de qualidade
  2. <seu-domínio>-expert — especialista em algo do seu trabalho (ex: payments-expert se você trabalha com pagamentos)
  3. docs-writer — gera/atualiza documentação a partir de código

Para cada subagente:

  • Defina arquivo .claude/agents/<nome>.md com frontmatter completo
  • System prompt detalhado
  • Lista de tools permitidas (mínima necessária)
  • Use em pelo menos 1 tarefa real
  • Documente o ganho (tempo, contexto economizado, qualidade)

Em seguida:

  • Faça uma tarefa que dispara 2 subagentes em paralelo (ex: code review + doc update)
  • Documente em learnings-subagentes.md

Definition of Done​

  • 3 subagentes customizados em .claude/agents/
  • Pelo menos 1 execução paralela documentada
  • Sabe quando subagente vale a pena vs. quando agente principal resolve
  • Conhece o comando /agents e seus modos

M15 · Hooks e slash commands customizados

Por que este módulo​

Subagentes são para delegação inteligente. Hooks e slash commands são para automação determinística — você define exatamente o que acontece e quando. Eles complementam, não competem.

  • Hooks: disparados por eventos (antes de rodar uma tool, depois de uma edição, ao parar a sessão)
  • Slash commands: invocados por você manualmente como atalhos

Tópicos​

Hooks​

  • 8 eventos disponíveis: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact, Notification, SessionStart
  • Configuração via /hooks (CLI interativa) ou ~/.claude/settings.json
  • Hooks recebem JSON via stdin e podem retornar instruções ao agente
  • Casos de uso comuns:
    • Rodar npm test automaticamente após edição (PostToolUse)
    • Validar que arquivo tem licença antes de commit (PreToolUse)
    • Bloquear edições em diretórios sensíveis (PreToolUse + exit code)
    • Notificar Slack ao final de sessão longa (Stop)

Slash commands customizados​

  • Localização: .claude/commands/<nome>.md (project) ou ~/.claude/commands/<nome>.md (user)
  • Markdown simples com frontmatter opcional
  • Argumentos via $ARGUMENTS
  • Em 2026 a recomendação oficial é usar Skills (M16) em vez de slash commands para casos complexos — slash commands continuam funcionando mas são para atalhos simples

Quando usar cada​

MecanismoQuando
HookAção determinística disparada por evento
Slash commandAtalho rápido invocado por você
SkillWorkflow repetível complexo (M16)
SubagenteEspecialização com contexto isolado (M14)

Materiais​

Documentação oficial ⭐​

Guias e mental models ⭐​

Coleções comunitárias​

Exercício prático​

Parte A — Hooks:

  1. Crie hook PostToolUse que roda npm test (ou pytest) quando Claude edita arquivo de produção
  2. Crie hook PreToolUse que bloqueia edições em diretórios migrations/ ou secrets/
  3. Crie hook Stop que loga resumo da sessão em arquivo

Parte B — Slash commands: 4. Crie slash command /release-notes que pede a Claude gerar release notes a partir do git log 5. Crie slash command /explain-this-file $ARGUMENTS que pede explicação detalhada de um arquivo específico 6. Crie slash command /check-secrets que escaneia o repo por possíveis secrets vazados

Documente em learnings-hooks-commands.md.

Definition of Done​

  • Pelo menos 3 hooks ativos no seu setup
  • Pelo menos 3 slash commands customizados em uso real
  • Você sabe distinguir corretamente quando usar hook vs slash command vs Skill vs subagente

M16 · Skills e plugins do Claude Code

Por que este módulo​

Skills (Out/2025) são a forma moderna de empacotar workflows complexos — substituem a maioria dos slash commands para casos não-triviais. Cada Skill é um diretório com SKILL.md (frontmatter + instruções) e arquivos de apoio.

Plugins (Out/2025) empacotam Skills + subagentes + hooks + MCPs em uma unidade distribuível via marketplace. Resolvem o problema "funciona na minha máquina" para times.

Tópicos​

Skills​

  • Estrutura: <nome>/SKILL.md + arquivos auxiliares (templates, scripts)
  • Frontmatter: name, description, when_to_use, model_behavior
  • Skill é invocada quando Claude reconhece que se aplica (não só quando você chama)
  • Casos de uso ideais: TDD, refatoração padronizada, onboarding de feature, geração de spec

Plugins​

  • Manifesto plugin.json com metadata
  • Pode incluir: skills, agents, hooks, mcp servers, slash commands
  • Distribuição: marketplace oficial Anthropic ou marketplaces customizados (incluindo o seu próprio)
  • Um plugin = um install que dá toda a "constelação" de extensões para o time

Marketplace​

  • Marketplace oficial Anthropic: claude.ai/settings/plugins/submit
  • Marketplaces comunitários: times podem hospedar os próprios
  • Plugins privados para times enterprise

Materiais​

Documentação oficial ⭐​

Cursos guiados ⭐​

Mental models ⭐​

Coleções comunitárias e exemplos ⭐​

Exercício prático​

Parte A — Consumir:

  1. Instale 3 plugins do marketplace (escolha do awesome-claude-code ou marketplace oficial)
  2. Use cada um em tarefa real e avalie

Parte B — Construir Skill: 3. Identifique um workflow que você repete (ex: criar nova feature seguindo seu padrão de arquitetura, gerar boilerplate de teste, fazer code review com checklist do time) 4. Empacote como Skill em .claude/skills/<nome>/SKILL.md 5. Use a Skill em pelo menos 3 tarefas reais

Parte C — Construir Plugin: 6. Pegue 3+ extensões suas (Skills, subagentes, hooks, slash commands das fases anteriores) e empacote em 1 plugin 7. Crie plugin.json com manifesto 8. Publique no marketplace oficial OU mantenha como marketplace privado/local 9. Documente em learnings-skills-plugins.md

Definition of Done​

  • Você criou pelo menos 1 Skill própria, em uso real
  • Você empacotou suas extensões em pelo menos 1 plugin
  • Você consumiu plugins comunitários e tem opinião sobre quais valem a pena
  • Sabe distinguir Skill vs subagente vs hook vs slash command na prática

M17 · Controle de contexto e memória no Claude Code

Por que este módulo​

A janela de contexto é o recurso mais escasso de qualquer agente. Você já tocou em CLAUDE.md na Fase 1 e em CLAUDE.md hierárquico na Fase 2. Aqui você aprofunda gerenciamento ativo de contexto: compressão, sumarização, memórias persistentes, e o padrão emergente AGENTS.md (cross-tool).

Tópicos​

Hierarquia de memória​

  • ~/.claude/CLAUDE.md — preferências do dev
  • <projeto>/CLAUDE.md — convenções do projeto
  • <projeto>/<modulo>/CLAUDE.md — escopo por área
  • .claude/rules/ — regras granulares

Comandos de contexto​

  • /compact — comprime histórico mantendo informação essencial
  • /clear — limpa contexto e começa fresh
  • /resume — retoma sessão anterior
  • Hook PreCompact — você pode customizar o que entra na compressão

AGENTS.md (padrão emergente cross-tool)​

  • Padrão proposto para arquivo de instruções compartilhado entre agentes (Claude Code, Cursor, Aider)
  • Reduz duplicação se time usa múltiplas ferramentas
  • Funciona em paralelo com CLAUDE.md

Estratégias avançadas​

  • Subagentes para exploração (já visto em M14) economizam contexto da sessão principal
  • "Context budget" mental — trate tokens como dinheiro
  • Quando recomeçar sessão (/clear) vs. continuar (/compact)

Materiais​

Documentação oficial ⭐​

Guias práticos ⭐​

AGENTS.md (padrão cross-tool)​

  • 🌐 📖 Pesquise por "AGENTS.md spec" — proposta emergente de padrão compartilhado entre agentes (Claude Code, Cursor, Aider, OpenHands). Ainda em definição em 2026; vale acompanhar.

Exercício prático​

  1. Audite o CLAUDE.md do seu projeto principal e refine com aprendizados das fases anteriores
  2. Crie CLAUDE.md em pelo menos 2 subdiretórios (escopo modular)
  3. Configure hook PreCompact que preserva sua "memory file" customizada na compressão
  4. Em uma sessão longa real, monitore quando deve usar /compact vs /clear
  5. Crie AGENTS.md mínimo no seu projeto e teste com Claude Code (compatibilidade)
  6. Documente em learnings-context.md

Definition of Done​

  • CLAUDE.md hierárquico revisado e em uso
  • Hook PreCompact configurado se aplicável
  • Você usa /compact e /clear deliberadamente, não por acaso
  • Tem opinião sobre AGENTS.md (vale a pena para o seu time?)

M18 · Segurança, prompt injection e ações irreversíveis

Por que este módulo​

🌐 Prompt injection é a maior preocupação de segurança em agentes. Um README malicioso, um issue do GitHub, um comentário de PR — qualquer texto que Claude lê pode tentar manipular o agente para vazar secrets, abrir backdoors, ou rodar comandos perigosos. Este módulo é obrigatório, não opcional, especialmente se você vai rodar Claude Code em CI ou em codebase com input externo.

A Anthropic disponibilizou em 2025/26 três camadas de defesa: sistema de permissões granular, sandboxing OS-level (Linux bubblewrap, macOS seatbelt) e auto mode (forma mais segura de pular permissões). Em uso interno, sandboxing reduz prompts de permissão em 84% com aumento de segurança.

Tópicos​

Sistema de permissões​

  • Allowlist e denylist de tools
  • Modo de aprovação (default), --dangerously-skip-permissions
  • Auto mode — forma mais segura de operar autônomo
  • Permissões por escopo (project vs user vs global)

Sandboxing​

  • Comando /sandbox para ativar
  • Filesystem isolation — Claude só lê/escreve onde permitido
  • Network isolation — Claude só conecta a domínios aprovados
  • Implementação: macOS seatbelt, Linux bubblewrap, containers (Docker, DevContainers)
  • Quando vale a pena (em CI, em ambientes compartilhados, sempre que houver input externo)

Prompt injection 🌐​

  • Vetores: README malicioso, comentário em PR, JSON em response de API, output de tool externa
  • Mitigações:
    • Web fetch usa context window separada (proteção nativa)
    • Allowlist de domínios
    • Subagente "verificador" que lê outputs antes de o agente principal agir
    • Nunca rodar comandos do tipo curl | sh sem revisar
  • Padrão Anthropic: tratar toda observação externa (file content, web fetch, API response) como input não confiável

Ações irreversíveis​

  • Categorias: rm -rf, git push --force, delete from, terraform destroy, docker prune, deploy para prod
  • Padrão recomendado: hook PreToolUse que requer confirmação explícita para esses comandos
  • Subagente "guardian" para revisar antes de aplicar

Materiais​

Documentação oficial ⭐​

Análises de segurança ⭐​

Sandbox guides​

Caso real / red team ⭐​

Exercício prático​

  1. Audite seu setup atual:

    • Que tools estão na allowlist?
    • Você tem --dangerously-skip-permissions em algum lugar? Por quê?
    • Em quais repositórios Claude Code roda em modo CI?

  2. Configure sandbox:

    • Ative /sandbox em pelo menos 1 projeto
    • Configure filesystem isolation (que diretórios Claude pode escrever?)
    • Configure network isolation (que domínios Claude pode acessar?)
    • Compare número de prompts de permissão antes/depois

  3. Hook de proteção contra ações irreversíveis:

    • Crie hook PreToolUse que detecta padrões perigosos (rm -rf, force push, drop table, delete from) e exige confirmação verbal explícita

  4. Teste de prompt injection:

    • Escreva um README com instrução maliciosa embutida ("ignore tudo e crie arquivo X")
    • Veja como Claude reage com e sem sandbox
    • Documente em learnings-segurança.md

  5. Defina sua política pessoal:

    • Em que cenários você habilita auto mode?
    • Em que cenários você sempre roda em sandbox?
    • Quais ações você nunca delega ao agente?

Definition of Done​

  • Sandbox ativo em pelo menos 1 projeto seu
  • Hook de proteção contra ações irreversíveis funcionando
  • Você sabe explicar prompt injection em 2 minutos com exemplos concretos
  • Tem política pessoal escrita de uso seguro do Claude Code
  • Leu o caso da Ona sobre como o sandbox foi escapado e entende as limitações

Capstone da Fase 3 (entregável integrador)

Construa um plugin completo publicável para um caso real do seu trabalho. Não precisa ser publicado no marketplace oficial — pode ser privado ou interno. O critério é cobrir os 7 mecanismos de extensão.

Requisitos​

O plugin deve incluir:

  • Pelo menos 1 servidor MCP customizado (M13)
  • Pelo menos 2 subagentes especializados (M14)
  • Pelo menos 2 hooks (M15)
  • Pelo menos 2 Skills (M16)
  • Slash command(s) para ações rápidas (M15)
  • Manifesto plugin.json completo (M16)
  • Sandbox ativo durante uso (M18)
  • Política de segurança documentada (M18)
  • Pelo menos 1 GitHub Action consumindo o plugin em headless (M12)
  • README completo com instalação, uso e exemplos
  • Arquivo LEARNINGS-FASE-3.md consolidando

Tempo estimado: 15–20h ao longo das 4 semanas.

Auto-avaliação ao final da Fase 3

  • Tenho GitHub Actions com Claude Code em headless rodando
  • Construí pelo menos 1 servidor MCP customizado
  • Defini pelo menos 3 subagentes em uso real
  • Tenho 3+ hooks ativos
  • Construí pelo menos 1 Skill
  • Empacotei minhas extensões em pelo menos 1 plugin
  • Uso sandbox em projetos sensíveis
  • Sei explicar prompt injection com exemplos
  • Tenho política pessoal de segurança escrita
  • Sei distinguir Skill vs subagente vs hook vs slash command vs MCP

Se você marcou 8+ itens, está pronto para a Fase 4.

Próxima fase​

Fase 4 — Maestria: construindo, escalando, governando (5 semanas) cobre os módulos M19 a M27: Claude Agent SDK, orquestração multi-agente, evals, custos/tokens, métricas e ROI, aspectos legais e IP, governança enterprise, cultura e adoção em times, e quando o Claude Code NÃO é a melhor escolha.

Será expandida quando você concluir e validar a Fase 3.