Guia de Início para Agency Agents: transforme o Claude Code em um “time dos sonhos” com 100+ papéis de especialistas em IA

Sabemos todos que escrever prompts é uma espécie de arte. Com o mesmo modelo Claude, pedir “escreva um componente React” e pedir “na perspectiva de um engenheiro frontend sênior, siga as normas de acessibilidade WCAG 2.1 AA, usando TypeScript + React 18 para criar uma tabela virtual acessível” gera resultados de qualidade drasticamente diferentes.

Agency Agents existe justamente para resolver esse problema — ele já orquestra tudo para você: são 16 departamentos e 100+ papéis de especialistas em IA (Frontend Developer, Backend Architect, Security Auditor, Reddit Community Ninja……), com personas, processos, entregáveis e métricas de avaliação bem definidos. Basta ativar o papel correspondente e a IA automaticamente entra no “modo profissional”.

O mais legal é que o repositório já vem com convert.sh e install.sh: você pode sincronizar, em um único passo, a mesma definição de papéis para Claude Code, OpenClaw, Cursor, OpenCode, Codex, Gemini CLI e mais de 10 ferramentas — sem precisar manter várias configurações.

Neste artigo, vamos começar do zero para colocá-lo em funcionamento e demonstrar como ativar um papel no OpenClaw para atender uma necessidade real.

Visão Geral do Projeto

o msitarzewski/agency-agents nasceu de uma discussão em um post no Reddit com a pergunta: “Se você pudesse contratar uma equipe de funcionários de IA, quais cargos você escolheria?”. Após meses de iteração, ele evoluiu para uma biblioteca de papéis de agentes de IA bem completa:

• 16 departamentos: engineering, design, marketing, finance, security, sales, testing…… praticamente cobre todos os cargos de que uma empresa de software precisa
• 100+ papéis: de Frontend Developer e Backend Architect até Whimsy Injector e Reality Checker — papéis com “temperatura de persona”
• Entregáveis mensuráveis: cada papel já marca success metrics, deliverables e critical rules — não são prompts genéricos
• Compatível com múltiplas ferramentas: a mesma fonte Markdown pode ser convertida para formatos como Claude Code subagent, OpenClaw workspace, Cursor rule, OpenCode agent, Codex TOML etc.

A maior diferença em relação a modelos tradicionais de prompt é que aqui cada papel tem uma configuração totalmente “personalizada” (tom, estilo, mecanismo de memória) + fluxo de negócio (mission / workflow / deliverables). É muito mais próximo de “uma descrição de cargo”.

Dificuldade / Duração / Benefícios

• Dificuldade: ⭐⭐ (usa comandos no terminal, sem nenhuma barreira de código)
• Duração: 15-30 minutos (primeira instalação + ativar um papel + executar uma demanda real)
• Benefícios: transformar o Claude Code / OpenClaw em uma equipe de IA com “escalonamento sob demanda”, mantendo por muito tempo as personas profissionais estáveis

Perfil do Público-Alvo

• Desenvolvedores que querem ganhar produtividade com IA, mas acham escrever prompts muito trabalhoso
• Engenheiros frontend / backend / full-stack / segurança / testes com 1 a 5 anos de experiência
• Pessoas que já usam ferramentas de programação com IA como Claude Code, Cursor, OpenClaw, Codex etc.
• Líderes técnicos que querem implementar “normas de colaboração com IA” na equipe

Dependências e Ambiente

Árvore completa da estrutura do projeto

agency-agents/
├── academic/                       # Pesquisa acadêmica
├── design/                         # Design de UI/UX
├── engineering/                    # Desenvolvimento (o maior departamento, 30+ papéis)
├── finance/                        # Finanças
├── game-development/               # Desenvolvimento de jogos
├── gis/                            # Informação geográfica
├── marketing/                      # Marketing
├── paid-media/                     # Publicidade paga
├── product/                        # Produto
├── project-management/           # Gestão de projetos
├── sales/                          # Vendas
├── security/                       # Segurança
├── spatial-computing/              # Computação espacial
├── specialized/                    # Especialistas (áreas específicas)
├── strategy/                       # Estratégia
├── support/                        # Suporte ao cliente
├── testing/                        # Testes
├── integrations/                   # Saídas de integrações com múltiplas ferramentas
│   ├── openclaw/                   # Workspace do OpenClaw (SOUL.md + AGENTS.md + IDENTITY.md)
│   ├── opencode/                   # Agente OpenCode (.md + YAML frontmatter)
│   ├── claude-code/                # Subagente do Claude Code
│   ├── cursor/                     # Regra do Cursor (.mdc)
│   ├── codex/                      # Agente custom do Codex (TOML)
│   ├── gemini-cli/                 # Subagente do Gemini CLI
│   ├── github-copilot/             # GitHub Copilot
│   ├── aider/                      # Aider CONVENTIONS.md
│   ├── windsurf/                   # Windsurf .windsurfrules
│   ├── kimi/                       # Kimi Code CLI
│   ├── qwen/                       # Qwen Code SubAgent
│   └── mcp-memory/                 # Memória de longo prazo via MCP
├── scripts/
│   ├── convert.sh                  # Conversor de formatos: definição do papel → formato da ferramenta
│   ├── install.sh                  # Instalação em um clique no ambiente local
│   ├── lib.sh                      # Funções compartilhadas
│   └── lint-agents.sh              # Lint das definições de papéis
├── README.md
└── CONTRIBUTING.md

Passo a passo

A seguir, vamos usar OpenClaw como exemplo para demonstrar o fluxo completo. Para outras ferramentas, basta substituir --tool pelo nome correspondente.

Passo 1: Clonar o repositório

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

Se a rede estiver restrita, primeiro faça fork no Gitee / no seu GitHub e então clone:

git clone https://github.com/<your-fork>/agency-agents.git
cd agency-agents

Passo 2: Ver departamentos e papéis que podem ser instalados

O install.sh oferece um modo “lista” bem conveniente:

./scripts/install.sh --list teams

Você verá uma saída parecida com esta:

engineering          33 agents
design               12 agents
marketing            18 agents
security              9 agents
testing              11 agents
...

Se quiser instalar apenas alguns departamentos (por exemplo, engineering + security), basta filtrar depois com --division.

Passo 3: Gerar arquivos de integração no formato do OpenClaw

O convert.sh divide o Markdown de origem no kit que o OpenClaw espera: SOUL.md (persona) + AGENTS.md (processo) + IDENTITY.md (identidade), assim:

./scripts/convert.sh --tool openclaw

Com sucesso, o diretório integrations/openclaw/ terá mais de 100 subdiretórios:

ls integrations/openclaw/ | head -20
# agency-frontend-developer
# agency-backend-architect
# agency-security-auditor
# agency-reddit-community-ninja
# agency-whimsy-injector
# ...

Cada subdiretório fica assim:

agency-frontend-developer/
├── SOUL.md        # Persona do papel: identidade, memória, tom, estilo
├── AGENTS.md      # Fluxo do negócio: mission, deliverables, workflow
└── IDENTITY.md    # Cartão de identidade: emoji + nome + vibe

Passo 4: Instalar no OpenClaw com um clique

# Instalação completa (cerca de 100+ papéis)
./scripts/install.sh --tool openclaw

# Recomendado: escolher por departamento (evita enfiar tudo de uma vez)
./scripts/install.sh --tool openclaw --division engineering,security

O script copia automaticamente o workspace para ~/.openclaw/agency-agents/ e registra no gateway do OpenClaw.

Passo 5: Reiniciar o gateway do OpenClaw para ativar os novos papéis

openclaw gateway restart

Passo 6: Ativar o Frontend Developer no OpenClaw

openclaw chat --agent agency-frontend-developer

Ou, no arquivo de configuração, altere o agent padrão para agency-frontend-developer, para que ao iniciar o OpenClaw ele entre automaticamente nesse papel.

Passo 7: Rodar uma demanda real

Vamos pedir para o Frontend Developer recém-ativado escrever um componente de tabela virtual acessível:

openclaw chat --agent agency-frontend-developer <<'EOF'
Ajude-me a escrever um componente DataTable usando React 18 + TypeScript. Requisitos:
1. Usar @tanstack/react-virtual para virtualização (virtual scrolling)
2. Atender a norma de acessibilidade WCAG 2.1 AA
3. Celulas com suporte a renderização customizada
4. Evento de clique na linha configurável
5. Fornecer código completo que rode diretamente
EOF

Você vai perceber que o estilo do código gerado é bem consistente — porque as restrições “WCAG 2.1 AA”, “memo envolvido (memo wrap)” e “otimização Core Web Vitals” já ficam cristalizadas na definição do papel. Assim, não precisamos repetir esses requisitos toda vez no prompt.

Passo 8: Demonstração cross-tool (opcional)

Com a mesma definição de papel, converter para Cursor também é só uma linha:

./scripts/convert.sh --tool cursor
./scripts/install.sh --tool cursor --agent frontend-developer,backend-architect

Solução de problemas (FAQ)

Q1: install.sh dá permission denied

Geralmente é porque install.sh não tem permissão de execução. Para usuários macOS / Linux:

chmod +x scripts/install.sh scripts/convert.sh scripts/lib.sh
./scripts/install.sh --tool openclaw

Se você estiver no Windows e esse erro ocorrer no Git Bash, primeiro confirme se o repositório foi baixado com git clone (não descompacte zip) e então rode os scripts com o Git Bash.

Q2: OpenClaw mostra “agent not found” ou “não registrado”

Em 99% dos casos, depois de instalar os papéis, você não reiniciou o gateway:

openclaw gateway restart
openclaw agent list | grep frontend-developer
# Se aparecer saída, o registro foi bem-sucedido

Se ainda não funcionar, verifique se realmente existe o arquivo agency-frontend-developer/SOUL.md dentro de ~/.openclaw/agency-agents/:

ls ~/.openclaw/agency-agents/agency-frontend-developer/
# Deve aparecer SOUL.md  AGENTS.md  IDENTITY.md

Q3: OpenCode instala muitos papéis e só mostra os 119 primeiros

Esse é um bug conhecido do upstream do OpenCode (issue #27988) — em tempo de execução ele registra apenas cerca de 119 subagents; os que passam disso são descartados silenciosamente.

Solução: use --division para dividir a instalação e mantenha o total de papéis dentro de 119:

./scripts/install.sh --tool opencode --division engineering
./scripts/install.sh --tool opencode --division marketing --out ~/.opencode-extra/

Quando detectar que passou do limite, o script vai emitir um warning. Você também pode fazer um dry-run antes:

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

Q4: frontmatter do papel sem campos obrigatórios faz o convert pular

O convert.sh pula arquivos de origem que não tenham o campo name. Se você fez fork de um papel e percebeu que ele não aparece em integrations/openclaw/:

# 1. Verifique o frontmatter do arquivo de origem
head -10 engineering/your-custom-agent.md

# 2. Pelo menos precisa conter:
#    ---
#    name: Your Agent Name
#    description: One-line description
#    ---

# 3. Reconverter
./scripts/convert.sh --tool openclaw

Q5: Erro por quebra de linha dos scripts bash no Windows

Se você copiou o script para o Windows depois de descompactar um zip, o arquivo pode ter quebras de linha CRLF, e o bash pode acusar \r: command not found:

# Opção A: use git clone em vez de baixar zip
git clone https://github.com/msitarzewski/agency-agents.git

# Opção B: converter manualmente os caracteres de fim de linha (Git Bash)
dos2unix scripts/*.sh

Q6: Conflito de persona entre papéis / “troca de contexto” (context bleeding)

Se você ativar o Frontend Developer e, em seguida, o Security Auditor em uma mesma session, pode notar que o tom do primeiro papel fica “residual” no contexto. Isso acontece porque a maioria das ferramentas CLI injeta o agent como “system prompt level”, e ao trocar o agent não há limpeza automática do histórico de conversa.

Solução:

# Abra uma nova sessão antes de trocar de agent
openclaw chat --new-session --agent agency-security-auditor

Ou, no OpenClaw, habilite a opção de “arquivar automaticamente as sessões antigas ao trocar de agent”.

Leitura adicional / Direções avançadas

1. Personalizar modelos de papéis

O arquivo engineering/engineering-frontend-developer.md é um ótimo exemplo. Tente fazer fork e criar uma versão como engineering-frontend-developer-chinese.md:

---
name: Engenheiro Frontend (versão em chinês)
description: Engenheiro frontend especializado em React/Vue, implementação de UI e otimização de performance, com comentários em chinês
color: cyan
emoji: 🖥️
vibe: Saída em chinês, seguindo as normas de frontend da ByteDance
---

# Engenheiro Frontend (versão em chinês)

Você é um**engenheiro frontend**，focado nas tecnologias Web modernas……

## 🧠 Sua identidade e sua memória
- Papel: especialista em aplicações Web modernas e implementação de UI
- Personalidade: atenção a detalhes, sensível a performance, foco no usuário
- Memória: lembrar padrões comuns de UI e melhores práticas de acessibilidade

Depois rode ./scripts/convert.sh --tool openclaw e o novo papel aparecerá em integrations/openclaw/.

2. Adicionar memória de longo prazo aos papéis com MCP-Memory

O diretório integrations/mcp-memory/ fornece uma configuração de MCP memory server. Após ativar, os papéis podem manter preferências ao longo de sessões (por exemplo: “este time prefere usar pnpm em vez de npm”). Para o método de configuração, veja o mcp-memory/README.md dentro do repositório.

3. Workflow de colaboração com múltiplos agentes

Um único papel já é bem poderoso, mas ainda mais estimulante é orquestrá-los em uma cadeia colaborativa. Por exemplo:

Demanda → [Product Manager] quebra as tarefas
         → [Frontend Developer] + [Backend Architect] implementam em paralelo
         → [Code Reviewer] faz auditoria automática
         → [QA Test Engineer] roda os testes
         → [Technical Writer] gera a descrição do PR

O OpenClaw tem o recurso de “workflow” embutido que consegue encadear esses papéis. Veja mais em documentação oficial do OpenClaw.

4. Reduzir o custo de chamadas

Como mencionado acima, os papéis de especialistas do Agency Agents usam modelos de ponta por trás. Rodar continuamente não é barato. Se você quiser rodar com preço de “meia oficial” usando os mesmos modelos, dá para conectar direto ao Defapi (na seção “Dependências e Ambiente” há uma explicação detalhada), sem necessidade de mudar código.

---

Este artigo foi escrito com base no msitarzewski/agency-agents na branch main atual (commit em 2026-06-13). Depois disso, o repositório pode adicionar departamentos ou ajustar interfaces de scripts. Recomendamos que você faça um git pull antes de colocar a mão na massa para sincronizar a versão mais recente.