378 lines
16 KiB
Markdown
378 lines
16 KiB
Markdown
---
|
||
name: spec-product-zh
|
||
version: 1.3.0
|
||
description: "基于 Kiro Spec-Driven Development 与 API-First 思想的‘规范驱动+接口先行’协同开发方法论。通过结构化文档（Requirements/OpenAPI/Design/Tasks）实现 AI 开发的全链路可控与高效协作。"
|
||
license: MIT
|
||
compatibility: opencode
|
||
metadata:
|
||
audience: "开发者, 架构师, AI 智能体"
|
||
workflow: specification
|
||
language: zh-CN
|
||
methodology:
|
||
- "Kiro Spec-Driven Development"
|
||
- "API-First (接口先行)"
|
||
artifacts:
|
||
- 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 标准模板（可直接复制）
|
||
|
||
```markdown
|
||
---
|
||
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 版本化模板
|
||
|
||
```markdown
|
||
---
|
||
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：
|
||
```yaml
|
||
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 节）追加新版本需求，保持文档精简。
|