Etkili, net ve hassas bir spesifikasyon oluşturma

14 dakika

Belirtim dosyası (spec.md), yazılımınızın yapması gerekenler için tek doğru kaynaktır. Bu ünite, kurumsal sınıf belirtimler yazmak için gelişmiş teknikleri kapsar.

Belirtim temellerini gözden geçirme

Belirtim temelli geliştirmede belirtim, yazılımın tam olarak ne yapması gerektiğini tanımlar ve her uygulama kararı buna geri döner. İyi yapılandırılmış bir belirtim şunları içerir:

Özet: Uygulamanın (veya yeni özelliğin) son kullanıcı perspektifinden kısa açıklaması.
Kullanıcı hikayeleri: Kullanıcıların uygulamayla nasıl etkileşime geçtiğini gösteren kısa anlatılar.
Kabul ölçütleri: Tamamlama için doğru olması gereken belirli, test edilebilir koşullar.
İşlevsel gereksinimler: Sistem davranışının ayrıntılı açıklamaları.
İşlevsel olmayan gereksinimler: Performans, güvenlik ve ölçeklenebilirlik gibi kalite öznitelikleri.
Uç durumlar: Olağan dışı senaryolar, hata koşulları ve sınır davranışları.

Tek doğru bilgi kaynağı olarak spesifikasyon

Belirtim temelli geliştirmede belirtim, yazılımın tam olarak ne yapması gerektiğini tanımlar ve her uygulama kararı buna geri döner. Fonksiyon spesifikasyonda görünmüyorsa, spesifikasyonu birisi güncelleştirmediği ve belge ile çıktıları yeniden oluşturmadığı sürece son üründe görünmez.

Bu yaklaşım bir düşünce değişikliğini temsil eder: belirtimi yazmak kod yazmak kadar önemlidir. Belirtim, proje yönetimini karşılamak için bir formalite değildir; yapay zeka kodu oluşturmayı yönlendiren yapıttır. Özellikleri el ile uygulama konusunda yaptığınız gibi teknik özellikler oluşturmaya da aynı özeni gösterebilirsiniz.

Belirtimi yürütülebilir belgeler olarak düşünün. Gereksinimleri değiştirdiğinizde, belirtimi güncelleştirir ve planı ve görevleri yeniden oluşturursunuz. Git'te sürüm denetiminde olan spesifikasyon, her özelliğin neyi başarması gereken nihai kayıt haline gelir.

Çevik iş akışlarına alışkın olan kurumsal geliştiriciler için belirtim, ayrıntılı kullanıcı hikayeleri ve kabul ölçütleriyle aynı ama yapay zeka yardımcılarının doğrudan kullanabileceği makine tarafından okunabilir bir yapıyla aynı amaca hizmet eder.

Belirtim yapısı

GitHub Spec Kit, belirtimleri işlevsel davranışı, kalite gereksinimlerini ve uç durumları kapsayan standartlaştırılmış bölümler halinde düzenler.

Özet bölümü

Özelliğin son kullanıcı perspektifinden kısa bir açıklaması. Bu bölüm bir veya iki cümlede "Bu özellik ne yapar?" sorusunu yanıtlamalıdır.

Örneğin:

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

Özet, üst düzey bağlam sağlar. Projeyi kullanmayan biri bu bölümü okuduktan sonra özelliğin amacını anlamalıdır.

Kullanıcı hikayeleri bölümü

Kullanıcıların işleve nasıl etkileşimde bulunduğunu gösteren kısa açıklamalar. Kullanıcı hikayeleri, teknik uygulama yerine amacı ve değeri yakalar.

Örneğin:

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

Kullanıcı hikayeleri, yapay zeka yardımcılarının özelliklerin ardındaki insan motivasyonlarını anlamasına yardımcı olur ve daha sezgisel uygulamalara yol açar.

Kabul ölçütleri bölümü

Özelliğin tamamlandı olarak kabul edilmesi için doğru olması gereken belirli, test edilebilir koşullar. Kabul ölçütleri, uygulamayı doğrulamak için bir denetim listesi oluşturur.

Örneğin:

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

Kabul ölçütlerini gözlemlenebilir olgular olarak yazın. "Sistem yanıt veriyor" gibi belirsiz deyimlerden kaçının; bunun yerine "API 200 ms içinde yanıt veriyor" ifadesini belirtin.

İşlevsel gereksinimler bölümü

Sistem davranışının ayrıntılı açıklamaları. İşlev gereksinimleri, özelliğin nasıl çalıştığı hakkında ayrıntılı bilgi sağlar.

Örneğin:

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

İşlev gereksinimleri, yapay zekanın tam kod yapısını belirlemeden uygun uygulamalar oluşturması için yeterli ayrıntı sağlar.

İşlevsel olmayan gereksinimler bölümü

Performans, güvenlik, ölçeklenebilirlik ve uyumluluk gibi kalite öznitelikleri. Bu gereksinimler genellikle anayasaya başvurur.

Örneğin:

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

İşlevsel olmayan gereksinimler, yapay zeka tarafından oluşturulan kodun yalnızca işlevsel doğruluğu değil kurumsal kalite standartlarını karşılamasını sağlar.

Edge servis talepleri bölümü

Olağan dışı senaryolar, hata koşulları ve sınır davranışları. Uç durumlarının açıkça belgelenmesi, yapay zekanın varsayımlarda bulunmasını önler.

Örneğin:

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

Belirtim sırasında uç durumlar üzerinden düşünmek, uygulama veya test sırasında ortaya çıkacak hataları önler.

GitHub Spec Kit ile belirtim oluşturma

GitHub Spec Kit'in /speckit.specify komutuyla etkili belirtimler yazmak daha kolaydır.

GitHub Spec Kit, doğal dil açıklamalarına dayalı belirtim taslakları oluşturarak tutarlı yapıyı korurken belirtim oluşturmayı hızlandırıyor.

Specify komutunu çağırma

Belirtim oluşturmak için:

Projenizi Visual Studio Code'da açın.
GitHub Copilot Sohbeti'ni /speckit.specify açın ve ardından oluşturmak istediğiniz özelliği açıklayan bir istemle komutunu çalıştırın.

Örneğin:
```
/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.
```
Bu açıklama aşağıdakileri kapsar:
- Nedir: PDF/DOCX belgelerini karşıya yükleme
- Nerede: Web panosu arabirimi
- Nasıl yapılır: Azure Blob Depolama'da depolanır
- Kimler: Katkıda Bulunan rolüne sahip kullanıcılar
- Kısıtlamalar: 50 MB sınırı, belirli dosya türleri
- Kullanıcı deneyimi: İlerleme durumu görüntüleme, hata iletileri

GitHub Copilot bu girişe dayalı olarak yapılandırılmış spec.md bir dosya oluşturur ve özet, kabul ölçütleri, gereksinimler ve uç durumlar için bölümler oluşturur.

Oluşturulan spesifikasyonu inceleyin

GitHub Copilot belirtimi oluşturduktan sonra açın spec.md ve doğrulayın:

Eksiksizlik: Belirtim, bahsettiğiniz tüm gereksinimleri kapsıyor mu? "Yalnızca PDF ve DOCX" belirttiyseniz, kabul ölçütlerinin bu dosya türlerini listelediğini onaylayın.
Doğruluk: Ayrıntılar doğru mu? Eğer 50 MB sınırı dedinizse, spesifikasyonun 50 MB olduğunu ve farklı bir değer olmadığını doğrulayın.
Tutarlılık: Farklı bölümler hizalanır mı? Özette ilerleme durumu gösteriliyorsa kabul ölçütleri bunu içermelidir.
Eksik öğeler: GitHub Copilot neleri çıkarmış veya atlamış? Yapay zekanın katılmadığınız varsayımlar yapıp yapmadığını görmek için oluşturulan gereksinimleri gözden geçirin.

İlk spesifikasyon güçlü bir başlangıç noktasıdır ancak nadiren mükemmeldir. Bunu netleştirme yoluyla iyileştirmeyi bekleyebilirsiniz.

/speckit.clarify ile özellikleri iyileştirme

komutu /speckit.clarify belirtiminizi analiz eder ve belirsizlikleri, boşlukları veya açıklama gerektiren varsayımları tanımlar.

Belirtim netliğini sağlayın

Belirtimlerdeki belirsizlikler yanlış uygulamalara yol açar. Belirsiz alanları ortaya çıkarabilmek için kullanın /speckit.clarify .

İlk belirtimi oluşturdıktan sonra:

GitHub Copilot Sohbeti'nde şunu çalıştırın:
```
/speckit.clarify
```

GitHub Copilot, belirsiz veya eksik ayrıntılar hakkında analizler spec.md ve sorular sorar

Örnek açıklama soruları:

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?

Bu sorular başlangıçta gözden kaçırmış olabileceğiniz konular hakkında karar vermenizi sağlar.

Açıklama sorularını yanıtlayın

Belirli kararlarla her soruya yanıt verin:

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.

Yanıtladıktan sonra GitHub Copilot, kararlarınızı dahil etmek için güncelleştirilir spec.md :

Kabul ölçütleri avantajları: "Kullanıcılar daha önce yüklenen belgeleri indirebilir."
İşlev gereksinimleri, indirme uç noktası belirtimi ekler.
Edge örnekleri şunlardır: "Yükleme zamanı ile ayırt edilen aynı adlara sahip birden çok dosya."
İşlevsel olmayan gereksinimler not: "Virüs taraması gelecek sürüme ertelendi."

Tamamlanana kadar yinele

Gerekirse birden çok kez çalıştırın /speckit.clarify . Her yineleme belirtimi daha da iyileştirmektedir:

İlk geçiş: Önemli işlevsellik boşlukları.
İkinci geçiş: Edge durum ayrıntıları.
Üçüncü geçiş: İşlevsel olmayan gereksinimlerde ince ayarlama.

GitHub Copilot'ta başka soru kalmadığında veya yalnızca ertelemek istediğiniz özellikler hakkında sorulduğunda durdurun.

Belirtim yazma için en iyi yöntemler

Net ve kesin özellikler yazmak, belirti güdümlü geliştirmenin başarılı olması için kritik öneme sahiptir.

Belirli ve ölçülebilir olun

Belirsiz terimleri kesin değerlerle değiştirin:

Not: "Büyük dosyaları destekleyin."
Bunun yerine: "50 MB'a kadar olan dosyaları destekleyin."
Not: "Yükleme hız performansı."
Bunun yerine: "5 MB'nin altındaki yüklemeler 10 Mbps bağlantıda 5 saniye içerisinde tamamlanır."

Belirli gereksinimler, yapay zekanın gerçek gereksinimlerinizi karşılayan uygulamalar oluşturmasını sağlar.

Tutarlı terminoloji kullanma

Terimleri bir kez tanımlayın ve belirtim boyunca yeniden kullanabilirsiniz. Özette bunları "belgeler" olarak adlandırıyorsanız, daha sonra "dosyalar" veya "ekler"e geçmeyin. Tutarsız terminoloji hem insanların hem de yapay zekanın kafasını karıştırır.

Kurumsal iç projeler için, kuruluşunuzun standartlarından resmi ürün adlarını ve terminolojisini kullanın.

Hata işlemeyi açıkça ele al

Yapay zekanın hataları uygun şekilde işlediğini varsaymayın. İşlemler başarısız olduğunda ne olacağını belirtin:

"Azure Blob Depolama'ya ulaşılamıyorsa şu hatayı görüntüleyin: 'Depolama hizmetine bağlanılamıyor. Daha sonra yeniden deneyin.'"
"Kullanıcının gerekli rolü yoksa HTTP 403'i şu iletiyle döndür: 'Belgeleri karşıya yükleme izniniz yok.'"

Açık hata işleme, yapay zekanın kullanıcılara yardımcı olmayan genel hata iletileri uygulamasını engeller.

Uygun kapsamı koruma

Bir özelliğin belirtilmesi için 300'den fazla satır gerekiyorsa, bunu birden çok belirtime bölmeyi göz önünde bulundurun:

Bir "Belge Yönetim Sistemi" belirtimi yerine.
Ayrı belirtimler oluşturun: "Belge Yükleme," "Belge İndirme," "Belge Paylaşımı" ve "Belge Arama."

Daha küçük özellikleri gözden geçirmek, netleştirmek ve uygulamak daha kolaydır. Bunlar aynı zamanda artımlı teslimat uygulamalarıyla uyumludur.

Ayrıntı "ne" değil "nasıl"

Belirtimler, uygulamaları değil gereksinimleri tanımlar. Sistemin yapması gerekenleri belirtme, nasıl kodlanmaları gerektiğini belirtme:

Özellik: "Yüklenen dosyaları Azure Blob Depolama'da depolayın."
Spesifikasyona dahil değil: "Azure.Storage.Blobs NuGet paketini BlobContainerClient sınıfıyla kullanın."

Uygulama kararları plan aşamasına aittir. Ancak, anayasa belirli teknolojileri zorunlu kılıyorsa, bunların belirtimde belirtilmesi uygun olur.

Anayasaya karşı doğrulama

Belirtimi sonlandırmadan önce proje ilkeleriyle çakışmadığını doğrulayın:

Anayasa, Microsoft Entra Id kimlik doğrulaması gerektirir → Belirtim, özel kimlik doğrulaması değil Microsoft Entra Kimliği belirtmelidir.
Anayasa, 90 günlük denetim saklamasını zorunlu kılar → Şartname, denetim günlüğü gereksinimlerini içermelidir.
Anayasa, maksimum dosya boyutunu 50 MB ile sınırlar → Belirtimler için 1 GB dosya desteği gerekmez.

Belirtim sırasında yakalanan tutarsızlıkların düzeltilmesi uygulamadan sonraya göre çok daha ucuz.

Tamamlanan spesifikasyon, GitHub Copilot ile olan sözleşmeniz haline gelir. Planlama aşamasına geçtiğinizde GitHub Copilot, gereksinimlerinize tam olarak uyan teknik uygulamalar tasarlamak için bu belirtimlere başvurur. Detaylı spesifikasyona yatırılan süre, geliştirme boyunca fayda sağlar.

Özet

Etkili belirtimler yazmak, başarılı belirtim temelli geliştirmenin temelini oluşturur. İyi yapılandırılmış bir belirtim, yapay zeka kodu oluşturma ve proje ilkeleriyle uyum sağlama konusunda yol gösteren tek gerçeklik kaynağı görevi görür. GitHub Spec Kit'in /speckit.specify ve /speckit.clarify komutlarını kullanarak, işlevsel davranışı, kalite özniteliklerini ve uç durumları kapsayan ayrıntılı belirtimleri hızla oluşturabilir ve geliştirebilirsiniz. Belirtim yazmada en iyi yöntemlerin uygulanması netliği artırır, belirsizliği azaltır ve hem kullanıcı gereksinimlerini hem de kurumsal standartları karşılayan uygulamalara yol açar.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?