Versões, artefatos e limites do Spec Kit

Esta trilha foi verificada com o Spec Kit v1.0.4 em 2026-09-07. Fixe uma versão de lançamento em vez de instalar conteúdo variável de main durante um workshop. O contrato e os testes da aplicação pertencem à pessoa em aprendizagem; Spec Kit não é um compilador, um limite de segurança em tempo de execução nem prova de que o código gerado funciona.

Uma mudança importante em relação às lições importadas

A integração do Copilot na v1.0.4 usa skills por padrão:

.github/skills/speckit-constitution/SKILL.md
.github/skills/speckit-specify/SKILL.md
.github/skills/speckit-plan/SKILL.md
...
.specify/memory/constitution.md
.specify/templates/
.specify/scripts/

A invocação correspondente usa hífen, por exemplo /speckit-specify. O layout opcional de comandos continua tendo suporte:

specify init --here --integration copilot --script sh --integration-options="--commands"

Esse layout gera arquivos de agente, arquivos complementares de prompt e configurações do VS Code. Seus prompts usam nomes com ponto, como /speckit.specify. Use uma sessão Local para arquivos de prompt: sessões do Agent Host não os consomem.

[!IMPORTANT] O guia de instalação da v1.0.4 ainda ilustra comandos com ponto, enquanto a referência e o código da integração do Copilot especificam skills como padrão. Inspecione os arquivos gerados e o seletor do host escolhido. Não misture os dois layouts nem presuma que uma captura antiga descreva a versão instalada.

Instale somente no diretório de ferramentas da unidade de trabalho

Siga a configuração de cache/diretório de ferramentas. A versão selecionada exige Python 3.11 ou posterior e uv para a forma recomendada de instalação.
Se Specify já estiver instalado, inspecione specify version e uv tool list antes de alterar qualquer coisa.

Quando a instalação for necessária, escolha uma forma revisada:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.4

A alternativa oficial no PyPI é:

uv tool install specify-cli==1.0.4

Use o executável no UV_TOOL_BIN_DIR configurado. Nesse terminal:
```
export PATH="$UV_TOOL_BIN_DIR:$PATH"
specify version
specify init --help
```
Uma saída de versão é uma verificação de disponibilidade, não uma evidência da proveniência do pacote. Registre também a fonte de instalação e a versão de lançamento.

Inicialize uma cópia do exercício, não o currículo

specify init --here --integration copilot --script sh

Use --script ps no PowerShell. Não execute a inicialização na raiz de Awesome Copilot Adventures. Primeiro crie uma cópia descartável, inicialize sua linha de base local do Git, inspecione os arquivos existentes de .github e .specify e revise a mesclagem proposta. Não use --force para ultrapassar conflitos que você não inspecionou.

O Spec Kit pode mesclar ou atualizar sua própria estrutura inicial. “Repositório existente” não é uma promessa de que toda personalização permanecerá inalterada byte a byte.

Fluxo de trabalho e pontos de controle de evidências

Skill padrão	Artefato ou ação	Verificação humana
`/speckit-constitution`	Princípios do projeto em `.specify/memory/constitution.md`	Regras acionáveis; nenhuma implementação sem relação com a tarefa
`/speckit-specify`	Especificação de funcionalidade em `specs/`	Comportamento do usuário, IDs, exclusões e casos extremos
`/speckit-clarify`	Resolver requisitos ausentes	Decisões registradas, sem ampliação silenciosa de escopo
`/speckit-plan`	Projeto técnico e contratos	Stack escolhida, interfaces preservadas, testes, riscos
`/speckit-tasks`	Trabalho ordenado por dependências	Cada requisito tem uma tarefa e uma verificação
`/speckit-analyze`	Consistência entre artefatos	Cobertura ausente/contraditória é tratada
`/speckit-checklist`	Lista de verificação da qualidade dos requisitos	A lista não é uma suíte de testes executada
`/speckit-implement`	Implementar as tarefas aprovadas	Inspecionar o diff e a saída real dos testes
`/speckit-converge`	Comparar código com especificação/plano/tarefas	Verificar de forma independente a conclusão relatada

Inspecione os caminhos realmente gerados em vez de presumir um número de diretório de funcionalidade. Use o comando correspondente com ponto somente se tiver selecionado intencionalmente o modo de comandos.

A entrada de exemplo é linguagem natural, não um analisador inventado de flags de linha de comando:

/speckit-constitution Use requirements.md and the existing baseline tests.
Require deterministic local tests, no secrets, preservation of the public contract,
and one bounded implementation slice at a time.

Não apresente --text ou --files como flags com suporte nesses fluxos de agentes. Anexe os arquivos pelo host ou nomeie seus caminhos na solicitação.

Três casos diferentes de desenvolvimento

Caso	Estado inicial	Risco principal	Ponto de controle antes da implementação
Projeto novo (greenfield)	Requisitos e nenhuma implementação	Construir demais	Contrato pequeno de aceitação e exclusões explícitas
Funcionalidade em projeto existente (brownfield)	Aplicação funcional e testes existentes	Quebrar consumidores atuais	Linha de base aprovada e novo teste de regressão com falha
Modernização	Código/dados existentes e uma alteração técnica necessária	Perder compatibilidade ou dados	Caracterização, verificações de importação, reversão

Os nomes dos fluxos do Spec Kit não tornam esses casos idênticos. O laboratório de modernização mantém deliberadamente o comportamento de negócio fixo enquanto altera o armazenamento.

Condições de parada

Pare após duas iterações de correção malsucedidas, uma falha inexplicada na linha de base, uma alteração de dependência não revisada ou uma proposta destrutiva. Registre o impedimento e atualize o plano. Não deixe um ciclo automático de convergência executar indefinidamente.