Fundamentos do agente

Problema: Num projeto real, normalmente é preciso mais do que uma pessoa a trabalhar nisso. Alguém para dar uma olhadela na segurança. Outro para verificar o desempenho. E alguém para garantir que a documentação está correta. Desempenhar todas essas funções numa única conversa consome concentração e tempo.

Solução rápida: Passa uma tarefa paralela a um subagente. Ele funciona sozinho e depois devolve o que encontrou à tua sessão principal.

Compreensão: O Claude Code oferece várias formas de obter um comportamento ao estilo de um agente, desde subagentes integrados até aos teus próprios comandos com barra. Cada um deles dá o seu valor em tarefas diferentes. Domina os conceitos básicos antes de avançares para os padrões mais sofisticados.

Aqui estão os cinco caminhos que o Claude Code oferece, lado a lado:

Cada caminho tem uma vantagem e uma desvantagem. Os subagentes ganham no trabalho paralelo. As definições de «.claude/agents/» dão aos subagentes um nome que fica. Os comandos com barra destacam-se pela reutilização.

Usa esta página para decidir qual a primitiva que realmente procuras. Se já sabes que queres vários agentes e a questão em aberto é a forma de coordenação, lê Padrões de Agentes. Se precisas de várias sessões do Claude a colaborar como pares, em vez de subagentes subordinados a um líder, vai para Equipas de Agentes de Código do Claude.

Uma escada de decisão simples

Se não tens a certeza de qual o caminho a seguir, não comeces pelo mais sofisticado. Desce esta escada:

1. Será que isto é apenas uma mudança de perspetiva pontual?

Usa prompts de perspetiva.

1. Trata-se de um fluxo de trabalho repetível que desejas acionar quando precisares?

Usa um comando de barra.

1. Será que isto é um especialista persistente que o Claude deveria conseguir encaminhar automaticamente?

Usa o comando «.claude/agents/».

1. Precisas de trabalho paralelo ou de um contexto isolado neste momento?

Usa um subagente através da ferramenta Tarefa.

1. A regra deve aplicar-se a todas as sessões no repositório?

Coloca-a no CLAUDE.md.

Essa ordem é importante porque evita que construas em excesso. A maioria das equipas deve progredir gradualmente, passando de prompts para comandos e, por fim, para agentes persistentes, em vez de saltar diretamente para uma enorme frota de especialistas.

A Ferramenta Tarefa

Dentro da tua sessão, a ferramenta Tarefa inicia pequenas instâncias do Claude Code. Cada subagente recebe uma janela de contexto nova, funciona de forma independente e envia os resultados de volta para o orquestrador.

Por que os subagentes são importantes:

• O contexto isolado impede que o trabalho numa tarefa interfira na seguinte
• As execuções em paralelo reduzem o tempo de processamento na análise de vários ficheiros
• Um subagente que falhe não leva a tua sessão principal a falhar com ele
• O modo de fundo permite-te continuar a trabalhar enquanto eles estão a funcionar (carrega em Ctrl+B)

Novidade : os subagentes criados pelo Claude podem agora ficar em segundo plano. Clica emCtrl+B e o agente principal fica livre para outras conversas. Os resultados aparecem assim que terminarem. Explicação completa no guia de fluxos de trabalho assíncronos.

Para padrões de orquestração mais avançados, consulta Padrões de Agentes.

Definições personalizadas de subagentes

Os subagentes também podem ficar no disco. Coloca um ficheiro Markdown num diretório dedicado agents/, com YAML no cabeçalho, e já tens uma definição de subagente personalizada. Isto não são comandos de barra. Os comandos de barra são prompts que chamas manualmente. Uma definição de agente configura um subagente persistente que o orquestrador do Claude pega sozinho quando a tarefa for adequada.

Dois âmbitos para definições de agente:

• Agentes de projeto (.claude/agents/) - Específicos do teu repositório, partilháveis com a tua equipa via git
• Agentes de utilizador (~/.claude/agents/) - Disponíveis em todos os teus projetos, pessoais para a tua máquina

Um subagente declarado em .claude/agents/ lê o ficheiro CLAUDE.md do teu projeto tal como a sessão principal faz. Padrões de codificação, convenções e regras do projeto são todos transferidos sem necessidade de configuração adicional.

Controlar o modelo do subagente: Define CLAUDE_CODE_SUBAGENT_MODEL no teu ambiente para apontar os subagentes para um modelo específico. Útil para reduzir custos (um modelo mais leve para subagentes) ou para tarefas que beneficiam de um raciocínio mais complexo.

Restringir o acesso dos subagentes com regras de permissão

Podes indicar ao Claude quais os subagentes que ele pode chamar, usando regras de permissão Task(AgentName). Coloca-as na matriz deny do teu settings.json, ou passa-as na linha de comando através de --disallowedTools.

Isso impede que o subagente Explore seja criado. Os nomes de agentes integrados incluem Explore, Plan e Verify. Os agentes também podem ser desativados no arranque.

Recorre a isto em ambientes sensíveis onde queiras controlar mais de perto o comportamento do agente, ou quando a exploração autónoma estiver a consumir demasiados tokens.

Comandos de barra personalizados

Os comandos com barra reutilizáveis estão armazenados como ficheiros Markdown em .claude/commands/. Executa /project:security-review src/auth/ e o teu especialista começa a trabalhar.

Localizações dos comandos:

• .claude/commands/ - Específicos do projeto, partilháveis via git
• ~/.claude/commands/ - Pessoais, disponíveis em qualquer lugar

Personas do CLAUDE.md

Todas as interações no teu projeto passam pelo que estiver no CLAUDE.md. O ficheiro acaba por definir como o Claude se apresenta por predefinição. Consistência ao estilo de um agente, sem nunca teres de chamar o agente pelo nome.

Solicitação de perspetiva: Mudanças rápidas de contexto

Para uma análise pontual, pede ao Claude para assumir uma perspetiva específica. Sem configuração. Análise especializada imediata.

Quando usar cada um

Usa subagentes quando: Queres execuções paralelas ou precisas de um contexto isolado em várias tarefas.

Usa o «.claude/agents/» quando: quiseres agentes especializados com nome que permaneçam ativos, e o orquestrador do Claude os seleciona automaticamente por tipo de tarefa.

Usa comandos com barra quando: O mesmo fluxo de trabalho se repete em várias sessões, ou se quiseres partilhá-lo com a equipa.

Usa o CLAUDE.md quando: O comportamento deve aplicar-se em todo o lado, em todas as interações, automaticamente.

Usa prompts de perspetiva quando: quiseres uma abordagem rápida e pontual a partir de um ângulo diferente.

Três configurações práticas

1. Revisão de segurança sem sobrecarga permanente

Se, ocasionalmente, quiseres um segundo par de olhos na autenticação, nas verificações de permissão ou no tratamento de segredos:

• mantém a tua sessão normal
• cria um subagente focado em segurança
• pede-lhe para reportar apenas as conclusões

Isto é melhor do que uma definição de agente permanente se a necessidade for ocasional.

2. Fluxo de trabalho de conteúdo que executas todas as semanas

Se continuas a escrever documentos, registos de alterações ou publicações no blogue com os mesmos critérios de qualidade:

• usa um comando de barra
• carrega a voz, o fluxo de trabalho e a lista de verificação lá
• não impores esse contexto de conteúdo em todas as sessões de programação

Esse é o meio-termo limpo e reutilizável.

3. Especialista na área para quem queres que o Claude encaminhe naturalmente

Se o teu repositório tem trabalhos recorrentes de front-end, back-end, base de dados ou segurança:

• define especialistas permanentes em .claude/agents/
• mantém as regras de domínio perto do agente
• deixa que o orquestrador os selecione quando a tarefa for adequada

É aí que os agentes persistentes começam a dar frutos.

Na prática, configurações bem desenvolvidas do Claude Code executam todas as cinco ao mesmo tempo. Definições persistentes para funções especializadas. Comandos de barra para fluxos de trabalho repetitivos. CLAUDE.md para padrões em todo o projeto. Subagentes para tarefas paralelas. O ClaudeFast Code Kit inclui 18 agentes pré-configurados (desde auditor de segurança até especialista em front-end), além dos comandos de barra e regras de roteamento já implementados, para que os padrões fiquem visíveis antes de criares os teus próprios.

Próxima ação: escolhe um fluxo de trabalho que executes frequentemente e transforma-o num comando de barra em .claude/commands/. A partir daí, aprofunda-te nas estratégias de distribuição que o trabalho de orquestração mais complexo requer.

Explora mais conceitos de agentes:

• Melhores práticas para subagentes - Quando usar execução paralela, sequencial ou em segundo plano
• Conceção de subagentes - Padrões de arquitetura para orquestrar vários agentes
• Agentes personalizados - Cria agentes especializados com comandos de barra
• Padrões de agente - Padrões de design comprovados para sistemas de agentes
• Agentes semelhantes a humanos - Cria agentes com personalidades distintas