Agent Development

Desenvolvimento de Agents para Plugins Claude Code

Visão Geral

Agents são subprocessos autônomos que lidam com tarefas complexas e multi-etapas de forma independente. Entender a estrutura de agent, condições de acionamento e design de prompt de sistema permite criar recursos autônomos poderosos.

Conceitos principais:

• Agents são PARA trabalho autônomo, comandos são PARA ações iniciadas pelo usuário
• Formato de arquivo Markdown com frontmatter YAML
• Acionamento via campo description com exemplos
• Prompt de sistema define comportamento do agent
• Personalização de modelo e cor

Estrutura de Arquivo de Agent

Formato Completo

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Campos de Frontmatter

name (obrigatório)

Identificador de agent usado para namespacing e invocação.

Formato: apenas minúsculas, números e hífens Comprimento: 3-50 caracteres Padrão: Deve começar e terminar com alfanumérico

Bons exemplos:

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Maus exemplos:

• helper (muito genérico)
• -agent- (começa/termina com hífen)
• my_agent (underscores não permitidos)
• ag (muito curto, < 3 caracteres)

description (obrigatório)

Define quando Claude deve acionar este agent. Este é o campo mais crítico.

Deve incluir:

1. Condições de acionamento ("Use este agent quando...")
2. Múltiplos blocos <example> mostrando uso
3. Contexto, solicitação do usuário e resposta do assistente em cada exemplo
4. <commentary> explicando por que o agent é acionado

Formato:

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

Melhores práticas:

• Inclua 2-4 exemplos concretos
• Mostre acionamento proativo e reativo
• Cubra diferentes formas de expressar a mesma intenção
• Explique o raciocínio em commentary
• Seja específico sobre quando NÃO usar o agent

model (obrigatório)

Qual modelo o agent deve usar.

Opções:

• inherit - Use o mesmo modelo do pai (recomendado)
• sonnet - Claude Sonnet (equilibrado)
• opus - Claude Opus (mais capaz, mais caro)
• haiku - Claude Haiku (rápido, barato)

Recomendação: Use inherit a menos que o agent precise de capacidades específicas do modelo.

color (obrigatório)

Identificador visual para o agent na UI.

Opções: blue, cyan, green, yellow, magenta, red

Diretrizes:

• Escolha cores distintas para diferentes agents no mesmo plugin
• Use cores consistentes para tipos similares de agent
• Azul/ciano: Análise, revisão
• Verde: Tarefas orientadas ao sucesso
• Amarelo: Cuidado, validação
• Vermelho: Crítico, segurança
• Magenta: Criativo, geração

tools (opcional)

Restrinja o agent a ferramentas específicas.

Formato: Array de nomes de ferramentas

tools: ["Read", "Write", "Grep", "Bash"]

Padrão: Se omitido, o agent tem acesso a todas as ferramentas

Melhor prática: Limite ferramentas ao mínimo necessário (princípio do menor privilégio)

Conjuntos de ferramentas comuns:

• Análise somente leitura: ["Read", "Grep", "Glob"]
• Geração de código: ["Read", "Write", "Grep"]
• Testes: ["Read", "Bash", "Grep"]
• Acesso total: Omita o campo ou use ["*"]

Design de Prompt de Sistema

O corpo do markdown se torna o prompt de sistema do agent. Escreva na segunda pessoa, dirigindo-se diretamente ao agent.

Estrutura

Template padrão:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Melhores Práticas

✅ FAÇA:

• Escreva na segunda pessoa ("You are...", "You will...")
• Seja específico sobre responsabilidades
• Forneça processo passo a passo
• Defina formato de saída
• Inclua padrões de qualidade
• Aborde casos extremos
• Mantenha menos de 10.000 caracteres

❌ NÃO FAÇA:

• Escreva na primeira pessoa ("I am...", "I will...")
• Seja vago ou genérico
• Omita etapas do processo
• Deixe formato de saída indefinido
• Pule orientações de qualidade
• Ignore casos de erro

Criando Agents

Método 1: Geração Assistida por IA

Use este padrão de prompt (extraído do Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Então converta para formato de arquivo de agent com frontmatter.

Veja examples/agent-creation-prompt.md para template completo.

Método 2: Criação Manual

1. Escolha identificador de agent (3-50 caracteres, minúsculas, hífens)
2. Escreva description com exemplos
3. Selecione modelo (geralmente inherit)
4. Escolha cor para identificação visual
5. Defina ferramentas (se restriger acesso)
6. Escreva prompt de sistema com estrutura acima
7. Salve como agents/agent-name.md

Regras de Validação

Validação de Identificador

✅ Válido: code-reviewer, test-gen, api-analyzer-v2
❌ Inválido: ag (muito curto), -start (começa com hífen), my_agent (underscore)

Regras:

• 3-50 caracteres
• Apenas letras minúsculas, números e hífens
• Deve começar e terminar com alfanumérico
• Sem underscores, espaços ou caracteres especiais

Validação de Description

Comprimento: 10-5.000 caracteres Deve incluir: Condições de acionamento e exemplos Ideal: 200-1.000 caracteres com 2-4 exemplos

Validação de Prompt de Sistema

Comprimento: 20-10.000 caracteres Ideal: 500-3.000 caracteres Estrutura: Responsabilidades claras, processo, formato de saída

Organização de Agents

Diretório de Agents do Plugin

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

Todos os arquivos .md em agents/ são descobertos automaticamente.

Namespacing

Agents são nomeados automaticamente:

• Plugin único: agent-name
• Com subdiretórios: plugin:subdir:agent-name

Testando Agents

Testar Acionamento

Crie cenários de teste para verificar se o agent é acionado corretamente:

1. Escreva agent com exemplos de acionamento específicos
2. Use fraseado similar aos exemplos em teste
3. Verifique se Claude carrega o agent
4. Confirme que o agent fornece funcionalidade esperada

Testar Prompt de Sistema

Certifique-se de que o prompt de sistema está completo:

1. Dê ao agent tarefa típica
2. Verifique se segue etapas do processo
3. Confirme que formato de saída está correto
4. Teste casos extremos mencionados no prompt
5. Confirme que padrões de qualidade são atendidos

Referência Rápida

Agent Mínimo

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Resumo de Campos de Frontmatter

Melhores Práticas

FAÇA:

• ✅ Inclua 2-4 exemplos concretos em description
• ✅ Escreva condições de acionamento específicas
• ✅ Use inherit para modelo a menos que haja necessidade específica
• ✅ Escolha ferramentas apropriadas (menor privilégio)
• ✅ Escreva prompts de sistema claros e estruturados
• ✅ Teste acionamento de agent minuciosamente

NÃO FAÇA:

• ❌ Use descrições genéricas sem exemplos
• ❌ Omita condições de acionamento
• ❌ Dê a todos os agents a mesma cor
• ❌ Conceda acesso a ferramentas desnecessárias
• ❌ Escreva prompts de sistema vagos
• ❌ Pule testes

Recursos Adicionais

Arquivos de Referência

Para orientação detalhada, consulte:

• references/system-prompt-design.md - Padrões completos de prompt de sistema
• references/triggering-examples.md - Formatos de exemplo e melhores práticas
• references/agent-creation-system-prompt.md - O prompt exato do Claude Code

Arquivos de Exemplo

Exemplos funcionais em examples/:

• agent-creation-prompt.md - Template de geração de agent assistida por IA
• complete-agent-examples.md - Exemplos completos de agent para diferentes casos de uso

Scripts de Utilidade

Ferramentas de desenvolvimento em scripts/:

• validate-agent.sh - Valide estrutura de arquivo de agent
• test-agent-trigger.sh - Teste se o agent é acionado corretamente

Fluxo de Implementação

Para criar um agent para um plugin:

1. Defina propósito de agent e condições de acionamento
2. Escolha método de criação (assistido por IA ou manual)
3. Crie arquivo agents/agent-name.md
4. Escreva frontmatter com todos os campos obrigatórios
5. Escreva prompt de sistema seguindo melhores práticas
6. Inclua 2-4 exemplos de acionamento em description
7. Valide com scripts/validate-agent.sh
8. Teste acionamento com cenários reais
9. Documente agent no README do plugin

Foque em condições de acionamento claras e prompts de sistema abrangentes para operação autônoma.