Generowanie jasnej, precyzyjnej i efektywnej specyfikacji

Zakończone

Plik specyfikacji (spec.md) jest pojedynczym źródłem prawdy dla tego, co powinno zrobić oprogramowanie. W tej lekcji omówiono zaawansowane techniki pisania specyfikacji klasy korporacyjnej.

Przegląd podstaw specyfikacji

W specyfikacyjnie zorientowanym programowaniu specyfikacja dokładnie określa, co oprogramowanie powinno robić, a każda decyzja dotycząca implementacji odnosi się do niej. Dobrze ustrukturyzowana specyfikacja obejmuje:

• Podsumowanie: zwięzły opis aplikacji (lub nowej funkcji) z perspektywy użytkownika końcowego.
• Historie użytkowników: krótkie narracje dotyczące sposobu interakcji użytkowników z aplikacją.
• Kryteria akceptacji: określone, testowalne warunki, które muszą być spełnione w celu ukończenia.
• Wymagania funkcjonalne: szczegółowe opisy zachowania systemu.
• Wymagania niefunkcjonalne: atrybuty jakości, takie jak wydajność, zabezpieczenia i skalowalność.
• Przypadki brzegowe: nietypowe scenariusze, warunki błędów i zachowania granic.

Specyfikacja techniczna jako jedno źródło prawdy

W specyfikacyjnie zorientowanym programowaniu specyfikacja dokładnie określa, co oprogramowanie powinno robić, a każda decyzja dotycząca implementacji odnosi się do niej. Jeśli funkcjonalność nie jest wyświetlana w specyfikacji, nie jest wyświetlana w końcowym produkcie, chyba że ktoś zaktualizuje specyfikację i ponownie generuje artefakty.

Takie podejście reprezentuje zmianę podejścia: pisanie specyfikacji jest równie ważne, jak pisanie kodu. Specyfikacja nie jest formalnością do zaspokojenia zarządzania projektami — jest to artefakt, który napędza generowanie kodu sztucznej inteligencji. Poświęć taką samą uwagę tworzeniu specyfikacji, jaką wykazujesz przy ręcznym implementowaniu funkcji.

Specyfikację można traktować jako dokumentację wykonywalną. Podczas modyfikowania wymagań należy zaktualizować specyfikację i ponownie wygenerować plan i zadania. Specyfikacja, która jest wersjonowana w systemie Git, staje się ostatecznym zapisem tego, co każda funkcja powinna osiągnąć.

W przypadku deweloperów korporacyjnych przyzwyczajonych do zwinnych przepływów pracy specyfikacje służą do tego samego celu co szczegółowe scenariusze użytkowników i kryteria akceptacji, ale ze strukturą czytelną dla maszyn, którą asystenci sztucznej inteligencji mogą korzystać bezpośrednio.

Struktura specyfikacji

Zestaw GitHub Spec Kit organizuje specyfikacje w ustandaryzowane sekcje, które obejmują zachowanie funkcjonalne, wymagania dotyczące jakości i przypadki brzegowe.

Sekcja podsumowania

Zwięzły opis funkcji z perspektywy użytkownika końcowego. W tej sekcji powinna znajdować się odpowiedź "Co robi ta funkcja?" w jednym lub dwóch zdaniach.

Przykład:

## 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.

Podsumowanie zawiera kontekst wysokiego poziomu. Ktoś, kto nie zna projektu, powinien zrozumieć przeznaczenie funkcji po przeczytaniu tej sekcji.

Sekcja scenariuszy użytkownika

Krótkie opisy narracji dotyczące sposobu interakcji użytkowników z funkcją. Scenariusze użytkownika przechwytują intencję i wartość, a nie implementację techniczną.

Przykład:

## 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.

Historie użytkowników pomagają asystentom sztucznej inteligencji zrozumieć ludzkie motywacje związane z funkcjami, co prowadzi do bardziej intuicyjnych implementacji.

Sekcja kryteriów akceptacji

Konkretne, testowalne warunki, które muszą być spełnione, aby funkcja została uznana za ukończoną. Kryteria akceptacji stanowią listę kontrolną weryfikacji implementacji.

Przykład:

## 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

Napisz kryteria akceptacji jako zauważalne fakty. Unikaj niejasnych instrukcji, takich jak "system jest responsywny", zamiast tego określ wartość "Interfejs API odpowiada w ciągu 200 ms".

Sekcja wymagań funkcjonalnych

Szczegółowe opisy zachowania systemu. Wymagania funkcjonalne zawierają szczegółowe informacje o sposobie działania funkcji.

Przykład:

## 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

Wymagania funkcjonalne zapewniają wystarczającą ilość szczegółów, aby sztuczna inteligencja generowała odpowiednie implementacje bez konieczności przepisywania dokładnej struktury kodu.

Sekcja wymagań niefunkcjonalnych

Atrybuty jakości, takie jak wydajność, zabezpieczenia, skalowalność i zgodność. Te wymagania często odwołują się do konstytucji.

Przykład:

## 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

Wymagania niefunkcjonalne zapewniają, że kod generowany przez sztuczną inteligencję spełnia standardy jakości przedsiębiorstwa, a nie tylko poprawność funkcjonalną.

Sekcja przypadków brzegowych

Nietypowe scenariusze, warunki błędów i zachowania na granicach. Jawne dokumentowanie przypadków brzegowych uniemożliwia wprowadzanie założeń przez sztuczną inteligencję.

Przykład:

## 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"

Myślenie za pomocą przypadków brzegowych podczas specyfikacji uniemożliwia błędy, które w przeciwnym razie pojawią się podczas implementacji lub testowania.

Tworzenie specyfikacji przy użyciu zestawu GitHub Spec Kit

Pisanie skutecznych specyfikacji jest łatwiejsze dzięki poleceniu /speckit.specify zestawu GitHub Spec Kit.

Zestaw GitHub Spec Kit generuje wersje robocze specyfikacji na podstawie opisów języka naturalnego, przyspieszając tworzenie specyfikacji przy zachowaniu spójnej struktury.

Wywołaj polecenie specify

Aby utworzyć specyfikację:

1. Otwórz projekt w programie Visual Studio Code.

2. Otwórz aplikację /speckit.specify GitHub Copilot Chat, a następnie uruchom polecenie z monitem opisującym funkcję, którą chcesz utworzyć.

   Przykład:

   /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.
   

   Ten opis obejmuje:

   • Co: przekazywanie dokumentów PDF/DOCX
   • Gdzie: internetowy interfejs pulpitu nawigacyjnego
   • Jak: przechowywane w Azure Blob Storage
   • Kto: Użytkownicy z rolą współautora
   • Ograniczenia: limit 50 MB, określone typy plików
   • Środowisko użytkownika: wyświetlanie postępu, komunikaty o błędach

Narzędzie GitHub Copilot generuje plik ustrukturyzowany spec.md na podstawie tych danych wejściowych, tworząc sekcje podsumowania, kryteriów akceptacji, wymagań i przypadków brzegowych.

Przejrzyj wygenerowaną specyfikację

Po wygenerowaniu specyfikacji przez narzędzie GitHub Copilot otwórz spec.md i zweryfikuj:

• Kompletność: Czy specyfikacja obejmuje wszystkie wymienione wymagania? Jeśli określono "tylko PDF i DOCX", potwierdź, że kryteria akceptacji obejmują te typy plików.

• Dokładność: Czy szczegóły są poprawne? Jeśli wspomniałeś o limicie 50 MB, zweryfikuj, czy specyfikacja rzeczywiście podaje wartość 50 MB, a nie inną.

• Spójność: Czy różne sekcje są zgodne? Jeśli podsumowanie wspomina o wyświetlaniu postępu, kryteria akceptacji powinny to uwzględniać.

• Brakujące elementy: Co wywnioskował lub pominął GitHub Copilot? Przejrzyj wygenerowane wymagania, aby sprawdzić, czy sztuczna inteligencja nie poczyniła założeń, z którymi się nie zgadzasz.

Początkowa specyfikacja jest silnym punktem wyjścia, ale rzadko jest idealna. Należy oczekiwać, że zostanie to doprecyzowane poprzez wyjaśnienia.

Uściślinie specyfikacji za pomocą pliku /speckit.clarify

Polecenie /speckit.clarify analizuje specyfikację i identyfikuje niejednoznaczności, luki lub założenia wymagające wyjaśnienia.

Zapewnianie jasności specyfikacji

Niejednoznaczności w specyfikacjach prowadzą do nieprawidłowych implementacji. Użyj /speckit.clarify, aby uwidocznić niejasne obszary.

Po wygenerowaniu początkowej specyfikacji:

1. W GitHub Copilot Chat uruchom:

   /speckit.clarify
   

2. GitHub Copilot analizuje spec.md i zadaje pytania dotyczące niejasnych lub brakujących szczegółów

   Przykładowe pytania wyjaśniające:

   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?
   

Te pytania ułatwiają podejmowanie decyzji dotyczących aspektów, które mogły zostać pominięte początkowo.

Odpowiedz na pytania dotyczące wyjaśnień

Odpowiedz na każde pytanie, podejmując określone decyzje:

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.

Po udzieleniu odpowiedzi usługa GitHub Copilot aktualizuje spec.md uwzględniając Twoje decyzje.

• Korzyści z kryterium akceptacji: "Użytkownicy mogą pobierać wcześniej przekazane dokumenty."
• Wymagania funkcjonalne dodają specyfikację punktu końcowego pobierania.
• Przypadki brzegowe obejmują: "Wiele plików o identycznych nazwach, wyróżnionych znacznikiem czasu przesyłania".
• Wymagania niefunkcjonalne, uwaga dotycząca: "Skanowanie wirusów przełożone na przyszłą wersję".

Iterowanie do momentu ukończenia

Uruchom /speckit.clarify wiele razy w razie potrzeby. Każda iteracja dodatkowo uściśli specyfikację:

• Pierwsza ocena: główne luki w funkcjonalności.
• Drugi etap: szczegóły przypadku brzegowego.
• Trzeci pass: Dostrajanie wymagań niefunkcjonalnych.

Zatrzymaj się, gdy narzędzie GitHub Copilot nie ma więcej pytań lub zadaje tylko pytania dotyczące funkcji, które chcesz odroczyć.

Najlepsze rozwiązania dotyczące pisania specyfikacji

Pisanie jasnych, jednoznacznych specyfikacji jest kluczem do pomyślnego opracowania opartego na specyfikacji.

Bądź konkretny i wymierny

Zastąp niejasne terminy precyzyjnymi wartościami:

• Nie: "Obsługa dużych plików".

• Zamiast tego: "Obsługa plików do 50 MB".

• Nie: "Wydajność szybkiego przesyłania".

• Zamiast tego: "Przesyłanie plików poniżej 5 MB trwa do 5 sekund na połączeniu 10 Mb/s".

Określone wymagania umożliwiają sztucznej inteligencji generowanie implementacji spełniających rzeczywiste potrzeby.

Używanie spójnej terminologii

Zdefiniuj terminy raz i ponownie użyj ich w całej specyfikacji. Jeśli wywołasz je jako "dokumenty" w podsumowaniu, nie przełącz się później na "pliki" ani "załączniki". Niespójna terminologia myli zarówno ludzi, jak i sztuczną inteligencję.

W przypadku projektów wewnętrznych przedsiębiorstwa użyj oficjalnych nazw produktów i terminologii ze standardów organizacji.

Wyraźne omówienie obsługi błędów

Nie zakładaj, że sztuczna inteligencja odpowiednio obsługuje błędy. Określ, co się stanie, gdy operacje kończą się niepowodzeniem:

• "Jeśli usługa Azure Blob Storage nie jest osiągalna, wyświetl błąd: "Nie można nawiązać połączenia z usługą magazynu. Spróbuj ponownie później.
• "Jeśli użytkownik nie ma wymaganej roli, zwróć odpowiedź HTTP 403 z wiadomością: "Nie masz uprawnień do przesyłania dokumentów"."

Jawna obsługa błędów uniemożliwia sztucznej inteligencji implementowanie ogólnych komunikatów o błędach, które nie pomagają użytkownikom.

Zachowaj odpowiedni zakres

Jeśli funkcja wymaga określenia więcej niż 300 wierszy, rozważ podzielenie jej na wiele specyfikacji:

• Zamiast jednej specyfikacji "System zarządzania dokumentami".
• Utwórz oddzielne specyfikacje: "Przekazywanie dokumentów", "Pobieranie dokumentów", "Udostępnianie dokumentów" i "Wyszukiwanie dokumentów".

Mniejsze specyfikacje są łatwiejsze do przejrzenia, wyjaśnienia i wdrożenia. Są one również zgodne z praktykami dostarczania przyrostowego.

Szczegóły "co", a nie "jak"

Specyfikacje definiują wymagania, a nie implementacje. Określ, co system powinien zrobić, a nie jak go kodować.

• Spec: "Przechowuj przekazane pliki w usłudze Azure Blob Storage."
• Nie ma w specyfikacji: "Użyj pakietu NuGet Azure.Storage.Blobs z klasą BlobContainerClient".

Decyzje dotyczące implementacji należą do fazy planu. Jeśli jednak konstytucja nakazuje określone technologie, odwoływanie się do nich w specyfikacji jest odpowiednie.

Weryfikowanie pod kątem konstytucji

Przed sfinalizowaniem specyfikacji sprawdź, czy nie powoduje to konfliktu z zasadami projektu:

• Polityka wymaga uwierzytelniania za pomocą Microsoft Entra ID → Specyfikacja musi określać Microsoft Entra ID, a nie niestandardowe uwierzytelnianie.
• Konstytucja wymaga 90-dniowego przechowywania audytów → Spec musi obejmować wymagania dotyczące rejestrowania audytów.
• Konstytucja ogranicza maksymalny rozmiar pliku do 50 MB → specyfikacji nie może wymagać obsługi plików 1 GB.

Niespójności przechwycone podczas specyfikacji są znacznie tańsze do naprawienia niż po wdrożeniu.

Ukończona specyfikacja staje się Twoją umową z GitHub Copilot. Po zakończeniu fazy planowania usługa GitHub Copilot odwołuje się do tej specyfikacji w celu projektowania implementacji technicznych, które dokładnie spełniają Wymagania. Czas zainwestowany w dokładną specyfikację płaci dywidendy w całym rozwoju.

Podsumowanie

Pisanie skutecznych specyfikacji jest podstawą pomyślnego opracowywania opartego na specyfikacji. Dobrze ustrukturyzowana specyfikacja służy jako pojedyncze źródło prawdy, prowadząc generowanie kodu sztucznej inteligencji i zapewniając zgodność z zasadami projektu. Za pomocą poleceń /speckit.specify i /speckit.clarify zestawu GitHub Spec Kit można szybko tworzyć i udoskonalać szczegółowe specyfikacje, które obejmują zachowanie funkcjonalne, atrybuty jakości oraz przypadki brzegowe. Stosowanie najlepszych rozwiązań w pisaniu specyfikacji zwiększa przejrzystość, zmniejsza niejednoznaczność i prowadzi do implementacji spełniających wymagania użytkowników i standardy przedsiębiorstwa.