Gere uma especificação clara, precisa e eficaz

14 minutos

O ficheiro de especificação (spec.md) é a única fonte de verdade sobre o que o seu software deve fazer. Esta unidade abrange técnicas avançadas para a elaboração de especificações de nível empresarial.

Revê os fundamentos das especificações

No desenvolvimento orientado por especificações, a especificação define exatamente o que o software deve fazer, e cada decisão de implementação remonta a ela. Uma especificação bem estruturada inclui:

Resumo: Descrição concisa da aplicação (ou nova funcionalidade) da perspetiva do utilizador final.
Histórias de utilizadores: Breves narrativas de como os utilizadores interagem com a aplicação.
Critérios de aceitação: Condições específicas e testáveis que devem ser verdadeiras para conclusão.
Requisitos funcionais: Descrições detalhadas do comportamento do sistema.
Requisitos não funcionais: Atributos de qualidade como desempenho, segurança e escalabilidade.
Casos extremos: cenários invulgares, condições de erro e comportamentos de limite.

A especificação como única fonte de verdade

No desenvolvimento orientado por especificações, a especificação define exatamente o que o software deve fazer, e cada decisão de implementação remonta a ela. Se a funcionalidade não aparece na especificação, não aparece no produto final a menos que alguém atualize a especificação e regenere artefactos.

Esta abordagem representa uma mudança de mentalidade: escrever a especificação é tão importante como escrever código. A especificação não é uma formalidade para cumprir a gestão de projetos—é o artefacto que impulsiona a geração de código por IA. Investe o mesmo cuidado na elaboração das especificações que investiria na implementação manual das funcionalidades.

Pensa na especificação como documentação executável. Quando modificas requisitos, atualizas a especificação e regeneras o plano e as tarefas. A especificação, que é controlada por versões no Git, torna-se o registo definitivo do que cada funcionalidade deve alcançar.

Para programadores empresariais habituados a fluxos de trabalho ágeis, a especificação serve o mesmo propósito que histórias detalhadas de utilizador e critérios de aceitação, mas com uma estrutura legível por máquina que os assistentes de IA podem consumir diretamente.

Estrutura de especificação

O GitHub Spec Kit organiza as especificações em secções padronizadas que cobrem comportamento funcional, requisitos de qualidade e casos limites.

Secção de resumo

Uma descrição concisa da funcionalidade a partir da perspetiva do utilizador final. Esta secção deve responder a "O que faz esta funcionalidade?" em uma ou duas frases.

Por exemplo:

## Summary

This feature enables employees to upload PDF and DOCX documents to their personal dashboard. Files are stored securely in Azure Blob Storage and appear in the user's document list immediately after upload.

O resumo fornece um contexto geral. Alguém que não esteja familiarizado com o projeto deverá compreender o propósito da funcionalidade após ler esta secção.

Secção de histórias de utilizador

Breves descrições narrativas de como os utilizadores interagem com a funcionalidade. As histórias de utilizador captam a intenção e o valor em vez da implementação técnica.

Por exemplo:

## User Stories

As an employee, I want to upload documents to my dashboard so that I can access them from any device.

As an employee, I want to see upload progress for large files so that I know the system is processing my request.

As a system administrator, I want uploads to be logged so that we can audit file activity for compliance purposes.

As user stories ajudam os assistentes de IA a compreender as motivações humanas por detrás das funcionalidades, levando a implementações mais intuitivas.

Secção de critérios de aceitação

Condições específicas e testáveis que devem ser verdadeiras para que a característica seja considerada completa. Os critérios de aceitação formam uma lista de verificação para verificar a implementação.

Por exemplo:

## Acceptance Criteria

- User can select PDF or DOCX files for upload
- Maximum file size is 50MB
- Files larger than 50MB display an error message
- Unsupported file types display an error message
- Successfully uploaded files appear in the document list within 2 seconds
- Upload progress is displayed for files larger than 1MB
- Only users with 'Contributor' role can upload documents
- Uploaded files are stored in user-specific folders in Azure Blob Storage

Escreva os critérios de aceitação como factos observáveis. Evite afirmações vagas como "o sistema é responsivo" — em vez disso, especifique "API responde em 200 ms."

Secção de requisitos funcionais

Descrições detalhadas do comportamento do sistema. Os requisitos funcionais detalham como funciona a funcionalidade.

Por exemplo:

## Functional Requirements

### Upload interface
- Dashboard displays an "Upload Document" button in the documents section
- Clicking "Upload Document" opens a file selection dialog
- User selects a file from their local filesystem
- System validates file type and size before initiating upload

### Upload process
- Files are uploaded via multipart HTTP POST to /api/documents endpoint
- Upload includes file content and metadata (filename, size, content type)
- Server validates authentication token before accepting upload
- Server checks user has 'Contributor' role before processing

### Storage
- Files are stored in Azure Blob Storage container 'employee-documents'
- Storage path follows pattern: {userId}/{fileId}/{filename}
- Server generates unique file ID to prevent naming collisions
- File metadata (original filename, upload timestamp, user ID) stored in Azure SQL Database

### User feedback
- Upload progress bar updates every 10% completion
- Success message displays upon completion: "Document uploaded successfully"
- Error messages display for: file too large, unsupported type, network error, server error

Os requisitos funcionais fornecem detalhe suficiente para que a IA gere implementações adequadas sem exigir uma estrutura exata de código.

Secção de requisitos não funcionais

Atributos de qualidade como desempenho, segurança, escalabilidade e conformidade. Estes requisitos frequentemente fazem referência à constituição.

Por exemplo:

## Non-Functional Requirements

### Performance
- File uploads under 5MB complete within 5 seconds on typical network
- Upload progress updates display with less than 100ms latency
- Document list refresh completes within 1 second after upload

### Security
- All uploads require valid Microsoft Entra ID authentication token
- HTTPS/TLS 1.2 enforced for all data transmission
- Files scanned for malware before storage (future enhancement)
- No sensitive data logged (filenames logged, content never logged)

### Scalability
- Support concurrent uploads (up to 5 simultaneous per user)
- Handle 1000 concurrent users uploading files

### Compliance
- Audit log records: user ID, filename, timestamp, file size, IP address
- Audit logs retained for 90 days minimum
- Support data deletion requests within the specified timeline

Os requisitos não funcionais garantem que o código gerado por IA cumpre os padrões de qualidade empresariais, não apenas a correção funcional.

Secção de casos extremos

Cenários invulgares, condições de erro e comportamentos de fronteira. Documentar explicitamente os casos limite, impede a IA de fazer suposições.

Por exemplo:

## Edge Cases

### Network interruption during upload
- If connection drops, display error: "Upload failed due to network error. Please retry."
- No partial files stored in Azure Blob Storage
- User can retry upload from beginning

### Duplicate filename
- System allows duplicate filenames by generating unique file IDs
- User sees original filename in document list
- Back end uses unique IDs to prevent overwrites

### Storage capacity limits
- If Azure Blob Storage quota exceeded, display error: "Upload failed due to storage limit. Contact support."
- Log storage errors for administrator notification

### Concurrent uploads by same user
- System supports up to 5 simultaneous uploads per user
- Sixth concurrent upload queued until one completes
- Progress bars update independently for each upload

### File type detection
- System validates file type by MIME type, not just extension
- File with .pdf extension but non-PDF content rejected
- Error message: "File appears corrupted or has incorrect type"

Pensar nos casos limites durante a especificação previne bugs que, de outra forma, surgiriam durante a implementação ou os testes.

Crie uma especificação com o GitHub Spec Kit

Escrever especificações eficazes é mais fácil com o comando do /speckit.specify GitHub Spec Kit.

O GitHub Spec Kit gera rascunhos de especificações baseados em descrições em linguagem natural, acelerando a criação de especificações enquanto mantém uma estrutura consistente.

Invocar o comando especificar

Para criar uma especificação:

Abra o seu projeto no Visual Studio Code.

Abre o GitHub Copilot Chat e depois executa o /speckit.specify comando com um prompt a descrever a funcionalidade que queres criar.

Por exemplo:

/speckit.specify Create a new document upload feature. The feature should allow employees to upload PDF or DOCX documents through the web dashboard. Files are stored in Azure Blob Storage under the user's account folder. After upload, the file appears in the user's document list. Only users with 'Contributor' role can upload. Maximum file size is 50MB. Show error messages for oversized files or unsupported types. Display upload progress for files larger than 1MB.

Esta descrição cobre:

O que: Carregar documentos PDF/DOCX
Onde: Interface de dashboard web
Como: Armazenado no Armazenamento de Blobs do Azure
Quem: Utilizadores com papel de Contribuidor
Restrições: limite de 50 MB, tipos específicos de ficheiros
Experiência do utilizador: Ecrã de progresso, mensagens de erro

O GitHub Copilot gera um ficheiro estruturado spec.md com base nesta entrada, criando secções para resumo, critérios de aceitação, requisitos e casos exceção.

Revise a especificação gerada

Depois de o GitHub Copilot gerar a especificação, abra spec.md e verifique:

Completude: A especificação cobre todos os requisitos que mencionaste? Se especificaste "apenas PDF e DOCX", confirma que os critérios de aceitação listam esses tipos de ficheiros.
Precisão: Os detalhes estão corretos? Se disseste limite de 50 MB, verifica se a especificação indica 50 MB, não um valor diferente.
Consistência: As diferentes secções estão alinhadas? Se o resumo mencionar a apresentação do progresso, os critérios de aceitação devem incluí-lo.
Elementos em falta: O que é que o GitHub Copilot deduziu ou omitiu? Revise os requisitos gerados para ver se a IA fez suposições com as quais discorda.

A especificação inicial é um ponto de partida forte, mas raramente perfeito. Espera-se aperfeiçoá-lo através de esclarecimentos.

Refinação de especificações com /speckit.clarify

O /speckit.clarify comando analisa a sua especificação e identifica ambiguidades, lacunas ou pressupostos que necessitam de esclarecimento.

Garantir a clareza das especificações

Ambiguidades nas especificações conduzem a implementações incorretas. Use /speckit.clarify para destacar áreas pouco claras.

Após gerar uma especificação inicial:

No GitHub Copilot Chat, executa:
```
/speckit.clarify
```

O GitHub Copilot analisa spec.md e faz perguntas sobre detalhes pouco claros ou em falta

Exemplos de perguntas de esclarecimento:

I've analyzed the specification and have some questions:

1. File retention: How long should uploaded documents be retained? Forever, or is there a retention policy?

2. Duplicate filenames: If a user uploads a file with the same name as an existing file, should the system:
    - Overwrite the existing file
    - Create a new version
    - Reject the upload with an error
    - Store both with unique identifiers

3. Virus scanning: Should uploaded files be scanned for malware? If so, when—before storage or asynchronously after upload?

4. Download capability: The spec describes upload but doesn't mention download. Should users be able to download their uploaded documents?

5. File sharing: Can users share documents with other employees, or are documents private to the uploader?

Estas perguntas ajudam-no a tomar decisões sobre aspetos que pode ter passado despercebido inicialmente.

Responder a perguntas de esclarecimento

Responda a cada pergunta com decisões específicas:

1. File retention: Retain documents indefinitely until user deletes them. No automatic deletion.

2. Duplicate filenames: Option d - Store both with unique identifiers. Users can have multiple files with the same name. Display upload timestamp to distinguish them in the list.

3. Virus scanning: Not required for initial release. Mark as future enhancement in the spec.

4. Download capability: Yes, users should be able to download their documents. Add this to the spec.

5. File sharing: Documents are private to the uploader for this release. Sharing is a future feature.

Depois de responderes, o GitHub Copilot atualiza spec.md para incorporar as tuas decisões:

Ganhos nos critérios de aceitação: "Os utilizadores podem descarregar documentos previamente carregados."
A especificação do ponto final de download é adicionada aos requisitos funcionais.
Casos extremos incluem: "Múltiplos ficheiros com nomes idênticos, distinguidos por carimbo temporal de upload."
Requisitos não funcionais nota: "Análise de vírus adiada para lançamento futuro."

Iterar até estar concluído

Corra /speckit.clarify várias vezes se necessário. Cada iteração refina ainda mais a especificação:

Passagem inicial: Principais falhas de funcionalidade.
Segunda passagem: detalhes do caso extremo.
Terceira passagem: Otimização dos requisitos não funcionais.

Parar quando o GitHub Copilot já não tiver mais perguntas ou apenas perguntar sobre funcionalidades que deseje adiar.

Melhores práticas para a redação de especificações

Escrever especificações claras e inequívocas é fundamental para um desenvolvimento orientado por especificações bem-sucedido.

Seja específico e mensurável

Substitua termos vagos por valores precisos:

Não: "Suportar ficheiros grandes."
Em vez disso: "Suporte ficheiros até 50 MB."
Não: "Desempenho rápido de upload."
Em vez disso: "Carregamentos inferiores a 5 MB são concluídos em 5 segundos numa ligação de 10 Mbps."

Requisitos específicos permitem que a IA gere implementações que respondam às suas necessidades reais.

Use terminologia consistente

Define os termos uma vez e reutiliza-os ao longo da especificação. Se lhes chamar "documentos" no resumo, não mude para "ficheiros" ou "anexos" mais tarde. A terminologia inconsistente confunde tanto humanos como IA.

Para projetos internos empresariais, utilize nomes oficiais de produtos e terminologia dos padrões da sua organização.

Definir o tratamento de erros explicitamente

Não assumas que a IA lida com erros de forma adequada. Especifique o que acontece quando as operações falham:

"Se o Armazenamento de Blobs do Azure estiver inacessível, erro de exibição: 'Não foi possível ligar-se ao serviço de armazenamento. Tenta outra vez mais tarde.'"
"Se o utilizador não possuir a função exigida, devolver o código HTTP 403 com a mensagem: 'Não tem permissão para carregar documentos.'"

O tratamento explícito de erros impede a IA de implementar mensagens de erro genéricas que não ajudam os utilizadores.

Manter o âmbito adequado

Se uma funcionalidade requer mais de 300 linhas para ser especificada, considere dividi-la em múltiplas especificações:

Em vez de uma especificação do "Sistema de Gestão de Documentos".
Crie especificações separadas: "Upload de Documentos", "Download de Documentos", "Partilha de Documentos" e "Pesquisa de Documentos."

Especificações mais pequenas são mais fáceis de rever, clarificar e implementar. Também estão alinhados com práticas de entrega incremental.

Detalhe "o quê", não "como"

Especificações definem requisitos, não implementações. Indique o que o sistema deve fazer, não como o programar:

Especificação: "Armazenar ficheiros carregados no Armazenamento de Blobs do Azure."
Não está especificado: "Use o pacote NuGet Azure.Storage.Blobs com a classe BlobContainerClient."

As decisões de implementação pertencem à fase do plano. No entanto, se a constituição exigir tecnologias específicas, referi-las na especificação é apropriado.

Validar contra a constituição

Antes de finalizar uma especificação, verifique se não entra em conflito com os princípios do projeto:

A Constituição exige autenticação Microsoft Entra ID → a especificação deve especificar o Microsoft Entra ID, não a autenticação personalizada.
A Constituição exige uma retenção de auditoria de 90 dias, pelo que a especificação deve incluir requisitos para o registo de auditoria.
A constituição limita o tamanho máximo dos ficheiros a 50 MB → a especificação não pode exigir suporte a ficheiros de 1 GB.

As inconsistências detetadas durante a especificação são muito mais baratas de corrigir do que após a implementação.

A especificação concluída torna-se o seu contrato com o GitHub Copilot. Quando avançar para a fase de planeamento, o GitHub Copilot faz referência a esta especificação para desenhar implementações técnicas que correspondam precisamente aos seus requisitos. O tempo investido numa especificação detalhada traz frutos ao longo do desenvolvimento.

Resumo

Escrever especificações eficazes é fundamental para o sucesso do desenvolvimento orientado por especificações. Uma especificação bem estruturada serve como a única fonte de verdade, orientando a geração de código de IA e assegurando o alinhamento com os princípios do projeto. Ao usar os GitHub /speckit.specify Spec Kit e /speckit.clarify comandos, pode criar e refinar rapidamente especificações detalhadas que abrangem comportamento funcional, atributos de qualidade e casos extremos. Seguir as melhores práticas na redação de especificações aumenta a clareza, reduz a ambiguidade e conduz a implementações que satisfazem tanto as necessidades dos utilizadores como os padrões empresariais.

Comentários

Esta página foi útil?