生成清晰、精确且有效的规范

  • 14 分钟

规范文件（spec.md）是定义您的软件应执行功能的唯一标准。 本单元介绍编写企业级规范的先进技术。

回顾规范基础知识

在规范驱动的开发中，规范准确定义了软件应执行的作，每个实现决策都追溯到它。 结构良好的规范包括：

  • 摘要：从最终用户的角度来看，应用程序（或新功能）的简明说明。
  • 用户情景：简要说明用户如何与应用程序交互。
  • 接受条件：完成时必须满足的特定可测试条件。
  • 功能要求：系统行为的详细说明。
  • 非功能要求：性能、安全性和可伸缩性等质量属性。
  • 边缘情况：异常方案、错误条件和边界行为。

作为唯一真实来源的规范

在规范驱动的开发中，规范准确定义了软件应执行的作，每个实现决策都追溯到它。 如果功能未显示在规范中，则它不会显示在最终产品中，除非有人更新该规范并重新生成项目。

此方法表示思维模式转变：编写规范与编写代码一样重要。 规范并非满足项目管理要求的形式主义 — 它是驱动 AI 代码生成的工件。 像手动实现功能一样，在编写规格说明时投入相同的精力。

将规范视为可执行文档。 修改要求时，更新规范并重新生成计划和任务。 规范在 Git 中受版本控制，成为每个功能应实现的权威记录。

对于习惯于敏捷工作流的企业开发人员，规范的作用与详细的用户情景和验收标准相同，但具有 AI 助手可以直接使用的计算机可读结构。

规范结构

GitHub 规范工具包将规范组织为标准化部分，这些部分涵盖功能行为、质量要求和边缘情况。

“摘要”部分

从终端用户的视角对功能进行简洁描述。 本部分应回答“此功能的作用是什么？” 在一两句话中。

例如：

## Summary

This feature enables employees to upload PDF and DOCX documents to their personal dashboard. Files are stored securely in Azure Blob Storage and appear in the user's document list immediately after upload.

摘要提供整体背景信息。 不熟悉项目的人在阅读本部分后应了解该功能的目的。

“用户情景”部分

用户如何与该功能交互的简要叙述说明。 用户故事体现意图和价值，而非技术实现。

例如：

## User Stories

As an employee, I want to upload documents to my dashboard so that I can access them from any device.

As an employee, I want to see upload progress for large files so that I know the system is processing my request.

As a system administrator, I want uploads to be logged so that we can audit file activity for compliance purposes.

用户故事帮助 AI 助手了解功能背后的人类动机，从而更直观地实现功能。

接受条件部分

必须满足特定的可测试条件，才能将功能视为完整。 验收条件构成了用于验证实现的清单。

例如：

## Acceptance Criteria

- User can select PDF or DOCX files for upload
- Maximum file size is 50MB
- Files larger than 50MB display an error message
- Unsupported file types display an error message
- Successfully uploaded files appear in the document list within 2 seconds
- Upload progress is displayed for files larger than 1MB
- Only users with 'Contributor' role can upload documents
- Uploaded files are stored in user-specific folders in Azure Blob Storage

将验收标准编写为可观察的事实。 避免模糊语句，如“系统响应”，而是指定“API 在 200 毫秒内响应”。

功能要求部分

系统行为的详细说明。 功能要求详细说明了该功能的工作原理。

例如：

## Functional Requirements

### Upload interface
- Dashboard displays an "Upload Document" button in the documents section
- Clicking "Upload Document" opens a file selection dialog
- User selects a file from their local filesystem
- System validates file type and size before initiating upload

### Upload process
- Files are uploaded via multipart HTTP POST to /api/documents endpoint
- Upload includes file content and metadata (filename, size, content type)
- Server validates authentication token before accepting upload
- Server checks user has 'Contributor' role before processing

### Storage
- Files are stored in Azure Blob Storage container 'employee-documents'
- Storage path follows pattern: {userId}/{fileId}/{filename}
- Server generates unique file ID to prevent naming collisions
- File metadata (original filename, upload timestamp, user ID) stored in Azure SQL Database

### User feedback
- Upload progress bar updates every 10% completion
- Success message displays upon completion: "Document uploaded successfully"
- Error messages display for: file too large, unsupported type, network error, server error

功能要求为 AI 提供了足够的详细信息，无需规定确切的代码结构即可生成适当的实现。

“非功能要求”部分

性能、安全性、可伸缩性和合规性等质量属性。 这些要求通常引用宪法。

例如：

## Non-Functional Requirements

### Performance
- File uploads under 5MB complete within 5 seconds on typical network
- Upload progress updates display with less than 100ms latency
- Document list refresh completes within 1 second after upload

### Security
- All uploads require valid Microsoft Entra ID authentication token
- HTTPS/TLS 1.2 enforced for all data transmission
- Files scanned for malware before storage (future enhancement)
- No sensitive data logged (filenames logged, content never logged)

### Scalability
- Support concurrent uploads (up to 5 simultaneous per user)
- Handle 1000 concurrent users uploading files

### Compliance
- Audit log records: user ID, filename, timestamp, file size, IP address
- Audit logs retained for 90 days minimum
- Support data deletion requests within the specified timeline

非功能要求可确保 AI 生成的代码符合企业质量标准，而不仅仅是功能正确性。

边缘案例部分

异常方案、错误条件和边界行为。 显式记录边缘事例可防止 AI 做出假设。

例如：

## Edge Cases

### Network interruption during upload
- If connection drops, display error: "Upload failed due to network error. Please retry."
- No partial files stored in Azure Blob Storage
- User can retry upload from beginning

### Duplicate filename
- System allows duplicate filenames by generating unique file IDs
- User sees original filename in document list
- Back end uses unique IDs to prevent overwrites

### Storage capacity limits
- If Azure Blob Storage quota exceeded, display error: "Upload failed due to storage limit. Contact support."
- Log storage errors for administrator notification

### Concurrent uploads by same user
- System supports up to 5 simultaneous uploads per user
- Sixth concurrent upload queued until one completes
- Progress bars update independently for each upload

### File type detection
- System validates file type by MIME type, not just extension
- File with .pdf extension but non-PDF content rejected
- Error message: "File appears corrupted or has incorrect type"

在规范制定过程中充分考虑边界情况，可防止在实现或测试阶段出现漏洞。

使用 GitHub 规范工具包创建规范

使用 GitHub 规范工具包的 /speckit.specify 命令编写有效的规范更容易。

GitHub 规范工具包基于自然语言说明生成规范草稿，加快规范创建，同时保持一致的结构。

调用“specify”命令

创建规范：

  1. 在 Visual Studio Code 中打开你的项目。

  2. 打开 GitHub Copilot 对话助手，然后使用描述要创建的功能的提示运行 /speckit.specify 命令。

    例如：

    /speckit.specify Create a new document upload feature. The feature should allow employees to upload PDF or DOCX documents through the web dashboard. Files are stored in Azure Blob Storage under the user's account folder. After upload, the file appears in the user's document list. Only users with 'Contributor' role can upload. Maximum file size is 50MB. Show error messages for oversized files or unsupported types. Display upload progress for files larger than 1MB.

    此说明涵盖：

    • 内容：上传 PDF/DOCX 文档
    • 所在位置：网页仪表板界面
    • 如何：存储在 Azure Blob 存储中
    • 谁：具有参与者角色的用户
    • 约束：50 MB 限制，特定文件类型
    • 用户体验：进度显示、错误消息

GitHub Copilot 基于此输入生成结构化 spec.md 文件，为摘要、验收条件、要求和边缘事例创建部分。

查看生成的规格

GitHub Copilot 生成规范后，打开 spec.md 并验证：

  • 完整性：规范是否涵盖你提到的所有要求？ 如果你指定了“仅 PDF 和 DOCX”，请确认验收标准中列出了这些文件类型。

  • 准确性：详细信息是否正确？ 如果你说限制为 50 MB，请验证规范中说明的是 50 MB，而不是其他的值。

  • 一致性：不同节是否一致？ 如果摘要提到进度显示，则验收条件应包含它。

  • 缺少元素：GitHub Copilot 推断或省略了什么？ 查看生成的要求，看看 AI 是否做出了你不同意的假设。

最初的规范是一个有力的起点，但往往不够完美。 期望通过澄清进行改进。

使用 /speckit.clarify 优化规范

该 /speckit.clarify 命令分析规范，并确定需要澄清的歧义、差距或假设。

确保规范清晰

规范中的歧义会导致实现不正确。 请使用 /speckit.clarify 来显现不明区域。

生成初始规格后：

  1. 在 GitHub Copilot 对话助手 中，运行：

    /speckit.clarify

  2. GitHub Copilot 分析 spec.md 并询问关于不清楚或缺失细节的问题。

    说明问题示例：

    I've analyzed the specification and have some questions:

1. File retention: How long should uploaded documents be retained? Forever, or is there a retention policy?

2. Duplicate filenames: If a user uploads a file with the same name as an existing file, should the system:
    - Overwrite the existing file
    - Create a new version
    - Reject the upload with an error
    - Store both with unique identifiers

3. Virus scanning: Should uploaded files be scanned for malware? If so, when—before storage or asynchronously after upload?

4. Download capability: The spec describes upload but doesn't mention download. Should users be able to download their uploaded documents?

5. File sharing: Can users share documents with other employees, or are documents private to the uploader?

这些问题可帮助你就最初可能错过的方面做出决策。

回答澄清问题

针对每个问题做出特定决策：

1. File retention: Retain documents indefinitely until user deletes them. No automatic deletion.

2. Duplicate filenames: Option d - Store both with unique identifiers. Users can have multiple files with the same name. Display upload timestamp to distinguish them in the list.

3. Virus scanning: Not required for initial release. Mark as future enhancement in the spec.

4. Download capability: Yes, users should be able to download their documents. Add this to the spec.

5. File sharing: Documents are private to the uploader for this release. Sharing is a future feature.

回答后，GitHub Copilot 会更新 spec.md 以纳入您的决策。

  • 验收标准新增：“用户可以下载之前上传的文档。”
  • 功能需求中增加下载端点的规范。
  • 边缘事例包括：“多个具有相同名称的文件通过上传时间戳来区分。
  • 非功能需求说明：“病毒扫描功能推迟到后续版本发布。”

迭代直到完成

如果需要，请多次运行 /speckit.clarify 。 每次迭代进一步优化规范：

  • 初次评估：主要功能上的不足之处。
  • 第二轮审核：边界情况细节。
  • 第三轮审核：微调非功能需求。

当 GitHub Copilot 没有更多问题，或者仅询问你想要推迟的功能时停止。

规范编写最佳做法

明确编写规范说明是成功的规范驱动开发的关键。

具体且可衡量

将模糊术语替换为精确值：

  • 不建议：“支持大文件。”

  • 相反：“支持最多 50 MB 的文件。

  • 不是：“上传速度快”。

  • “相反：在 10-Mbps 连接下，5 MB 以下的上传可以在 5 秒内完成。”

特定要求使 AI 能够生成满足实际需求的实现。

使用一致的术语

定义术语一次，并在整个规范中重复使用它们。如果在摘要中将其称为“文档”，请稍后不要切换到“文件”或“附件”。 不一致的术语混淆了人类和 AI。

对于企业内部项目，请使用组织标准的正式产品名称和术语。

明确处理错误处理问题

不要假设 AI 正确处理错误。 指定操作失败时的处理措施：

  • “如果 Azure Blob 存储无法访问，则显示错误：”无法连接到存储服务。 请稍后再试。
  • “如果用户缺少所需角色，则返回 HTTP 403 并显示消息：”您没有上传文档的权限。

显式错误处理可防止 AI 实现不帮助用户的通用错误消息。

维护适当的范围

如果某个功能需要 300 多行才能指定，请考虑将其拆分为多个规格：

  • 而不是单一的“文档管理系统”规格。
  • 创建单独的规范：“文档上传”、“文档下载”、“文档共享”和“文档搜索”。

较小的规格更易于查看、澄清和实施。 它们还与增量交付做法保持一致。

详细说明“内容是什么”，而不是“如何实现”

规范定义要求，而不是实现。 描述系统应该做什么，而不是编码它：

  • 规范：“将上传的文件存储在 Azure Blob 存储中。
  • 规范中不包含：“使用 Azure.Storage.Blobs NuGet 包和 BlobContainerClient 类。”

实施决策属于计划阶段。 然而，如果宪法规定具体技术，则以规范引用这些技术是适当的。

根据基本准则验证

在完成规范之前，请验证它与项目原则不冲突：

  • 宪法要求Microsoft Entra ID 身份验证→规范必须指定Microsoft Entra ID，而不是自定义身份验证。
  • 基本准则要求保留 90 天的审核记录 → 规范必须包含审核日志要求。
  • 宪法将最大文件大小限制为 50 MB →规范不需要 1 GB 的文件支持。

在规格制定阶段发现的不一致性修正成本比实现后要便宜得多。

完成的规范将成为与 GitHub Copilot 签订的合同。 继续规划阶段时，GitHub Copilot 引用此规范来设计与要求完全匹配的技术实现。 投入在详细规格上的时间为整个开发过程带来了回报。

概要

编写有效的规范是成功进行规范驱动开发的基础。 结构良好的规范充当单一事实来源，指导 AI 代码生成并确保与项目原则保持一致。 通过使用 GitHub 规范工具包 /speckit.specify 和 /speckit.clarify 命令，可以快速创建和优化涵盖功能行为、质量属性和边缘事例的详细规范。 遵循规范编写中的最佳做法可提高清晰度，减少歧义，并导致满足用户需求和企业标准的实现。