生成任务并实现代码

  • 10 分钟

技术计划提供体系结构方向，但实施需要具体可行的步骤。 本单元介绍适用于企业方案的高级任务生成和管理技术。

查看任务基本原理

GitHub Spec Kit 的 /speckit.tasks 命令将高级体系结构决策转换为 tasks.md 文件中的特定工作项。 每个任务都表示可以独立实现、测试和验证的离散工作单元。

范围良好的任务的主要特征：

  • 可执行的：明确说明需要执行的任务。
  • 可测试：完成验证非常简单。
  • 独立：无需等待无关的工作即可完成。
  • 时间限制：可以在合理的时间范围内完成（一天到几小时）。

基于阶段的组织

复杂的功能受益于将任务按照阶段组织。 例如：设置、基础、核心功能、UI/集成、安全性和测试。 每个阶段都表示一个逻辑分组，为实现里程碑目标而进行构建。

任务细分的优点

除了组织工作之外，任务细分还具有多种用途。 它们可帮助 AI 为特定目标生成重点代码，而不是尝试在单个作中实现整个功能。 它们创建自然验证点，你可以在其中测试部分实现，然后再继续作。 它们通过准确显示完成项和剩余项，支持精确的进度跟踪。 它们通过明确依赖项来促进团队协调。

对于文档上传功能，该计划描述了总体体系结构和技术选择。 任务列表将体系结构决策转换为特定作：创建数据库表、实现 API 终结点、生成 React 组件、添加验证逻辑、写入测试。 每个任务都足够小，可以在合理的时间范围内完成，而足够大，足以表示有意义的进度。

检查任务结构和组织

结构良好的任务列表以逻辑方式组织工作，对依赖项进行适当的排序，并为实现提供明确的指导。

基于阶段的组织

复杂功能受益于基于阶段的组织。 每个阶段表示围绕特定里程碑的相关任务的逻辑分组。

对于文档上传功能，典型的阶段结构可能包括：

  • 阶段 1：基础和配置

    • 在 appsettings.json中设置 Azure Blob 存储连接配置。
    • 在具有适当架构的 SQL 数据库中创建 DocumentMetadata 表。
    • 将 Azure.Storage.Blobs NuGet 包添加到后端项目。
    • 创建封装存储操作的 DocumentService 类。

  • 阶段 2：核心上传功能

    • 在 DocumentsController 中实现 POST /api/documents/upload 终结点。
    • 将文件验证逻辑（大小、类型）添加到 DocumentService。
    • 实现具有错误处理的 Blob 存储上传方法。
    • 成功上传后，将文档元数据保存到数据库。
    • 将包含文档 ID 和 URL 的上传结果返回给客户端。

  • 阶段 3：前端实现

    • 使用文件输入创建 DocumentUpload React 组件。
    • 在组件中添加文件大小和类型验证。
    • 实现上传进度指示器。
    • 处理上传成功和错误响应。
    • 成功上传后刷新文档列表。

  • 阶段 4：安全性和验证

    • 将 Microsoft Entra ID 的身份验证检查添加到上传端点。
    • 使用 magic 数字实现服务器端文件类型验证。
    • 添加阻止 DoS 攻击的请求大小限制。
    • 根据允许的列表验证文件扩展名。
    • 添加上传操作的审核日志记录。

  • 阶段 5：测试和文档

    • 编写 DocumentService 上传方法的单元测试。
    • 为完整的上传流创建集成测试。
    • 添加错误场景测试（文件类型无效，大小超限）。
    • OpenAPI/Swagger 中的文档 API 端点。
    • 对用户文档进行更新，以包含上传说明。

此分阶段方法可创建自然里程碑。 阶段 2 后，你拥有一个可用但非常基础的后端系统。 阶段 3 后，用户可以上传文件。 阶段 4 后，系统已安全且生产就绪。 第 5 阶段后，将测试并记录所有内容。

任务粒度和范围

每个任务都应适当地确定范围-具体到足以提供明确的方向，但不太详细，使其成为规范性微管理。

范围明确的任务具有以下特征：

  • 可执行的：任务明确说明需要执行的内容。
  • 可测试：可以验证任务何时完成。
  • 尽可能独立：任务可以完成，而无需等待无关的工作。
  • 时间限制：开发人员可以在合理的时间范围内完成任务（通常为一天到一天，而不是几周）。

范围良好的任务示例：“实现接受多部分文件上传的 POST /api/documents/upload 终结点，验证文件大小是否低于 50 MB，将文件存储在 Azure Blob 存储中，并返回 Blob URL 和文档 ID。

此任务明确指定要构建的内容（终结点）、接受的内容（多部分文件）、需要应用的验证（大小限制）、文件的存储位置（Azure Blob 存储），以及返回的内容（URL 和 ID）。 开发人员确切地知道要实现什么。

下面是范围不足的任务示例：“让上传功能正常运行”。本示例没有提供关于“正常运行”具体含义或涉及哪些组件的指导。

下面是一个过于规定化的任务示例：“在 DocumentsController.cs 的第 47 行，添加一个名为 UploadDocument 的方法，其参数为（IFormFile 文件, string userId），并严格按照这些步骤实现它...” 这种任务描述剥夺了开发人员的自主性，并且没有考虑到代码结构的变化。

任务依赖项和排序

任务顺序很重要。 某些任务必须先完成，然后才能开始。

数据库架构更改通常优先，因为后端代码依赖于架构存在。 后端 API 终结点位于调用这些终结点的前端组件之前。 配置设置位于使用该配置的代码之前。 测试是在测试代码存在之后执行的。

任务列表应对工作进行排序，以最大程度地减少阻止。 如果前端和后端任务是独立的，则可以并行执行。 如果存在多个后端终结点，开发人员可以同时实现这些任务。

对于文档上传功能，逻辑序列可确保：

  1. 首先进行配置和数据库设置（无依赖项）。
  2. 后端 API 实现遵循数据库设置（取决于架构）。
  3. 前端组件遵循 API 实现（依赖于现有终结点）。
  4. 安全强化是在核心功能（取决于现有代码）完成之后进行的。
  5. 测试在所有实现后发生（取决于已完成的代码）。

此任务序列允许持续进度，而无需等待无关的工作完成。

使用 /speckit.tasks 生成任务

GitHub Spec Kit 通过 GitHub Copilot 对话助手 中的 /speckit.tasks 命令生成任务列表。 此命令处理 spec.md 和 plan.md，以生成全面的有序实现任务列表。

AI 分析规范以了解需要生成的内容、查看了解体系结构方法的计划，并生成弥合这些文档与实际代码之间的差距的任务。 生成的 tasks.md 文件包含编号或项目符号形式的任务，通常按照复杂功能的阶段进行组织。

调用任务生成命令

在 Visual Studio Code 中打开 GitHub Copilot 对话助手 并输入 /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。 任务列表应反映现实情况，而不是过时的计划。

在团队成员之间分配任务

清晰的任务定义使得可以将工作分配给多个开发人员。 后端团队可以在前端团队生成 UI 组件时处理 API 任务。 数据库管理员可以在开发人员准备配置时设置架构。

显式调用任务依赖项有助于防止阻止。 如果任务 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 可能会在测试任务的实现时发现 bug。 提供详细信息以帮助诊断问题。 如果 AI 遇到歧义，还可以提供额外的上下文或说明。

当在聊天视图中出现帮助提示时，快速响应有助于保持实现顺利进行。

验证检查点

完成实现命令后，请先验证结果，然后再继续。 运行应用程序，执行测试，并确认每个任务都已实现并实现其目标。 此增量验证在最容易修复时会提前捕获问题。

跨任务的上下文维护

完成任务时，以前完成的工作为后续任务提供上下文。 AI 可以在生成相关功能、提高代码质量和维护体系结构一致性时引用早期实现。

管理实现任务时会出现常见的难题。

范围不断扩大的任务

当任务在实现期间显示意外的复杂性时，暂停和重新评估。 将膨胀的任务分解为多个较小的任务。 更新 tasks.md 以反映真实范围。 将范围扩展传达给利益干系人。

受阻任务

有时，外部依赖项会阻止任务。 在 tasks.md 文件中使用阻止原因显式标记被阻止的任务：“已阻止：正在等待 Azure Blob 存储容器预配 - 票证 #1234”。要单独跟踪被阻止的任务，确保它们不会被遗忘。

更改优先级

业务需求不断发展。 当优先级发生更改时，请相应地更新 tasks.md。 以反映新优先级的方式对任务重新排序。 为新兴要求添加新任务。 请考虑延迟或删除不再有价值的任务。

实现过程中发现的任务不明确性

当出现歧义时，请暂停执行并寻求澄清。 查阅规范和计划，以更好地理解初衷。 在继续作之前，请使用特定的明确语言更新任务说明。

概要

任务生成将体系结构计划转换为可作的实现步骤。 使用 /speckit.tasks 生成任务清单，以创建结构化的阶段性实施工作细分。 批判性地查看生成的任务，以确保覆盖范围全面、排序逻辑和粒度适当。 使用验证的任务列表指导系统实现、跟踪进度和协调团队工作。

spec.md、plan.md 和 tasks.md 的组合将创建完整的开发框架。 该规范定义了构建的内容以及为什么这样做。 该计划定义了如何从架构上进行构建。 这些任务定义了执行构建的具体步骤。 这些工件共同将不明确的要求转换为具体、可跟踪的开发工作，使这些开发工作在整个实施过程中始终与项目目标保持一致。