制定詳細的技術計畫

12 分鐘

規格說明你需要建造什麼。技術計畫定義了你如何建造它。本單元涵蓋企業棕地情境的進階規劃技術。

檢討計畫基礎原則

plan.md 檔案作為設計文件，銜接 spec.md 中高階需求與後續具體實作任務之間的橋樑。完整的技術計畫包含：

架構概述：高階的元件互動視角。
技術堆疊與關鍵決策：明確記錄技術選擇並附上理由。
實施順序：實施步驟的邏輯性進展。
憲法驗證：明確檢查所提出方案是否符合專案原則。
假設與未解決問題：記錄假設與未解決問題。

基於這些基本原則，讓我們探討企業發展中進階規劃的考量。

關注點分離——規格與計畫

規範與技術計畫之間的關切分離至關重要。雖然規格保持穩定且聚焦於「做什麼」，但隨著你嘗試不同的「如何」方法，計畫仍可演變。

假設你的規格要求內部員工入口網站有文件上傳功能。規範定義了使用者需求：檔案大小限制、支援格式、上傳回饋及存取控制。技術計畫將這些需求轉化為具體的架構決策：使用哪種 Azure 儲存服務、如何結構 API、實作哪種認證機制，以及如何驗證檔案。如果你決定從一種技術切換到另一種，例如從 Azure Blob 儲存體轉用 Azure 檔案儲存體，你會更新 plan.md，而 spec.md 大致保持不變。功能需求沒有改變;只有實施方式有所改變。

檢視計畫結構與內容

完整的技術計畫包含多個關鍵部分，共同定義你的實施方法。

架構概觀

架構概述提供了元件如何互動的高層次視角。對於文件上傳功能，架構可能會描述：

「實作一個新的後端 API 端點 /api/documents/upload 來處理多階段檔案上傳。 React 前端包含一個新的 DocumentUpload 元件，包含檔案選擇器和進度指示器。當使用者選擇檔案時，前端會先驗證大小與類型，然後再上傳。後端會接收檔案，再次驗證，將它儲存在 Azure Blob 儲存，並將中繼資料記錄到 SQL 資料庫中。成功上傳後，前端會刷新文件清單以顯示新檔案。」

此摘要建立整體流程，且不深入程式碼層級細節。它確保每個人都了解主要組成部分及其互動方式。

技術堆疊與關鍵決策

該計畫明確記錄了技術選擇與理由。本節可避免未來對為什麼選擇特定軟體庫或服務產生的混淆。

技術決策範例：

後端：.NET 8 Web API 搭配 Azure.Storage.Blobs SDK v12 用於 blob 操作。
前端：React 18 搭配 Ant Design 的 Upload 元件以維持 UI 一致性。
認證：使用入口網站認證上下文中的現有 Microsoft Entra ID 令牌。
儲存：Azure Blob 儲存容器，名為 employee-documents。
資料庫：擴充現有 SQL 資料庫，加入文件元資料表（欄位：Id、UserId、FileName、BlobUrl、UploadDate、FileSize）。

每項決策都應同時符合規格要求與憲法原則。如果你的憲法規定「所有雲端資源都必須使用 Azure 服務」，該計畫會明確選擇 Azure Blob 儲存並引用這個原則。

實作順序

計畫列出實施步驟的順序。雖然不如後續產生的任務清單那麼細緻，但這個順序從設定到完成提供了合理的進展。

文件上傳功能的典型實作順序：

資料庫結構更新：建立具備適當索引與約束的文件元資料表。
後端 API 開發：實作 POST /api/documents/upload 端點，包含檔案驗證、blob 儲存整合及元資料持久化。
前端元件建立：建立文件上傳元件，包含檔案選擇、用戶端驗證及上傳進度顯示。
整合：將前端元件接線至後端 API，處理回應並更新文件清單。
安全強化：實作伺服器端檔案類型驗證、大小限制及認證檢查。
錯誤處理：新增完整的錯誤訊息以處理用戶端與伺服器端的故障。
測試：建立 API 方法的單元測試，以及上傳流程的整合測試。

此序列確保基礎元素（資料庫結構）在相依元件（寫入資料庫的 API）實作前已存在。每個步驟都在先前的工作基礎上建立，降低整合問題的可能性。

憲法驗證

計畫包含一個核查部分，明確核對提出的解決方案是否符合憲法。此驗證防止建築偏移，並確保與專案原則一致。

如果您的章程包含「所有資料儲存必須使用 Azure 服務」以及「API 必須同時驗證用戶端與伺服器的輸入」，計畫驗證部分會確認：

使用 Azure Blob 儲存體滿足 Azure 服務的需求。
「在 React 元件（客戶端）與 .NET API（伺服器）中實作驗證，符合防禦深度安全原則。」
「Microsoft Entra ID 認證要求是透過使用現有的入口認證上下文來達成。」

此驗證起到檢查點的作用。如果計畫提出違反憲法的內容，AI 通常會標記，或你在審查時注意到。在計畫階段處理憲法衝突，可以防止後續重做。

假設與未解問題

精心設計的計畫記錄假設與未解決的問題。這種透明度有助於您在實施前識別潛在問題。

假設範例：

「假設 Azure Blob 儲存體容器 'employee-documents' 存在且設定為私人存取。」
「假設現有的 SQL 資料庫有足夠的儲存空間來存放元資料。」
「假定在這次更新中，上傳檔案的病毒掃描不在範圍之內。」

開放式問題範例：

「管理員應該有權刪除其他使用者上傳的文件嗎？」
「我們需要所有文件存取嘗試都要做審計記錄嗎？」
「系統在文件上傳時應該發送電子郵件通知嗎？」

記錄這些假設與問題可防止範圍蔓延，並確保利害關係人在編碼開始前就做出重要決策。如果在實施過程中假設錯誤，你可以相應地更新計畫。

使用 /speckit.plan 產生計畫

GitHub Spec Kit 透過 /speckit.plan GitHub Copilot Chat 的指令產生計畫。此指令結合 spec.md 與 constitution.md 作為輸入，產生完整的技術設計。

在呼叫指令前，先考慮 AI 還需要哪些其他上下文。你現有的程式碼庫、技術偏好和基礎設施限制都會影響計畫。事先提供這些背景，能產生更準確且可行的結果。

在內部員工入口網站的檔案上傳功能中，你可以提供如下背景說明：

「現有入口網站使用 React 前端，後端則是 .NET 8 Web API。我們需要把上傳功能整合進這個堆疊裡。使用 Azure Blob 儲存體來維持檔案持久化。要求所有上傳操作都必須使用 Microsoft Entra ID 驗證。該入口網站已經有一個SQL資料庫可供儲存元資料。」

這樣的情境引導 AI 產生一個能無縫融入你現有架構的計畫，而不是提出一個與現有架構不符的綠地解決方案。

啟動規劃命令

在 Visual Studio Code 中開啟 GitHub Copilot Chat 並輸入 /speckit.plan。如果 AI 要求更多資訊，請提供你的架構背景。 GitHub Copilot 會處理規格、架構以及額外的上下文來產生 plan.md。

規劃階段可能會花點時間，AI 會考慮各種方法，將它們與你的架構比對，並將輸出組織成連貫的設計文件。

檢視並驗證計畫

制定計畫只是第一步。關鍵審查確保計畫準確、完整，且符合您的專案需求。

確認規範要求的覆蓋範圍

系統性地比較計畫與 spec.md。規範中的每個需求都應對應到計畫中的實作方法。

例如，若 spec.md 要求「對超過 50 MB 的檔案顯示錯誤訊息」，計畫應說明此驗證的地點與方式。若計畫中省略了這些驗證，則要麼計畫不完整，要麼規範需要澄清。

檢查是否符合技術標準

確保計畫中的技術選擇符合貴組織的標準與最佳實務。若團隊標準化特定函式庫或圖樣，計畫應反映這些偏好。

需要考慮的問題：

所提議的架構是否適合現有系統？
所選圖書館是否已獲准在您所在環境中使用？
技術選擇是否符合組織的安全與合規政策？
有沒有類似功能的既定模式應該遵循？

在 Azure 環境中的文件上傳功能，請確認 Azure Blob 儲存體是否為核准服務，認證方法是否符合企業身份標準（如使用 Microsoft Entra ID），且所提議的 SQL 架構是否遵循資料庫命名規則。

驗證憲法遵守

計畫應明確核實所提出的解決方案是否符合憲法要求。請仔細檢視此驗證部分，確保沒有違反任何原則。

如果你的憲法要求「所有秘密必須儲存在 Azure Key Vault 中」，而計畫建議將 Azure 儲存體連線字串存放在 appsettings.json，則會產生衝突。計畫應修訂，在執行時從金鑰保存庫取得連線字串。

規劃過程中發現的憲法違規很容易修正。在程式碼審查或生產部署期間發現的憲法違規，成本高昂且造成干擾。

反覆修改並精煉計畫

計劃通常在初步生成後需要進一步調整。不要期待第一次就完美無缺。使用 GitHub Copilot 的澄清功能來提升計畫品質。

解決歧義與缺口

如果計畫中有模糊的說法，例如「實施適當的錯誤處理」，請追問具體細節。可能會發生哪些錯誤？每個錯誤應該如何處理？應該記錄哪些錯誤資訊，哪些則應該顯示給使用者？

使用 GitHub Copilot Chat 詢問後續問題：「上傳端點應該處理哪些具體錯誤？」或「如果 Azure Blob 儲存體無法使用，應該怎麼辦？」AI 可以將模糊的部分擴展成具體規格。

驗證技術可行性

確認建議架構在你的限制條件下是否技術上可行。如果計畫建議透過 Web API 同步上傳 50 MB 檔案，且逾時 30 秒，那就存在問題。超過 50 MB 的檔案可能需要分段上傳或增加逾時時間。

請諮詢具備相關專業知識的團隊成員。若計畫建議更改資料庫結構，請與資料庫管理員進行審查。如果需要新的 Azure 資源，請與基礎架構工程師確認配置是否可行。

考慮非功能需求

確保計畫涵蓋規範中非功能性的需求：效能、安全性、可擴展性、可維護性、可及性。

上傳文件時，請確認計畫內容包括：

效能：上傳應該多快完成？最大同時上傳量是多少？
安全性：檔案如何掃描惡意軟體？出入是如何被控制的？稽核日誌存放在哪裡？
可擴展性：系統如何處理上傳量增加？什麼是儲存容量限制？
可維護性：員工離職後，上傳的檔案如何被清理？
無障礙：上傳介面是否符合網頁內容無障礙指引（WCAG）2.1 AA 標準？

如果計畫中省略了這些考量，請明確加入。如果在規劃中沒有被處理，非功能性需求常常成為事後才考慮的事項。

評估可行性與完整性

評估該計畫是否提供足夠的執行指引。過於模糊的計畫（如「實施檔案上傳」）並無幫助。過於規範化的計畫（「使用精確 47 行程式碼」）會過於限制。

適當的細節層級能提供明確的方向，同時不剝奪所有彈性。這個計畫應該回答以下問題：

哪些元件需要被創建或修改？
這些元件如何互動？
使用哪些技術和函式庫？
實施順序是什麼？
哪些驗證步驟能確保正確性？

如果你無法想像如何從計畫中實作這個功能，那就需要更多細節。如果計畫感覺像是在幫你寫程式碼，可能太詳細了。

識別缺失元素

找出計畫中的漏洞。常見遺漏包括：

錯誤處理：系統如何處理網路故障、儲存錯誤或資料庫問題？
效能考量：有沒有關於上傳速度、同時使用者或儲存空間限制的疑慮？
測試策略：需要撰寫哪些測試來驗證實作？
復原方式：如果部署造成問題，您要如何復原變更？

透過手動編輯 plan.md 或提供更多背景資訊並重新生成相關章節來彌補這些缺口。

使用精煉後的內容重新產生

如果初始計畫不符合需求，請提供更具體的內容並重新產生。例如，如果計畫建議使用新的資料庫，但你需要使用現有的，請說明：「使用現有的 EmployeePortal 資料庫。在這個資料庫中新增一個文件元資料表，而不是建立新的。」

重新生成計畫，並 /speckit.plan 納入這些更新的情境。 AI 會相應調整方法。

手動編輯計畫

因為 plan.md 是 Markdown 檔案，你可以直接編輯。如果 AI 建議的方法是 90% 正確但需要小幅調整，請編輯檔案，而不是全部重新生成。

例如，如果計畫提出了特定的 blob 容器名稱，但你的組織有命名慣例，就直接在 plan.md 更新容器名稱。

與團隊成員合作

在團隊環境中，分享 plan.md 以便檢視。資深開發者或架構師可以在實施前驗證架構決策。此同儕審查能發現自動檢查可能忽略的問題。

團隊審查也能建立共同的理解。當多位開發人員共同開發某項功能時，共同檢視計畫能確保大家都了解方法，並能發現與其他進行中的工作可能產生的衝突。

文件架構決策

圖則不僅要記錄你將建造什麼，還應該記錄你為何做出特定的建築選擇，幫助未來開發者理解決策脈絡。

考慮的紀錄替代方案

當你在多種可行方案間做選擇時，請記錄你考慮過的選項，以及為何選擇其中一種而非其他。

關於檔案儲存，你可以考慮三種方法：

Azure Blob 儲存：因成本效益、可擴展性及與現有 Azure 環境整合而被選中。
Azure 檔案儲存體：因大型檔案儲存成本較高及不必要的伺服器訊息區塊（SMB）協定開銷而被拒絕。
SQL 資料庫檔案串流：為避免增加資料庫大小與複雜度而被拒絕。

這些文件防止未來開發者質疑為何沒有採用更簡單的方法。判決的理由得以保存，而非隨時間流逝而消失。

記錄假設

計畫對現有系統、基礎設施及組織限制做出假設。請明確說明這些假設。

文件上傳的假設範例：

Azure Blob 儲存體容器 employee-documents 會在開發開始前由基礎架構團隊配置好。
現有的入口驗證提供經過驗證的 Microsoft Entra ID 憑證，可信賴用於使用者識別。
SQL 資料庫有足夠的容量容納另一個元資料表，且不需要擴充儲存空間。
網路基礎架構支援 50 MB 的 HTTP 上傳，無需代理或防火牆限制。

如果執行過程中有任何假設錯誤，你可以重新檢視計畫並相應調整。有文件記錄的假設使得影響分析在情勢變化時變得簡單明瞭。

未來演進計畫

考慮功能可能如何演進，並確保你的架構能容納可能的擴充功能。

文件上傳時，未來可能的要求包括：

支援 PDF 與 DOCX 以外的其他檔案格式。
實施員工間檔案共享。
新增文件版本管理。
啟用多個檔案的批量上傳。
整合病毒掃描

如果你的架構讓這些延伸變得困難，請考慮是否有必要調整最初的設計。您現在不實作未來功能，但會避免把自己逼進讓未來變更變得痛苦的死角。

計畫將成為你在整個實施過程中的參考。開發者應定期參考計畫，確保其程式碼與文件架構一致。

計畫最終確定後，請與相關利害關係人分享以供驗證：

產品經理：確認計畫符合所有規格要求。
安全團隊：確認安全控制符合組織標準。
基礎架構團隊：確保擬議的 Azure 資源能夠被配置與設定。
架構團隊：驗證是否符合組織架構原則。

此利害關係人審查能在實施開始前發現問題。如果資安團隊的回饋顯示提議的認證不夠，你就要在撰寫程式碼前更新計畫。

必要時更新計畫

計畫是動態的文件。當你在實施過程中發現某個方法無法如預期運作時，請更新計畫以反映新的做法。

如果你原本打算把上傳進度存到瀏覽器的 localStorage，但發現這在私密瀏覽模式下會造成問題，請更新計畫改用記憶體內狀態。記錄為何必須更改，以保存理由。

保持 plan.md 與實際執行同步。當計畫與法規分歧時，該計畫作為參考文件的價值將喪失。

這些安全措施是否符合組織的需求？
資料庫結構的設計是否遵循命名慣例？

如果計畫建議使用資料庫，但你現有的入口網站已經有資料庫，那很可能是過度大材小用。如果計畫提出的技術是你的團隊避免的，請記錄原因或調整計畫。

避免常見的規劃陷阱

在制定和檢視計畫時，請避免以下常見錯誤：

跳過規劃階段：直接從規格跳到規範卻沒有計畫，會增加架構錯誤的風險。規劃上投入的時間能帶來回報，避免重工。
未經審查就接受設計圖：AI 生成的計畫是起點，而非最終設計。務必批判性地檢視，並根據你的具體情境進行驗證。
過度限制執行：計畫應該是指引，而非規定每個細節。在實施過程中，留有空間讓開發者做出適當的戰術決策。
忽視憲法衝突：若計畫違反憲法原則，應立即處理衝突。如果原則需要修訂，則調整計畫以符合規定，或是更新章程。
忘記更新計畫：當實施時發現新資訊時，應更新 plan.md。陳舊的計畫會誤導未來的開發者，並降低你文件的價值。

總結

技術計畫將你的規格轉化為可執行的架構。使用 /speckit.plan，根據您的技術堆疊和基礎設施的適當背景制定計畫。仔細審查計畫，確保涵蓋所有規範要求，符合您的憲法，並提供足夠的實施指引。利用經過驗證的計畫來指導任務產生與執行。將 plan.md 視為一份隨著理解演進的活文件，並為整個開發生命週期提供寶貴的背景。

意見反應

此頁面對您有幫助嗎？