產生任務並實作程式碼

  • 10 分鐘

技術計畫提供架構方向，但實施則需要具體且可行的步驟。 本單元涵蓋企業情境下的進階任務產生與管理技術。

複習任務基礎

GitHub Spec Kit 的 /speckit.tasks 指令會將高階架構決策轉換成 tasks.md 檔案中的特定工作項目。 每個任務代表一個獨立的工作單元，可以獨立實施、測試與驗證。

明確界定任務範圍的特徵要點：

  • 可執行性：明確說明需要完成的事項。
  • 可測試：驗證是否完成相當簡單。
  • 獨立：可以在不等待無關工作的情況下完成。
  • 時限：可在合理時間內完成（數小時至一天）。

階段式組織

複雜功能則受益於將任務分階段組織。 例如：設定、基礎、核心功能、使用者介面/整合、安全性和測試。 每個階段代表一個邏輯分組，朝向一個里程碑前進。

任務分解的好處

任務分解不僅用於整理工作，還有多重用途。 它們幫助 AI 針對特定目標產生專注程式碼，而非嘗試以單一操作實現整個功能。 它們創造了自然的驗證點，讓你可以在繼續前測試部分實作。 它們能精確顯示完成與剩餘進度。 它們透過明確表示相依關係，促進團隊協調。

文件上傳功能中，計畫描述整體架構與技術選擇。 任務清單將架構決策轉化為具體行動：建立資料庫資料表、實作 API 端點、建置 React 元件、新增驗證邏輯、撰寫測試。 每個任務都小到能在合理時間內完成，同時又夠大以代表有意義的進展。

檢視任務結構與組織

結構良好的任務清單能合理組織工作，適當排序相依關係，並提供明確的執行指引。

階段式組織

複雜特徵受益於階段式組織。 每個階段代表一組相關任務的邏輯組合，逐步朝向特定里程碑發展。

文件上傳功能中，典型的階段結構可能包括：

  • 第一階段：基礎與配置

    • 在 appsettings.json中設定 Azure Blob 儲存體 連線設定。
    • 在 SQL 資料庫中建立 DocumentMetadata 表格，並搭配適當的結構。
    • 將 Azure.Storage.Blobs NuGet 套件加入後端專案。
    • 建立封裝儲存操作的 DocumentService 類別。

  • 第二階段：核心上傳功能

    • 在 DocumentsController 中實作 POST /api/documents/upload 端點。
    • 在 DocumentService 中加入檔案驗證邏輯（大小、類型）。
    • 實作具有錯誤處理的 Blob 儲存上傳方法。
    • 成功上傳後，將文件元資料儲存到資料庫。
    • 請將上傳結果連同文件 ID 和 URL 回傳給客戶端。

  • 第三階段：前端實施

    • 建立帶有檔案輸入的 DocumentUpload React 元件。
    • 在元件中新增檔案大小與型別驗證功能。
    • 實施上傳進度指示器。
    • 處理上傳成功與錯誤回應。
    • 成功上傳後重新整理文件清單。

  • 第四階段：安全性與驗證

    • 在上傳端點新增 Microsoft Entra ID 驗證檢查。
    • 實作使用魔術數字的伺服器端檔案類型驗證。
    • 新增請求大小限制以防止拒絕服務攻擊。
    • 驗證檔案副檔名是否符合允許清單。
    • 為上傳操作新增稽核日誌。

  • 第五階段：測試與文件化

    • 撰寫 DocumentService 上傳方法的單元測試。
    • 建立整合測試以完成上傳流程。
    • 新增錯誤情境測試（檔案類型無效、大小超過）。
    • OpenAPI/Swagger 中的文件 API 端點。
    • 更新使用者文件並附上上傳說明。

這種分階段的做法會創造自然的里程碑。 在第 2 階段之後，您會擁有一個可運作但精簡的後端。 第三階段後，使用者可以上傳檔案。 第四階段結束後，系統已安全且準備生產。 第五階段結束後，所有內容都會被測試並記錄下來。

任務細緻度與範圍

每項任務都應具備適當的範圍——要有足夠的具體性來提供明確指引，但不能過於細緻，以免變成細節過多的微觀管理。

範圍明確的任務具備以下特徵：

  • 可執行性：任務明確說明需要完成的事項。
  • 可測試：你可以驗證任務何時完成。
  • 盡可能獨立：任務可以在不必等待無關工作的情況下完成。
  • 時限：開發人員可以在合理的時間內完成任務（通常是幾小時到一天，而非數週）。

明確範圍的任務範例：「實作 POST /api/documents/upload 端點，接受多部分檔案上傳，驗證檔案大小在 50 MB 以下，將檔案儲存在 Azure Blob 儲存空間，並回傳 blob URL 與文件 ID。」

這個任務針對要建置什麼（端點）、接受什麼（多部分檔案）、要套用哪些驗證（大小限制）、檔案要存放哪裡（Azure Blob 儲存體）以及要回傳什麼（URL 和 ID）。 開發者非常清楚該實施什麼。

這裡有一個範圍不夠明確的任務範例：「讓上傳成功。」此範例未提供可行的指引，說明「工作」的意義或包含哪些組成部分。

這裡有一個過於規範化的任務範例：「在DocumentsController.cs的第47行，新增一個名為 UploadDocument 的方法，並帶有參數（IFormFile file、string userId），並用這些步驟實作......」這個任務描述剝奪了開發者的自主權，也沒有考慮到不斷演變的程式碼結構。

任務依賴性與排序

任務順序很重要。 有些任務必須先完成，其他任務才能開始。

資料庫架構的變更通常會先進行，因為後端程式碼依賴於結構的存在。 後端 API 端點排在呼叫這些端點的前端元件之前。 設定設定會先於使用該設定的程式碼。 測試是在被測試的程式碼存在之後進行的。

任務清單應該依序排列工作，以減少阻塞。 如果前端和後端任務獨立，它們可以並行進行。 若存在多個後端端點，開發者可同時實作這些任務。

對於文件上傳功能，邏輯序列確保：

  1. 設定和資料庫設定會先進行（沒有相依關係）。
  2. 後端 API 的實作會跟隨資料庫設定（視結構而定）。
  3. 前端元件會依照 API 實作（依賴端點的存在）。
  4. 安全強化是在核心功能之後發生的（取決於程式碼本身）。
  5. 測試是在所有實作之後進行（視完成的程式碼而定）。

此任務序列允許持續推進，無需等待無關工作完成。

使用 /speckit.tasks 來產生任務

GitHub Spec Kit 透過 GitHub Copilot Chat 中的指令產生任務清單 /speckit.tasks 。 此指令同時處理 spec.md 與 plan.md，產生一份完整且有序的實作任務清單。

AI 分析規格以了解需要建置的內容，檢視計畫以了解架構方法，並生成任務，彌合文件與實際程式碼之間的差距。 產生的 tasks.md 檔案包含已編號或以項目符號列出的工作，對於複雜功能通常會依階段加以組織。

呼叫任務產生指令

在 Visual Studio Code 中開啟 GitHub Copilot Chat 並輸入 /speckit.tasks。 GitHub Copilot 負責處理規格並計畫產生結構化的任務清單。 生成過程通常在數分鐘內完成，產生完整的實施工作分解。

任務清單會自動繼承你的規格和計畫中的上下文。 如果計畫中明確表示「使用 Azure Blob 儲存體」，產生的任務會包含設定 blob 儲存連線、實作上傳邏輯及處理儲存錯誤的具體步驟。

檢視並驗證任務清單

任務清單需要關鍵審查以確保完整性與正確性。

確認計畫要素的保障範圍

系統性地比較 tasks.md 與 plan.md。 計畫中的每個架構決策與實施步驟都應對應一項或多項任務。

若計畫明確規定「實作伺服器端驗證」，具體任務應涵蓋檔案類型驗證、檔案大小驗證及錯誤回應處理。 如果計畫中提到「稽核日誌」，任務應該會針對為上傳操作建立日誌條目。

缺少的任務表示產生不完整，或是計畫元素無法轉化為具體工作。 解決這個問題的方法，是手動新增任務或提供更多上下文並重新生成。

檢查邏輯上的空白

尋找那些在計畫中不明顯，但在考量實施細節時會顯現的功能缺口。

常見的缺口包括：

  • 錯誤處理：是否有處理網路錯誤、儲存功能故障或資料庫問題的任務？
  • 邊緣案例：當使用者上傳名稱相同的檔案時會發生什麼事？ 同時上傳是怎麼處理的？
  • 設定：連線字串、API 金鑰和服務端點是否已妥善配置？
  • 用戶回饋：用戶如何知道上傳何時完成或失敗？
  • 資料清理：如果上傳部分成功後失敗，清理會被處理嗎？

在審查時識別這些缺口，並在實施前加入適當的任務。

評估任務順序與相依關係

確認任務順序正確。 資料庫結構任務應該先於存取這些資料表的程式碼。 API 端點任務應該置於呼叫這些端點的前端元件之前。

如果發現任務順序錯亂，請手動重新排序。 例如，如果前端任務出現在對應的後端任務之前，則將其移至適當的階段。

考慮同一階段內任務間的依賴關係。 如果一個任務的輸出需要另一個任務，請確保第一個任務出現在序列的較前面。

驗證任務的細緻度

確保每項任務的範圍都適當。 過大的任務（「實作整個後端」）應該拆分成較小且易於管理的部分。 過小的任務（例如「在第42行加分號」）應該合併成更有意義的單元。

一個範圍明確的任務通常只需幾小時到一天完成，可以獨立測試，並產生明顯的進展。

利用任務來指導實施

一旦驗證，tasks.md 就成為你的實作路線圖。

系統性地完成任務

按順序完成任務，完成一項後再進行下一個。 這種有紀律的方法確保沒有遺漏，並提供明確的進度指標。

完成每一項任務時：

  1. 實作所需的功能。
  2. 測試實作以驗證正確性。
  3. 標記任務為完成（新增勾選框或劃線）。
  4. 提交變更時，請參考任務內容。

這種系統化的方法建立了清晰的稽核軌跡，將已完成的工作與特定任務連結起來。

追蹤進度並溝通狀態

任務清單提供了衡量進度的客觀指標。 如果完成 30 個任務中的 15 個，該功能大約有 50% 實現。 此指標有助於專案規劃與利害關係人溝通。

與團隊分享 tasks.md，以溝通哪些已完成，哪些尚未完成。 團隊成員一目了然地看出哪些領域需要關注，以及應聚焦在哪些地方進行審查工作。

在實施過程中調整任務

若實施過程中發現新需求或改進方法，請相應更新 tasks.md。 任務清單應該反映現實，而非過時的計畫。

將任務分配給團隊成員

明確的任務定義允許工作分配至多個開發者。 後端團隊負責 API 任務，而前端團隊則負責建置 UI 元件。 資料庫管理員可以在開發人員準備設定時設定結構。

明確指出任務相依關係有助於防止阻塞。 如果任務 B 依賴任務 A，請確保任務 A 被適當指派並優先排序。 在任務中記錄完成標準，以確保交接過程乾淨。

使用 /speckit.implement 來產生程式碼

指令 /speckit.implement 使用 tasks.md 系統性地產生程式碼。 AI 不會嘗試一次實作整個功能，而是依序執行任務。 這種方法能產生更聚焦且正確的程式碼。

你可以用特定的任務編號、任務範圍，或是從 tasks.md 檔案中擷取的實作描述來呼叫 /speckit.implement 。 AI 會參考 spec.md、plan.md 和 tasks.md，產生符合整體架構與需求的程式碼。

例如，要實作文件上傳端點，你可以輸入：

/speckit.implement Implement the MVP first strategy (Tasks: T001 - T027)

此指令指示 AI 專注於任務 T001 至 T027，並依序生成符合各任務需求的程式碼。

在執行過程中提供協助

AI 可能需要協助或權限才能繼續執行某些工作。 例如，如果任務需要建置或執行應用程式，AI 可能會在繼續前先確認。

此外，AI 在測試任務實作時也可能發現錯誤。 提供詳細資訊以協助診斷問題。 如果 AI 遇到模糊之處，你也可以提供額外的背景或說明。

當在聊天視窗中被要求協助時，快速回應有助於推動實施順利進行。

驗證檢查站

完成實作指令後，先驗證結果再進行。 執行應用程式、執行測試，並確認每個任務都已實現並達成其目標。 這種漸進式驗證能在問題最容易修復時及早發現。

跨任務的上下文維護

隨著任務進展，先前完成的工作會為後續任務提供背景。 AI 在建構相關功能、提升程式碼品質及維持架構一致性時，能參考早期實作。

管理實施任務時常見的挑戰。

範圍擴大的任務

當任務在執行過程中發現意外的複雜性時，請暫停並重新評估。 把冗長的任務拆成多個較小的任務。 請更新 tasks.md 以反映真實範圍。 向利害關係人溝通擴大範圍。

阻塞任務

任務有時會被外部依賴性阻擋。 Mark 明確封鎖了 tasks.md 任務，並有封鎖理由：「BLOCKED： 等待 Azure Blob 儲存體 容器配置 - 工單 #1234。」分開追蹤被封鎖的任務，確保它們不會被遺忘。

優先順序的變化

商業需求會不斷演變。 當優先順序改變時，請相應地更新 tasks.md。 重新排列你的任務，以反映新的優先順序。 新增任務以應對緊急需求。 考慮延後或移除不再有價值的任務。

實作過程中發現的任務歧義

當模糊不清浮現時，暫停實施並尋求澄清。 檢視規格與計畫，了解原始意圖。 在繼續前，請以具體且明確的語言更新任務描述。

總結

任務產生將架構計畫轉化為可執行的步驟。 產生任務清單 /speckit.tasks ，以建立結構化、階段為基礎的實施工作分解。 批判性地檢視產生的任務，以確保涵蓋範圍全面、邏輯順序及適當的細節。 利用經過驗證的任務清單來引導系統性執行、追蹤進度並協調團隊努力。

spec.md、plan.md 與 tasks.md 的結合，創造出完整的開發框架。 規範定義了要建造什麼以及為什麼要建造。 該計畫定義了建築上的建造方式。 任務定義了執行建置的具體步驟。 這些工件共同將模糊的需求轉化為具體且可追蹤的開發工作，並在整個實施過程中與專案目標保持一致。