MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/docs/spec-product-zh.md

16 KiB
Raw Blame History

name version description license compatibility metadata
spec-product-zh 1.3.0 基于 Kiro Spec-Driven Development 与 API-First 思想的‘规范驱动+接口先行’协同开发方法论。通过结构化文档（Requirements/OpenAPI/Design/Tasks）实现 AI 开发的全链路可控与高效协作。 MIT opencode
audience workflow language methodology artifacts
开发者, 架构师, AI 智能体 specification zh-CN
Kiro Spec-Driven Development
API-First (接口先行)
requirements.md
openapi.provider.yaml
openapi.deps.yaml
design.md
tasks.md

规范驱动 + 接口先行（Spec-Driven + API-First）开发方法论

本方法论旨在通过结构化规范文档作为人类与 AI 的“共同语言”，并以接口契约作为协作锚点，实现多角色 AI 的并行、有序、高质量开发。

职责边界：

  • 本文档专注于生成规范文档（requirements/design/tasks/openapi）。
  • AI 在编码阶段的行为准则、门禁、引用规则等执行规范：遵循项目根目录 agents.md。
  • 契约成熟度与门禁的硬规则（给 AI）：见 spec/contracting.md。
  • hooks/构建检查等落地细则（给人）：见 docs/contracting-guide.md。

0. 前置步骤：模块拆分与依赖接口盘点（Module & Dependency Scoping）

在进入“某个模块的 Spec 生成”之前，必须先做一次轻量的边界澄清，否则后续文档会不可控、也无法高效并行。

0.1 产出物

建议在本模块的 Spec 目录下新增一个轻量清单（可写在 requirements.md 中的 Scope/Dependencies 小节，或单独写在 scope.md）：

  • 模块边界说明（Module Scope）：本次 Spec 只覆盖哪个模块/子域？不覆盖什么？
  • 依赖清单（Dependencies）：本模块会调用哪些外部模块/第三方？
  • 依赖接口清单（Dependency Contracts）：对每个依赖，列出“需要的接口能力”（先不管实现在哪）。

0.2 判定标准（进入第 1 阶段的准入条件）

  • 能明确回答：
    • “这是哪个模块的需求？”
    • “本模块对外提供什么能力？”
    • “本模块依赖谁？依赖哪些接口？”
  • 若依赖不明确：先补齐依赖接口清单（哪怕先是草案），再进入需求与接口建模。

1. 核心流程：三阶段协同（每次只做一个模块/一个领域边界）

第一阶段：需求定义与接口建模（Requirements & API Design）

  • 目标：明确“做什么”以及“如何交互”，建立单一可信源（SSOT）。
  • 模块化原则：对于庞大系统，一个 Spec 上下文应仅聚焦于一个功能模块或领域边界（如 ruoyi-forum），避免跨模块需求混杂导致 AI 上下文过载。
  • 依赖先行（Dependency-First）：
    • 如果本模块依赖其他模块（或第三方服务），必须在此阶段先完成外部依赖接口契约（哪怕只有最小集合）。
    • 调用方：基于依赖契约生成 Mock 并直接进入开发逻辑，无需等待被调用方实现。
    • 实现方：后续根据该依赖契约补全真实实现，并通过契约一致性验证。
  • 产出（默认建议放在 spec/<module>/ 目录下，例如 spec/ruoyi-forum/requirements.md）：
    • requirements.md（本模块需求）
    • openapi.provider.yaml（本模块对外提供的 API）
    • openapi.deps.yaml（本模块依赖的外部 API 契约，供 Mock/SDK 生成）

第二阶段：技术设计与方案评审（Technical Design）

  • 目标：细化“怎么实现”，解决技术实现路径与数据模型问题。
  • 产出：design.md（技术蓝图）。
  • 规范：
    • 设计方案必须引用需求 ID。
    • 若涉及跨模块调用，应明确定义：依赖 API 的 Mock 策略、超时/重试/熔断/降级、错误映射。

第三阶段：任务分解与并行开发（Task Decomposition & Implementation）

  • 目标：将设计转化为可执行的原子任务。
  • 并行编程协作（多窗口并行）：
    • 前端/调用方 AI：基于 openapi.provider.yaml + openapi.deps.yaml 生成 SDK + Mock，优先完成页面与业务流程。
    • 后端/提供方 AI：实现 openapi.provider.yaml 对应接口，并持续导出 OpenAPI 工件供校验。
    • 依赖实现方 AI：对照 openapi.deps.yaml（或其子集）补齐真实实现。
  • 产出：tasks.md（执行清单）。

2. 关键文档规范

2.1 requirements.md（需求规范）

requirements 的目标是把“自然语言需求”固化为可追踪、可校验、可版本化的规范。

必须包含以下结构：

  • Frontmatter：包含 feature_id, title, status, version（可按团队需要扩展）。
  • 用户故事：使用统一句式“作为…我希望…以便…”。
  • 验收标准（EARS 语法）：每条验收标准必须带稳定 ID（推荐 AC-<FEATURE>-NN）。
  • 追踪映射（Traceability）：验收标准到接口端点（以及可选 operationId）的映射。

2.1.1 requirements.md 标准模板（可直接复制）

---
feature_id: "REG"               # 功能短 ID（用于拼接 US/AC/NFR 编号）
title: "用户注册"
status: "draft"                # draft | review | approved | implemented
version: "0.1.0"
owners:
  - "product"
  - "backend"
  - "frontend"
last_updated: "2026-02-23"
source:
  type: "conversation"          # conversation | issue | doc | meeting
  ref: ""
---

# 用户注册（REG）

## 1. 背景与目标
- 背景：
- 目标：
- 非目标（Out of Scope）：

## 2. 模块边界（Scope）
- 覆盖：
- 不覆盖：

## 3. 依赖盘点（Dependencies）
- 依赖模块/第三方：
  - 依赖 A：用途说明
  - 依赖 B：用途说明

## 4. 用户故事（User Stories）
- [US-REG-01] 作为访客，我希望使用邮箱注册账号，以便获得会员权益。

## 5. 验收标准（Acceptance Criteria, EARS）
- [AC-REG-01] WHEN 访客提交有效的邮箱与密码 THEN 系统 SHALL 创建用户并返回 201。
- [AC-REG-02] WHEN 访客提交的邮箱不合法 THEN 系统 SHALL 返回 400，并给出字段级错误信息。
- [AC-REG-03] WHEN 邮箱已被注册 THEN 系统 SHALL 返回 400，并提示“邮箱已注册”。

## 6. 追踪映射（Traceability）

| AC ID | Endpoint | 方法 | operationId（可选） | 备注 |
|------|----------|------|---------------------|------|
| AC-REG-01 | /users/register | POST | registerUser | 创建用户 |
| AC-REG-02 | /users/register | POST | registerUser | 参数校验 |
| AC-REG-03 | /users/register | POST | registerUser | 唯一性约束 |

2.2 OpenAPI 契约（openapi.provider.yaml / openapi.deps.yaml）

为支持“大系统多模块 + 多窗口并行”，推荐将 OpenAPI 拆成两份：

  • openapi.provider.yaml：本模块对外提供的 API（本模块是 Provider）。
  • openapi.deps.yaml：本模块依赖的外部 API 契约（本模块是 Consumer，便于 Mock/SDK 生成）。

约定：

  • 两份文件都必须可被 Mock/SDK/测试工具消费。
  • Provider 文件建议带 x-requirements: [AC-xxx] 追踪需求。
  • Deps 文件应定义你“需要对方提供什么能力”，不以对方当前实现为准（可以先草案，后续对齐）。

2.2.1 契约成熟度（Contract Refinement Levels）

为减少“边实现边改契约”导致的需求偏移，本方法论引入契约成熟度等级，并要求在 OpenAPI 的 info 下进行全局标记：

  • info.x-contract-level: L0 | L1 | L2 | L3

约定：

  • openapi.deps.yaml 与 openapi.provider.yaml 都必须标记该字段。
  • L0/L1 用于并行启动；Provider 在进入可合并的实现阶段前应提升到 L2。

L0（占位/可 Mock）

  • 目标：调用方可快速生成 Mock，跑通主流程（happy path）。
  • 必须：最小 path/method/2xx 响应骨架；统一错误响应骨架（可粗）。
  • 允许：schema 粗粒度、校验缺失、错误码不细。

L1（可调用/可生成 SDK）

  • 目标：调用方可基于契约生成 SDK，并开发主要业务流程。
  • 必须：关键请求/响应字段（必填/可选）、基本状态码集合、operationId、描述。

L2（可验收/可契约测试）

  • 目标：提供者可运行 Provider-driven 契约校验（schema/错误语义/边界）。
  • 必须：关键校验规则（format/minLength/enum/range 等）、结构化错误模型、核心异常分支。

L3（可演进/可兼容治理）

  • 目标：长期维护与兼容演进，减少 breaking change。
  • 必须：deprecated/兼容策略、示例（examples）、变更记录（changelog 或版本策略）。

2.2.2 从轻量切分到可验收契约：细化路径

  • 在第 0 节（Scoping）阶段：输出依赖能力清单（自然语言即可），并将其转写为 openapi.deps.yaml 的 L0 草案。
  • 在第 1 阶段（需求与接口建模）阶段：
    • 新增/完善 AC（EARS）会驱动契约从 L0 → L1（补齐核心字段、状态码与映射）。
    • 每个新增字段/错误语义/校验规则，应能追溯到某条 AC-*（否则属于“潜在需求漂移”）。
  • 在进入“提供者实现可合并”之前：必须将 openapi.provider.yaml 提升到 L2（达到可契约测试的程度）。
  • 在产品稳定期：逐步推动关键接口达到 L3（兼容治理与示例完善）。

门禁落点（实现细节）：成熟度等级与合并策略、校验规则应由 agents.md 中的执行规则 + Git hooks/构建检查共同约束。

2.3 design.md（技术设计）

  • 内容：系统架构、数据模型（ER 图）、核心流程、异常与重试、鉴权与审计。
  • 跨模块调用要求：必须描述依赖 API 的失败策略（超时/重试/熔断/降级）以及错误映射。

2.4 tasks.md（任务清单）

  • 结构：带状态的 Markdown 任务列表。
  • 要求：任务按“本模块提供能力”与“本模块消费依赖”拆分；每个任务需标注关联 AC-ID。

3. 自动化协同增强（Hooks/门禁）

本方法论要求在流程中引入自动化门禁，以确保文档与交付一致。

  • 当 requirements.md / OpenAPI 文件变更时，应触发：OpenAPI Lint、Diff（兼容性检查）、契约一致性测试。
  • 当 tasks.md 任务完成时，应同步更新进度与相关说明。

说明：关于“AI 编码行为准则、阶段闸门、引用规则、变更策略”等执行层规范，见项目根目录 agents.md；关于 hooks/构建检查等落地细则，见 docs/contracting-guide.md。

4. 版本化迭代规则（Version Iteration Protocol）

4.1 问题背景

在多次迭代后，规范文档（尤其是 requirements.md）会因 AC 不断累积导致文档膨胀，进而引发：

  • AI 上下文快速占满（单个文档可能 500+ 行）
  • 历史需求干扰当前迭代的理解
  • 难以快速定位当前活跃的 AC 范围

4.2 解决方案：单文档内版本分区

采用 单文档内版本分区 + 历史折叠 策略：

  • 保留最近 1-2 个版本为”活跃版本”（展开）
  • 将更早的版本折叠为 <details> 标签（AI 默认跳过）
  • 在 frontmatter 中标记 active_version 和 version_history

4.3 requirements.md 版本化模板

---
feature_id: “MOD”                   # 模块短 ID
title: “模块需求规范”
status: “in-progress”
version: “0.3.0”                    # 当前最新版本
active_version: “0.2.0-0.3.0”      # 活跃版本范围（展开显示）
version_history:                    # 版本历史索引
  - version: “0.3.0”
    ac_range: “AC-MOD-21~30”
    description: “功能增强 C”
  - version: “0.2.0”
    ac_range: “AC-MOD-11~20”
    description: “功能扩展 B”
  - version: “0.1.0”
    ac_range: “AC-MOD-01~10”
    description: “基础功能 A（已折叠）”
last_updated: “2026-02-27”
---

# 模块需求规范（MOD）

## 1. 背景与目标
[保持不变，描述整体背景]

## 2. 模块边界（Scope）
[保持不变]

## 3. 依赖盘点（Dependencies）
[保持不变]

## 4. 用户故事（User Stories）
[仅保留活跃版本的 US，历史 US 折叠]

## 5. 验收标准（Acceptance Criteria, EARS）

### 📌 当前活跃版本（v0.2.0 - v0.3.0）

#### 5.2 功能扩展 B（v0.2.0）
- [AC-MOD-11] WHEN 用户执行操作 X THEN 系统 SHALL 返回结果 Y
- [AC-MOD-12] WHEN 参数无效 THEN 系统 SHALL 返回 400 错误
[展开显示 v0.2.0 的所有 AC]

#### 5.3 功能增强 C（v0.3.0）
- [AC-MOD-21] WHEN 用户触发事件 Z THEN 系统 SHALL 执行流程 W
- [AC-MOD-22] WHEN 条件满足 THEN 系统 SHALL 更新状态
[展开显示 v0.3.0 的所有 AC]

---

### 📦 历史版本（已归档）

<details>
<summary>v0.1.0：基础功能 A（AC-MOD-01~10）</summary>

#### 5.1 基础功能 A（v0.1.0）
- [AC-MOD-01] WHEN 用户提交请求 THEN 系统 SHALL 处理并返回
- [AC-MOD-02] WHEN 请求格式错误 THEN 系统 SHALL 返回错误信息
[折叠的历史 AC]

</details>

## 6. 追踪映射（Traceability）
[仅保留活跃版本的映射表]

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-MOD-11 | /api/resource | GET | getResource | v0.2.0 |
| AC-MOD-21 | /api/resource | POST | createResource | v0.3.0 |

4.4 AI 执行规则（新增迭代需求时）

当用户提出新迭代需求时，AI 必须：

  1. 读取 frontmatter：识别 version 和 active_version
  2. 确定新版本号：按语义化版本递增（如 0.6.0 → 0.7.0）
  3. 判断是否需要折叠：
    • 若活跃版本已有 2 个（如 0.5.0-0.6.0），则将最旧的版本（0.5.0）折叠
    • 若活跃版本仅 1 个，则保留并追加新版本
  4. 追加新需求：
    • 在”当前活跃版本”区域末尾追加新章节（如 #### 5.7 新功能（v0.7.0））
    • 新 AC 编号延续上一版本（如上一版本最大为 AC-AISVC-90，则新版本从 AC-AISVC-91 开始）
  5. 更新 frontmatter：
    • version: “0.7.0”
    • active_version: “0.6.0-0.7.0”
    • 在 version_history 中追加新版本记录
  6. 更新追踪映射表：仅保留活跃版本的映射

4.5 折叠策略

  • 保留活跃版本数：最多 2 个版本展开（当前版本 + 上一版本）
  • 折叠粒度：按大版本折叠（如 v0.1.0-0.4.0 合并为一个折叠块）
  • 折叠标记：使用 <details><summary> 标签，AI 读取时会自动跳过折叠内容
  • AC 编号连续性：折叠不影响 AC 编号的全局唯一性，新 AC 始终递增

4.6 示例：从 v0.2.0 迭代到 v0.3.0

用户需求：新增”功能增强 C”

AI 执行步骤：

  1. 读取 requirements.md，识别当前 version: “0.2.0”，active_version: “0.1.0-0.2.0”
  2. 确定新版本号为 0.3.0
  3. 将 v0.1.0 的内容移入 <details> 折叠块
  4. 在”当前活跃版本”区域追加 #### 5.3 功能增强 C（v0.3.0）
  5. 新 AC 从 AC-MOD-21 开始编号（上一版本最大为 AC-MOD-20）
  6. 更新 frontmatter： 
    version: “0.3.0”
active_version: “0.2.0-0.3.0”
version_history:
  - version: “0.3.0”
    ac_range: “AC-MOD-21~30”
    description: “功能增强 C”
  - version: “0.2.0”
    ac_range: “AC-MOD-11~20”
    description: “功能扩展 B”
  - version: “0.1.0”
    ac_range: “AC-MOD-01~10”
    description: “基础功能 A（已折叠）”

5. 如何执行

  1. 前置步骤：完成模块拆分与依赖接口盘点（第 0 节）。
  2. 发起需求：仅针对”一个模块”，生成初始 requirements.md（v0.1.0）。
  3. 定义契约：输出 openapi.provider.yaml 与 openapi.deps.yaml，并进行接口走查。
  4. 架构设计：生成 design.md，明确模块内边界、数据流与依赖策略。
  5. 任务执行：生成并执行 tasks.md；调用方优先基于 deps 契约 Mock 并行推进。
  6. 迭代需求：按”版本化迭代规则”（第 4 节）追加新版本需求，保持文档精简。