Uma pasta que cabe dentro de qualquer projeto e faz qualquer agente de IA trabalhar como um engenheiro full-stack de verdade: entende o código que já existe, descobre o que o problema realmente precisa, decide a arquitetura, constrói, e prova que funciona antes de dizer que terminou.
agents-guru é um sistema de engenharia autocontido. Você copia a pasta para dentro de um projeto e o agente que abrir esse projeto ganha um método de trabalho completo, mais um time de papéis especializados para delegar. Não há nada para instalar e nenhuma dependência de configuração global: todo o conhecimento mora em arquivos de markdown puro dentro do diretório.
A ideia é simples. Um agente sem método pula direto para o código e resolve o problema errado. agents-guru impõe um caminho: entender, planejar, implementar, verificar. E não deixa nada ser declarado pronto sem prova.
Não é amarrado a uma ferramenta. Na raiz existe o AGENTS.md, um manual neutro que qualquer agente lê: os princípios, o loop de operação, o índice de capacidades e como consumir tudo de fora. Ferramentas que já leem AGENTS.md (entre elas Codex CLI, Antigravity, Hermes, OpenClaw, Gemini CLI) consomem direto. O Claude Code ganha uma camada por cima, com comandos prontos, descrita em CLAUDE.md. O resto é markdown puro, que qualquer agente abre e aplica.
Clone o repositório:
git clone https://github.com/gutomec/agents-guru.gitPara colocá-lo num projeto seu, copie o conteúdo para a raiz dele (ou abra a própria pasta agents-guru no agente, se for começar do zero):
cp -R agents-guru/. /caminho/do/seu-projeto/Pronto. Agora é só abrir o projeto no seu agente e pedir, em linguagem natural, o que você quer. Você não decora comando nenhum: descreve a tarefa e o agente escolhe sozinho o método e o papel certos. Peça para ele entender o que já existe, depois desenhar a arquitetura de uma feature, implementar, e provar que funciona. Ele segue o caminho na ordem certa e não declara nada pronto sem verificar.
Sete capacidades, do entendimento à prova:
- Compreensão — mapeia um projeto que já existe: arquitetura, stack, modelo de dados, superfície de API, pontos de extensão e riscos, sempre com evidência.
- Escopo — pega um pedido raso e revela o que não foi dito mas é necessário, junto dos efeitos de segunda ordem.
- Gaps e dependências — acha o que falta ou está frágil e rastreia a cadeia de dependências até o elo mais fraco.
- Arquitetura — identifica as necessidades técnicas e escolhe os padrões de código pela força do problema, não pela moda, com o trade-off na mesa.
- Build — implementa interfaces e serviços de backend, no nível e no padrão que o projeto pede.
- Verificação — prova que funciona num loop: testa, e no vermelho corrige e re-testa até passar.
- Qualidade — revisa o código, escreve testes, audita segurança e performance, e refatora sem mudar comportamento, cada um num papel dedicado.
Por baixo das capacidades há um núcleo universal que vale para qualquer codebase: seis métodos e dez papéis. O resto (a parte de interface) é capacidade aplicada que se apoia neles.
Os seis métodos: raciocínio calibrado, planejamento antes do código, o loop de verificação, a escolha de padrões de código, a gestão da janela de contexto, e a autoria de novas peças (para o sistema crescer sem inchar).
Os dez papéis, acionáveis por delegação:
| Papel | Função |
|---|---|
| cartographer | entende o código existente |
| architect | decide a arquitetura |
| gap-hunter | acha o que falta |
| build-verifier | prova que funciona |
| code-reviewer | revisa o diff em contexto fresco |
| debugger | acha a causa-raiz de uma falha |
| test-engineer | escreve e roda testes |
| security-auditor | encontra vulnerabilidades |
| performance-engineer | acha gargalos, com medida |
| refactorer | melhora a estrutura sem mudar comportamento |
Você conversa com o agente como conversaria com um engenheiro sênior. Diz o que precisa, em português mesmo, e ele descobre qual capacidade usar. Não há comando para memorizar.
Na prática, os pedidos caem em alguns tipos. Peça para ele entender um projeto que você acabou de abrir, e ele mapeia a arquitetura, os dados e os riscos antes de tocar em qualquer coisa. Peça para ampliar o escopo de uma ideia ainda rasa, e ele revela o que você não pediu mas vai precisar. Peça para achar o que falta num código ou num plano, e ele aponta os gaps com evidência. Peça uma arquitetura para uma feature, e ele compara os caminhos e escolhe pela força do problema, com o trade-off na mesa. Peça para construir, e ele implementa, seja a interface ou o serviço de backend. Peça para verificar, e ele testa; no vermelho, corrige e re-testa até passar.
Os papéis de qualidade entram do mesmo jeito. Peça uma revisão do que mudou, a causa de um bug, testes para uma função, uma auditoria de segurança, uma caça a gargalos, ou uma refatoração que não altera o comportamento. O agente delega para o papel certo quando a tarefa casa.
Por baixo, no Claude Code isso vira slash commands; em outro agente, vira a leitura do método certo no AGENTS.md. Você não precisa saber disso para usar. É só pedir.
AGENTS.md manual neutro do agente (qualquer ferramenta)
CLAUDE.md camada operacional do Claude Code
.claude/
agents/ os papéis especializados
commands/ as receitas (slash commands)
skills/ os métodos autocontidos (markdown puro, portáveis)
checklists/ critérios de qualidade
scripts/
doctor.ts valida a integridade do diretório
A qualquer momento, confirme que o diretório está completo e consistente:
bun ./scripts/doctor.tsVocê deve ver algo assim:
agents-guru doctor
Verificados: 94 item(ns) ok.
Scaffold íntegro. Nenhum problema encontrado.
O doctor confere que todos os arquivos esperados existem, que o frontmatter é válido e que toda reference citada resolve. Sai com código 0 quando está tudo certo, e com 1 listando o que falta. É a prova de que a pasta funciona em qualquer máquina, e a rede de segurança para quando você adiciona uma peça nova.
- Um agente de IA via CLI que leia
AGENTS.mdouCLAUDE.md. - Bun, apenas para os scripts de verificação. Os papéis funcionam sem ele; os scripts é que dão a checagem determinística.