创建详细的技术计划

  • 12 分钟

规范定义需要生成的内容。 技术计划定义如何构建它。 本单元介绍企业棕色地带方案的高级规划技术。

审查计划基本原理

plan.md 文件充当设计文档，弥合 spec.md 中高级要求与后续具体实现任务之间的差距。 全面的技术计划包含：

  • 体系结构概述：组件交互方式的高级视图。
  • 技术堆栈和关键决策：具有合理性的技术选择的明确文档。
  • 实现序列：实现步骤的逻辑进度。
  • 宪法核查：明确检查建议的解决方案是否符合项目原则。
  • 假设和公开问题：假设和未解决的问题文档。

考虑到这些基础知识，让我们探讨企业开发的高级规划注意事项。

关注点分离 - 规格与计划

规范和技术计划之间的关注点分离至关重要。 虽然规范保持稳定，并专注于“什么”，但随着你尝试不同的“方法”时，该计划可以不断发展。

假设你的规范需要内部员工门户的文档上传功能。 规范定义了用户要求：文件大小限制、支持的格式、上传反馈和访问控制。 技术计划将这些要求转化为具体的体系结构决策：要使用的 Azure 存储服务、如何构建 API、要实现的身份验证机制以及如何验证文件。 如果决定从一种技术切换到另一种技术（例如从 Azure Blob 存储迁移到 Azure 文件存储），则更新 plan.md，而 spec.md 保持不变。 功能要求不会更改;仅更改实现方法。

检查计划结构和内容

全面的技术计划包含几个关键部分，这些部分共同定义了实现方法。

体系结构概述

体系结构概述提供了组件交互方式的高级视图。 对于文档上传功能，体系结构可能描述：

“实现新的后端 API 终结点 /api/documents/upload 来处理多部分文件上传。 React 前端包含一个新的 DocumentUpload 组件，其中包含文件选取器和进度指示器。 当用户选择文件时，前端会在上传之前验证大小和类型。 后端接收文件，再次验证，将其存储在 Azure Blob 存储中，并在 SQL 数据库中记录元数据。 成功上传后，前端会刷新文档列表以显示新文件。

此摘要可建立整体流，而无需深入了解代码级详细信息。 它可确保每个人都了解主要组件及其交互。

技术堆栈和关键决策

该计划明确记录了技术选择和理由。 本部分可防止将来对选择特定库或服务的原因产生混淆。

示例技术决策：

  • 后端：使用 Azure.Storage.Blobs SDK v12 进行 Blob 操作的 .NET 8 Web API。
  • 前端：使用 Ant Design 的上传组件 React 18 实现 UI 一致性。
  • 身份验证：使用门户身份验证上下文中的现有Microsoft Entra ID 令牌。
  • 存储：名为 employee-documentsAzure Blob 存储容器。
  • 数据库：使用 DocumentMetadata 表扩展现有 SQL 数据库（列：Id、UserId、FileName、BlobUrl、UploadDate、FileSize）。

每个决定都应符合规范要求和宪法原则。 如果宪法规定“对所有云资源使用 Azure 服务”，该计划将显式选择 Azure Blob 存储并引用此原则。

实现序列

该计划概述了实施步骤的顺序。 虽然与稍后生成的任务列表不一样精细，但此序列提供从设置到完成的逻辑进度。

文档上传功能的典型实现序列：

  1. 数据库架构更新：使用适当的索引和约束创建 DocumentMetadata 表。
  2. 后端 API 开发：使用文件验证、Blob 存储集成和元数据持久性实现 POST /api/documents/upload 终结点。
  3. 前端组件创建：使用文件选择、客户端验证和上传进度显示生成 DocumentUpload 组件。
  4. 集成：将前端组件连接到后端 API，处理响应并更新文档列表。
  5. 安全强化：实现服务器端文件类型验证、大小限制和身份验证检查。
  6. 错误处理：为客户端和服务器端故障添加全面的错误消息。
  7. 测试：为 API 方法创建单元测试，为上传流程创建集成测试。

此序列可确保在实现依赖组件（写入数据库的 API）之前存在基础元素（数据库架构）。 每个步骤都基于以前的工作，从而减少集成问题的可能性。

宪法验证

该计划包括一个核查部分，该部分明确检查了针对宪法的建议解决方案。 此验证可防止体系结构偏差，并确保与项目原则保持一致。

如果宪法包括“所有数据存储都必须使用 Azure 服务”和“API 必须验证客户端和服务器上的输入”，计划验证部分将确认：

  • “使用 Azure Blob 存储满足 Azure 服务要求。
  • “在 React 组件（客户端）和 .NET API（服务器）中实现验证符合深层防御安全原则。
  • 满足 Microsoft Entra ID 身份验证要求是通过现有的门户身份验证上下文实现的。

此验证充当检查点。 如果该计划提出违反宪法的内容，AI 通常会标记它，或在审查期间注意到。 在计划阶段解决宪法冲突可以防止以后的返工。

假设和公开问题

构造良好的计划记录假设和未解决的问题。 这种透明度有助于在实现开始之前识别潜在问题。

示例假设：

  • 假设名为“employee-documents”的 Azure Blob 存储容器存在，并已配置为专用访问。
  • “假设现有 SQL 数据库有足够的存储容量用于元数据。
  • 假设已上传文件的病毒扫描不在此迭代的范围之内。

示例开放性问题：

  • “管理员是否能够删除其他用户上传的文档？”
  • “是否需要对所有文档访问尝试进行审核日志记录？”
  • “系统是否应在上传文档时发送电子邮件通知？”

记录这些假设和问题可防止范围爬行，并确保利益干系人在编码开始之前处理重要决策。 如果假设在实现过程中证明不正确，则可以相应地更新计划。

使用 /speckit.plan 生成计划

GitHub Spec Kit 通过 GitHub Copilot 对话助手 中的 /speckit.plan 命令生成计划。 此命令使用 spec.md 和 constitution.md 作为输入来生成全面的技术设计。

在调用命令之前，请考虑 AI 需要的其他上下文。 现有的代码库、技术首选项和基础结构约束都会影响计划。 提前提供此上下文会产生更准确且可作的结果。

对于内部员工门户方案中的文档上传功能，可以提供如下所示的上下文：

“现有门户使用具有 .NET 8 Web API 后端的 React 前端。 我们需要将上传功能集成到此堆栈中。 使用 Azure Blob 存储进行文件暂留。 要求对所有上传作Microsoft Entra ID 身份验证。 门户已有可用于元数据存储的 SQL 数据库。

此上下文指导 AI 生成适合现有体系结构的计划，而不是提出与当前堆栈不一致的绿地解决方案。

调用规划命令

在 Visual Studio Code 中打开 GitHub Copilot 对话助手 并输入 /speckit.plan。 如果 AI 请求更多信息，请提供体系结构上下文。 GitHub Copilot 处理规范、结构和额外上下文以生成 plan.md。

规划阶段可能需要一段时间，因为 AI 会考虑各种方法，根据宪法检查它们，并将输出构建成一个连贯的设计文档。

查看并验证计划

生成计划只是第一步。 关键评审可确保计划准确、完整且符合项目需求。

验证规范要求的覆盖范围

系统地将计划与 spec.md 进行比较。 规范中的每个要求都应映射到计划中的实施方法。

例如，如果 spec.md 需要“显示超过 50 MB 的文件的错误消息”，计划应描述此验证的发生位置和方式。 如果计划省略此验证，则计划不完整或规范需要澄清。

检查与技术标准的一致性

确保计划的技术选择与组织的标准和最佳做法保持一致。 如果团队针对特定库或模式进行标准化，计划应反映这些首选项。

要考虑的问题：

  • 建议的体系结构是否适合现有系统？
  • 所选库是否获准在环境中使用？
  • 技术选择是否符合组织安全性和合规性策略？
  • 是否有应遵循的类似功能的已建立模式？

对于 Azure 环境中的文档上传功能，请验证 Azure Blob 存储是否为已批准的服务，身份验证方法是否符合企业标识标准（例如使用 Microsoft Entra ID），并且建议的 SQL 架构遵循数据库命名约定。

验证宪法符合性

该计划应包括明确验证建议的解决方案符合宪法要求。 仔细查看此验证部分，以确保不违反任何原则。

如果宪法要求“所有机密都必须存储在 Azure 密钥保管库 中”，并且计划建议将 Azure 存储连接字符串存储在 appsettings.json中，则存在冲突。 应修改计划，以在运行时从 密钥保管库 检索连接字符串。

在规划期间发现的违反宪法很容易解决。 代码评审或生产部署期间发现的违反宪法的行为成本高昂且具有破坏性。

迭代和完善计划

计划通常需要在初始生成后进行优化。 第一次尝试时不要期待完美。 使用 GitHub Copilot 的澄清功能提高计划质量。

解决歧义和差距问题

如果计划包含诸如“实现适当的错误处理”这样的模糊语句，请对具体内容进行详述。 可能会出现哪些错误？ 应如何处理每个错误？ 应记录哪些错误信息而不是向用户显示？

使用 GitHub Copilot 聊天询问后续问题：“上传终结点应该处理哪些特定错误？”或“如果 Azure Blob 存储不可用，会发生什么情况？”AI 可以将模糊部分扩展到具体规范中。

验证技术可行性

根据约束，验证建议的体系结构在技术上是否可行。 如果计划建议通过具有 30 秒超时的 Web API 同步上传 50 MB 文件，则存在问题。 超过 50 MB 的文件可能需要分块上传或增加超时。

咨询具有相关专业知识的团队成员。 如果计划建议数据库架构更改，请与数据库管理员一起查看。 如果需要新的 Azure 资源，请使用基础结构工程师验证预配是否可行。

考虑非功能要求

确保计划满足规范中的非功能要求：性能、安全性、可伸缩性、可维护性、可访问性。

对于文档上传，请确认计划包括：

  • 性能：上传完成的速度有多快？ 最大并发上传量是多少？
  • 安全性：如何扫描文件以查找恶意软件？ 访问如何被控制？ 审核日志存储在何处？
  • 可伸缩性：系统如何处理增加的上传量？ 什么是存储容量限制？
  • 可维护性：员工离开组织时如何清理上传的文件？
  • 辅助功能：上传用户界面是否符合 Web 内容辅助功能准则 （WCAG） 2.1 AA 标准？

如果计划省略上述任何注意事项，请显式添加它们。 如果未在规划中解决，非功能要求常常在实施时才被考虑，成为事后想法。

评估可行性和完整性

评估计划是否为实施提供足够的指导。 过于模糊（“实现文件上传”）的计划没有帮助。 过于规范（“完全使用 47 行代码”）的计划过于约束。

正确的详细信息级别提供了明确的方向，而无需消除所有灵活性。 计划应回答：

  • 需要创建或修改哪些组件？
  • 这些组件如何交互？
  • 使用哪些技术和库？
  • 实现顺序是什么？
  • 哪些验证步骤可确保正确性？

如果无法设想如何从计划中实现该功能，则需要更多详细信息。 如果计划感觉它正在为你编写代码，则它可能过于详细。

标识缺少的元素

寻找计划中的差距。 常见遗漏包括：

  • 错误处理：系统如何处理网络故障、存储错误或数据库问题？
  • 性能注意事项：上传速度、并发用户或存储限制是否有任何问题？
  • 测试策略：需要编写哪些测试来验证实现？
  • 回滚方法：如果部署导致问题，如何还原更改？

通过手动编辑 plan.md 或提供更多上下文并重新生成相关部分来解决这些差距。

利用优化过的上下文重新生成

如果初始计划未达到目标，您可以提供更具体的上下文信息，然后重新生成。 例如，如果计划建议使用新数据库，但你需要使用现有数据库，请澄清：“使用现有的 EmployeePortal 数据库。 将 DocumentMetadata 表添加到此数据库，而不是创建新表。

重新生成包含 /speckit.plan 此更新上下文的计划。 AI 相应地调整方法。

手动编辑计划

由于 plan.md 是 Markdown 文件，因此可以直接对其进行编辑。 如果 AI 建议采用 90% 正确但需要细微调整的方法，请编辑文件，而不是重新生成所有内容。

例如，如果计划建议特定的 Blob 容器名称，但组织具有命名约定，请直接更新 plan.md 中的容器名称。

与团队成员协作

在团队环境中，共享 plan.md 以供审阅。 高级开发人员或架构师可以在实施开始之前验证体系结构决策。 此对等评审可捕获自动检查可能错过的问题。

团队评审还构建了共享理解。 当多个开发人员处理某个功能时，一起查看计划可确保每个人都知道这种方法，并可以识别与其他正在进行的工作的潜在冲突。

文档体系结构决策

计划不仅应该记录要生成的内容，还应该记录为什么你做出了特定的体系结构选择，以帮助未来的开发人员了解决策上下文。

记录已考虑的替代方案

在多种可行方法之间进行选择时，请记录你考虑的替代方法，以及为什么你选择了一种替代方法。

对于文件存储，可以考虑以下三种方法：

  • Azure Blob 存储：选择此项是为了获得成本效益、可伸缩性和与现有 Azure 环境的集成。
  • Azure 文件：由于大型文件存储和不必要的服务器消息块（SMB）协议开销较高，因此被拒绝。
  • SQL 数据库 FILESTREAM：拒绝以避免增加数据库大小和复杂性。

本文档可防止未来的开发人员质疑为何未使用更简单的方法。 决定的理由得以保存，而不是随着时间被遗忘。

记录假设

计划对现有系统、基础结构和组织约束做出假设。 明确这些假设。

文档上传的示例假设：

  • 在开始开发之前，基础结构团队会预配 Azure Blob 存储容器 employee-documents 。
  • 当前的门户身份验证提供经过验证的 Microsoft Entra ID 令牌，这些令牌可用于可信用户标识。
  • SQL 数据库有足够的容量用于另一个元数据表，而无需存储扩展。
  • 网络基础结构支持 50 MB 的 HTTP 上传，且不受代理或防火墙限制。

如果任何假设在实施过程中证明不正确，则可以重新访问计划并相应地进行调整。 记录的假设使影响分析变得简单明了，当情况发生更改时。

规划未来演变

考虑该功能的发展方式，并确保体系结构能够适应可能扩展。

对于文档上传，潜在的未来要求可能包括：

  • 支持 PDF 和 DOCX 以外的其他文件类型。
  • 实现员工之间的文件共享。
  • 添加文档版本控制。
  • 启用批量上传多个文件的功能。
  • 集成病毒扫描

如果体系结构使这些扩展变得困难，请考虑是否需要调整初始设计。 可以现在不实现未来的功能，但要避免自我设限，以免将来的调整变得困难。

在实施过程中共享和维护计划

该计划会在整个实现过程中成为参考。 开发人员应定期咨询计划，以确保其代码与记录的体系结构保持一致。

与利益干系人共享计划

完成计划后，请与相关利益干系人共享，进行验证：

  • 产品经理：验证计划是否满足所有规范要求。
  • 安全团队：确认安全控制符合组织标准。
  • 基础结构团队：确保可以预配和配置建议的 Azure 资源。
  • 体系结构团队：验证符合组织体系结构原则。

此利益干系人评审在实施开始之前会捕获问题。 如果安全团队反馈显示建议的身份验证不足，在编写代码之前更新计划。

根据需要更新计划

计划是活生生的文档。 在实现过程中发现某个方法无法按预期工作时，请更新计划以反映新方法。

如果计划在浏览器 localStorage 中存储上传进度，但发现这会导致在专用浏览模式下出现问题，请更新计划以改用内存中状态。 记录更改所需的原因，以便保留推理。

使 plan.md 与实际实现保持同步。 当计划和代码发生分歧时，该计划将失去作为参考文档的值。

  • 安全方法是否满足组织要求？
  • 数据库架构设计是否遵循命名约定？

如果计划建议使用数据库，但您的现有门户已经有一个数据库，这可能是多此一举。 如果计划建议团队避免的技术，请记录或调整计划的原因。

要避免的常见规划陷阱

创建和审查计划时避免以下常见错误：

  • 跳过规划阶段：直接从规范跳转到代码，而无需计划会增加体系结构错误的风险。 投入于计划的时间通过防止返工而带来回报。

  • 接受未经审查的计划：AI 生成的计划是起点，而不是最终设计。 请始终认真审查并针对特定上下文进行验证。

  • 过度约束实现：计划应起指导作用，而不是规定每个细节。 让开发人员在实现过程中做出适当的战术决策留出空间。

  • 忽视宪法冲突：如果该计划违反宪法原则，请立即解决冲突。 如果原则需要修订，请调整计划，以遵守或更新宪法。

  • 忘记更新计划：当在实施过程中发现新信息时，更新计划文件 plan.md。 陈旧的计划误导未来的开发人员并降低了文档的价值。

概要

技术计划将规范转换为可作的体系结构。 使用 /speckit.plan 并结合技术堆栈和基础结构的适当上下文生成计划。 关键地审查计划，以确保它们涵盖所有规范要求，符合宪法，并提供足够的实施指导。 使用验证的计划来指导任务生成和实现。 将 plan.md 视为随理解而演变的活文档，并为整个开发生命周期提供有价值的上下文。