spec-driven-development

Visão geral da skill spec-driven-development

spec-driven-development é uma skill de fluxo de trabalho para escrever uma especificação clara antes do código e usar essa especificação para orientar o planejamento, as tarefas e a implementação. A skill spec-driven-development é mais indicada quando você está começando um novo recurso, mudando a arquitetura ou trabalhando a partir de requisitos vagos e precisa reduzir ao máximo as suposições no resultado final.

Para que esta skill serve

Use este guia de spec-driven-development quando o principal risco for construir a coisa errada, e não apenas construir mal. Ele ajuda a transformar uma ideia ainda bruta em uma fonte única de verdade, definindo escopo, comportamento, restrições e critérios de aceitação antes de você partir para a implementação.

Casos de adoção mais adequados

Esta skill faz sentido para times e pessoas desenvolvedoras solo que querem um alinhamento mais rigoroso com um revisor humano, especialmente quando a tarefa atravessa vários arquivos, depende de decisões de produto ou é grande o bastante para fazer o “só codar” gerar retrabalho. Também é útil para spec-driven-development for Skill Authoring quando você quer que a própria skill produza saídas disciplinadas e fáceis de revisar.

O que a torna diferente

O valor está no fluxo com etapas e validações: especificar, depois planejar, depois dividir em tarefas, e só então implementar, com revisão humana em cada fase. Isso a torna mais forte do que um prompt genérico, porque reduz suposições ocultas e força pontos de decisão mais cedo, quando mudanças custam menos.

Como usar a skill spec-driven-development

Instale e carregue o contexto

Para instalar a spec-driven-development, adicione a skill à configuração de skills do seu agente e então abra primeiro o arquivo da skill:

npx skills add addyosmani/agent-skills --skill spec-driven-development

Depois leia SKILL.md antes de qualquer outra coisa. Este repositório não inclui pastas de apoio como rules/, references/ ou scripts/, então o contexto da skill vive quase todo no arquivo principal da skill.

Dê à skill um ponto de partida concreto

O padrão de uso da spec-driven-development funciona melhor quando você informa um objetivo, restrições e dúvidas conhecidas. Um input fraco seria “crie um dashboard”. Um input forte seria:

“Crie uma especificação para um dashboard que mostre a saúde das assinaturas, suporte acesso por função e precise funcionar com a nossa API REST existente. Faça perguntas de esclarecimento antes de rascunhar a especificação. Ainda não proponha detalhes de implementação.”

Isso dá à skill contexto suficiente para explicitar suposições e evitar decisões de design precipitadas.

Siga o fluxo com etapas e validação

A skill foi desenhada para parar em cada fase até haver validação. Na prática, isso significa:

1. Especificar o problema e as suposições.
2. Planejar a abordagem depois da aprovação da especificação.
3. Quebrar o plano em tarefas.
4. Implementar somente após a revisão das tarefas.

Se você pular os pontos de revisão, perde a principal vantagem da skill: menos retrabalho causado por suposições não testadas.

Leia primeiro e use depois

Comece por SKILL.md e depois use as seções de visão geral, quando usar e fluxo com etapas e validação como regras de operação. Se você estiver adaptando isso para o fluxo do seu próprio agente, preserve os checkpoints de revisão e o comportamento de “perguntar até ficar concreto”, porque são justamente as partes com maior chance de melhorar a qualidade da saída.

Perguntas frequentes sobre a skill spec-driven-development

A spec-driven-development é melhor do que um prompt normal?

Normalmente, sim, quando a tarefa é ambígua, atravessa várias áreas ou seria cara de refazer. Um prompt comum pode gerar código rapidamente, mas a spec-driven-development é melhor quando você precisa concordar sobre o que construir antes de alguém começar a codar.

Quando eu não devo usar?

Não use a skill spec-driven-development para edições triviais, correções óbvias de bugs ou mudanças isoladas sem ambiguidade real de produto. Nesses casos, a sobrecarga de um ciclo completo de especificação pode ser mais lenta do que o próprio trabalho.

Ela é amigável para iniciantes?

Sim, desde que você esteja disposto a responder perguntas de esclarecimento e revisar rascunhos. A skill é mais fácil de usar do que inventar seu próprio processo porque ela orienta o agente a pausar, explicitar suposições e avançar pelas fases na ordem certa.

Ela se encaixa em fluxos de Skill Authoring?

Sim, especialmente para spec-driven-development for Skill Authoring quando você quer um processo repetível para escrever uma nova skill ou evoluir uma já existente. Ela é mais útil quando a tarefa de autoria precisa de escopo claro, pontos de revisão e uma especificação que possa ser validada antes da implementação.

Como melhorar a skill spec-driven-development

Forneça entradas mais precisas desde o início

Os melhores resultados vêm de informar o usuário-alvo, o resultado desejado, as restrições e o que ainda não se sabe. Por exemplo: “Migre o fluxo de checkout sem alterar a API pública, preserve os eventos de analytics existentes e identifique quaisquer riscos de dependência antes de planejar.”

Force a skill a nomear as suposições

Um modo comum de falha são especificações vagas que parecem completas, mas escondem decisões críticas. Peça ao modelo que liste as suposições antes de redigir a especificação e depois revise essas suposições com o engenheiro humano antes de avançar para o planejamento. É aí que a spec-driven-development costuma economizar mais tempo.

Itere na especificação, não no código

Se a primeira versão estiver ruim, corrija escopo, critérios de aceitação ou restrições antes de pedir a implementação. O fluxo funciona melhor quando cada revisão torna o contrato mais preciso, porque as fases seguintes dependem da exatidão da especificação.

Use quando as revisões forem caras

A skill é mais valiosa quando suposições erradas sairiam caro: mudanças em vários arquivos, alterações de arquitetura ou recursos que afetam múltiplas partes interessadas. Se o primeiro rascunho da sua especificação ainda estiver vago, mantenha-o por mais tempo na fase de especificação em vez de forçar tarefas ou código cedo demais.