🌱 Fundamentos

O seu chat principal é o maestro: ele entende o pedido e decide delegar. O subagente é o músico especialista que executa uma parte.

Sem essa separação de papéis você tenta fazer tudo numa conversa só e perde o controle do que está acontecendo.

Maestro = orquestra e decide; subagente = executa uma tarefa e reporta.

O subagente recebe a tarefa, abre uma janela de contexto própria, trabalha e devolve só o resultado para o maestro.

É esse ciclo que mantém a sua conversa enxuta — o trabalho sujo fica na janela do subagente.

Janela própria = isolamento; relatório = só o essencial volta.

Cinco subagentes diferentes podem rodar em paralelo, cada um com seu papel, devolvendo cinco resumos ao maestro.

Visualizar a frota ajuda a entender o ganho: várias frentes ao mesmo tempo, sem misturar contextos.

Paralelismo = N janelas independentes; cada persona = um especialista.

O subagente não conversa com você turno a turno. Ele recebe uma tarefa, executa e some — não é um segundo chat.

Esperar diálogo do subagente é o erro mental mais comum. Saber o que ele NÃO é evita frustração.

Sem ida-e-volta; sem memória da sua conversa; tarefa única.

Cada subagente fala apenas com o maestro que o chamou. Subagentes não conversam entre si.

Define o que dá e o que não dá para orquestrar — e por que a coordenação é sempre do maestro.

Topologia estrela; o maestro é o único ponto de junção.

O Claude Code já vem com subagentes prontos (como o general-purpose). Você pode invocar um sem criar nada.

Experimentar antes de teorizar fixa o conceito: você vê o relatório voltar limpo na prática.

Built-in = pronto pra uso; delegar é pedir "abra um subagente pra…".

A janela de contexto é a memória de trabalho da sessão. A status line mostra quantos tokens e qual % você já usou.

Quem entende a janela entende por que delegar. É um recurso finito que você gasta a cada arquivo lido.

Contexto = recurso limitado; %/tokens = seu orçamento.

Tudo que você lê na conversa principal — logs, arquivos enormes, saídas — fica lá ocupando espaço até o fim da sessão.

Contexto poluído degrada as respostas seguintes. Reconhecer a poluição é o primeiro passo pra evitá-la.

Leitura = custo permanente; ruído acumulado piora o foco.

Ler 300 páginas na conversa principal versus mandar um subagente ler e te trazer só os 3 fatos que importam.

É a decisão central do curso. Internalizar a troca muda como você trabalha no dia a dia.

Você = contexto sujo; subagente = contexto preservado.

O subagente faz o trabalho pesado na janela dele e devolve um resumo destilado — não a pilha bruta.

É o que entra na sua conversa. Um bom resumo é o produto do subagente; você só vê o ouro.

Destilação; o relatório é a interface entre as duas janelas.

Muita gente acha que subagente é sobre ser mais rápido. O ganho principal é a preservação de contexto.

Mirar no motivo certo faz você usar subagentes nas situações certas, não só "pra ir mais rápido".

Contexto > velocidade; velocidade é bônus, não o objetivo.

Uma pesquisa de produto sobre documentação enorme: o subagente lê tudo e volta com os 3 pontos decisivos.

Um número concreto fixa a ideia melhor que a teoria: centenas de páginas custariam metade da sua janela.

Relação de compressão; o resumo cabe onde a fonte bruta não caberia.

Agente = o assistente principal; subagente = especialista delegado em janela própria; skill = instrução/capacidade carregada no contexto atual.

Confundir as três leva a usar a ferramenta errada. Uma frase clara de cada destrava tudo.

Três primitivas, três papéis; não são sinônimos.

O subagente tem janela própria e isolada; a skill roda dentro do contexto compartilhado do agente atual.

É o eixo que mais diferencia: skill suja seu contexto, subagente protege.

Isolamento (subagente) vs in-loco (skill).

Subagentes podem rodar vários em paralelo; uma skill executa dentro do fluxo sequencial do agente.

Quando você precisa de N frentes ao mesmo tempo, só o subagente entrega isso.

Paralelo = subagente; in-line = skill.

Um subagente pode rodar num modelo diferente do maestro; uma skill usa o modelo do agente que a carregou.

É a base da economia: subagente em Haiku barato enquanto o chefe fica em Opus.

Modelo por agente; skill herda o modelo atual.

Skills e agentes se chamam mutuamente, mas um agente não invoca outro agente — a coordenação volta sempre ao maestro.

Define os limites da orquestração. Tentar fazer agent chamar agent quebra o modelo.

skill ↔ agent OK; agent → agent NÃO.

Uma tabela viva cruzando contexto, paralelismo, modelo e invocação para apontar a primitiva certa por cenário.

É o entregável que você vai consultar pra sempre. Memorize os eixos, não as células.

Decisão por eixos; a tabela é a espinha da Trilha 1.

O Claude Code já traz subagentes de fábrica: Explore (busca), Plan (arquitetura), general-purpose (multiuso) e o próprio claude.

Antes de criar qualquer coisa, você já tem ferramentas poderosas. Saber quais existem evita reinventar.

Built-in = pronto; cobre busca, plano e tarefas gerais.

Dar uma persona ao general-purpose num prompt não cria um subagente custom — é só uma instrução temporária.

É uma confusão comum. Custom de verdade é um arquivo persistente, reusável e que dispara sozinho.

Persona ad-hoc ≠ agente salvo; custom = arquivo.

Um subagente custom é um arquivo Markdown com frontmatter + corpo. Ele vive no disco e está sempre disponível.

É a ponte pra Trilha 2. Entender que "é só um .md" desmistifica a criação.

.md = subagente; frontmatter (config) + corpo (cérebro).

O Claude lê só o name e a description de cada agente até decidir usar um. O corpo completo só entra quando o agente é chamado.

Explica por que a description é tão importante e por que ter muitos agentes não pesa no contexto.

Revelação progressiva; só carrega o detalhe quando precisa.

Como só name+description ficam carregados, você pode ter dezenas de agentes sem inchar o contexto.

Tira o medo de "ter agentes demais". O catálogo é leve por design.

Custo do catálogo ≈ só metadados; corpo sob demanda.

O comando /agents lista os subagentes disponíveis (built-in e custom) e abre o assistente de criação.

É a porta de entrada prática. Antes de criar, veja o que já tem com um comando.

/agents = listar + criar; ponto de partida da T2.

Uma única pergunta resolve a maioria dos casos: "isso vai gerar uma pilha que eu nunca mais vou reler?". Se sim, delegue.

É a heurística que dispensa decorar listas. Uma frase no bolso vale por dez regras.

Reuso futuro do output = critério; "lixo de leitura" → subagente.

Muitos arquivos, parede de output, tarefa repetida, jobs independentes em paralelo, ou precisar de um revisor imparcial.

Reconhecer o sinal verde rápido faz você delegar na hora certa, sem hesitar.

Volume, ruído, repetição, paralelismo, imparcialidade.

Edição rápida, passos dependentes, agentes que precisariam conversar, quando você precisa da conversa inteira ou de te fazer pergunta.

Forçar subagente onde não cabe gera retrabalho. O sinal vermelho economiza tempo.

Rapidez, dependência, diálogo, contexto pessoal.

Regra de bolso: 10+ arquivos para varrer ou um output que você nunca vai reler = subagente.

Um número torna a decisão objetiva quando a intuição titubeia.

Limiar 10 arquivos; parede de output = gatilho.

Quando o job exige dezenas ou centenas de subagentes, você passa pra um workflow dinâmico que orquestra a frota.

Marca o limite entre "um subagente" e "uma operação em escala" — assunto aprofundado na Trilha 3.

Escala muda a ferramenta; cuidado com custo.

Para uma coisa rápida, fazer direto no chat é melhor. Subagente tem custo de partida — não vale pra tudo.

Equilíbrio: a ferramenta certa pra cada tamanho de tarefa, sem dogma.

Overhead de partida; tarefa pequena fica no chat.

Não existe nada mágico: o subagente é literalmente um arquivo Markdown, com a mesma forma de uma skill.md.

Desmistifica de vez. Se você sabe editar texto, sabe criar um subagente.

Arquivo = agente; texto simples, versionável.

O topo entre --- é o frontmatter (configuração em YAML); o resto é o corpo, o cérebro com as instruções.

Ver as duas zonas é o mapa mental de toda a Trilha 2. Cada uma tem um papel distinto.

Frontmatter = como o agente é selecionado; corpo = como ele age.

Os campos essenciais do frontmatter: name, description, tools e model.

Com esses quatro você já cria um subagente funcional. O resto é refinamento.

name (id), description (gatilho), tools (permissão), model (custo).

Um bom corpo define o papel ("você é um…"), os passos numerados, o formato de saída e o que NÃO fazer.

Essa estrutura é o que separa um agente confiável de um genérico. É o esqueleto da Trilha 2.

Papel → passos → saída → restrições.

O arquivo fica em .claude/agents/ (no projeto) ou ~/.claude/agents/ (global) — assunto da Trilha 2.

Saber onde mora é o que conecta "criar o .md" com "o Claude encontrar e usar".

Pasta determina escopo; projeto vs global.

Além dos 4 campos-chave existem campos avançados (color, memory, disallowed-tools, MCP) documentados oficialmente.

Você não precisa decorar tudo: precisa saber que a referência completa existe e onde achá-la.

4 campos pra começar; doc oficial pro resto.