Superpowers ou o seu próprio CLAUDE.md: quando vale adotar um framework de skills pronto?

Adotar o método pronto, manter as suas regras na unha, ou misturar os dois

Fala aí, beleza? O Superpowers é um framework de skills agênticas e metodologia de desenvolvimento distribuído como plugin, mantido no repositório obra/superpowers, da conta obra (Jesse Vincent)

Do outro lado da balança tá o CLAUDE.md, o arquivo de instruções persistentes que o Claude Code lê no início de toda sessão, com o contexto do projeto, comandos de build, convenções e as regras do tipo "sempre faça X"

O foco deste post é a decisão: o que tu ganha em consistência adotando um método fechado, o que abre mão em liberdade de fluxo, e como dá pra combinar os dois sem escolher lado

O que o Superpowers entrega de pronto

A ideia do framework é essa: em vez de você descrever o seu processo em texto, ele já chega com o processo embalado em skills

As skills vivem em pastas nomeadas dentro do diretório skills/ do repositório: skills/brainstorming, skills/writing-plans, skills/executing-plans, skills/writing-skills e skills/using-superpowers

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

A de brainstorming roda ANTES de escrever código: refina a ideia por perguntas, explora alternativas e apresenta o design em seções pra você validar

Com o design aprovado, a writing-plans entra e quebra o trabalho em tarefas pequenas, cada uma com caminho de arquivo exato e passos de verificação

Se você conhece a lógica de "pensa, escreve o plano, só então executa", é isso mesmo, só que virou peça instalável em vez de parágrafo no seu arquivo de regras

Os comandos e a pegadinha do prefixo:

Os comandos de barra são namespaced pelo prefixo do plugin: /superpowers:brainstorm pro refino de design, /superpowers:write-plan pro plano de implementação e /superpowers:execute-plan pra execução em lotes

Tome cuidado com o material antigo que anda por aí: as versões sem prefixo (/brainstorm, /write-plan e /execute-plan) foram depreciadas, mostram aviso apontando pras skills correspondentes e serão removidas no próximo major

Como ele chega no seu Claude Code:

Pelo marketplace oficial de plugins da Anthropic, o claude-plugins-official:

/plugin install superpowers@claude-plugins-official

Ou pelo marketplace da comunidade mantido pelo mesmo autor:

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

As skills são distribuídas sob licença MIT, e a versão mais recente que localizei nas releases é a v6.2.0, publicada em 2026-07-23

Um detalhe de arquitetura que ajuda a entender o projeto: a partir da v2.0 as skills, scripts e documentação saíram do plugin pra um repositório próprio, o obra/superpowers-skills, e o plugin virou um shim que gerencia um clone local desse repositório

E não, ele não é exclusivo do Claude Code: o README lista instalação pra Codex, Cursor, Gemini CLI e OpenCode, entre outros harnesses, e existe até uma entrada superpowers no marketplace de plugins do Codex, da OpenAI

O que o seu CLAUDE.md (e suas skills próprias) já resolvem

Agora o outro prato da balança, que muita gente subestima porque acha que é "só um markdown"

O Claude Code trabalha com níveis de memória: política gerenciada pela organização, nível de usuário e nível de projeto

O de usuário fica em ~/.claude/CLAUDE.md e o de projeto em ./CLAUDE.md, os dois mantidos manualmente por você

Pra não começar do zero, o comando /init lê o projeto e escreve um CLAUDE.md inicial com comandos de build, arquitetura e convenções

E quando o arquivo cresce demais?

Ele aceita import: arquivos referenciados com @caminho são expandidos e carregados no contexto junto com o CLAUDE.md, e caminho relativo resolve a partir do arquivo que importa

Ou seja, dá pra quebrar aquele monstro de 400 linhas em pedaços por assunto e importar

Tem também a auto memória, que é outra coisa: são notas que o próprio Claude Code escreve, em pasta separada, dentro de ~/.claude/projects/<projeto>/memory/, uma pasta por raiz de repositório git, e o comando /memory abre essa pasta

Suas skills próprias:

Você também pode escrever skill sem framework nenhum

Skill própria vive em pasta com um arquivo SKILL.md: pessoal em ~/.claude/skills/<nome>/SKILL.md, que vale em todos os projetos, ou de projeto em .claude/skills/<nome>/SKILL.md

Todo SKILL.md tem duas partes: frontmatter YAML entre marcadores --- indicando quando usar a skill, e as instruções em markdown logo abaixo

E tem uma regra de ouro pra quem quer misturar os dois mundos: skill pessoal ou de projeto com o mesmo nome sobrescreve a versão embutida ou de plugin

Superpowers x CLAUDE.md próprio: comparação lado a lado

Quando adotar o framework e quando ficar no caseiro

Time novo ou projeto sem processo escrito:

Aqui o framework ganha fácil

Se cada dev do time conduz o agente de um jeito, um manda escrever o código direto, outro pede plano, outro nem revisa, o método fechado resolve inconsistência sem reunião de padronização

Quando a conversa já é de equipe, ela costuma esbarrar em custo também, e eu abri essa conta nos planos de time do Claude Code

O que você abre mão: do seu jeito de trabalhar, porque agora o design e o plano seguem a régua de outra pessoa

Repositório com convenções muito próprias e stack incomum:

Aqui o caseiro ganha

Método pronto não conhece o seu domínio, nem aquele detalhe do tipo "nesse repo, migration nunca roda sem X"

Esse conhecimento é exatamente o que mora bem no CLAUDE.md e nas suas skills de projeto

O que você abre mão: de consistência garantida, porque regra escrita à mão envelhece e ninguém lembra de atualizar

Você trabalha em mais de um agente de código:

Se o seu dia alterna entre harnesses, o framework atravessa: o mesmo conjunto de skills tem instalação listada pra Codex, Cursor, Gemini CLI e OpenCode

CLAUDE.md, por natureza, é o formato de memória do Claude Code

O que você abre mão: de personalização fina por ferramenta

As regras precisam chegar nas sessões remotas:

Esse ponto pega muita gente de surpresa

Skill que existe só na pasta pessoal não sincroniza: sessão na nuvem carrega skill de projeto commitada em .claude/skills/ do repositório clonado, e skill que só está em ~/.claude/skills/ é reportada como não encontrada

Então se o processo precisa valer em todo lugar, commit no projeto

O que você abre mão: privacidade das suas manias, elas viram parte pública do repo

Uso híbrido, que é o que eu faria:

Instala o framework, roda um tempo e sobrescreve só a skill que atrapalha o seu fluxo, já que skill local tem precedência sobre skill de plugin

O que você abre mão: de simplicidade, porque agora você mantém duas fontes de verdade e precisa lembrar qual venceu

O que aprendi usando skills no dia a dia

Deixa eu ser honesto no escopo: minha vivência aqui é com skills no geral, não com o Superpowers em si

No vídeo sobre a Archify eu mostro justamente o formato que está por trás dos dois caminhos deste post, a skill mudando o comportamento do agente

Quando testei, instalei pelo terminal com um comando npx do repositório de skills, escolhendo o Claude Code durante a instalação, e optei pela instalação recomendada via symlink em vez de cópia local

Processo simples, de um comando só

A parte que me convenceu foi a comparação: eu comparei o resultado da skill especializada com simplesmente mandar um prompt pra uma IA genérica, e a entrega final fica MUITO melhor com a skill pronta

Usei de duas formas bem diferentes

Primeiro pra idear um sistema do zero, planejei um e-commerce

Depois pedi pra IA clonar o repositório da Evolution API, analisar o código e gerar um diagrama de arquitetura de runtime com componentes principais, fluxo de dados, dependências externas e fronteiras de segurança

E ela executou o pedido inteiro: clonou, entendeu o projeto e devolveu o diagrama

Abrindo o desenho dava pra ver a complexidade real: o caminho da mensagem até a API, banco de dados, cache, integração com armazenamento em nuvem e a resposta voltando

Aliás, esse tipo de uso puxa uma pergunta que já rendeu post aqui: quem vê o seu código quando o agente clona e lê um repositório inteiro

Dois aprendizados que valem pra qualquer skill pronta, inclusive framework de processo

O primeiro: você não precisa escrever o pedido de forma ultra técnica, dá pra descrever com as suas palavras em português e ainda assim sair coisa boa

O segundo: o resultado vira insumo, não ponto final

Eu achei no diagrama um componente que eu não conhecia e usei a própria descrição gerada pra entender do que se tratava e seguir pesquisando

Depois rodei um segundo prompt de evolução (transmissões ao vivo, marketplace no app, busca de perfis, versão web, escala pra outros países e alerta de queda antes da reclamação do usuário) e a skill atualizou o diagrama existente com as novas funcionalidades, incluindo marketplace e pagamentos

O desenho ainda pode voltar pra IA como insumo de revisão do plano, pra checar o que ficou faltando

Minha leitura é essa: arquitetura mal planejada tende a não escalar ou deixar buraco, e ter o desenho ajuda em sistema de pequeno a grande porte

Pra começar do zero e ver skill funcionando na prática antes de decidir entre framework e caseiro, esse vídeo mostra o ciclo completo: instalar, pedir e ler o que voltou 🙂

Veredito: qual escolher no seu caso

Sem ficar em cima do muro

Se o seu problema é inconsistência de processo, adote o Superpowers no Claude Code e pare de reescrever regra de fluxo

Você ganha design, plano e execução prontos, mantidos por releases do repositório e ainda portáveis pra outros agentes, sem escrever uma linha de metodologia

O custo é liberdade: quem dita o ritmo passa a ser o método do framework, e o brainstorm vem antes do código quer você queira ou não

Se você já tem convenções fortes, stack fora do comum e um CLAUDE.md que reflete de verdade como o time trabalha, fica no caseiro

O custo aqui é manutenção eterna, na mão, e a chance de o arquivo virar folclore desatualizado que ninguém revisa

E se nenhum dos dois extremos te serve, o híbrido segue de pé: framework como base, skill local sobrescrevendo o que atrapalha

E se te acalma: a decisão é reversível

Plugin instala e desinstala por comando, e skill local de mesmo nome sobrescreve a de plugin, então dá pra testar sem casamento

Conclusão

Antes de instalar qualquer coisa, abre o seu CLAUDE.md e lê ele inteiro

Eu aposto que metade das regras que estão lá são justamente o processo que o framework entrega pronto, e a outra metade é conhecimento de domínio que nenhum framework vai adivinhar

Essa leitura já responde boa parte da sua dúvida

Depois disso, testa o Superpowers em um projeto de baixo risco, roda um ciclo de brainstorm, plano e execução, e compara com o que você já fazia

Se brigar com o seu fluxo, sobrescreve a skill que atrapalha ou desinstala, sem drama

Fica de olho aqui no blog e lá no canal, que a gente vai continuar destrinchando esse assunto de skills e memória do Claude Code

Até o próximo post! =)