MÓDULO 1.1

🧠 Fundamentos: Por que agentes falham sem método

Entenda por que pedir "só escreve o código" é a raiz de todos os problemas e como a metodologia Superpowers resolve isso.

📋6 tópicos ⏱️~25 min 🎯Intermediário 📖Teoria + Prática
1

🚨 O problema do "só escreve o código"

O anti-padrão mais comum e mais caro no desenvolvimento com agentes de IA é simples: pedir para o agente implementar algo sem antes definir o que "algo" significa. Parece óbvio evitar, mas a velocidade aparente que o agente oferece seduz desenvolvedores a pular etapas.

Por que isso acontece

  • →O agente responde imediatamente com código plausível, criando a ilusão de progresso
  • →Requisitos vagos são preenchidos com suposições razoáveis — mas raramente corretas
  • →O custo real aparece horas depois, quando o código precisa ser reescrito
  • →Cada sessão de reescrita come tokens e tempo que poderiam ter sido evitados

Comparação: com e sem método

Sem método

  • "Cria um sistema de login"
  • → Agente assume JWT
  • → Você queria OAuth
  • → Reescrita completa
  • Custo: 3-4 horas perdidas

Com método

  • Brainstorm: "Que tipo de auth?"
  • → Spec: OAuth com Google
  • → Plano aprovado
  • → Implementação correta
  • Custo: 20 min extras de spec
2

⚙️ O que são Skills e como moldam o agente

Skills são arquivos de texto especialmente formatados (SKILL.md) que são injetados no contexto do agente via sistema de prompts. Eles funcionam como instruções persistentes que moldam como o agente responde a situações específicas — sem precisar repetir as mesmas instruções toda sessão.

Como uma skill funciona tecnicamente

# Estrutura de uma SKILL.md

---

name: brainstorming

triggers: [brainstorm, spec, "antes de codificar"]

---

# Conteúdo da skill aqui

Quando ativada, faça perguntas antes...

O que o Superpowers oferece out-of-the-box

  • •brainstorming — extrai specs de conversas vagas
  • •writing-plans — cria planos detalhados de implementação
  • •tdd — força o ciclo red-green-refactor
  • •executing-plans — execução com checkpoints humanos
  • •debugging — processo sistemático de 4 fases
  • •code-review — revisão estruturada contra o plano
3

📦 Instalação e configuração por plataforma

O Superpowers é um zero-dependency plugin — não precisa de nenhuma ferramenta externa além do harness de agente que você já usa. A instalação varia conforme a plataforma, mas o conceito é o mesmo: copiar os arquivos SKILL.md para o lugar certo e configurar os hooks.

Claude Code

# Instalar globalmente

cd ~/.claude

git clone [repo] superpowers

./superpowers/sync.sh

Cursor / Codex

# Por projeto

cd seu-projeto

git clone [repo] .superpowers

./.superpowers/sync.sh

Dica importante

O sync.sh copia os arquivos para o local correto de cada harness. Execute-o após cada atualização do Superpowers para manter as skills sincronizadas. O script detecta automaticamente qual plataforma você está usando.

4

🔗 Como os hooks funcionam

Hooks são scripts executados automaticamente pelo harness em momentos específicos da sessão. Diferente das skills (que moldam o comportamento via texto), os hooks executam código real — scripts bash, Python ou qualquer linguagem — e podem modificar inputs, validar outputs e registrar ações.

Tipos de hooks no Claude Code

  • PreToolUse Executa antes de uma ferramenta. Pode bloquear a execução se retornar exit code não-zero.
  • PostToolUse Executa após uma ferramenta. Útil para validar outputs ou registrar ações.
  • Stop Executa quando o agente para. Ideal para resumos e relatórios automáticos.

Configuração em settings.json

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": "~/.claude/hooks/pre-bash.sh" }
      ]}
    ]
  }
}
5

🗺️ O fluxo básico do Superpowers

O Superpowers organiza o desenvolvimento em cinco fases sequenciais. Cada fase tem um artefato de saída que serve de input para a próxima. Pular fases não economiza tempo — apenas adia o custo de retrabalho para um momento em que o retrabalho é mais caro.

1

Brainstorm

Conversa socrática → spec document aprovado

2

Plan

Spec → plano de tarefas de 2-5 min com verificação

3

TDD

Red → Green → Refactor → commit por ciclo

4

Review

Revisão em 2 estágios: spec + qualidade

5

Merge

Branch finalizada, PR aberto ou merge direto

Princípio fundamental

Cada fase valida a anterior. Você não começa o TDD sem plano aprovado. Você não faz review sem testes passando. O fluxo é uma sequência com gates, não uma sugestão.

6

🚀 Primeiros passos: verificando que funciona

Depois de instalar o Superpowers, vale 5 minutos para verificar que tudo está funcionando corretamente antes de depender das skills em um projeto real. Uma instalação silenciosamente incorreta é pior do que uma instalação visivelmente quebrada.

Smoke test básico

  1. 1. Abra uma nova sessão no seu harness
  2. 2. Digite: quais skills estão disponíveis?
  3. 3. O agente deve listar as skills instaladas (brainstorming, writing-plans, tdd...)
  4. 4. Teste um gatilho: quero fazer um brainstorming
  5. 5. O agente deve ativar a skill de brainstorming e iniciar o processo socrático

Se não funcionar

Verifique se os arquivos SKILL.md estão no diretório correto para seu harness. Para Claude Code: ~/.claude/commands/. Execute o sync.sh novamente e reinicie a sessão.

Resumo do Módulo 1.1

✓Identifiquei o anti-padrão "só escreve o código" e seu custo real
✓Entendi o que são skills e como elas moldam o comportamento do agente
✓Instalei e configurei o Superpowers na minha plataforma
✓Compreendi como hooks funcionam e quando usá-los
✓Conheço o fluxo completo brainstorm→plan→TDD→review→merge
✓Verifiquei que a instalação está funcionando com o smoke test
Próximo módulo: 1.2 — Brainstorming antes do código
← Voltar para Trilha Próximo Módulo →