產生清晰、精確且有效的規格

  • 14 分鐘

規格檔（spec.md）是你軟體應該做什麼的唯一真實來源。 本單元涵蓋撰寫企業級規格的進階技術。

複習規格基礎

在規格驅動的開發中，規範明確定義軟體應該做什麼，而每一個實作決策都源自此。 結構良好的規範包括：

  • 摘要：從終端使用者的角度簡明說明應用程式（或新功能）。
  • 使用者故事：簡短敘述使用者如何與應用程式互動。
  • 驗收標準：必須符合才能完成的具體且可測試的條件。
  • 功能需求：系統行為的詳細描述。
  • 非功能性需求：品質屬性如效能、安全性與可擴展性。
  • 邊緣案例：特殊情境、錯誤條件及邊界行為。

規格作為唯一真實來源

在規格驅動的開發中，規範明確定義軟體應該做什麼，而每一個實作決策都源自此。 如果功能沒有出現在規格裡，那它就不會出現在最終產品裡，除非有人更新規格並重新生成產出物。

這種做法代表了一種思維轉變：撰寫規格書和寫程式碼一樣重要。 規範不是為了滿足專案管理的要求而出現的形式——它是驅動 AI 程式碼生成的產物。 製作規格時，要像手動實作功能一樣用心。

把規格看作是可執行的文件。 當你修改需求時，你會更新規格並重新生成計畫和任務。 在 Git 中進行版本控制的規範成為每個功能應達成目標的權威紀錄。

對於習慣敏捷工作流程的企業開發者來說，該規範與詳細的使用者故事及驗收標準具有相同的功能，但結構可機器讀取，AI 助理可直接理解。

規範結構

GitHub Spec Kit 將規範組織成標準化的章節，涵蓋功能行為、品質要求與邊緣案例。

摘要區段

從終端使用者的角度簡明說明此功能。 本節應用一到兩句話來回答「這個功能的作用是什麼？」。

例如：

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

摘要提供了高層次的背景。 不熟悉此專案的人閱讀此節後應該能理解此功能的目的。

使用者故事區塊

簡短敘述使用者如何與此功能互動。 使用者故事捕捉的是意圖與價值，而非技術實作。

例如：

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

使用者故事幫助 AI 助理理解功能背後的人類動機，進而推動更直覺的實作。

錄取標準部分

具體且可測試的條件必須成立，特徵才被視為完整。 驗收標準構成一份驗證實施的檢查清單。

例如：

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

將接受標準寫成可觀察的事實。 避免使用模糊的說法，例如「系統響應式」，而是明確說明「API 在 200 毫秒內回應」。

功能需求章節

系統行為的詳細描述。 功能需求會詳細說明該功能的運作方式。

例如：

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

功能需求提供了足夠的細節，讓 AI 能產生適當的實作，而不必規定精確的程式碼結構。

非功能需求章節

品質屬性如效能、安全性、可擴展性與合規性。 這些要求通常參考憲法。

例如：

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

非功能性需求確保 AI 生成的程式碼符合企業品質標準，而不僅僅是功能正確性。

邊緣案例章節

不尋常的情況、錯誤條件與邊界行為。 明確記錄邊緣案例能防止 AI 做出假設。

例如：

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

在規格化過程中思考邊緣案例，可以避免在實作或測試中可能出現的錯誤。

使用 GitHub Spec Kit 建立規範

使用 GitHub Spec Kit /speckit.specify 的指令，撰寫有效的規格會更容易。

GitHub Spec Kit 根據自然語言描述產生規範草稿，加速規範創建同時保持結構一致。

執行 specify 指令

要建立規範：

  1. 用 Visual Studio Code 開啟你的專案。

  2. 打開 GitHub Copilot Chat，然後用一個描述你想建立功能的提示符執行 /speckit.specify 指令。

    例如：

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

    本描述涵蓋：

    • 內容：上傳PDF/DOCX文件
    • 其中：網頁儀表板介面
    • 方法：儲存在 Azure Blob 儲存中
    • 誰：具貢獻者角色的使用者
    • 限制：50 MB 限制、特定檔案類型
    • 使用者體驗：進度顯示、錯誤訊息

GitHub Copilot 會根據這些輸入產生結構化 spec.md 檔案，並建立摘要、接受標準、需求及邊緣案例等區塊。

檢視產生的規格

GitHub Copilot 產生規格後，開啟 spec.md 並驗證：

  • 完整性：規格是否涵蓋你提到的所有要求？ 如果你指定「僅 PDF 和 DOCX」，請確認接受條件並列出這些檔案類型。

  • 準確性：細節正確嗎？ 如果你說的是 50 MB 限制，請確認規格上寫的是 50 MB，而不是其他數值。

  • 一致性：不同區塊是否對齊？ 如果摘要提到進度展示，接受標準應該包含它。

  • 缺少的元素：GitHub Copilot 推斷或遺漏了什麼？ 檢視生成的需求，看看 AI 是否有你不同意的假設。

初始規格是個強而有力的起點，但很少完美。 預期會透過澄清來進一步完善。

使用 /speckit.clarify 精煉規格

指令 /speckit.clarify 會分析你的規格，並找出需要澄清的歧義、缺口或假設。

確保規格清晰

規範中的模糊會導致錯誤的實作。 用 /speckit.clarify 來顯示不清的區域。

產生初始規格後：

  1. 在 GitHub Copilot 聊天中，執行：

    /speckit.clarify

  2. GitHub Copilot 會 spec.md 分析並針對不清楚或缺失的細節提出問題

    說明問題範例：

    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?

這些問題能幫助你做出可能一開始忽略的決策。

回答釐清問題

請以具體的決定回應每個問題：

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.

回答後，GitHub Copilot 會更新 spec.md 以納入您的決策：

  • 接受標準提升：「使用者可下載先前上傳的文件。」
  • 功能需求新增下載端點規範。
  • 邊緣案例包括：「多個名稱相同且由上傳時間戳區分的檔案。」
  • 非功能性需求說明：「病毒掃描延後至未來發布。」

不斷迭代直到完成

如果需要，可以執行 /speckit.clarify 多次。 每次迭代都進一步精煉規格：

  • 初步檢查：存在重大功能缺口。
  • 第二次檢查：邊緣案例細節。
  • 第三階段：微調非功能需求。

當 GitHub Copilot 沒有更多問題或只問你想延後的功能時，就停止使用。

規範撰寫的最佳實務

撰寫清晰且明確的規格是成功以規格為驅動開發的關鍵。

要具體且可衡量

用精確的數值替換模糊的詞彙：

  • 不是：「支援大型檔案」。

  • 取而代之的是：「支援最高 50 MB 的檔案。」

  • 不是：「快速上傳效能」。

  • 取而代之的是：「5 MB 以下的上傳在 10-Mbps 連線下 5 秒內完成。」

特定需求使 AI 能產生符合你實際需求的實作。

使用一致的術語

定義一次術語，並在整個規格中重複使用。如果你在摘要中稱它們為「文件」，之後不要改成「檔案」或「附件」。 不一致的術語會讓人類和人工智慧都感到困惑。

對於企業內部專案，請使用貴組織標準中的官方產品名稱與術語。

明確涵蓋錯誤處理

不要假設 AI 能妥善處理錯誤。 請說明操作失敗時會發生什麼：

  • 「如果 Azure Blob 儲存無法存取，顯示錯誤：『無法連接儲存服務。 稍後再試。』」
  • 「如果使用者缺少所需角色，請回傳 HTTP 403 並附上訊息：『你沒有上傳文件的權限。』」

明確的錯誤處理防止 AI 實施對使用者無益的通用錯誤訊息。

維持適當的範圍

如果一個特徵需要超過 300 行來指定，可以考慮將其拆分成多個規格：

  • 而不是只有一個「文件管理系統」規格。
  • 建立獨立的規範：「文件上傳」、「文件下載」、「文件分享」和「文件搜尋」。

較小的規格比較容易審查、釐清和實作。 它們也與增量式交付的做法相符。

要詳細說明「做什麼」，而不是「怎麼做」

規範定義的是需求，而非實作。 說明系統應該做什麼，而不是怎麼寫：

  • 規格：「將上傳的檔案儲存在 Azure Blob 儲存空間。」
  • 不符合規格：「使用 Azure.Storage.Blobs NuGet 套件搭配 BlobContainerClient 類別。」

執行決策應屬於計畫階段。 然而，如果憲法規定特定技術，在規範中提及這些技術是合適的。

根據憲法驗證

在確定規格前，請確認其不與專案原則相衝突：

  • 憲法要求Microsoft Entra ID 認證→規範必須指定 Microsoft Entra ID，而非自訂認證。
  • 憲法規定審計保留期限為90天→規範必須包含審計記錄要求。
  • Constitution 限制最大檔案大小為 50 MB，→ Spec 不能要求支援 1 GB 檔案。

在規格制定過程中發現的不一致，修復成本遠低於實施後。

完成的規格就會成為你與 GitHub Copilot 的合約。 當你進入規劃階段時，GitHub Copilot 會參考此規格，設計出完全符合你需求的技術實作。 投入於嚴謹規格的時間，在整個開發過程中都帶來回報。

總結

撰寫有效的規範是成功以規格驅動開發的基礎。 結構良好的規範是唯一的真實來源，指導 AI 程式碼生成並確保與專案原則一致。 透過使用 GitHub Spec Kit /speckit.specify 與 /speckit.clarify 指令，您可以快速建立並精煉涵蓋功能行為、品質屬性及邊緣案例的詳細規範。 遵循規範撰寫的最佳實務能提升清晰度、減少歧義，並促成同時符合使用者需求與企業標準的實作。