Anatomia de um subagente

Toda vez que o maestro aciona um subagente, ele está lendo um arquivo .md. Esse arquivo tem duas zonas obrigatórias: o frontmatter (entre os três traços ---) e o corpo (tudo depois). A primeira zona configura o agente — diz o nome, o gatilho, as ferramentas e o modelo. A segunda zona é o cérebro — diz quem ele é e o que faz. Juntas, essas duas partes formam o subagente completo.

↑ A equação do subagente: frontmatter (config) + corpo (cérebro) = agente completo.

Conteúdo detalhado

📄 O arquivo .md é o subagente

Se você já trabalhou com skills no Claude Code, já viu a estrutura: um arquivo Markdown com frontmatter no topo. Um subagente é exatamente isso — um .md com um frontmatter de configuração e um corpo de instruções. Não é binário, não é código compilado, não é plugin. É um arquivo de texto que qualquer editor abre.

🔑 Por que isso importa

Quando o arquivo é texto simples, você ganha três coisas de graça:

•Legibilidade — você lê, entende e edita sem ferramenta especial.
•Versionamento — vai para o git junto com o projeto. Diff funciona.
•Portabilidade — copie a pasta .claude/agents/ para outro projeto e o agente vai junto.

📋 Skill (.claude/skills/)

Invocada com /skill-name · mesmo modelo e ferramentas do chat · mesma janela de contexto.

🤖 Subagente (.claude/agents/)

Acionado pela description · janela própria · modelo e tools distintos · devolve só o relatório.

O que é:

Um arquivo Markdown com frontmatter + corpo. A analogia com skill.md é intencional — mesma estrutura, propósito diferente.

Por que aprender:

Desmistifica o subagente. Não há nada oculto: tudo que o maestro sabe sobre o agente está nesse arquivo.

Conceitos-chave:

Arquivo .md · frontmatter YAML · corpo Markdown · versionável no git · portável entre projetos.

⚙️ Frontmatter (config) × corpo (cérebro)

As duas zonas têm responsabilidades completamente diferentes. O frontmatter é lido pelo Claude Code para decidir se aciona o agente e como ele vai rodar. O corpo é o prompt enviado ao modelo quando ele é acionado — é literalmente o "sistema" daquele agente. Confundir as duas zonas é o erro mais comum ao criar o primeiro subagente.

.claude/agents/code-reviewer.md Markdown

⚙️ FRONTMATTER — configuração

---

name: code-reviewer

description: Revisa o diff atual em busca de bugs e

falhas de segurança. Use após qualquer mudança de código.

tools: Read, Grep, Glob

model: claude-sonnet-4-5

---

🧠 CORPO — cérebro (prompt)

You are a senior code reviewer.

When invoked:

1. Run git diff to see what changed.

2. Read the changed files and understand the intent.

3. Review for correctness, security and missing tests.

Flag: bugs, security holes, and missing tests.

Be concise. Do not rewrite the code — only report.

↑ Recriação ilustrativa — as duas zonas do arquivo .md de um subagente

⚙️ Frontmatter — o que faz

✓Define o identificador do agente (name)
✓Descreve quando o maestro deve usá-lo (description)
✓Lista as ferramentas permitidas (tools)
✓Escolhe o modelo que vai rodar (model)

🧠 Corpo — o que faz

✓Define o papel do agente ("You are a...")
✓Descreve os passos de execução
✓Especifica o formato da saída
✓Lista o que o agente NÃO deve fazer

O que é: a divisão em duas responsabilidades: configuração do runtime (frontmatter) e prompt do modelo (corpo).

Por que aprender: sem essa distinção você coloca instrução no lugar errado — tenta configurar tools no corpo ou descreve o papel no frontmatter.

Conceitos-chave: frontmatter YAML entre --- · corpo Markdown livre · lidos em momentos diferentes · propósitos não intercambiáveis.

🔑 Os 4 campos-chave do frontmatter

O frontmatter aceita muitos campos, mas quatro deles são os que você vai escrever em todo subagente. Os demais — color, memory, disallowed-tools — são opcionais e cobertos na Trilha 2. Por agora, domine esses quatro.

`name` — identificador

Minúsculas + hífens, sem espaço. Aparece nos logs e no FleetView. Use nomes descritivos: code-reviewer > cr.

`description` — gatilho

O maestro lê este campo para decidir quando acionar o agente. Description vaga = agente nunca acionado. A Trilha 2 inteira é dedicada a escrever boas descriptions.

`tools` — permissões

Princípio do menor privilégio: agente leitor → Read, Grep, Glob. Agente editor → adicione Edit, Write. Não omita — sem declarar, herda tudo do maestro.

`model` — quem executa

Mecânico → haiku. Análise → sonnet. Raciocínio estratégico → opus. Escolha intencional aqui economiza custo e tempo. Trilha 3 aprofunda.

💡 Todos os campos disponíveis

Além dos quatro acima, o frontmatter aceita: color (cor no FleetView), memory (project/user/local/none), disallowed-tools (bloqueio explícito) e campos avançados de MCP. A documentação oficial lista todos — link no tópico 6 deste módulo.

O que é: os quatro campos que todo subagente precisa: name, description, tools, model.

Por que aprender: sem os quatro, o agente não é acionado, usa ferramentas demais ou roda no modelo errado.

Conceitos-chave: name (id) · description (gatilho) · tools (menor privilégio) · model (custo × qualidade).

🧠 O corpo: as quatro seções do cérebro

O corpo é Markdown livre — você pode escrever o que quiser. Mas há quatro peças que um corpo bem formado quase sempre tem. Pense nelas como as seções de um briefing para um funcionário novo: quem você é, o que fazer, o que entregar e o que nunca fazer.

👤

Papel (Role)

A primeira linha do corpo. Define a identidade do agente.

You are a senior code reviewer
focused on security.

📋

Passos (Steps)

O que fazer quando acionado, passo a passo.

When invoked:
1. Run git diff.
2. Read changed files.
3. Look for bugs.

📤

Saída (Output)

Formato e conteúdo do que volta para o maestro.

Report: a bullet list of
issues. Include file path
and line number.

🚫

Não-fazer (Limits)

Fronteiras explícitas — o que o agente não faz.

Do not rewrite code.
Do not open new files
beyond the diff.

✓ Corpo bem formado

✓Começa com "You are a..." — papel claro
✓Passos numerados, sem ambiguidade
✓Instrução de saída explícita (bullet, JSON, prose)
✓Ao menos um "Do not..." para limitar escopo

✗ Corpo fraco

✗Sem papel — o modelo improvisa a identidade
✗Passos vagos: "analise o código"
✗Sem instrução de saída — o maestro não sabe o que esperar
✗Sem limites — o agente edita quando só devia ler

O que é: o corpo como um briefing de quatro seções: papel, passos, saída e limites.

Por que aprender: um corpo incompleto produz agentes imprevisíveis — que fazem mais (ou menos) do que você esperava.

Conceitos-chave: role · steps · output format · limits · Markdown livre.

📁 Onde vive: .claude/agents — a ponte para a Trilha 2

O Claude Code procura subagentes em .claude/agents/ na raiz do projeto. É uma pasta oculta, igual à .claude/skills/ que você já conhece. Qualquer .md salvo ali é automaticamente carregado como subagente disponível — sem restart, sem comando de registro.

estrutura de pastas projeto

seu-projeto/
├── .claude/
│   ├── agents/               # subagentes do projeto
│   │   ├── code-reviewer.md   # ← aqui!
│   │   ├── test-writer.md
│   │   └── doc-writer.md
│   ├── skills/               # skills (diferente!)
│   └── CLAUDE.md             # instruções do projeto
└── src/
    └── …

🗂️ Projeto — `.claude/agents/`

Só neste projeto · vai no git · compartilhado com o time.

🌐 Global — `~/.claude/agents/`

Todos os projetos · home do usuário · agentes pessoais.

🔭 Ponte para a Trilha 2: Na Trilha 2 você cria esses arquivos — frontmatter completo, corpo real e o comando /agents para gerenciar o catálogo.

O que é: a pasta .claude/agents/ como ponto de montagem dos subagentes de um projeto.

Por que aprender: saber onde salvar é o primeiro passo para criar. Sem o caminho certo, o agente não aparece.

Conceitos-chave: .claude/agents/ · escopo de projeto vs. global · carregamento automático · versionável.

📚 Documentação oficial — todos os campos

O frontmatter aceita mais campos além dos quatro essenciais. A referência abaixo cobre os mais usados.

📖 Campos do frontmatter — referência rápida

Campo	Obrigatório?	Para que serve
name	✓ sim	Identificador único — minúsculas e hífens
description	✓ sim	Gatilho — quando o maestro aciona este agente
tools	recomendado	Ferramentas permitidas (lista separada por vírgula)
model	recomendado	Modelo do Claude que executa (haiku / sonnet / opus)
color	opcional	Cor do badge no FleetView
memory	opcional	Acesso à memória: project / user / local / none
disallowed-tools	opcional	Bloqueia ferramentas específicas explicitamente

Doc completa: use /help agents no Claude Code (offline) ou docs.anthropic.com/claude/code/agents. Campos avançados como memory e disallowed-tools desbloqueiam comportamentos extras cobertos na Trilha 3+.

O que é: referência de todos os campos — obrigatórios e opcionais.

Por que aprender: saber onde encontrar campos avançados poupa tentativa-e-erro na hora de criar agentes mais sofisticados.

Conceitos-chave: campos obrigatórios × opcionais · /help agents · docs.anthropic.com/claude/code/agents.

📄

Exemplo .md totalmente anotado

Leia este doc-writer.md com atenção às anotações em comentário. Cada linha está rotulada com a seção a que pertence e a razão de estar ali.

.claude/agents/doc-writer.md exemplo anotado

--- ← delimitador de abertura do frontmatter

name: doc-writer
  ↑ identificador — minúsculas, hífens, sem acento

description: Escreve documentação técnica e READMEs
  a partir de código existente. Use quando o usuário
  pedir para documentar um módulo, função ou projeto.
  ↑ gatilho — 3 frases: o que faz, quando usar, sinal

tools: Read, Glob, Write
  ↑ menor privilégio — lê código, escreve .md, sem Bash

model: claude-sonnet-4-5
  ↑ sonnet: boa escrita, custo razoável. Haiku bastaria?
     Não — qualidade de prosa importa aqui.

--- ← delimitador de fechamento do frontmatter

# corpo (tudo aqui é o prompt enviado ao modelo)

You are a technical documentation writer.
  ↑ papel — identidade do agente (primeira coisa!)

When invoked:
1. Read the files listed in the task.
2. Identify the public interface (exports, classes, functions).
3. Write a clear README.md at the module root.
  ↑ passos — numerados, ação concreta em cada um

Output: a single README.md file with:
  - One-sentence summary
  - Installation (if applicable)
  - Usage examples in code blocks
  - API reference table
  ↑ saída — formato explícito; o maestro sabe o que esperar

Do not invent behavior that isn't in the source code.
Do not modify source files — only create/update .md files.
  ↑ limites — dois "do not" que previnem alucinação e dano

⌨️

Prompts prontos (copie e cole)

Três prompts para explorar a anatomia de um subagente que você já tem — ou para inspecionar o que o maestro sabe.

Prompt 1 — inspecionar um agente existente entender cada campo

Abra o arquivo .claude/agents/code-reviewer.md e
me explique cada campo do frontmatter — o que faz,
por que está com esse valor e o que mudaria se eu
trocasse. Depois leia o corpo e identifique o papel,
os passos, a saída esperada e os limites.

Prompt 2 — listar todos os agentes disponíveis ver o catálogo

Liste todos os subagentes disponíveis em
.claude/agents/ e para cada um me mostre:
- o campo name e description
- as tools permitidas
- o modelo configurado
Formato: tabela markdown.

Prompt 3 — diagnosticar um agente que nunca é acionado debugar description

Leia o arquivo .claude/agents/meu-agente.md.
O maestro nunca aciona este agente. Analise a
description: ela é específica o suficiente?
Tem as palavras-gatilho certas? Sugira 3 versões
melhoradas da description, do mais genérico
ao mais específico.

🎯

Exercício — Rotule as partes

Abaixo está um arquivo .md de subagente com 8 linhas numeradas. Para cada linha, identifique: (a) em qual zona está (frontmatter ou corpo), (b) qual campo ou seção do corpo ela representa.

L1---

L2name: test-writer

L3description: Escreve testes unitários para funções Python.

L4tools: Read, Write, Bash

L5model: claude-haiku-4-5

L6---

L7You are a Python test engineer.

L8When invoked, read the target file and write pytest tests.

✅ Critério — você acertou se, para cada linha, disse:

→Zona: frontmatter (L1–L6) ou corpo (L7–L8).
→Campo/seção: delimitador, name, description, tools, model, papel ou passos.
→Impacto: o que quebra se essa linha sumir.

Bônus: qual ferramenta em L4 é a mais arriscada e por quê Bash exige cuidado.

Gabarito

L1,L6 → delimitadores · sem eles o YAML não parseado

L2 → frontmatter · name · sem ele o agente perde id

L3 → frontmatter · description (gatilho de acionamento)

L4 → frontmatter · tools · Bash = execução livre = risco maior

L5 → frontmatter · model · haiku = rápido e barato

L7 → corpo · papel · identidade do modelo (vem primeiro)

L8 → corpo · passos · instrução de execução

✅ Resumo do módulo

✓

O .md é o subagente — arquivo de texto, versionável, portável. A mesma estrutura da skill.md, mas com propósito diferente.

✓

Duas zonas — frontmatter (config, lido pelo runtime) e corpo (prompt, enviado ao modelo).

✓

4 campos do frontmatter — name (id), description (gatilho), tools (menor privilégio), model (custo × qualidade).

✓

4 seções do corpo — papel, passos, saída e limites. Corpo sem limites produz agentes que fazem mais do que deviam.

✓

Onde vive — .claude/agents/ no projeto (ou ~/.claude/agents/ no global). Carregamento automático.

✓

Documentação oficial — /help agents para referência local; docs.anthropic.com para a lista completa de campos.

Próximo — Trilha 2:

Trilha 1 completa. Na Trilha 2 você cria na prática: frontmatter completo (todos os campos), a description como gatilho, ferramentas e permissões, e o comando /agents para gerenciar seu catálogo.

← Módulo anterior Trilha 2: Na prática →