Back to Details

update-specification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Update Specification

更新规范文件

Your goal is to update the existing specification file 
${file}
based on new requirements or updates to any existing code.
The specification file must define the requirements, constraints, and interfaces for the solution components in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
你的目标是根据新需求或现有代码的更新，更新现有的规范文件
${file}
。
该规范文件必须清晰、明确、结构化地定义解决方案组件的需求、约束和接口，以便生成式AI能够有效使用。遵循既定的文档标准，确保内容可被机器读取且独立完整。

Best Practices for AI-Ready Specifications

适配AI的规范文件最佳实践

  • Use precise, explicit, and unambiguous language.
  • Clearly distinguish between requirements, constraints, and recommendations.
  • Use structured formatting (headings, lists, tables) for easy parsing.
  • Avoid idioms, metaphors, or context-dependent references.
  • Define all acronyms and domain-specific terms.
  • Include examples and edge cases where applicable.
  • Ensure the document is self-contained and does not rely on external context.
The specification should be saved in the /spec/ directory and named according to the following convention: 
[a-z0-9-]+.md
, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].
The specification file must be formatted in well formed Markdown.
Specification files must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
md
---
title: [Concise Title Describing the Specification's Focus]
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this spec]
tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
---
  • 使用精确、明确且无歧义的语言。
  • 清晰区分需求、约束和建议。
  • 使用结构化格式（标题、列表、表格）以便于解析。
  • 避免使用习语、隐喻或依赖上下文的引用。
  • 定义所有缩写和领域特定术语。
  • 适用时包含示例和边缘情况。
  • 确保文档独立完整，不依赖外部上下文。
规范文件应保存至/spec/目录，并遵循以下命名约定：
[a-z0-9-]+.md
，文件名应清晰描述规范内容，且以高级用途开头，可选的高级用途包括[schema, tool, data, infrastructure, process, architecture, or design]。
规范文件必须采用格式规范的Markdown编写。
规范文件必须遵循以下模板，确保所有部分都已适当填写。Markdown的前置元数据应按照以下示例正确结构化：
md
---
title: [Concise Title Describing the Specification's Focus]
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this spec]
tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
---

Introduction

引言

[A short concise introduction to the specification and the goal it is intended to achieve.]
[关于本规范及其预期实现目标的简短介绍。]

1. Purpose & Scope

1. 目的与范围

[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
[清晰、简洁地描述本规范的目的及其适用范围。说明目标受众和任何假设条件。]

2. Definitions

2. 定义

[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
[列出并定义本规范中使用的所有缩写、简称和领域特定术语。]

3. Requirements, Constraints & Guidelines

3. 需求、约束与指南

[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
  • REQ-001: Requirement 1
  • SEC-001: Security Requirement 1
  • [3 LETTERS]-001: Other Requirement 1
  • CON-001: Constraint 1
  • GUD-001: Guideline 1
  • PAT-001: Pattern to follow 1
[明确列出所有需求、约束、规则和指南。使用项目符号或表格以确保清晰。]
  • REQ-001: 需求1
  • SEC-001: 安全需求1
  • [3 LETTERS]-001: 其他需求1
  • CON-001: 约束1
  • GUD-001: 指南1
  • PAT-001: 需遵循的模式1

4. Interfaces & Data Contracts

4. 接口与数据契约

[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
[描述接口、API、数据契约或集成点。使用表格或代码块展示schema和示例。]

5. Acceptance Criteria

5. 验收标准

[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
  • AC-001: Given [context], When [action], Then [expected outcome]
  • AC-002: The system shall [specific behavior] when [condition]
  • AC-003: [Additional acceptance criteria as needed]
[为每个需求定义清晰、可测试的验收标准，适用时采用Given-When-Then格式。]
  • AC-001: Given [上下文], When [操作], Then [预期结果]
  • AC-002: 系统应在[条件]下表现出[特定行为]
  • AC-003: [其他必要的验收标准]

6. Test Automation Strategy

6. 测试自动化策略

[Define the testing approach, frameworks, and automation requirements.]
  • Test Levels: Unit, Integration, End-to-End
  • Frameworks: MSTest, FluentAssertions, Moq (for .NET applications)
  • Test Data Management: [approach for test data creation and cleanup]
  • CI/CD Integration: [automated testing in GitHub Actions pipelines]
  • Coverage Requirements: [minimum code coverage thresholds]
  • Performance Testing: [approach for load and performance testing]
[定义测试方法、框架和自动化要求。]
  • 测试层级: 单元测试、集成测试、端到端测试
  • 框架: MSTest、FluentAssertions、Moq（适用于.NET应用）
  • 测试数据管理: [测试数据的创建和清理方法]
  • CI/CD集成: [GitHub Actions流水线中的自动化测试]
  • 覆盖率要求: [最低代码覆盖率阈值]
  • 性能测试: [负载和性能测试方法]

7. Rationale & Context

7. 依据与背景

[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
[解释需求、约束和指南背后的理由。为设计决策提供背景信息。]

8. Dependencies & External Integrations

8. 依赖与外部集成

[Define the external systems, services, and architectural dependencies required for this specification. Focus on what is needed rather than how it's implemented. Avoid specific package or library versions unless they represent architectural constraints.]
[定义本规范所需的外部系统、服务和架构依赖。重点关注所需内容而非实现方式。除非是架构约束，否则避免指定具体的包或库版本。]

External Systems

外部系统

  • EXT-001: [External system name] - [Purpose and integration type]
  • EXT-001: [外部系统名称] - [用途和集成类型]

Third-Party Services

第三方服务

  • SVC-001: [Service name] - [Required capabilities and SLA requirements]
  • SVC-001: [服务名称] - [所需功能和SLA要求]

Infrastructure Dependencies

基础设施依赖

  • INF-001: [Infrastructure component] - [Requirements and constraints]
  • INF-001: [基础设施组件] - [需求和约束]

Data Dependencies

数据依赖

  • DAT-001: [External data source] - [Format, frequency, and access requirements]
  • DAT-001: [外部数据源] - [格式、频率和访问要求]

Technology Platform Dependencies

技术平台依赖

  • PLT-001: [Platform/runtime requirement] - [Version constraints and rationale]
  • PLT-001: [平台/运行时要求] - [版本约束及理由]

Compliance Dependencies

合规依赖

  • COM-001: [Regulatory or compliance requirement] - [Impact on implementation]
Note: This section should focus on architectural and business dependencies, not specific package implementations. For example, specify "OAuth 2.0 authentication library" rather than "Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1".
  • COM-001: [监管或合规要求] - [对实现的影响]
注意: 本节应聚焦于架构和业务依赖，而非具体的包实现。例如，应指定“OAuth 2.0认证库”而非“Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1”。

9. Examples & Edge Cases

9. 示例与边缘情况

code
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
code
// 展示指南正确应用的代码片段或数据示例，包括边缘情况

10. Validation Criteria

10. 验证标准

[List the criteria or tests that must be satisfied for compliance with this specification.]
[列出符合本规范必须满足的标准或测试。]

11. Related Specifications / Further Reading

11. 相关规范 / 进一步阅读

[Link to related spec 1] [Link to relevant external documentation]
undefined
[相关规范链接1] [相关外部文档链接]
undefined