Guia completo do usuário do Specsfy: visão geral e leitura

O Specsfy ajuda você a transformar uma ideia em software testado sem espalhar requisitos, planos e tarefas por vários arquivos. Você conversa normalmente com o agente, e as skills organizam o trabalho em uma única especificação. Nesse arquivo, você consegue conferir o que será entregue, quais testes comprovam o comportamento e o que já foi concluído.

Este guia começa pela lógica da metodologia, prepara o ambiente e acompanha uma entrega completa. Os capítulos seguintes explicam a rotina com o CLI, as mudanças posteriores e os recursos avançados. Você não precisa conhecer a implementação do framework para seguir esse percurso.

Percurso pedagógico

Siga a ordem abaixo na primeira leitura. Quando já conhecer o método, use os links para voltar diretamente à tarefa que precisa executar.

1. Entenda a metodologia

Comece pela Metodologia. Cada entrega mantém o problema, os requisitos, os exemplos de comportamento, o plano técnico, as tarefas, os testes e as evidências em uma única spec.md. O capítulo mostra como esse arquivo muda ao longo do trabalho e o que comprova a passagem entre os atos.

Os três atos ligam cada fase a uma evidência verificável na spec.md:

Ato I — Definir: entender e validar o que deve ser entregue.
Ato II — Projetar e provar: preparar tarefas e obter o RED, a falha esperada antes da implementação.
Ato III — Entregar e validar: implementar, obter testes verdes e registrar evidências.

2. Instale o Specsfy

Com o método entendido, siga a Instalação para instalar o CLI e preparar seu repositório. Ao final, specsfy skills list mostra as skills disponíveis e specsfy progress --project . confirma que o CLI consegue ler o projeto, mesmo que ainda não exista uma spec.

3. Faça a primeira entrega

Use Primeiro projeto como tutorial guiado. Você começa com uma mudança pequena, acompanha a criação da spec.md e termina conferindo os testes e as evidências registradas, sem precisar decorar cada skill.

Para preservar uma entrada sem iniciar a especificação, escolha uma destas entradas:

preserve um texto sem perguntas na Inbox.
refine e priorize uma proposta no Backlog.

4. Aprofunde o fluxo base

O índice de Skills base apresenta o fluxo completo. Leia cada etapa nesta ordem:

Essas páginas explicam quando usar cada skill, como descrever a tarefa em linguagem natural, o resultado esperado, os erros comuns e o próximo passo.

5. Opere o projeto no dia a dia

Depois da primeira entrega, escolha os guias ligados à sua rotina:

CLI e TUI: comandos, interface visual e acompanhamento.
Informações permanentes do projeto: stack, regras, banco e convenções.
Documentação do sistema: documentação técnica derivada da aplicação.
Mudanças posteriores: como incorporar um novo requisito à mesma especificação.

6. Avance quando precisar

Os próximos guias são opcionais. Consulte-os quando a entrega exigir uma integração ou tecnologia específica:

Especialistas, para conhecimento técnico adicional.
Uso avançado, para automação e integrações.
aplicação em projetos Laravel, Astro ou Next.js.
Créditos, para autoria e identidade do projeto.

Para contribuir ou modificar o próprio framework, consulte a documentação técnica no repositório oficial do Specsfy — é um percurso separado do uso em projetos consumidores.

Conversa contínua entre etapas

Quando uma etapa depende de outra skill, o agente anuncia a transição, explica o que falta e retoma o trabalho na mesma conversa. Você acompanha a mudança de etapa sem repetir a instrução inicial nem escolher manualmente cada skill.

A ideia central em um exemplo

Imagine uma página de boas-vindas. Você pode preservar a ideia, refiná-la no backlog e promovê-la até chegar a:

1
specs/specs/0001-pagina-boas-vindas/spec.md

Em seguida, o agente valida a definição, organiza tarefas, prepara testes, implementa e registra evidências nesse mesmo arquivo. Se depois você solicitar um botão novo, a alteração retorna à mesma spec.md. O agente reabre somente os atos cujas provas perderam validade, sem criar plan.md, tasks.md ou outra fonte normativa.

Para começar esse percurso com orientação passo a passo, siga agora a Metodologia.