subagent-driven-development

Visão geral da skill subagent-driven-development

O que a subagent-driven-development realmente faz

A subagent-driven-development é uma workflow para executar um plano de implementação dividindo o trabalho em tarefas independentes, delegando cada tarefa a um subagente novo e revisando cada resultado em duas passadas: primeiro aderência à especificação, depois qualidade de código. O valor real não está em “usar mais agentes”, e sim em usar contexto isolado de forma intencional, para que cada executor receba apenas a tarefa, os requisitos e o contexto local de código de que precisa.

Quando esta skill é mais indicada

A subagent-driven-development skill funciona melhor para quem já tem um plano e precisa transformá-lo em uma implementação confiável dentro da sessão atual. Ela se encaixa especialmente bem quando:

• as tarefas são majoritariamente independentes
• você quer que o agente coordenador continue focado na orquestração
• você se importa tanto em detectar desvio de requisito quanto código mal feito
• você quer um ciclo de revisão repetível, e não só um prompt único para gerar código

O trabalho que ela resolve

As pessoas adotam subagent-driven-development for Agent Orchestration quando um prompt comum do tipo “implemente este plano” começa a falhar de formas previsíveis: o agente mistura tarefas, esquece restrições, implementa além do necessário ou entrega um código que parece plausível, mas não atende à especificação. Esta skill oferece um padrão disciplinado de delegação e revisão que reduz esse tipo de falha.

O que diferencia da abordagem com prompt genérico

Os principais diferenciais são práticos:

• Subagente novo por tarefa em vez de um único agente de longa duração carregando histórico ruidoso
• Pacotes de tarefa explícitos com o texto completo da tarefa colado no prompt, em vez de pedir que o executor deduza os requisitos a partir de arquivos dispersos
• Perguntas obrigatórias antes de codar, para que ambiguidades apareçam cedo
• Revisão em duas etapas, separando “isso corresponde à especificação?” de “o código está bom?”

Essa separação importa. Muitas equipes revisam qualidade antes de validar escopo, o que dificulta perceber quando houve implementação a mais ou a menos.

Quando esta não é a escolha certa

Não comece com subagent-driven-development se você ainda não tiver um plano de implementação concreto, se as tarefas forem fortemente acopladas ou se o trabalho pertencer a um fluxo paralelo separado, e não a esta sessão. Nesses casos, planejamento ou outra skill de execução costuma ser um primeiro passo melhor.

Como usar a skill subagent-driven-development

Como instalar a skill subagent-driven-development

Se você instala skills deste repositório via Skills CLI, use:

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

Depois, abra a skill instalada e os templates de prompt de apoio antes da primeira execução.

Leia estes arquivos primeiro

Para adotar mais rápido, leia os arquivos nesta ordem:

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

Essa sequência mostra primeiro o workflow e, depois, os formatos exatos de prompt do implementador e das duas etapas de revisão.

Entenda o padrão de chamada antes de começar

Na prática, subagent-driven-development usage não é um comando mágico único. Você usa a skill atuando como coordenador:

1. pegue uma tarefa do plano
2. dispare um subagente implementador novo com um prompt bem delimitado
3. exija um retorno com relatório
4. execute um spec reviewer contra o código real
5. só se a spec passar, execute um code quality reviewer
6. aceite, peça revisão ou delegue novamente

Se você pula as etapas de revisão, já não está mais usando a skill como ela foi desenhada.

Quais entradas a skill precisa

Prepare estes insumos antes de disparar qualquer subagente:

• o texto exato da tarefa no seu plano
• critérios de aceitação ou requisitos
• contexto arquitetural relevante
• diretório de trabalho ou escopo do repositório
• quaisquer notas sobre dependências ou ordem de execução
• o commit base ou SHA para revisar os diffs
• número e nome da tarefa para rastreabilidade

Os templates de origem deixam bem claro que você deve colar a tarefa completa no prompt, e não mandar o subagente “ir ler o arquivo do plano”.

Como transformar um objetivo vago em um bom prompt de implementação

Um prompt fraco diria:

• “Implement task 4 from the plan.”

Um prompt melhor no estilo subagent-driven-development guide inclui:

• Título e número da tarefa
• Texto completo da tarefa
• Por que essa tarefa existe
• Em que parte do repo trabalhar
• Restrições sobre a estrutura de arquivos
• Se testes são obrigatórios
• O que fazer se for necessário assumir algo
• A exigência de fazer perguntas antes de codar

Esse formato importa porque a skill foi pensada para contexto controlado, e não para uma interpretação autônoma do repo inteiro.

Exemplo de um pacote de tarefa melhor

Use uma estrutura como esta ao despachar o implementador:

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

Isso é mais confiável do que pedir para o executor explorar o repositório de forma ampla, porque a skill parte do princípio de que o coordenador é responsável por empacotar bem a atribuição.

Por que a revisão de especificação vem antes da revisão de qualidade

Este é um dos pontos de maior valor em decisões de subagent-driven-development install: a ordem é intencional.

Rode primeiro o spec reviewer para responder:

• o código implementou o que foi pedido?
• algum requisito foi ignorado?
• houve trabalho extra que não foi solicitado?
• a tarefa foi mal interpretada?

Só depois disso faz sentido rodar o code quality reviewer, que avalia manutenibilidade, decomposição, responsabilidade por arquivo e formato da mudança. Se você inverter a ordem, um código com boa aparência pode esconder erros de escopo.

Como usar bem o spec reviewer

O template spec-reviewer-prompt.md é incomumente direto: ele instrui o revisor a não confiar no relatório do implementador e a verificar o código real linha por linha. Preserve esse tom ao adaptá-lo. O revisor precisa de:

• texto completo dos requisitos da tarefa
• saída declarada pelo implementador
• acesso ao código alterado

O objetivo é verificação independente, não uma confirmação educada.

Como usar bem o code quality reviewer

A revisão de qualidade de código não é uma fiscalização genérica de estilo. Nesta skill, ela enfatiza:

• uma responsabilidade clara por arquivo
• interfaces bem definidas
• decomposição em unidades fáceis de entender
• alinhamento com a estrutura de arquivos planejada
• se a tarefa criou arquivos novos grandes demais ou inflou arquivos existentes

Esse último ponto é útil porque subagentes frequentemente resolvem a tarefa concentrando coisa demais em uma única mudança.

Workflow sugerido dentro de um repo real

Um loop prático de subagent-driven-development usage costuma ser assim:

1. escolha a próxima tarefa independente
2. registre o commit atual como baseline
3. despache o implementador com o texto completo da tarefa
4. colete o resumo dele e os arquivos alterados
5. execute a spec review contra requisitos e código
6. se a spec falhar, devolva lacunas específicas ao implementador
7. se a spec passar, execute a code quality review
8. se a qualidade falhar, peça uma revisão focada
9. faça merge ou siga para a próxima tarefa

Isso mantém o coordenador no controle da sequência e da aceitação.

Restrições que afetam a qualidade da saída

A skill funciona melhor quando você respeita seus limites:

• tarefas independentes funcionam melhor do que tarefas emboladas
• requisitos explícitos funcionam melhor do que requisitos inferidos
• escopo estreito de repo é melhor do que “olha aí e decide”
• ciclos curtos de tarefa funcionam melhor do que lotes grandes com várias funcionalidades
• regras claras de escalonamento funcionam melhor do que suposições silenciosas

Se você perceber que precisa de um subagente para conciliar muitas partes móveis por todo o codebase, a tarefa provavelmente está ampla demais para este workflow.

Erro comum na adoção

O erro mais frequente é usar a subagent-driven-development skill só como rótulo, mas continuar escrevendo prompts soltos. O workflow só compensa se você realmente empacotar o contexto com cuidado e fizer valer a sequência de revisão. Sem isso, você fica com o overhead da orquestração sem ganhar em qualidade.

FAQ da skill subagent-driven-development

subagent-driven-development é boa para iniciantes?

Sim, desde que você já entenda a tarefa que quer implementar. O workflow é explícito e os templates de prompt fornecidos reduzem o improviso. Mas ela não substitui planejamento. Iniciantes que ainda não têm um plano de implementação claro podem ter dificuldade, porque a skill assume que as definições das tarefas já existem.

Quando eu não devo usar subagent-driven-development?

Pule subagent-driven-development quando:

• você ainda estiver explorando o problema
• as tarefas forem profundamente interdependentes
• os requisitos estiverem instáveis
• uma pessoa ou um agente precisar raciocinar continuamente sobre o sistema como um todo

Ela é um padrão de execução, não um padrão de descoberta.

Em que isso difere de simplesmente pedir para um único agente codar tudo?

Um único prompt longo costuma misturar planejamento, implementação, validação e revisão na mesma janela de contexto. Esta skill separa esses papéis. Isso normalmente melhora o foco, facilita detectar desvios de requisito e preserva o contexto do coordenador para orquestração em vez de geração de código.

A skill exige ferramentas especiais?

Não. Nenhum script especial vem incluído nesta pasta da skill. O repositório fornece templates de prompt em markdown, e não código de automação. Você pode usar esse padrão em qualquer lugar onde consiga disparar subagentes e executar tarefas de code review.

subagent-driven-development serve só para projetos grandes?

Não. Ela também pode funcionar para mudanças pequenas, mas entrega mais valor quando o plano tem várias tarefas independentes e o custo de deixar passar requisitos é alto o suficiente para justificar o overhead da revisão.

Que evidência no repositório mais importa antes de instalar?

Para esta skill, a principal evidência está no desenho do workflow em SKILL.md e nos três templates de prompt. Não há scripts auxiliares nem pastas de recursos fazendo trabalho oculto, então sua decisão de instalação deve se basear em quanto a estrutura dos prompts e a disciplina de revisão combinam com a forma como sua equipe já entrega código.

Como melhorar a skill subagent-driven-development

Dê pacotes de tarefa melhores, não prompts maiores

Para melhorar os resultados da subagent-driven-development skill, aumente a precisão, não a verbosidade. Os acréscimos mais úteis são:

• critérios de aceitação exatos
• não objetivos explícitos
• notas de arquitetura relevantes só para esta tarefa
• limites de arquivo ou diretório
• exemplos do comportamento esperado
• expectativas de teste

Isso ajuda o implementador a manter o foco e ajuda o spec reviewer a detectar desvios.

Deixe os limites das tarefas mais nítidos

Muitas falhas vêm de tarefas mal fatiadas. Se um subagente precisa coordenar várias partes móveis, decidir arquitetura e inferir requisitos ao mesmo tempo, divida a tarefa. Tarefas melhores são estreitas o suficiente para que “implementou exatamente o que foi pedido” seja algo fácil de verificar.

Preserve a etapa de perguntar antes de começar

O template do implementador diz explicitamente para o executor fazer perguntas antes de começar e novamente se surgirem surpresas durante a implementação. Mantenha esse comportamento. Suprimir pedidos de esclarecimento gera saída rápida, mas pouco confiável — exatamente o oposto do propósito da skill.

Melhore a qualidade da revisão com insumos de comparação mais fortes

Para o spec reviewer, forneça:

• texto completo dos requisitos
• relatório do implementador
• arquivos alterados ou escopo do diff
• quaisquer exclusões explícitas

Para o code quality reviewer, forneça:

• BASE_SHA
• HEAD_SHA
• resumo da tarefa
• seção relevante do plano

Esses pontos de comparação concretos fazem a revisão ir além de opinião.

Fique atento a estes modos de falha comuns

Os problemas mais comuns de subagent-driven-development for Agent Orchestration são:

• o implementador inferir funcionalidades extras
• o pacote da tarefa omitir uma restrição importante
• o revisor confiar demais no resumo do implementador
• a revisão de qualidade rodar antes da revisão de especificação
• as tarefas serem grandes demais para verificar com clareza
• o crescimento dos arquivos passar sem controle

Cada um deles pode ser evitado com melhor empacotamento da tarefa e gates de revisão mais rígidos.

Itere depois da primeira saída

Se a primeira passada vier fraca, não recomece do zero imediatamente. Primeiro identifique em qual camada houve falha:

• spec failure: requisitos ambíguos, ausentes ou implementados além do pedido
• quality failure: problemas de decomposição, manutenibilidade ou estrutura de arquivos
• coordination failure: o fatiamento da tarefa ou o empacotamento do contexto estava errado

Depois, revise só essa camada. Isso mantém o workflow eficiente.

Aperte a orientação sobre estrutura de arquivos

Um detalhe útil do template de qualidade é verificar se a implementação seguiu a estrutura de arquivos planejada e se os arquivos criados já nasceram grandes demais. Se manutenibilidade importa para você, inclua os limites de arquivos pretendidos no pacote da tarefa desde o início, em vez de esperar que os revisores percebam isso depois.

Crie um checklist local reutilizável

Se você vai usar subagent-driven-development com frequência, mantenha um checklist curto do coordenador:

• o plano existe
• a tarefa é independente
• o texto completo da tarefa foi colado
• as restrições foram incluídas
• o baseline SHA foi registrado
• o implementador foi instruído a pedir esclarecimentos antes de codar
• a spec review foi concluída
• a quality review foi concluída

Esse pequeno hábito melhora mais a consistência do que escrever prompts cada vez maiores.

Adapte a skill ao seu próprio workflow

A skill base é intencionalmente enxuta. Para deixá-la mais eficaz no seu ambiente, adapte os templates de prompt ao seu stack e aos seus padrões de revisão:

• adicione seus comandos de teste
• adicione regras de arquitetura específicas do repo
• defina o que conta como over-engineering
• especifique seu formato preferido de relatório
• inclua padrões de falha comuns no seu codebase

Esse tipo de ajuste local normalmente melhora mais o subagent-driven-development usage do que acrescentar mais teoria.