以实际项目为例：记录规范驱动开发工具选型决策过程

文档编号：28

创建时间：2026-01-24

📋 前言

在使用 AI 编程助手（如 Claude Code、Cursor）进行开发时，一个常见的问题是：如何让 AI 生成的代码更符合预期，减少反复修改的次数？

这就是规范驱动开发（Spec-Driven Development, SDD）要解决的问题。OpenSpec 是一个轻量级的 SDD 工具，可以在编码前通过规范让人类和 AI 达成一致。

本文以 实际项目（一个多模块 Maven 项目）为例，详细记录从了解到 OpenSpec、对比同类工具、到最终选择 OpenSpec 的完整决策过程，希望能为面临类似选择的技术团队提供参考。

🎯 问题背景

当前项目特征

实绩项目具有以下特征：

特征	描述
项目规模	多模块 Maven 项目（Java 8）
模块数量	5+ 子模块（pishi-bom、pishi-framework、pishi-app-*）
团队规模	个人/小团队
AI 使用	已在使用 Claude Code
开发模式	新功能开发 + 现有功能维护
技术栈	Spring Boot 2.7.18、MyBatis-Plus、MySQL

遇到的挑战

在使用 AI 编程助手时，我们面临以下问题：

需求分散：需求隐含在聊天记录中，难以追溯
输出不可预测：同一提示词可能产生不同的代码
变更管理困难：多个功能修改时缺乏统一管理
协作效率低：团队成员之间缺乏统一的规范

🔍 工具调研

SDD 工具对比

我们调研了以下主要的 SDD 工具：

工具	特点	适用场景
OpenSpec	轻量级、无需 API Key、Brownfield 优先	修改现有功能 (1→n)
spec-kit	企业级治理、Specialist 模式	新功能开发 (0→1)
Kiro.dev	快速原型开发	快速验证想法
BMAD	战略性 SDD 方法论	团队协作场景
AgentOS	全面的 Agent 开发平台	复杂 Agent 应用
LeanSpec	超轻量级规范方法论	小型项目

🤔 决策过程

第一轮：了解 OpenSpec

首先，我们了解了 OpenSpec 的核心特性：

核心功能：

规范先行：在编码前确定需求
变更追踪：分离当前规范与提议变更
任务管理：每个变更包含提案、任务清单和规范差异
多工具兼容：支持 Claude Code、Cursor、GitHub Copilot 等 20+ AI 工具

工作流程：

复制代码

起草变更提案 → 审核对齐 → 实现任务 → 归档更新规范

目录结构：

复制代码

openspec/
├── specs/          # 当前规范（已批准的真理来源）
├── changes/        # 变更提案（提议中的更新）
└── archive/        # 已完成的变更

第二轮：适配性分析

我们分析了 OpenSpec 与项目的匹配度：

维度	项目特征	OpenSpec 适配度	说明
项目规模	多模块 Maven 项目，5+ 子模块	⚠️ 中等	规模适中，OpenSpec 可以应对
团队规模	个人/小团队	⚠️ 可能过重	轻量级工具，影响可控
代码复杂度	标准 Spring Boot 应用	✅ 适合	架构清晰，适合规范化
AI 辅助使用	已在使用 Claude Code	✅ 很适合	原生集成，开箱即用
变更频率	有定时任务、SSH 等功能迭代	✅ 适合	需要变更管理
新功能 vs 维护	两者都有	✅ 适合	Brownfield-first 设计

结论：推荐使用 OpenSpec，但建议轻量级起步。

第三轮：对比 spec-kit

作为最接近的竞品，我们深入对比了 OpenSpec 和 spec-kit：

维度	OpenSpec	spec-kit	项目需求匹配
适用场景	Brownfield 优先（修改现有代码）	Greenfield 优先（0→1 新功能）	✅ 已有大量代码
目录模型	双文件夹：specs/ + changes/	单一文件夹，每个功能独立	✅ 需要变更追踪
Claude Code 集成	原生 slash 命令	需要配置	✅ 使用 Claude Code
上手难度	5 分钟初始化	需要理解 Specialist 模式	✅ 轻量级更友好
项目规模	个人/小团队	企业级团队	✅ 个人项目
API Key	无需	需要配置 GitHub/模型	✅ OpenSpec 更简单
灵活性	高（可 hack 的 OPSX）	相对固定	✅ 更灵活

核心差异：

复制代码

OpenSpec：双文件夹模型
├── specs/     ← 当前规范（已批准的真理）
└── changes/   ← 提议中的变更（未批准）

优势：已批准的规范与提议变更完全分离
适合：持续维护现有功能、跨多个规范的更新

spec-kit：Specialist 模式
├── specialists/    ← 每个 AI 专注一个领域
└── features/       ← 每个功能独立 spec

优势：强大的领域建模和验证
适合：新功能开发、企业级质量要求

决策结论 ：选择 OpenSpec。

✅ 最终选择：OpenSpec

选择理由

基于以下原因，我们最终选择了 OpenSpec：

Brownfield 场景匹配
- 项目已有 5+ 子模块和大量代码
- 日常以维护 + 小功能迭代为主
- OpenSpec 的双文件夹模型特别适合
Claude Code 原生集成
- 项目团队使用 Claude Code
- 原生 slash 命令：/openspec:proposal、/openspec:apply、/openspec:archive
- 无需额外配置
轻量级、无依赖
- 无需 API Key，零成本使用
- 5 分钟即可上手
- 个人/小团队友好
渐进式采用
- 可以先用于新功能开发
- 现有功能维护保持原样
- 评估 2-4 周后再决定全面采用

采用策略

复制代码

第一阶段：试用
├── 初始化 OpenSpec
├── 填充 project.md（项目上下文）
└── 选择一个小功能试点

第二阶段：评估
├── 用于 2-3 个新功能
├── 观察 AI 输出质量提升
└── 评估团队接受度

第三阶段：全面采用（可选）
├── 扩展到更多功能
├── 为现有功能补充规范
└── 建立团队协作流程

💡 最佳实践

1. 渐进式采用

阶段	策略	目标
试用期	只用于新功能	验证工具价值
评估期	2-3 个功能	观察效果
成长期	逐步扩大范围	建立团队流程
成熟期	全面采用	持续优化

2. 保持规范简洁

markdown 复制代码

# 好的规范
### Requirement: 用户登录
系统应当使用邮箱和密码对用户进行认证。

# 避免过度细化
### Requirement: 用户登录邮箱字段验证
系统应当验证邮箱字段格式...
### Requirement: 用户登录密码字段验证
系统应当验证密码复杂度...

3. 使用场景描述行为

每个需求至少包含一个场景（Scenario）：

markdown 复制代码

### Requirement: 密码重置
系统应当允许用户通过邮箱重置密码。

#### Scenario: 有效邮箱
- 当用户使用有效邮箱请求密码重置时
- 那么系统会发送包含重置链接的邮件

4. 及时归档

完成的变更应该及时归档，保持 changes/ 目录整洁。

🐛 常见问题

Q1: OpenSpec 会增加开发负担吗？

A: 不会。OpenSpec 的核心理念是"在编码前锁定意图"，实际上减少了反复修改的时间。对于小功能，从提案到归档通常只需要 10-15 分钟。

Q2: 现有功能需要补充规范吗？

A: 不需要。建议从新功能开始使用 OpenSpec，现有功能在维护时逐步补充规范。

Q3: 团队成员使用不同的 AI 工具怎么办？

A: OpenSpec 是工具无关的。不同成员可以使用 Claude Code、Cursor、GitHub Copilot 等不同工具，所有工具都能访问相同的规范文件。

Q4: 规范文件需要纳入版本控制吗？

A : 是的。openspec/ 目录应该纳入 Git 版本控制，这样团队可以共享规范和变更历史。

📊 效果评估

预期收益

指标	预期改善
AI 输出质量	更符合预期，减少反复修改
需求追溯性	规范清晰，易于审查
团队协作	统一规范，减少沟通成本
变更管理	完整的历史记录和审计线索

评估方法

定量指标：功能开发周期、代码修改次数
定性指标：开发体验、团队满意度

建议在采用 2-4 周后进行评估，根据效果决定是否全面采用。

📚 相关文档

文档结束

以实际项目为例：记录规范驱动开发 工具选型决策过程