Adicione uma funcionalidade a um painel existente com Spec Kit

Um projeto existente tem comportamento, consumidores, testes e convenções. Uma nova funcionalidade deve se integrar a essas restrições em vez de regenerar o projeto.

Resumo do laboratório

[!NOTE] Um ator de teste confiável é uma costura, não autenticação de produção.

Conceitos · Primeira tarefa · Lista de evidências · Redefinir

Objetivos de aprendizagem

• Caracterize os endpoints/contratos de módulos existentes antes de inicializar a estrutura.
• Especifique uma funcionalidade como uma alteração delimitada.
• Mantenha a identidade separada de campos fornecidos pelo modelo ou pela solicitação.
• Verifique o comportamento antigo e o novo juntos.

Antes de começar

Conclua a preparação do Spec Kit. Prepare 14-brownfield usando o guia da unidade de trabalho. Este módulo de painel incluído substitui a importação obrigatória de um repositório externo. Não são necessários LocalDB, alterações de contas na nuvem, upload binário ou repositório público.

Conceitos e casos de uso

Cenário do exercício

O painel já lista um projeto de treinamento. Adicione títulos e IDs de documentos com escopo no ator atual da fixture. Uploads reais de arquivos, verificação de malware, armazenamento externo e autenticação real de usuários são explicitamente trabalhos separados.

Tarefa 1 - Execute os contratos antigos e novos separadamente

node --test --test-concurrency=1 baseline.test.mjs
node --test --test-concurrency=1 feature.test.mjs

1. Confirme que a linha de base passa.
2. Confirme que os testes da funcionalidade falham porque ela não está implementada.
3. Registre as mensagens exatas e os códigos de saída.
4. Leia requirements.md; mapeie DOC-1..4 para testes e identifique o conhecimento ausente.

Tarefa 2 - Adote o Spec Kit sem substituir a aplicação

1. Faça um commit de linha de base no projeto descartável.
2. Inspecione .github, .specify e os arquivos do editor antes de specify init --here.
3. Revise cada alteração da estrutura inicial e preserve as instruções pertencentes ao projeto.
4. Crie uma constituição que preserve DOC-1 e proíba modernização sem relação com a tarefa.

Não use --force como substituto da resolução de conflitos.

Tarefa 3 - Especifique a alteração e esclareça a propriedade

/speckit-specify Add document metadata to the existing dashboard in requirements.md.
Preserve health/projects exactly. Derive ownerId from a trusted actor supplied by
the application boundary, not from document input. Reject missing project/title,
overlong title, missing actor and owner spoofing. No file upload.

Use /speckit-clarify para responder:

• Quem estabelece o ator em produção?
• Qual é o comprimento máximo do título?
• Uma adição com falha deixa estado parcial?
• Outro ator pode listar esses registros?

O ator injetado da fixture é um ponto de isolamento para testes, não uma comprovação de autenticação de produção.

Tarefa 4 - Planeje com pontos de controle de compatibilidade

Use /speckit-plan para exigir:

1. health e projects existentes inalterados.
2. Novo armazenamento e validação de metadados restritos ao módulo.
3. Listagem por proprietário com cópias defensivas.
4. Execução combinada dos testes de linha de base e da funcionalidade.
5. Propagação explícita de erros, sem proprietário alternativo silencioso.

Para .NET, proponha uma adaptação de controlador/serviço autenticado; para TypeScript, adicione tipos explícitos de entrada/saída. Ambos devem preservar DOC-1..4. Não alegue que esses adaptadores foram executados, a menos que você implemente e execute seus testes.

Tarefa 5 - Implemente e avalie a alteração

1. Execute /speckit-tasks e /speckit-analyze.

2. Revise os mapeamentos tanto para os testes antigos quanto para os novos.

3. Implemente um recorte e execute:

   node --test --test-concurrency=1 baseline.test.mjs feature.test.mjs
   

4. Inspecione todo o diff, não apenas o novo método.

5. Remova temporariamente a filtragem por proprietário. Confirme que o teste entre atores falha e restaure-a.

6. Use /speckit-converge como apoio à revisão, não como evidência de que os testes foram executados.

Verifique seu trabalho

• Os testes antigos continuam passando junto com a nova funcionalidade.
• A propriedade vem do limite confiável.
• Ator errado, proprietário falsificado e entrada inválida são rejeitados ou isolados.
• A funcionalidade não introduz upload binário nem novo serviço de rede.
• O ponto de controle de compatibilidade está representado na especificação, nas tarefas e nos testes executados.

Solução de problemas

Se o código gerado reescrever o painel inteiro, pare e compare a linha de base. Se os testes passarem somente individualmente, inspecione o estado compartilhado. Se uma string “owner” for lida da entrada do usuário, isso não é autorização.

Prática independente

Especifique uma funcionalidade separada de upload binário com limites de tamanho, validação de conteúdo, propriedade do armazenamento, tratamento de malware e política de exclusão. Mantenha-a como exercício de projeto até que existam fixtures e testes próprios.

Restauração

Salve as evidências e restaure somente dashboard.mjs na cópia descartável. Mantenha o currículo e o material de origem intactos; não remova branches nem contas compartilhadas.

Referências oficiais

• Instalação e adoção do Spec Kit
• Integração do Spec Kit
• Autorização no ASP.NET Core