Spec Kit 的技術(shù)中樞：Plan 階段如何將需求轉(zhuǎn)化為 API 與架構(gòu)設(shè)計
I. 引言：從“做什么”到“怎么做”的過渡
在我們的 Spec Kit 系列博客中，我們已經(jīng)完成了兩項關(guān)鍵工作：
- 通過 Constitution，我們?yōu)轫椖苛⑾铝恕皯椃ā?，定義了技術(shù)棧、架構(gòu)風格和安全約束（如何做的邊界）。
- 通過 Specification (
spec.md)，我們?yōu)?AI 編寫了“精確化 PRD”，明確了用戶需求、業(yè)務(wù)目標和驗收標準（做什么）。
現(xiàn)在，我們手握清晰的業(yè)務(wù)需求和技術(shù)約束，終于進入了 Spec Kit 流程中至關(guān)重要的第二步：Plan（技術(shù)規(guī)劃）。
spec.md 告訴我們目標，但編碼前，AI 必須知道詳細的、基于項目架構(gòu)的實現(xiàn)路徑。Plan 階段的輸出文檔 plan.md，就是項目的技術(shù)設(shè)計文檔（TDD），它是連接產(chǎn)品需求和最終代碼實現(xiàn)的“技術(shù)中樞”。
II. Plan 階段的核心職能與價值
Plan 階段的本質(zhì)是：從抽象的用戶故事中提取技術(shù)契約和架構(gòu)模式。它要求我們站在架構(gòu)師的角度，回答：“在現(xiàn)有技術(shù)體系下，我們?nèi)绾胃咝А⒎€(wěn)定地實現(xiàn) Spec 中定義的每一個驗收標準？”
Plan 的三大輸入/輸出關(guān)系：
| 關(guān)系 | 描述 | 目的 |
|---|---|---|
| 輸入 Spec | 將 spec.md 中的用戶故事和驗收標準作為規(guī)劃的起點。 |
確保技術(shù)方案能百分之百滿足業(yè)務(wù)需求。 |
| 輸入 Constitution | 遵循項目設(shè)定的技術(shù)棧、命名規(guī)范和安全約束。 | 確保新代碼與項目既有架構(gòu)保持一致性。 |
| 輸出 Tasks | 產(chǎn)出詳細的 plan.md，直接指導 AI 將方案拆解為可執(zhí)行的代碼任務(wù)。 |
將高層設(shè)計轉(zhuǎn)化為可立即編碼的 Pull Request。 |
Plan 階段的價值：
一個高質(zhì)量的 plan.md 能夠確保技術(shù)方案在編碼開始前經(jīng)過充分的評審和確認，從而避免在實現(xiàn)過程中才發(fā)現(xiàn)架構(gòu)漏洞或與既有系統(tǒng)的沖突，極大降低了返工成本。Plan 階段賦予了 AI 程序員架構(gòu)師的視角。
III. plan.md 模板解析：TDD 的核心要素
plan.md 的結(jié)構(gòu)必須清晰且具有指導性。以下是 Plan 文檔必須包含的核心要素：
1. ?? 引用規(guī)格 (Reference Specification)
這是 Plan 文檔的溯源。必須明確指出本次技術(shù)方案依據(jù)的 spec.md 文件名和 ID。
2. ?? 技術(shù)上下文與約束 (Technical Context)
- 架構(gòu)模式： 明確本次開發(fā)將采用的架構(gòu)模式（例如：Flutter App 沿用 Bloc 進行狀態(tài)管理）。
-
依賴/庫選擇： 計劃引入的外部庫及其目的（例如：為了裁剪功能，計劃引入
image_cropper庫）。 - 現(xiàn)有組件復用： 明確哪些現(xiàn)有服務(wù)（如認證服務(wù)、API 客戶端）會被復用。
3. ?? 核心技術(shù)設(shè)計 (Core Technical Design)
這是 plan.md 最重要的部分，它定義了代碼的骨架。
A. 數(shù)據(jù)模型與狀態(tài)管理
-
數(shù)據(jù)模型 (Model): 定義需要創(chuàng)建或修改的實體屬性。例如，在用戶模型
User中新增字段profileImageUrl: String。 -
狀態(tài) (State): 規(guī)劃 App 中功能界面的狀態(tài)流。例如：
AvatarUploadState必須包含Initial、ImageSelected、Cropping、Uploading、Success、Error等狀態(tài)。
B. API 設(shè)計與接口契約
- 目的： 定義客戶端（App）和服務(wù)器端的交互契約。
-
上傳 API 接口：
-
端點 (Endpoint):
POST /api/v1/user/avatar - 請求體 (Request): Multipart/form-data，包含裁剪后的圖片文件。
-
響應(yīng)體 (Response):
200 OK+ JSON 格式的新頭像 URL。
-
端點 (Endpoint):
C. 模塊拆分與組件規(guī)劃
-
數(shù)據(jù)層 (Repository): 規(guī)劃
AvatarRepository類，負責處理網(wǎng)絡(luò)請求和文件上傳。 -
業(yè)務(wù)邏輯層 (Bloc/Service): 規(guī)劃
AvatarUploadBloc或AvatarService，負責處理狀態(tài)轉(zhuǎn)換、調(diào)用 Repository 并執(zhí)行業(yè)務(wù)邏輯（如文件校驗）。 -
UI 組件： 確定高層組件，如
AvatarCropperWidget和ProfileSettingsScreen的修改。
4. ?? 風險、限制與測試策略
- 風險 (Risks): 預(yù)測技術(shù)障礙，如跨平臺裁剪庫的兼容性問題。
- 技術(shù)限制 (Constraints): 明確的技術(shù)約束，如網(wǎng)絡(luò)請求超時時間、資源限制等。
-
測試策略 (Testing Strategy): 規(guī)劃單元測試應(yīng)覆蓋哪些關(guān)鍵邏輯（例如
AvatarUploadBloc的所有狀態(tài)轉(zhuǎn)換），以及集成測試的范圍。
IV. 實戰(zhàn)案例：需求到技術(shù)方案的轉(zhuǎn)化路徑
我們使用上一篇的“用戶頭像上傳”功能，演示 spec.md 中的需求是如何在 plan.md 中被轉(zhuǎn)化為具體技術(shù)方案的：
| Spec.md 中的需求 (What) | Plan.md 中的技術(shù)方案 (How) | 對應(yīng)技術(shù)設(shè)計章節(jié) |
|---|---|---|
| US-3： 必須支持 1:1 比例裁剪。 |
組件/依賴： 引入并配置 image_cropper 庫，強制設(shè)置裁剪選項為 aspectRatio: 1/1。 |
組件規(guī)劃 |
| US-4： 點擊保存，更新頭像。 |
API 接口： 定義 POST /api/v1/user/avatar 端點，要求使用 Multipart/form-data 格式。 |
API 設(shè)計 |
| AC-7： 在上傳過程中必須顯示加載指示器。 |
狀態(tài)管理： AvatarUploadBloc 必須在開始上傳時發(fā)出 Uploading 狀態(tài)，并在 UI 層進行監(jiān)聽。 |
數(shù)據(jù)模型與狀態(tài)流 |
| AC-5/6： 限制文件大?。?lt; 5MB）和格式。 | 客戶端校驗： 在文件選擇后，上傳前，使用 Dart 代碼執(zhí)行本地文件大小和 MimeType 校驗。 | 技術(shù)上下文 |
通過這種轉(zhuǎn)化，原本面向用戶的需求（如“用戶希望能夠拖動和縮放”）被分解成了 AI 可執(zhí)行的技術(shù)指令（“配置裁剪庫的拖動和縮放屬性”）。
V. 總結(jié)：Plan——將 AI 從文員變成工程師
plan.md 是 Spec-Driven Development 流程中不可或缺的中間件。它成功地橋接了產(chǎn)品的價值和代碼的實現(xiàn)，使得整個開發(fā)流程不再是瀑布式的猜測，而是清晰、可回溯的。
一個高質(zhì)量的 plan.md 能夠最大化 AI 的效率和代碼的規(guī)范性。它不僅告訴 AI 寫什么代碼，更告訴 AI 代碼應(yīng)該如何組織和交互。
現(xiàn)在，AI 已經(jīng)掌握了所有的先決條件。在下一階段，它將把這個詳細的 plan.md 轉(zhuǎn)化為一個個可執(zhí)行的代碼任務(wù)。
在接下來的系列文章中，我將會探索 AI 如何基于這兩份文件，進入 Plan (技術(shù)規(guī)劃) 階段，真正將需求轉(zhuǎn)化為可執(zhí)行的代碼架構(gòu)。
下一篇預(yù)告： 敬請期待《Spec Kit 的終極輸出：Tasks 階段如何將 plan.md 轉(zhuǎn)化為可合并的 Pull Requests》。
本文由mdnice多平臺發(fā)布
