11 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. 如何执行

前置步骤：完成模块拆分与依赖接口盘点（第 0 节）。
发起需求：仅针对“一个模块”，生成初始 requirements.md。
定义契约：输出 openapi.provider.yaml 与 openapi.deps.yaml，并进行接口走查。
架构设计：生成 design.md，明确模块内边界、数据流与依赖策略。
任务执行：生成并执行 tasks.md；调用方优先基于 deps 契约 Mock 并行推进。

11 KiB Raw Blame History Unescape Escape