Spec Kit 的技术中枢：Plan 阶段如何将需求转化为 API 与架构设计
I. 引言：从“做什么”到“怎么做”的过渡
在我们的 Spec Kit 系列博客中，我们已经完成了两项关键工作：
- 通过 Constitution，我们为项目立下了“宪法”，定义了技术栈、架构风格和安全约束（如何做的边界）。
- 通过 Specification (
spec.md)，我们为 AI 编写了“精确化 PRD”，明确了用户需求、业务目标和验收标准（做什么）。
现在，我们手握清晰的业务需求和技术约束，终于进入了 Spec Kit 流程中至关重要的第二步：Plan（技术规划）。
spec.md 告诉我们目标，但编码前，AI 必须知道详细的、基于项目架构的实现路径。Plan 阶段的输出文档 plan.md，就是项目的技术设计文档（TDD），它是连接产品需求和最终代码实现的“技术中枢”。
II. Plan 阶段的核心职能与价值
Plan 阶段的本质是：从抽象的用户故事中提取技术契约和架构模式。它要求我们站在架构师的角度，回答：“在现有技术体系下，我们如何高效、稳定地实现 Spec 中定义的每一个验收标准？”
Plan 的三大输入/输出关系：
| 关系 | 描述 | 目的 |
|---|---|---|
| 输入 Spec | 将 spec.md 中的用户故事和验收标准作为规划的起点。 |
确保技术方案能百分之百满足业务需求。 |
| 输入 Constitution | 遵循项目设定的技术栈、命名规范和安全约束。 | 确保新代码与项目既有架构保持一致性。 |
| 输出 Tasks | 产出详细的 plan.md，直接指导 AI 将方案拆解为可执行的代码任务。 |
将高层设计转化为可立即编码的 Pull Request。 |
Plan 阶段的价值：
一个高质量的 plan.md 能够确保技术方案在编码开始前经过充分的评审和确认，从而避免在实现过程中才发现架构漏洞或与既有系统的冲突，极大降低了返工成本。Plan 阶段赋予了 AI 程序员架构师的视角。
III. plan.md 模板解析：TDD 的核心要素
plan.md 的结构必须清晰且具有指导性。以下是 Plan 文档必须包含的核心要素：
1. 🔗 引用规格 (Reference Specification)
这是 Plan 文档的溯源。必须明确指出本次技术方案依据的 spec.md 文件名和 ID。
2. ⚙️ 技术上下文与约束 (Technical Context)
- 架构模式： 明确本次开发将采用的架构模式（例如：Flutter App 沿用 Bloc 进行状态管理）。
-
依赖/库选择： 计划引入的外部库及其目的（例如：为了裁剪功能，计划引入
image_cropper库）。 - 现有组件复用： 明确哪些现有服务（如认证服务、API 客户端）会被复用。
3. 🧱 核心技术设计 (Core Technical Design)
这是 plan.md 最重要的部分，它定义了代码的骨架。
A. 数据模型与状态管理
-
数据模型 (Model): 定义需要创建或修改的实体属性。例如，在用户模型
User中新增字段profileImageUrl: String。 -
状态 (State): 规划 App 中功能界面的状态流。例如：
AvatarUploadState必须包含Initial、ImageSelected、Cropping、Uploading、Success、Error等状态。
B. API 设计与接口契约
- 目的： 定义客户端（App）和服务器端的交互契约。
-
上传 API 接口：
-
端点 (Endpoint):
POST /api/v1/user/avatar - 请求体 (Request): Multipart/form-data，包含裁剪后的图片文件。
-
响应体 (Response):
200 OK+ JSON 格式的新头像 URL。
-
端点 (Endpoint):
C. 模块拆分与组件规划
-
数据层 (Repository): 规划
AvatarRepository类，负责处理网络请求和文件上传。 -
业务逻辑层 (Bloc/Service): 规划
AvatarUploadBloc或AvatarService，负责处理状态转换、调用 Repository 并执行业务逻辑（如文件校验）。 -
UI 组件： 确定高层组件，如
AvatarCropperWidget和ProfileSettingsScreen的修改。
4. ⚠️ 风险、限制与测试策略
- 风险 (Risks): 预测技术障碍，如跨平台裁剪库的兼容性问题。
- 技术限制 (Constraints): 明确的技术约束，如网络请求超时时间、资源限制等。
-
测试策略 (Testing Strategy): 规划单元测试应覆盖哪些关键逻辑（例如
AvatarUploadBloc的所有状态转换），以及集成测试的范围。
IV. 实战案例：需求到技术方案的转化路径
我们使用上一篇的“用户头像上传”功能，演示 spec.md 中的需求是如何在 plan.md 中被转化为具体技术方案的：
| Spec.md 中的需求 (What) | Plan.md 中的技术方案 (How) | 对应技术设计章节 |
|---|---|---|
| US-3： 必须支持 1:1 比例裁剪。 |
组件/依赖： 引入并配置 image_cropper 库，强制设置裁剪选项为 aspectRatio: 1/1。 |
组件规划 |
| US-4： 点击保存，更新头像。 |
API 接口： 定义 POST /api/v1/user/avatar 端点，要求使用 Multipart/form-data 格式。 |
API 设计 |
| AC-7： 在上传过程中必须显示加载指示器。 |
状态管理： AvatarUploadBloc 必须在开始上传时发出 Uploading 状态，并在 UI 层进行监听。 |
数据模型与状态流 |
| AC-5/6： 限制文件大小（< 5MB）和格式。 | 客户端校验： 在文件选择后，上传前，使用 Dart 代码执行本地文件大小和 MimeType 校验。 | 技术上下文 |
通过这种转化，原本面向用户的需求（如“用户希望能够拖动和缩放”）被分解成了 AI 可执行的技术指令（“配置裁剪库的拖动和缩放属性”）。
V. 总结：Plan——将 AI 从文员变成工程师
plan.md 是 Spec-Driven Development 流程中不可或缺的中间件。它成功地桥接了产品的价值和代码的实现，使得整个开发流程不再是瀑布式的猜测，而是清晰、可回溯的。
一个高质量的 plan.md 能够最大化 AI 的效率和代码的规范性。它不仅告诉 AI 写什么代码，更告诉 AI 代码应该如何组织和交互。
现在，AI 已经掌握了所有的先决条件。在下一阶段，它将把这个详细的 plan.md 转化为一个个可执行的代码任务。
在接下来的系列文章中，我将会探索 AI 如何基于这两份文件，进入 Plan (技术规划) 阶段，真正将需求转化为可执行的代码架构。
下一篇预告： 敬请期待《Spec Kit 的终极输出：Tasks 阶段如何将 plan.md 转化为可合并的 Pull Requests》。
本文由mdnice多平台发布
