subagent-driven-development

Visão geral

O que é subagent-driven-development?

subagent-driven-development é uma skill de orquestração de agentes para executar um plano de implementação como uma sequência de tarefas independentes, cada uma tratada por um novo subagent. Para cada tarefa, você:

1. Sobe um subagent implementer dedicado.
2. Executa um subagent spec compliance reviewer.
3. Executa um subagent code quality reviewer.

Os três são mantidos em um contexto rigidamente controlado, para que foquem apenas na tarefa atual, enquanto a sua sessão principal fica livre para coordenação e tomada de decisão.

Para quem é esta skill?

subagent-driven-development foi projetada para desenvolvedores e equipes que:

• Usam assistentes de codificação com IA (como Claude / claude-code) e querem resultados mais confiáveis.
• Trabalham a partir de um plano de implementação escrito e quebrado em tarefas discretas.
• Precisam de uma forma estruturada e repetível de implementar e revisar código em uma única sessão de IA.
• Se importam tanto com a correção em relação à especificação quanto com a qualidade do código, e não apenas com "algo que funciona".

Ela se encaixa especialmente bem em fluxos centrados em GitHub, onde você pode passar SHAs, arquivos de plano e diffs para os subagents.

Que problemas ela resolve?

Esta skill aborda problemas comuns ao usar um único agente de IA para desenvolvimento ponta a ponta:

• Inchaço de contexto: Um único agente acumula histórico demais e perde o foco.
• Desvio de especificação: As implementações vão se afastando gradualmente do plano ou dos requisitos originais.
• Revisões fracas: O mesmo contexto que escreveu o código tenta revisá-lo e acaba deixando passar erros.

subagent-driven-development impõe um padrão: agente novo por tarefa, contexto estrito e revisão em duas etapas (primeiro especificação, depois qualidade). Isso melhora a correção, mantém as mudanças bem delimitadas e facilita raciocinar sobre cada etapa do seu plano de implementação.

Quando subagent-driven-development é uma boa escolha?

Use esta skill quando:

• Você já tem um plano de implementação quebrado em tarefas.
• As tarefas são majoritariamente independentes – não exigem coordenação constante entre si.
• Você pretende concluir o plano na sessão atual, sem espalhar o trabalho por vários dias.

Se você ainda não tem um plano, ou se as tarefas são fortemente acopladas e mudam rápido, talvez seja melhor:

• Primeiro fazer brainstorming ou desenhar o plano com outras skills ou com planejamento manual.
• Usar um fluxo mais livre, com agente único, para trabalho exploratório.

Como usar

Instalação

1. Adicione a skill ao seu ambiente

Instale a skill subagent-driven-development a partir do repositório obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

Isso traz a definição da skill e os templates de prompt de suporte para o seu ambiente com skills, permitindo orquestrar subagents para cada tarefa do seu plano.

2. Inspecione os arquivos principais

Após a instalação, abra o diretório da skill no repositório (ou via seu navegador de skills) e revise:

• SKILL.md – descrição em alto nível, quando usar e fluxo principal.
• implementer-prompt.md – template para o seu subagent implementer.
• spec-reviewer-prompt.md – template para o seu subagent spec compliance reviewer.
• code-quality-reviewer-prompt.md – template para o seu subagent code quality reviewer.

Trate esses arquivos como templates para copiar ou adaptar na sua automação ou na fiação das suas próprias ferramentas.

Preparando seu plano de implementação

1. Escreva ou refine sua lista de tarefas

Antes de usar subagent-driven-development, prepare um plano de implementação com tarefas que sejam:

• Claramente delimitadas e testáveis.
• Em grande parte independentes entre si.
• Descritas com detalhes suficientes para que um subagent implementer consiga agir sem ter que adivinhar.

Cada tarefa deve ser fácil de copiar e colar no prompt do implementer como “FULL TEXT of task from plan”.

2. Defina seu diretório de trabalho e sua estratégia Git

Os templates de prompt assumem um fluxo baseado em Git e um diretório de trabalho concreto:

• Escolha um directory onde o implementer irá trabalhar.
• Decida como você vai acompanhar as mudanças (por exemplo, BASE_SHA e HEAD_SHA para cada tarefa).

Você passará esses valores para os prompts de spec reviewer e code quality reviewer para obter revisões precisas.

Executando o fluxo por tarefa

1. Dispare um subagent implementer

Para cada tarefa N, crie um novo subagent implementer usando o template em implementer-prompt.md.

Pontos-chave do template:

• O implementer é instruído explicitamente: “You are implementing Task N: [task name]”.
• Você cola o texto completo da tarefa na seção ## Task Description.
• Você preenche:
  • Context – onde isso se encaixa no seu sistema.
  • directory – onde as mudanças serão feitas.

O implementer é instruído a:

1. Fazer perguntas de esclarecimento antes de começar, se algo não estiver claro.
2. Implementar exatamente o que a tarefa especifica.
3. Escrever e rodar testes quando fizer sentido.
4. Verificar a implementação.
5. Comitar o trabalho.
6. Produzir um relatório claro do que foi feito.

Como você cria um subagent novo para cada tarefa, ele só enxerga o contexto que você fornece e não herda histórico irrelevante da sessão principal.

2. Execute a revisão de aderência à especificação

Quando o implementer terminar e reportar de volta, dispare um subagent spec compliance reviewer usando spec-reviewer-prompt.md.

Nesse template você:

• Cola os requisitos da tarefa em ## What Was Requested.
• Cola o relatório do implementer em ## What Implementer Claims They Built.

O spec reviewer é explicitamente instruído a não confiar no relatório do implementer e deve:

• Ler o código de fato.
• Comparar linha a linha com os requisitos.
• Identificar requisitos ausentes, trabalho extra/indesejado e interpretações equivocadas.

Se o spec reviewer encontrar problemas, você volta a iterar com o implementer (o mesmo agente ou um novo subagent) para fechar as lacunas antes de seguir adiante.

3. Execute a revisão de qualidade de código

Depois que a aderência à especificação for aprovada, dispare um subagent code quality reviewer usando code-quality-reviewer-prompt.md.

O template espera uma descrição no estilo de revisão de código, por exemplo:

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

O reviewer verifica:

• Limpeza e manutenibilidade da implementação.
• Responsabilidades e interfaces dos arquivos (idealmente uma responsabilidade clara por arquivo).
• Se os arquivos novos ou alterados têm tamanho e decomposição adequados.
• Cobertura de testes e se é possível entender e testar unidades de forma independente.

Ele retorna feedback estruturado: pontos fortes, problemas (Critical / Important / Minor) e uma avaliação geral.

Você então pode decidir se:

• Aceita a mudança como está.
• Pede para o implementer fazer refactors de follow-up.

Adaptando o fluxo ao seu ambiente

1. Personalize os prompts para a sua stack

Os templates em implementer-prompt.md, spec-reviewer-prompt.md e code-quality-reviewer-prompt.md são propositalmente genéricos. Adapte-os à sua realidade de:

• Linguagens de programação e frameworks.
• Convenções de teste (por exemplo, pytest, Jest, Go test).
• Estrutura e nomenclatura do repositório.

Mantenha a estrutura central — subagent novo, seções claras, descrição explícita do papel — mesmo ao personalizar detalhes.

2. Automatize as etapas repetitivas

Quando você se sentir confortável com o padrão, pode criar scripts ou ferramentas em cima dele:

• Encapsule as três chamadas de subagent (implementer → spec reviewer → code quality reviewer) em um único comando por tarefa.
• Gere prompts específicos de cada tarefa automaticamente a partir de um arquivo de plano.
• Preencha BASE_SHA e HEAD_SHA automaticamente lendo os metadados do Git.

Isso transforma subagent-driven-development em um fluxo de trabalho automatizado, repetível, para sua equipe.

3. Quando esta skill não é uma boa opção

Talvez seja melhor seguir outra abordagem quando:

• As tarefas são altamente interdependentes e não conseguem ser bem isoladas.
• Você ainda não tem um plano de implementação claro.
• Você precisa de trabalho de longa duração, entre sessões, em que o contexto precise persistir por vários dias.

Nesses casos, use skills ou processos focados em planejamento, arquitetura ou agentes de longo prazo e depois volte a subagent-driven-development quando estiver pronto para executar tarefas discretas.

FAQ

O que "subagent-driven-development" significa na prática?

Na prática, subagent-driven-development significa que você não pede para um único agente onisciente planejar, codar e revisar tudo. Em vez disso, você:

• Mantém a coordenação e o contexto geral na sua sessão principal.
• Para cada tarefa, constrói um subagent novo com apenas as informações de que ele precisa.
• Executa esse subagent para implementar a tarefa e depois usa mais dois subagents para revisá-la.

Isso separa bem as responsabilidades, mantém o contexto controlável e aumenta a confiabilidade de cada etapa do seu plano de implementação.

Em que isso é diferente de uma sessão normal de codificação com agente único?

Com um agente único, a conversa anterior e as edições de código vão se acumulando em um único contexto, o que pode levar a:

• Confusão entre requisitos antigos e novos.
• Os mesmos padrões de raciocínio serem usados tanto para codar quanto para revisar.

subagent-driven-development, por sua vez:

• Usa prompts e papéis separados para implementação e revisão.
• Inicia cada subagent com contexto selecionado, e não com todo o histórico da sessão.
• Faz cumprir uma ordem de revisão primeiro especificação, depois qualidade.

Isso tende a produzir implementações mais precisas e revisões mais honestas.

Eu preciso seguir os templates à risca?

Não. Os templates no repositório são exemplos de como estruturar os prompts de implementer, spec reviewer e code quality reviewer. A expectativa é que você:

• Mantenha o padrão geral: implementer → spec review → quality review.
• Preserve comportamentos-chave (por exemplo, o spec reviewer deve ler o código real e não confiar apenas no relatório).

Dentro dessa estrutura, você pode ajustar a redação, adicionar orientações específicas do projeto e integrar com suas ferramentas e convenções.

Posso usar subagent-driven-development sem Git?

O template do code quality reviewer assume campos como BASE_SHA e HEAD_SHA, que são naturais em um fluxo com Git. Se você não usa Git:

• Ainda pode aplicar as mesmas ideias centrais — subagents novos e revisão em duas etapas.
• Substitua os SHAs pela sua própria forma de referenciar o estado antes/depois (por exemplo, identificadores de arquivos de arquivo ou paths de snapshots).

A skill não exige Git em si; ela apenas fornece exemplos orientados a Git.

Essa skill depende de um modelo de IA específico?

O repositório não fixa um modelo específico, mas claramente mira modelos modernos e de uso geral para código, como Claude / claude-code da Anthropic. Você deve:

• Usar um modelo capaz de ler e raciocinar sobre código e testes.
• Garantir que seu ambiente suporte criar múltiplos subagents com prompts personalizados.

Se sua stack suporta agent tools ou task runners, você pode integrar esses templates nesse sistema.

Como saber quando usar subagent-driven-development versus outra skill de superpowers?

O arquivo SKILL.md descreve os critérios de decisão: use subagent-driven-development quando você tem um plano de implementação, suas tarefas são em grande parte independentes e você pretende permanecer na sessão atual. Se qualquer um desses pontos não for verdade, você pode:

• Usar skills de planejamento ou brainstorming para criar o plano primeiro.
• Usar outros padrões de execução ou planejamento para trabalho fortemente acoplado e entre sessões.

Por onde começar no repositório?

Se você está avaliando se deve instalar ou adotar esta skill, comece por:

1. SKILL.md – para entender o racional e o fluxo em alto nível.
2. implementer-prompt.md – para ver como os subagents implementer são configurados.
3. spec-reviewer-prompt.md – para entender as checagens de aderência à especificação.
4. code-quality-reviewer-prompt.md – para ver as verificações adicionais de qualidade e de estrutura.

A partir daí, você pode adaptar esses templates à sua própria orquestração de agentes ou automação de fluxo de trabalho e tirar máximo proveito de subagent-driven-development.