⚡ Superpowers — Desenvolvimento com Agentes de IA

O anti-padrão de pedir ao agente para implementar funcionalidades sem especificação, contexto ou plano. O resultado é código que funciona tecnicamente mas resolve o problema errado.

Sem entender esse anti-padrão, você continuará repetindo o ciclo de reescrever código várias vezes, desperdiçando horas de sessão e tokens.

Ambiguidade de requisitos, especificação implícita, custo de retrabalho, garbage in / garbage out.

Skills são arquivos SKILL.md que injetam comportamentos no agente via contexto de sistema. Eles moldam como o agente responde a gatilhos específicos.

Entender a arquitetura de skills permite customizar o comportamento do agente para o seu workflow específico e criar skills próprias.

Frontmatter YAML, gatilhos de skill, injeção de contexto, comportamento emergente, skills core vs. plugins.

O processo de instalar o Superpowers em diferentes plataformas de agente de IA, adaptando a configuração para cada harness.

Cada plataforma tem suas particularidades. Instalar corretamente garante que as skills sejam carregadas e os hooks sejam executados.

Harness, settings.json, diretório .claude, sync script, configuração por projeto vs. global.

Hooks são scripts que o harness executa automaticamente em momentos específicos da sessão — antes de uma mensagem, após uma ferramenta, ao encerrar.

Hooks permitem automações que o agente não consegue fazer sozinho: injetar contexto, validar outputs, registrar ações.

PreToolUse, PostToolUse, Stop hooks, stdin/stdout, exit codes, permissões de hook.

O pipeline completo de desenvolvimento com agentes: brainstorm → spec → plano → TDD → execução → revisão → merge.

Seguir o fluxo completo garante que cada fase valide a anterior, eliminando erros acumulados e retrabalho.

Pipeline de desenvolvimento, gates de validação, handoff entre fases, contexto acumulado.

Verificação prática de que a instalação está correta: skills carregadas, hooks ativos, agente respondendo aos gatilhos esperados.

Uma instalação silenciosamente incorreta desperdiça horas. Verificar logo no início poupa problemas futuros.

Smoke test, verificação de skills ativas, teste de gatilho, diagnóstico de instalação.

A skill de brainstorming instrui o agente a fazer perguntas direcionadas antes de qualquer implementação, usando o método socrático para revelar requisitos implícitos.

Perguntas certas antes do código economizam horas de refatoração. Um agente que age sem perguntar está adivinhando — e adivinhações são caras.

Requisitos implícitos, perguntas abertas vs. fechadas, clareza antes de velocidade, custo de assunções erradas.

O processo de transformar uma conversa informal sobre uma feature em um documento de especificação estruturado e revisável.

Spec documents criam um contrato entre você e o agente. Sem isso, cada sessão parte do zero e o agente pode tomar direções diferentes.

Spec document, critérios de aceitação, casos de borda, dependências técnicas, escopo negativo.

Validação seção por seção da spec antes de avançar. O agente apresenta cada parte e aguarda aprovação explícita antes de continuar.

Aprovar tudo de uma vez é uma ilusão de revisão. Aprovação incremental garante que você realmente leu e concordou com cada parte.

Aprovação incremental, checkpoints de validação, feedback loop curto, custo de mudança tardia.

Uma interface visual que o agente inicia durante o brainstorming para renderizar a spec em tempo real, permitindo revisar o documento enquanto a conversa acontece.

Ler uma spec em texto puro no chat é difícil. O servidor visual muda o formato de revisão e acelera a validação.

Servidor local, renderização em tempo real, markdown-to-HTML, companion de design, porta 3000.

As seções obrigatórias de uma spec bem escrita: objetivo, contexto técnico, critérios de aceitação, casos de borda, escopo negativo.

Uma spec incompleta é quase tão ruim quanto não ter spec. Saber o que deve estar presente evita lacunas que o agente vai preencher com suposições.

Objetivo, contexto, critérios de aceitação, casos de borda, fora de escopo, dependências, perguntas em aberto.

Exercício prático completo: partir de uma ideia vaga, conduzir o brainstorming com o agente e chegar a uma spec aprovada pronta para planejamento.

O conceito só sedimenta quando você executa o fluxo completo. Este exercício une todos os tópicos anteriores em uma sessão real.

Sessão de brainstorming real, critérios de "spec aprovada", transição para planejamento.

A distinção entre planos que realmente guiam o agente (com caminhos de arquivo, código real, verificações) e planos genéricos que apenas listam intenções.

Um plano genérico dá ao agente margem para improvisar — e improviso com agentes gera divergência. Um plano bom é uma trilha sem bifurcações.

Granularidade de tarefa, especificidade de caminho, verificabilidade, margem de improviso.

O princípio de quebrar planos em tarefas pequenas o suficiente para serem executadas em 2-5 minutos cada, com verificação clara de conclusão.

Tarefas grandes criam contexto longo e perda de foco. Tarefas de 2-5 minutos permitem commits frequentes e detecção precoce de desvios.

Granularidade, atomic tasks, commit frequente, detecção precoce, feedback loop curto.

Os três elementos que toda tarefa de plano deve ter: caminho exato do arquivo, trecho de código completo (não pseudocódigo) e critério de verificação.

Sem esses três pilares, o agente preenche lacunas com interpretação própria. Com eles, a tarefa é determinística.

Caminho absoluto, código completo vs. pseudocódigo, critério de verificação, determinismo de tarefa.

O processo pelo qual o agente revisa o plano que acabou de escrever, verificando completude, consistência e ausência de ambiguidades antes de apresentá-lo.

Agentes cometem erros na geração de planos. A auto-revisão captura esses erros antes que eles se tornem bugs na execução.

Auto-revisão, checklist de plano, completude, consistência interna, ambiguidade.

O ciclo de revisão do plano com feedback humano antes de iniciar a execução. O agente ajusta o plano baseado nas correções e reapresenta.

Corrigir um plano custa segundos. Corrigir código implementado errado custa horas. Iterar o plano antes de executar é o investimento mais rentável.

Iteração de plano, custo de mudança, feedback antes da execução, aprovação de plano.

Exercício prático: pegar a spec do módulo anterior e criar um plano de implementação completo com todos os pilares, revisão e aprovação.

A transição spec→plano é onde mais ocorrem perdas de requisitos. Este exercício treina exatamente essa transição crítica.

Transição spec→plano, cobertura de requisitos, rastreabilidade, plano aprovado.

A fase RED do TDD: escrever o teste antes do código de produção, executá-lo e confirmar que ele falha pelo motivo certo antes de implementar.

Agentes frequentemente escrevem testes que passam sem nunca terem falhado, criando falsa segurança. Ver o RED garante que o teste realmente testa algo.

Red phase, falha esperada, motivo de falha correto, testes que passam sem testar, falsa segurança.

Aplicação prática dos princípios You Ain't Gonna Need It e Don't Repeat Yourself no contexto de agentes, que tendem à super-engenharia por padrão.

Agentes adoram abstrações prematuras e generalizações desnecessárias. YAGNI e DRY são freios importantes para manter o código simples e testável.

YAGNI, DRY, super-engenharia, abstração prematura, código mínimo para passar o teste.

Os antipadrões mais comuns que agentes cometem ao escrever testes: testes tautológicos, mocks excessivos, testes de implementação e não de comportamento.

Um conjunto de testes ruim é pior que nenhum — dá falsa confiança. Identificar esses antipadrões permite corrigi-los antes de confiar nos testes.

Teste tautológico, mock excessivo, teste de implementação vs. comportamento, falsa cobertura.

A disciplina de fazer um commit ao final de cada ciclo RED-GREEN completo, criando um histórico granular e pontos de retorno claros.

Commits frequentes são a rede de segurança do TDD. Se algo quebrar, você sabe exatamente o que mudou desde o último estado verde.

Commit atômico, histórico granular, ponto de retorno, estado verde, commit message por ciclo.

A fase REFACTOR do TDD: melhorar o código depois que os testes passam, mantendo todos os testes verdes durante todo o processo.

Refatoração sem testes é reescrita arriscada. Com testes verdes, cada passo de refatoração é verificado imediatamente.

Refatoração segura, invariância de comportamento, pequenos passos, cobertura como rede de segurança.

Exercício completo: implementar uma feature pequena do zero usando TDD estrito com o agente — RED, GREEN, REFACTOR, commit.

TDD com agente é diferente de TDD solo. Este exercício treina a coordenação entre humano e agente em cada fase do ciclo.

TDD assistido por agente, coordenação humano-agente, ciclo completo, disciplina de processo.

A skill executing-plans organiza a execução em lotes de tarefas com checkpoints obrigatórios onde o humano revisa o progresso antes de continuar.

Execução sem checkpoints deixa erros se acumularem por horas. Checkpoints regulares permitem corrigir o curso cedo.

Lotes de tarefa, checkpoint humano, aprovação de lote, correção de curso, execução supervisionada.

O padrão de delegar cada tarefa do plano a um subagente independente, com contexto isolado, que reporta o resultado ao agente coordenador.

Subagentes evitam contaminação de contexto entre tarefas e permitem execução de múltiplas tarefas independentes em paralelo.

Subagente, isolamento de contexto, agente coordenador, delegação, relatório de resultado.

O processo de revisão em dois estágios: primeiro verificar se o código cumpre a spec, depois verificar qualidade técnica independentemente.

Misturar os dois critérios de revisão confunde prioridades. Separar garante que conformidade com spec e qualidade sejam avaliadas com o critério certo.

Revisão de conformidade, revisão de qualidade, critérios separados, prioridade de correção.

O critério de decisão entre usar executing-plans (tarefas sequenciais com dependência) vs. subagents (tarefas independentes paralelizáveis).

A escolha errada desperdiça tempo ou cria conflitos. Entender quando cada abordagem se aplica maximiza velocidade e controle.

Dependência sequencial, independência de tarefa, overhead de coordenação, trade-off velocidade/controle.

Técnicas para monitorar o progresso de subagentes em execução e intervir quando necessário sem perder o contexto do plano maior.

Subagentes podem desviar. Saber quando e como intervir — sem travar o fluxo — é essencial para execução de planos longos.

Sinal de desvio, intervenção de contexto, reconstrução de estado, interrupção controlada.

Exercício prático: pegar o plano do módulo anterior e executá-lo com subagentes, incluindo monitoramento e revisão em dois estágios.

A execução com subagentes é o modo mais poderoso do Superpowers. Este exercício consolida todo o pipeline até agora.

Pipeline completo, execução com subagentes, revisão em dois estágios, resultado entregue.

O processo estruturado em 4 fases: observar o sintoma, formular hipóteses, testar hipóteses sistematicamente, identificar a causa raiz.

Sem processo, debugging com agente é uma série de tentativas aleatórias. Com as 4 fases, cada passo elimina hipóteses e converge para a solução.

Sintoma vs. causa, hipótese, eliminação sistemática, causa raiz, método científico aplicado.

O padrão de esperar por condições específicas ao invés de sleep fixo — aguardar que um serviço responda, que um arquivo exista, que um processo termine.

Sleep fixo cria testes frágeis e debugging impreciso. Condition-based waiting é determinístico e mais rápido na maioria dos casos.

Polling de condição, timeout com fallback, race condition, determinismo de sincronização.

A prática de exigir evidência verificável antes de declarar que um bug foi corrigido — logs, output de teste, screenshot, não apenas "parece que está funcionando".

Agentes frequentemente declaram sucesso prematuramente. Exigir evidência real elimina a falsa conclusão de debugging.

Evidência verificável, prova de correção, output de teste, declaração prematura de sucesso.

Técnicas avançadas de rastreamento: stack traces, logs estruturados, bisect de git, reprodução mínima do bug, isolamento de variáveis.

Bugs em sistemas complexos raramente são óbvios. Técnicas de rastreamento permitem encontrar origens não intuitivas sem tentar fixes aleatórios.

Stack trace, git bisect, reprodução mínima, isolamento de variável, log estruturado.

Após corrigir um bug, adicionar camadas de proteção — teste de regressão, validação de input, assertion — para garantir que ele não reapareça.

Bugs sem teste de regressão voltam. Defense-in-depth garante que o próximo agente (ou próxima sessão) não desfaça a correção.

Teste de regressão, assertion defensiva, validação de input, camadas de proteção, bug que volta.

Exercício com um bug real: aplicar as 4 fases, condition-based waiting, verificar evidência e adicionar proteção contra regressão.

Debugging sistemático parece lento no início mas é mais rápido no total. O exercício prático desenvolve o instinto para o processo.

Processo completo de debugging, disciplina de investigação, evidência de correção, proteção de regressão.

O checklist que o agente executa antes de solicitar revisão: testes passando, código limpo, sem debug logs, documentação atualizada.

Solicitar review de código sujo desperdiça o tempo do revisor. O checklist pré-revisão garante que o agente fez sua parte antes de pedir feedback.

Checklist pré-review, critério de pronto, código limpo, respeito ao tempo do revisor.

O processo de receber feedback de code review com rigor: entender a issue, confirmar o motivo, propor solução e validar antes de implementar.

Agentes frequentemente implementam o feedback errado ou resolvem o sintoma sem entender a issue. Rigor no recebimento evita retrabalho.

Compreensão da issue, confirmação de motivo, proposta de solução, validação antes de implementar.

O princípio de usar o plano de implementação aprovado como critério objetivo de revisão, ao invés de preferências estilísticas ou intuições do revisor.

Reviews baseados em intuição são inconsistentes e criam conflitos. O plano como critério torna a revisão objetiva e previsível.

Critério objetivo, plano como contrato, conformidade vs. preferência, review consistente.

A classificação de issues de review em bloqueadores (devem ser corrigidos antes do merge) e sugestões (melhorias desejáveis mas não obrigatórias).

Tratar todas as issues com a mesma urgência paralisa o desenvolvimento. Saber o que bloqueia o merge e o que pode esperar é decisivo.

Bloqueador de merge, sugestão opcional, prioridade de correção, critério de severidade.

O padrão de usar um agente separado (sem o contexto de implementação) como revisor externo, simulando a perspectiva de alguém que não escreveu o código.

O agente que implementou o código tem viés de confirmação. Um revisor sem contexto de implementação encontra issues que o implementador ignora.

Viés de confirmação, perspectiva externa, revisor sem contexto, objetividade de revisão.

Exercício completo: checklist pré-review, review pelo agente externo, classificação de issues, correção e confirmação de merge.

Review é a última barreira antes do merge. Treinar o ciclo completo garante que o processo seja fluido e não um gargalo.

Ciclo de review completo, PR pronto para merge, confiança no processo, qualidade garantida.

Git worktrees permitem ter múltiplos branches do mesmo repositório abertos simultaneamente em diretórios separados, cada um com seu estado próprio.

Sem worktrees, trabalhar em múltiplas features exige stash ou commits intermediários. Worktrees eliminam esse overhead completamente.

Worktree, diretório isolado, estado independente, overhead de stash, branches simultâneos.

A skill using-git-worktrees instrui o agente a criar e configurar worktrees automaticamente com os parâmetros corretos, sem intervenção manual.

Configurar worktrees manualmente é tedioso e propenso a erros. A automação via skill garante configuração correta sempre.

git worktree add, branch tracking, diretório de worktree, configuração automática, convenção de nomenclatura.

O processo de finalizar uma branch de desenvolvimento: decidir entre merge direto, abrir PR ou descartar, e limpar a worktree após a decisão.

Branches abandonadas acumulam e confundem. Ter um processo claro de finalização mantém o repositório limpo e o histórico legível.

Critério de merge, PR workflow, branch cleanup, git worktree remove, histórico limpo.

O padrão de manter 3-5 worktrees abertas simultaneamente, cada uma com um agente trabalhando em uma feature diferente.

Este é o modo de máxima velocidade do Superpowers. Múltiplos agentes em paralelo multiplicam o throughput de desenvolvimento.

Paralelismo de features, throughput, overhead de coordenação, limite prático de worktrees.

O processo de resolver conflitos de merge quando múltiplas branches tocam nos mesmos arquivos — identificando conflitos semânticos além dos sintáticos.

Conflitos são inevitáveis em desenvolvimento paralelo. Resolvê-los com rigor evita bugs sutis que passam pela resolução automática.

Conflito sintático vs. semântico, resolução manual, teste pós-merge, integração contínua.

Exercício completo: criar worktree, implementar feature, resolver conflitos e finalizar com merge ou PR.

O fluxo de worktree é novo para a maioria dos desenvolvedores. Praticar o ciclo completo uma vez remove toda a fricção futura.

Ciclo worktree completo, criação, desenvolvimento, merge, limpeza.

Os critérios para decidir quando vale paralelizar trabalho entre múltiplos agentes: independência de tarefas, tamanho mínimo, overhead de coordenação.

Paralelizar tudo é tão problemático quanto não paralelizar nada. O critério certo maximiza ganho sem criar complexidade desnecessária.

Independência de tarefa, overhead de coordenação, tamanho mínimo, ponto de break-even.

Padrões para coordenar múltiplos agentes trabalhando no mesmo repositório sem colisões de arquivo, conflitos de estado ou trabalho duplicado.

Agentes não se comunicam espontaneamente. Sem coordenação explícita, dois agentes podem modificar o mesmo arquivo simultaneamente.

Partição de trabalho, arquivos exclusivos, worktrees separadas, agente coordenador, lock implícito.

A prática de definir interfaces (tipos, APIs, contratos) antes de paralelizar — permitindo que cada agente implemente sua parte sem esperar pelo outro.

Sem contratos de interface, agentes paralelos criam APIs incompatíveis que precisam ser refatoradas na integração. O contrato prévio elimina isso.

Contrato de interface, API agreement, tipagem compartilhada, independência de implementação.

O processo de integrar o trabalho de múltiplos agentes paralelos: coletar resultados, resolver conflitos semânticos e verificar o sistema integrado.

A integração é onde o paralelo se torna arriscado. Um processo estruturado de integração captura incompatibilidades antes que virem bugs.

Coleta de resultado, conflito semântico, teste de integração, sistema integrado.

Os cenários onde paralelizar é contraproducente: tarefas com dependência forte, contexto compartilhado essencial, overhead maior que o ganho.

O entusiasmo com paralelismo pode criar complexidade que não compensa. Reconhecer quando não dividir é tão importante quanto saber como dividir.

Dependência forte, contexto compartilhado, overhead de coordenação, custo-benefício do paralelo.

Exercício completo: dividir uma feature em partes independentes, definir contratos, despachar agentes paralelos e integrar os resultados.

Paralelismo de agentes é a habilidade que separa usuários avançados do Superpowers de usuários básicos. Este exercício é o treino dessa habilidade.

Divisão de trabalho, contrato de interface, execução paralela, integração, velocidade multiplicada.

A estrutura de um arquivo SKILL.md: frontmatter YAML com metadados, seção de gatilhos, conteúdo da skill e exemplos de uso.

Entender a anatomia completa permite criar skills que funcionam corretamente em qualquer harness suportado pelo Superpowers.

SKILL.md, frontmatter YAML, campo triggers, conteúdo instrucional, exemplos de ativação.

O processo de usar a skill writing-skills para testar uma skill nova com subagentes — verificando que os gatilhos disparam e o comportamento é o esperado.

Skills não testadas geram comportamento imprevisível. Testar antes de usar em produção garante que a skill faz o que você escreveu.

writing-skills, teste adversarial, gatilho correto, comportamento esperado, avaliação de skill.

A filosofia do Superpowers sobre qualidade de skills: a taxa de 94% de rejeição de PRs reflete que skills são código comportamental que exige o mesmo rigor que código de produção.

Entender a filosofia por trás da barra alta ajuda a criar skills que realmente valem a pena — ao invés de skills genéricas que não melhoram nada.

Rigor de skill, domínio específico vs. geral, evidência de melhoria, barra de qualidade, filosofia de contribuição.

O critério para decidir se uma skill pertence ao core do Superpowers (beneficia todos) ou a um plugin privado (específica ao seu projeto ou domínio).

Publicar skills específicas como core polui o projeto para todos. Entender o critério mantém o core valioso e seus plugins relevantes para você.

Universalidade, especificidade de domínio, plugin privado, critério de core, contribuição responsável.

O processo de empacotar skills customizadas em um plugin distribuível — com versionamento, documentação e processo de atualização.

Skills úteis para você podem ser valiosas para outros do mesmo domínio. Saber distribuí-las permite compartilhar sem comprometer o core.

Plugin standalone, versionamento semântico, changelog de skill, distribuição via repositório.

Exercício final: identificar um comportamento que você quer automatizar, escrever a skill completa, testá-la com subagentes e documentá-la para uso futuro.

Criar suas próprias skills é o nível máximo de domínio do Superpowers. Este exercício fecha a trilha com a habilidade mais avançada do sistema.

Skill do zero, teste adversarial, documentação, skill pronta para uso, maestria do sistema.