⚡

规范规范格式参考Skill canonical-spec-format

这个技能提供规范规范格式的参考指南，用于理解和处理软件开发中的规范结构、验证规范、创建规范以及管理供应商转换。关键词包括规范规范、规范模式、规范验证、供应商无关、YAML规范、JSON模式，便于SEO搜索和技能应用。

架构设计 0 次安装 0 次浏览 更新于 3/11/2026

name: canonical-spec-format description: 规范规范格式参考。在理解规范规范模式、字段要求、供应商无关规范结构或验证规范时使用。 allowed-tools: Read, Glob, Grep

规范规范格式

规范规范格式的参考指南 - 定义在ADR-115中的供应商无关中间表示。

何时使用此技能

关键词: 规范规范, 规范模式, 规范格式, 供应商无关, 规范字段, 规范验证, 规范结构, YAML规范, JSON模式

使用此技能当:

  • 理解规范规范结构
  • 根据模式验证规范
  • 手动创建规范
  • 映射供应商和规范格式
  • 调试规范转换问题

快速参考

最小有效规范

id: "SPEC-001"
title: "功能标题"
type: feature

context:
  problem: "问题描述（最少20个字符）"
  motivation: "业务价值"

requirements:
  - id: "REQ-001"
    text: "系统应该做某事"
    priority: must
    ears_type: ubiquitous
    acceptance_criteria:
      - id: "AC-001"
        given: "前置条件"
        when: "动作"
        then: "结果"

metadata:
  status: draft
  created: "2025-12-24"
  provider: canonical

必需字段

字段 类型 描述
id string 格式: SPEC-{number}
title string 人类可读标题
type enum feature, bug, chore, spike, tech-debt
context.problem string 最少20个字符
context.motivation string 业务价值
requirements array 至少一个需求
metadata.status enum draft, review, approved, implemented, deprecated
metadata.created string ISO 8601日期
metadata.provider string 创建此规范的供应商

字段参考

根级别

id: "SPEC-001"           # 必需: 唯一标识符
title: "功能标题"    # 必需: 人类可读名称
type: feature             # 必需: 规范类型

类型值:

类型 描述
feature 新功能或能力
bug 缺陷修复
chore 维护任务
spike 研究或调查
tech-debt 技术债务减少

上下文部分

context:
  problem: |                    # 必需: 最少20个字符
    问题的清晰描述。
    这解决了什么痛点？
  motivation: |                 # 必需
    业务价值或用户利益。
    为什么我们应该投资这个？
  background: |                 # 可选
    附加上下文、历史、约束

需求部分

requirements:
  - id: "REQ-001"               # 必需: 规范内唯一
    text: "EARS需求"    # 必需: EARS格式
    priority: must              # 必需: must/should/could/wont
    ears_type: event-driven     # 必需: EARS模式类型
    acceptance_criteria:        # 必需: 至少一个
      - id: "AC-001"
        given: "前置条件"
        when: "动作"
        then: "结果"
        and:                    # 可选: 附加条件
          - "附加条件"
    notes: "可选笔记"     # 可选

优先级值 (MoSCoW):

优先级 描述
must 不可协商，系统没有它会失败
should 重要但不关键
could 如果资源允许，可取
wont 明确排除在范围外

EARS 类型值:

类型 模式 示例
ubiquitous The system SHALL… “系统应该加密数据”
state-driven WHILE…, the system SHALL… “活动时，系统应该…”
event-driven WHEN…, the system SHALL… “点击时，系统应该…”
unwanted IF…, THEN the system SHALL… “如果错误，则系统应该…”
complex 组合 “活动时，点击…”
optional WHERE…, the system SHALL… “启用时，系统应该…”

设计部分 (可选)

design:
  approach: |                   # 可选: 实现方法
    如何实施的高级别描述
  components:                   # 可选: 受影响的组件
    - "组件 1"
    - "组件 2"
  dependencies:                 # 可选: 先决条件
    - "外部依赖"
  alternatives:                 # 可选: 考虑的替代方案
    - name: "替代方法"
      reason_rejected: "为何未选择"

可追溯性部分 (可选)

traceability:
  adr_refs:                     # 可选: 相关ADRs
    - "ADR-115"
  requirement_refs:             # 可选: 相关需求
    - "FR-001"
    - "NFR-001"
  epic_ref: "EPIC-1118"         # 可选: 父级EPIC
  user_story_refs:              # 可选: 相关用户故事
    - "US-001"

元数据部分

metadata:
  status: draft                 # 必需
  created: "2025-12-24"         # 必需: ISO 8601
  provider: canonical           # 必需
  version: "1.0.0"              # 可选: 语义版本
  bounded_context: "WorkManagement"  # 可选: 来自ADR-024

状态值:

状态 描述
draft 初始创建，未审查
review 审查/细化中
approved 批准实施
implemented 实施完成
deprecated 不再有效

边界上下文值 (ADR-024):

  • WorkManagement
  • Orchestration
  • Workflows
  • Expertise
  • ExecutionControl
  • TriggerManagement
  • Integrations

验证规则

ID 格式

字段 格式 示例
规范 ID SPEC-{number} SPEC-042
需求 ID REQ-{number} REQ-001
验收标准 ID AC-{number} AC-001
ADR 参考 ADR-{number} ADR-115
EPIC 参考 EPIC-{number} EPIC-1118
用户故事参考 US-{number} US-001

内容约束

字段 约束
context.problem 最少20个字符
requirements 至少一个需求
acceptance_criteria 每个需求至少一个标准
metadata.created 有效 ISO 8601 日期

EARS 模式验证

每个需求的 text 字段必须匹配其声明的 ears_type:

ears_type 必需模式
ubiquitous 以 “The” + 实体 + “SHALL” 开头
state-driven 以 “WHILE” 开头
event-driven 以 “WHEN” 开头
unwanted 包含 “IF” 和 “THEN”
optional 以 “WHERE” 开头
complex 多个模式关键词

JSON 模式位置

schemas/canonical-spec.schema.json

供应商转换

规范格式作为所有供应商转换的中心:

                    ┌─────────────┐
                    │  规范  │
                    │   规范    │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │       │       │       │       │
           ▼       ▼       ▼       ▼       ▼
        ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
        │EARS │ │Ghrkn│ │Kiro │ │SpKit│ │ ADR │
        └─────┘ └─────┘ └─────┘ └─────┘ └─────┘

所有供应商实现 ISpecificationProvider:

interface ISpecificationProvider
{
    string ProviderName { get; }
    Task<Result<CanonicalSpec>> ParseAsync(string input);
    Task<Result<string>> GenerateAsync(CanonicalSpec spec);
    Task<ValidationResult> ValidateAsync(CanonicalSpec spec);
    bool CanParse(string input);
}

参考

详细文档:

仓库资源:

  • schemas/canonical-spec.schema.json - JSON 模式
  • docs/adr/ADR-115-specification-provider-abstraction.md - 架构决策

最后更新: 2025-12-26