Como Instalar Mais de 300 Especialistas de IA no Claude Code e Cursor

agency-agents: personas de IA para agentes de código

Em resumo: agency-agents é a maior coleção curada de personas de agentes de IA no GitHub, com 149.312 estrelas em 1º de setembro de 2026. O repositório reúne mais de 300 arquivos de definição em cerca de 20 categorias e os instala, com um único comando, em Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Windsurf, Aider e outras ferramentas. O resultado é enquadramento, não capacidade: as personas mudam como o agente aborda uma tarefa, mas não fornecem fatos que ele desconhece nem sobrevivem além da sessão.

Experimente o Apidog hoje

Este artigo analisa uma ferramenta do nosso resumo de cinco ferramentas de agente de IA de código aberto que vale a pena instalar em 2026.

O que você está instalando

Cada agente é um arquivo Markdown — não um prompt de sistema de uma linha nem um plugin com código. O arquivo normalmente define:

• identidade e personalidade;
• missão central;
• processo de trabalho;
• entregáveis técnicos, com exemplos;
• métricas de sucesso.

Em 1º de setembro de 2026, a árvore do repositório continha 312 arquivos em 20 categorias de nível superior, ou 306 sem examples/. A distribuição era:

Divisão	Arquivos de agente
engineering	59
specialized	58
marketing	36
game-development	21
integrations	18
strategy	16
gis	13
security	12
design	10
sales	9
testing	9
paid-media	7
project-management	7
academic	6
spatial-computing	6
support	6
finance	5
product	5
healthcare	3

O README ainda anuncia “230+ agentes”, mas essa informação está desatualizada.

A categoria engineering é o ponto de partida mais provável. Além de Desenvolvedor Frontend e Arquiteto Backend, há personas para Cisco IOS-XE, Juniper Junos, Palo Alto PAN-OS, ESP32, STM32, Nordic, resposta a incidentes e onboarding de código.

O Codebase Onboarding Engineer, por exemplo, explora um repositório em modo somente leitura e declara fatos sobre sua estrutura, sem propor alterações. Essa restrição explícita torna a persona realmente diferente de um agente generalista.

Instale apenas o que precisa

Clone o repositório e execute o instalador:

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
./scripts/install.sh

Para controlar a instalação:

# tudo, para Claude Code
./scripts/install.sh --tool claude-code

# apenas duas divisões
./scripts/install.sh --tool claude-code --division engineering,security

# apenas agentes nomeados
./scripts/install.sh --tool cursor --agent frontend-developer,ui-designer

# veja o que existe antes de confirmar
./scripts/install.sh --list teams
./scripts/install.sh --tool opencode --division engineering --dry-run

Os alvos incluem Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Aider, Kimi Code, Hermes, Antigravity, Osaurus e Mistral Vibe.

Também existe o aplicativo desktop agencyagents.app, para macOS, Linux e Windows, com navegação, instalação em um clique e atualizações automáticas. O projeto oferece ainda um cask do Homebrew.

Atenção ao limite do OpenCode

O runtime do OpenCode registra atualmente cerca de 119 agentes e descarta o restante silenciosamente. O próprio repositório documenta esse problema upstream.

Use --division para permanecer dentro do limite. O instalador avisa quando uma seleção pode excedê-lo. Execute o dry run antes de confirmar:

./scripts/install.sh --tool opencode --division engineering --dry-run

Mesmo sem esse limite, instalar 300 personas costuma ser contraproducente. Instale as divisões relacionadas ao seu trabalho, leia quatro ou cinco arquivos e remova os que não correspondem às práticas da sua equipe.

O que uma persona muda — e o que não muda

Uma persona define:

• o que o agente deve procurar;
• qual formato deve produzir;
• o que significa concluir a tarefa.

Isso corrige um problema comum: a saída pode estar tecnicamente razoável, mas otimizada para o tipo errado de resposta.

Uma persona, porém, não fornece informações ausentes no modelo. Por exemplo, um Arquiteto Backend pode gerar um cliente limpo para uma API interna, mas não sabe que:

• uma chave de idempotência repetida retorna 409;
• esse 409 usa um envelope de erro diferente;
• o cursor de paginação é opaco, e não um offset.

A persona melhora a organização do código; não garante sua correção.

O mesmo vale para testes. Uma persona de QA pode escrever uma suíte completa baseada em um modelo mental incorreto da API. Os testes passam, mas não validam o comportamento real. Consulte também:

• testes de agentes de IA não determinísticos;
• o que acontece quando mudanças na API quebram agentes de IA.

A solução é fornecer o contrato. Se a API foi projetada no Apidog, a especificação OpenAPI pode ser a fonte da verdade, incluindo:

• esquemas reais;
• códigos de status;
• envelopes de erro;
• regras de paginação.

O agente lê a especificação em vez de reconstruir a API a partir de suposições. Mocks podem ser gerados a partir do mesmo contrato, incluindo caminhos de erro, e os testes de contrato falham no CI quando a implementação e a especificação divergem.

A regra prática é simples:

A persona define como o agente trabalha. A especificação define o que é verdadeiro.

Leituras relacionadas:

• usando sua especificação OpenAPI como ferramentas de agente;
• projetando esquemas de ferramentas de API para agentes.

Para conectar uma especificação ativa ao contexto do agente, baixe o Apidog e aponte-o para o projeto existente.

Uma persona não é uma equipe

A coleção sugere uma agência completa, mas a instalação não cria uma equipe persistente. Você ativa uma persona, executa uma tarefa e perde o contexto quando a sessão termina. Não há atribuição, histórico compartilhado ou registro do que outro revisor encontrou anteriormente.

Para fazer essa ideia sobreviver a uma sessão de terminal, é necessária uma camada de gerenciamento de trabalho. O Sharkly foi criado para isso:

• Agentes são configurações salvas com instruções, runtime, habilidades, repositórios e ambiente.
• Equipes combinam um agente líder, outros agentes e pessoas. O líder lê o contexto da tarefa, escolhe os participantes e consolida os resultados.
• Trabalho é atribuído, não apenas invocado. A tarefa vive em um espaço, projeto e sprint, com sincronização com o Jira quando necessário.
• Execução usa um Computador — laptop, servidor ou contêiner — e o runtime já instalado. Sua assinatura do Claude Code ou Codex executa o trabalho.
• Saída fica disponível para revisão. Progresso, chamadas de ferramenta e resultados são transmitidos para a tarefa como comentários. Uma tarefa no backlog não inicia uma execução automaticamente.

Em resumo: agency-agents fornece descrições de função; o Sharkly fornece o local para atribuí-las, executá-las e revisá-las.

Crie personas específicas para sua stack

Depois de ler alguns arquivos, criar uma persona interna leva cerca de quinze minutos. Uma persona específica da sua organização costuma ser mais útil do que uma genérica.

Uma boa estrutura contém:

1. Identidade e voz — quem é o agente e como ele se comunica.
2. Missão central — uma frase que define o sucesso.
3. Processo de trabalho — passos ordenados e verificáveis.
4. Entregáveis — artefatos concretos e seu formato.
5. Métricas de sucesso — como saber que o trabalho terminou.

Exemplo para uma equipe de API:

# Revisor de Contrato de API

## Missão
Verificar se os endpoints novos ou alterados correspondem à especificação OpenAPI neste
repositório antes de chegarem à revisão. Reportar inconsistências. Não editar código.

## Processo
1. Ler a especificação para cada endpoint afetado pelo diff atual.
2. Para cada um, comparar o manipulador com a especificação: códigos de status,
   esquema de resposta, envelope de erro, cabeçalhos obrigatórios, estilo de paginação.
3. Executar os testes de contrato. Registrar as falhas literalmente.
4. Verificar se novos endpoints foram adicionados à especificação, não apenas ao roteador.
5. Sinalizar qualquer campo de resposta presente no código e ausente na especificação.

## Entregáveis
Uma tabela: endpoint, método, tipo de inconsistência, linha da especificação, linha do código, gravidade.
Sem resumo em prosa. Sem sugestões de correção, a menos que solicitado.

## Concluído quando
Cada endpoint no diff aparece na tabela com um veredito, e a
saída do teste de contrato é incluída como evidência.

Esse arquivo é curto, mas define a especificação, os testes e a definição de pronto da equipe. O agente precisa produzir evidências, não apenas opiniões.

O padrão também funciona para resposta a incidentes, migrações, atualizações de dependência e integrações. Mantenha a estrutura do repositório e substitua o conteúdo genérico pelas regras da sua organização. Para saídas que precisam sobreviver a uma transferência entre pessoas ou agentes, um contrato de formato é essencial — veja transferência de agente e passagem de contexto.

As 149.312 estrelas importam?

149.312 estrelas representam uma adoção expressiva, mas exigem contexto. Repositórios de personas crescem rápido porque são fáceis de entender, compartilhar e experimentar. Uma estrela indica que alguém gostou da ideia; não prova uso contínuo.

O trabalho é mais relevante que a contagem:

• contribuições reais desde outubro de 2025;
• licença MIT;
• limites documentados, incluindo o limite do OpenCode;
• conteúdo específico de domínio, em vez de trivialidades genéricas.

Abra três arquivos de uma divisão que você conhece. Se o conteúdo refletir o que um bom profissional faria, a coleção provavelmente é útil. Se os arquivos parecem anúncios de emprego, ignore o repositório.

Um fluxo de trabalho prático

1. Instale uma divisão. engineering é o ponto de partida para a maioria das equipes.
2. Leia os arquivos. Comece por quatro ou cinco, do início ao fim.
3. Edite as personas. Adicione sua stack, convenções e definição de pronto.
4. Forneça entradas reais. Dê ao revisor de segurança sua especificação OpenAPI; sem ela, ele produzirá apenas uma lista de verificação.
5. Promova as personas úteis. Uma persona usada duas vezes por semana deve virar um Agente salvo em um sistema de gerenciamento de trabalho, não um arquivo copiado manualmente entre máquinas.

Esse último passo determina se a equipe escala o uso ou o abandona silenciosamente.

FAQ

O agency-agents funciona com Cursor e Codex ou apenas com Claude Code?

Funciona com todos eles. convert.sh gera arquivos de integração por ferramenta, e install.sh --tool direciona a instalação. O projeto suporta Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Copilot, Windsurf, Aider, Kimi Code e outros.

Para comparar ferramentas de API em diferentes clientes, consulte nossa análise de clientes de API em Cursor e Copilot.

Devo instalar todos os 300 agentes?

Não. No OpenCode, o runtime registra aproximadamente 119 e descarta o restante silenciosamente. Nas outras ferramentas, você pode instalar todos, mas provavelmente não usará a maioria. Instale por divisão.

As personas tornam o agente mais inteligente?

Elas o tornam mais bem direcionado. A precisão factual — inclusive sobre o que sua API retorna — não muda. Para isso, forneça uma especificação real e siga práticas de limites de segurança para agentes de IA.

É seguro executar o script de instalação?

O script escreve arquivos de definição nos diretórios de configuração da ferramenta, que é exatamente sua finalidade. O projeto é licenciado sob MIT e disponibiliza o código-fonte completo. Use --dry-run para revisar as alterações antes de aplicá-las.

Qual é a diferença entre agency-agents e um framework de agentes?

agency-agents fornece arquivos Markdown que alteram o comportamento de um agente existente. Um framework fornece orquestração de runtime em código.

Para executar várias personas em paralelo, veja Orca. Para frameworks, consulte Strands e AgentKit. São camadas diferentes e não substituem a coleção de personas.

Conclusão

agency-agents materializa uma ideia útil: um agente trabalha melhor quando sabe qual papel desempenhar. Instale uma divisão, leia os arquivos e adapte-os à sua equipe. Em cerca de vinte minutos, você pode obter personas muito mais consistentes.

Mas mantenha claros os limites:

• personas não sabem o que sua API realmente retorna — uma especificação OpenAPI, como as gerenciadas no Apidog, fornece essa verdade;
• personas não persistem em um espaço que uma equipe possa atribuir, acompanhar e revisar — esse é o papel do Sharkly.

Uma lista de personas é um bom começo. Não é uma organização nem uma fonte da verdade.