Skip to content

TEMPLATE-AGENTES.md

Latest commit

 

History

History
449 lines (327 loc) · 12.2 KB

TEMPLATE-AGENTES.md

File metadata and controls

449 lines (327 loc) · 12.2 KB

Template Base para Criacao de Agentes

Este documento define a estrutura padrao para criacao de novos agentes Claude Code, baseado na analise dos agentes kubernetes-troubleshooter e python-bug-fixer.

Analise Comparativa dos Agentes Existentes

Estrutura do kubernetes-troubleshooter.md

Secao Linhas Proposito
Frontmatter YAML 1-6 Metadados (name, description, model, color)
Persona 8 Define expertise e experiencia
Regras Fundamentais 10-71 Proibicoes e obrigacoes criticas
Missao 73-74 Responsabilidade principal
Regras de Ferramentas 76-99 Tabela de tools MCP permitidas
Fluxo de Trabalho 100-110 Passos obrigatorios sequenciais
Metodologia (Ciclo AAO) 112-187 Analise -> Acao -> Observacao
Ferramentas Disponiveis 205-215 Lista detalhada de tools
Formato de Resposta 217-226 Estrutura para diagnosticos
Principios de Operacao 228-258 Regras absolutas e de conduta
Cenarios Especiais 269-282 Tratamento de casos edge
Relatorio Obrigatorio 284-342 Template + instrucao de salvamento

Estrutura do python-bug-fixer.md

Secao Linhas Proposito
Frontmatter YAML 1-6 Metadados (name, description, model, color)
Persona 8-17 Expertise e conhecimentos tecnicos
Responsabilidades 18-36 3 tipos de tarefas que executa
Metodologia 37-44 6 passos de debugging
Formato de Resposta 46-94 Template + instrucao de salvamento
Regras Importantes 96-105 Comportamentos esperados

Elementos Comuns

  1. FRONTMATTER YAML

    • name, description, model, color
    • Exemplos de uso no description

  2. PERSONA/PAPEL

    • Quem e o agente
    • Expertise e qualificacoes

  3. RESPONSABILIDADES/MISSAO

    • O que o agente faz
    • Escopo de atuacao

  4. METODOLOGIA

    • Como o agente trabalha
    • Passos ou ciclo de trabalho

  5. RELATORIO OBRIGATORIO

    • Template estruturado em markdown
    • Caminho absoluto para salvamento
    • Instrucao explicita de Write

  6. REGRAS DE COMPORTAMENTO

    • O que deve fazer
    • Comunicacao em portugues brasileiro

Elementos Diferentes

Aspecto kubernetes-troubleshooter python-bug-fixer
Extensao ~342 linhas (detalhado) ~105 linhas (conciso)
Regras de Proibicao Extensas e repetitivas Minimas
Ferramentas Tabela explicita de MCP tools Implicito
Restricoes de Escopo Explicitas (nao le codigo) Nao possui
Ciclo Metodologico Elaborado (AAO com 3 fases) Simples (6 passos lineares)
Cenarios Especiais Secao dedicada Nao possui
Tratamento de Erros "Se nao conseguir executar" Nao aborda

Estrutura Base para Novos Agentes

---
name: [nome-do-agente]
description: [Descricao com 2-3 exemplos de uso no formato <example>]
model: inherit
color: [cor]
---

# 1. PERSONA
[Quem e o agente - expertise, experiencia, qualificacoes]

# 2. REGRAS FUNDAMENTAIS (se necessario)
**VOCE ESTA PROIBIDO DE:**
- [Proibicao critica 1]
- [Proibicao critica 2]

**VOCE DEVE OBRIGATORIAMENTE:**
- [Obrigacao 1]
- [Obrigacao 2]

# 3. MISSAO/RESPONSABILIDADES
[O que o agente faz e seu escopo de atuacao]

# 4. FERRAMENTAS DISPONIVEIS (se usa ferramentas especificas)
| Tool | Finalidade |
|------|------------|
| [tool_name] | [descricao] |

# 5. METODOLOGIA DE TRABALHO
[Ciclo ou passos que o agente segue]

# 6. FORMATO DE RESPOSTA
[Estrutura esperada das respostas durante a execucao]

# 7. REGRAS DE COMPORTAMENTO
- [Regra 1]
- [Regra 2]
- Sempre comunique em portugues brasileiro

# 8. CENARIOS ESPECIAIS (se aplicavel)
[Tratamento de casos edge]

# 9. RELATORIO OBRIGATORIO
### Template (salvar em agentes/relatorio-[tipo].md)

# RELATORIO DE [TIPO]

**Data**: [Data e hora]

## STATUS: [STATUS_1 | STATUS_2 | STATUS_N]

## RESUMO
[Conteudo]

## DETALHES
[Conteudo estruturado]

## SOLUCAO/ACAO
[Proximos passos]

### Instrucao de Salvamento
Write(file_path="[caminho_absoluto]/agentes/relatorio-[tipo].md", content="[conteudo]")

**NUNCA finalize sem salvar o relatorio.**

Recomendacoes por Tipo de Agente

Agentes de Infraestrutura

Exemplo: kubernetes-troubleshooter, aws-troubleshooter, network-analyzer

  • Regras de proibicao extensas e repetitivas (enfatizar NUNCA INVENTE)
  • Tabela explicita de ferramentas permitidas
  • Metodologia ciclica (AAO - Analise, Acao, Observacao)
  • Cenarios especiais documentados
  • Restricoes de escopo claras (nao analisa codigo)
  • Tratamento explicito de falhas de ferramentas

Agentes de Codigo

Exemplo: python-bug-fixer, code-reviewer, refactoring-agent

  • Estrutura mais enxuta
  • Foco nas responsabilidades
  • Metodologia linear simples
  • Menos restricoes explicitas

Agentes de Analise/Pesquisa

Exemplo: security-analyzer, performance-auditor

  • Balanco entre detalhamento e concisao
  • Metodologia estruturada mas flexivel
  • Enfase em evidencias e fontes

Elementos Obrigatorios para Todos os Agentes

  1. Frontmatter YAML

    • name: identificador unico
    • description: com exemplos no formato <example>
    • model: inherit (ou especifico se necessario)
    • color: para identificacao visual

  2. Persona Definida

    • Expertise clara
    • Nivel de experiencia

  3. Metodologia de Trabalho

    • Passos ou ciclo definido
    • Criterios de conclusao

  4. Relatorio Obrigatorio

    • Template estruturado
    • Caminho absoluto para salvamento
    • Instrucao explicita de Write
    • Aviso: "NUNCA finalize sem salvar"

  5. Regras de Comunicacao

    • Portugues brasileiro
    • Tom e estilo apropriados

Checklist para Criacao de Novo Agente

  • Frontmatter YAML completo com exemplos
  • Persona com expertise definida
  • Regras fundamentais (se agente de infra)
  • Missao/responsabilidades claras
  • Ferramentas listadas (se usa MCP tools)
  • Metodologia de trabalho documentada
  • Formato de resposta definido
  • Regras de comportamento
  • Cenarios especiais (se aplicavel)
  • Template de relatorio com caminho absoluto
  • Instrucao de salvamento explicita
  • Comunicacao em portugues brasileiro

Templates para Comandos (Slash Commands)

Os comandos sao arquivos .md localizados em .claude/commands/ que definem fluxos de trabalho e orquestracao de agentes.

Analise do Comando Existente: processo-analise.md

Estrutura Identificada

Secao Proposito
Titulo e Papel Define o que o comando faz (orquestrador)
Restricoes Criticas Ferramentas proibidas e permitidas
Fluxo de Trabalho Passos sequenciais do processo
Agentes Disponiveis Lista de agentes com quando/como usar
Regras do Orquestrador Comportamentos obrigatorios
Sequencia de Analise Ordem recomendada de execucao
Formato de Resposta Final Template de output para usuario
Checklists de Validacao Verificacoes antes de cada acao

Elementos-Chave do Comando

  1. Papel Claro: Define que e um orquestrador, nao executor
  2. Restricoes Explicitas: Lista ferramentas proibidas e permitidas
  3. Justificativa: Explica POR QUE as restricoes existem
  4. Mapeamento de Agentes: Qual agente usar para cada situacao
  5. Regras de Decisao: Condicoes claras para acionar cada agente
  6. Fluxo de Dados: Como ler e usar os relatorios dos agentes
  7. Checklists: Validacoes antes de cada acao

Template Base para Comandos

# [Nome do Comando]

[Descricao do papel e responsabilidade principal do comando]

## RESTRICOES DO COMANDO

> **ATENCAO**: Estas restricoes sao OBRIGATORIAS.

### Ferramentas PROIBIDAS:
- `[tool_name]` - [motivo]
- `[tool_name]` - [motivo]

### Ferramentas PERMITIDAS:
- `Task` - Para delegar trabalho aos agentes
- `TodoWrite` - Para organizar e acompanhar progresso
- `AskUserQuestion` - Para esclarecer duvidas
- `Read` - APENAS para ler arquivos de dados dos agentes:
  - `agentes/relatorio-[tipo].md`

### Por que estas restricoes existem:
1. [Justificativa 1]
2. [Justificativa 2]

## Fluxo de Trabalho

1. **[Etapa 1]**: [Descricao]
2. **[Etapa 2]**: [Descricao]
3. **[Etapa N]**: [Descricao]

## Agentes Disponiveis

### [nome-do-agente-1]
**Quando usar:** [Situacoes que disparam este agente]
- [Cenario 1]
- [Cenario 2]

**Como invocar:**
Task tool com:
- subagent_type: "[nome-do-agente]"
- prompt: "[Descricao do que investigar]"

### [nome-do-agente-2]
**Quando usar:** [Situacoes que disparam este agente]

**Condicoes para acionar (TODAS devem ser verdadeiras):**
- [Condicao 1]
- [Condicao 2]

**NAO acionar se:**
- [Excecao 1]
- [Excecao 2]

**Como invocar:**
Task tool com:
- subagent_type: "[nome-do-agente]"
- prompt: "[Descricao do que investigar]"

## Regras do Comando

1. **NUNCA [acao proibida]** - [justificativa]
2. **SEMPRE [acao obrigatoria]** - [justificativa]
3. **AGUARDE [condicao]** antes de [proxima acao]
4. **ANALISE [fonte de dados]** verificando [campos importantes]
5. **CONSOLIDE [resultados]** em [formato final]

## Sequencia de Execucao Recomendada

Para [tipo de problema]:

1. **Primeiro**: Acione `[agente-1]` para [objetivo]
2. **Ler dados**: `Read(agentes/relatorio-[tipo].md)`
3. **Analisar**: Verificar campos [X, Y, Z]
4. **Decidir**: Se [condicao], acionar `[agente-2]`
5. **Consolidar**: Apresentar relatorio unificado

### Regra de Decisao

| Situacao | Acao |
|----------|------|
| [Cenario 1] | [Acao correspondente] |
| [Cenario 2] | [Acao correspondente] |

## Formato de Resposta Final

## Relatorio de [Tipo]

### Problema Reportado
[Descricao do problema original]

### Diagnostico de [Area 1] (fonte: agentes/relatorio-[tipo1].md)
**Status**: [STATUS]
**Resumo**: [RESUMO]
**Problema**: [PROBLEMA]
**Solucao**: [SOLUCAO]

### Diagnostico de [Area 2] (fonte: agentes/relatorio-[tipo2].md)
[Se foi acionado: dados do arquivo]
[Se nao foi necessario: "Nao foram identificados problemas"]

### Acoes Realizadas
[Lista de acoes baseada nos arquivos de dados]

### Status Final
[Estado atual apos as acoes]

### Proximos Passos (se houver)
[Acoes que o usuario precisa executar]

### Arquivos de Referencia
- `agentes/relatorio-[tipo1].md`
- `agentes/relatorio-[tipo2].md`

---

## Checklists de Validacao

Antes de usar QUALQUER ferramenta:

- [ ] A ferramenta esta na lista de PERMITIDAS?
- [ ] Estou delegando para um agente ou executando diretamente?
- [ ] Li o arquivo de dados correspondente?
- [ ] Estou baseando decisoes nos dados dos arquivos?

### Checklist ANTES de acionar [agente-condicional]

**TODAS as condicoes devem ser verdadeiras:**

- [ ] Li o arquivo de dados do agente anterior?
- [ ] O relatorio indica que [condicao 1]?
- [ ] O relatorio indica que [condicao 2]?

**Se QUALQUER resposta for "nao", NAO acione o agente.**

---

**INICIO**: [Instrucao de como o comando deve comecar - perguntar ao usuario ou iniciar diretamente]

Diferencas entre Agentes e Comandos

Aspecto Agente Comando
Localizacao .claude/agents/ .claude/commands/
Funcao Executa tarefas especificas Orquestra agentes
Ferramentas Usa ferramentas diretamente Delega via Task
Output Relatorio em arquivo Relatorio consolidado
Escopo Especializado (K8s, Python, etc.) Coordenacao geral
Invocacao Via Task tool Via slash command (/nome)

Tipos de Comandos

Comandos de Orquestracao

Exemplo: processo-analise

  • Coordenam multiplos agentes
  • Definem regras de decisao entre agentes
  • Consolidam resultados de varios relatorios
  • Restricoes extensas de ferramentas

Comandos de Workflow

Exemplo: deploy-pipeline, code-review-flow

  • Definem sequencia de passos
  • Podem usar agentes ou ferramentas diretamente
  • Focam em um fluxo especifico

Comandos Utilitarios

Exemplo: generate-docs, run-tests

  • Tarefas simples e diretas
  • Podem nao usar agentes
  • Estrutura mais enxuta

Checklist para Criacao de Novo Comando

  • Nome do arquivo em kebab-case (ex: processo-analise.md)
  • Papel e responsabilidade claros
  • Restricoes de ferramentas (se orquestrador)
  • Justificativa das restricoes
  • Fluxo de trabalho sequencial
  • Mapeamento de agentes disponiveis
  • Regras de decisao entre agentes
  • Sequencia de execucao recomendada
  • Formato de resposta final
  • Checklists de validacao
  • Instrucao de inicio