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.

Leia online ou como ebook

Este mesmo percurso compõe a edição portátil v1.8.0. Use o PDF para leitura e impressão ou o EPUB em leitores que permitem ajustar fonte e tamanho:

PDF, para leitura, compartilhamento e impressão.
EPUB, para leitores digitais com fonte e tamanho ajustáveis.

Os dois formatos são reconstruídos a partir destas páginas. O manifesto da edição informa a versão vigente e os hashes usados para conferir se o PDF e o EPUB correspondem ao mesmo build.

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.

Para interpretar cada campo da spec, consulte a Referência do método. Ela detalha Effort, estados, transições, gates, IDs, pesquisa, tarefas e progresso.

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 ideia sem iniciar a especificação, escolha uma destas entradas:

preserve um texto sem perguntas na Inbox.
refine e priorize uma proposta no Backlog.
organize o MVP e o roadmap com Milestones.

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. Quando uma delas precisar perguntar, você recebe uma pergunta numerada por rodada. Ela traz três ou mais opções numeradas, Escrever outra resposta, Gere outras opções e Avançar desde o início da conversa. Cada área aceita no máximo oito perguntas, salvo se você pedir mais e informar quantas deseja responder. Depois de avançar, você informa se quer encerrar definitivamente as perguntas daquela área, responder depois ou retomar agora. O encerramento é respeitado até você reabrir a área, o adiamento preserva os pontos para retomada.

No setup, o perfil persistente em .specsfy/USER-PROFILE.md registra o nível de conhecimento e as respostas já confirmadas. O agente consulta esse arquivo, a conversa e as fontes do projeto antes de perguntar novamente.

5. Opere o projeto no dia a dia

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

CLI e TUI: interface visual e acompanhamento.
Referência dos comandos: parâmetros, efeitos, saídas e exemplos do CLI.
Informações permanentes do projeto: stack, regras, banco e convenções.
Design system de interface: regras macro, padrões CRUD, estados e exceções com alcance.
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.
Como funciona o Deploy da aplicação, para ligar SEMVER, imagem, Ansible e Docker Swarm em um deploy verificável.
Servidores e comandos de deploy, para cadastrar servidores, conferir conexões, sincronizar chaves públicas e usar os comandos curtos no Herdr.
Uso avançado, para automação e integrações.
aplicação em projetos Laravel, Astro ou Next.js.
Quadro técnico, para conhecer os módulos do monorepo.
Créditos, para autoria e identidade do projeto.

Se você pretende contribuir ou modificar o próprio framework, continue no guia técnico. Ele é 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/<estado>/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.