OpenSpec：用规格驱动开发解决AI编码助手“自由发挥”难题-平芜编程栈

1. 项目概述：当AI助手不再“自由发挥”

最近在跟几个团队做技术交流，发现一个挺普遍的现象：大家用上AI编码助手后，效率确实有提升，但代码质量却像开盲盒。有时候生成的函数逻辑精妙，但更多时候，它要么“过度设计”塞给你一堆用不上的抽象，要么干脆“放飞自我”，完全偏离你脑海里的业务意图。你不得不花大量时间在聊天窗口里跟它来回掰扯，反复修正提示词，最后发现，沟通成本可能比手写代码还高。这感觉就像请了个能力超强但理解力堪忧的实习生，你得把需求掰开揉碎、一字一句地教，它还不一定能一次做对。

OpenSpec的出现，就是冲着解决这个“沟通鸿沟”来的。它不是一个新的大模型，也不是另一个IDE插件，而是一套规格驱动开发的方法论和配套的CLI工具。核心思想很简单：把人类对代码的“意图”和“约束”，用一种机器和人都能无歧义理解的形式（规格说明书）写下来，然后让AI编码助手严格“照单执行”。这相当于在开发者和AI之间，建立了一份具有法律效力的“技术合同”，AI不再是猜你想法的“占卜师”，而是严格按图纸施工的“工程师”。

我自己在几个中小型项目里试用了OpenSpec一段时间，最直接的感受是：需求越复杂、约束越具体，它的优势就越明显。以前让AI写一个带分页、排序、条件过滤的查询接口，提示词得写小作文。现在，我只需要在.openspec文件里定义好输入参数、输出结构、错误码、性能要求（比如响应时间<100ms），AI生成的代码几乎就是最终版，省去了大量调试和重构的环节。对于那些重复性强、但细节要求苛刻的“脏活累活”（比如数据校验层、API客户端、特定设计模式的实现），OpenSpec简直是生产力核弹。

2. 核心理念拆解：从TDD到SDD的范式迁移

要理解OpenSpec，得先跳出“更好的提示词工程”这个框。它背后代表的是一种开发范式的演进，我们可以类比一下熟悉的TDD。

2.1 TDD的局限与SDD的诞生

测试驱动开发大家都很熟了：先写一个会失败的测试用例，然后写最简单的代码让它通过，最后重构。TDD的核心验证对象是代码的行为，它保证了“代码做得对不对”。但它有一个前提：开发者自己得先知道“对的代码”长什么样，并且能把它写出来。在AI辅助编码的语境下，这个前提被打破了。现在的情况是，开发者知道“想要什么功能”（需求），但可能不熟悉具体实现（比如一个新的库或框架），或者不想亲手写那些繁琐的模板代码。这时，你让AI去实现，如果只给一个模糊的需求描述，AI生成的代码即便通过了TDD的测试，其内部结构、可维护性、是否符合团队规范，都是未知数。

规格驱动开发正是在这个缺口上发力。SDD关注的是代码的规格与约束，它定义了“好的代码应该长什么样”，而不仅仅是“代码能不能跑”。你可以把SDD看作是TDD的前置补充阶段：

TDD：定义行为正确性（Functional Correctness）。——“这个函数输入A，必须输出B。”
SDD：定义实现规格（Implementation Specification）。——“这个函数要用Go语言编写，遵循项目目录结构，使用context处理超时，错误必须包装并记录日志，循环内不得有数据库查询，返回结构体必须实现JSON序列化标签...”

在SDD范式下，开发流程变成了：1. 编写规格说明书 -> 2. AI根据规格生成代码 -> 3. 运行TDD测试验证行为。规格说明书成了连接人类意图与AI产出的唯一可信源。

2.2 OpenSpec如何充当“规格编译器”

OpenSpec工具链的核心角色，就是充当这个“规格编译器”。它定义了一种名为OpenSpec Markdown的轻量级标记语言，用来书写规格。这种语言的关键在于结构化和无歧义。

举个例子，传统提示词可能是：“请用Python写一个函数，从数据库读取用户信息，如果用户不存在就返回404，还要处理可能的网络异常。” 而OpenSpec规格会是这样：

## Function: get_user_by_id **Language**: Python 3.9+ **Framework**: FastAPI **Input**: - `user_id: int` (Path parameter) - `db_session: AsyncSession` (Dependency injection) **Output**: - Success: `UserSchema` (Pydantic model, includes `id`, `name`, `email` fields) - Error: `HTTPException` with status_code 404 if user not found. **Logic**: 1. Query `User` model where `id == user_id`. 2. If no result, raise `HTTPException(status_code=404, detail="User not found")`. 3. Return `UserSchema.from_orm(user)`. **Constraints**: - Must use async/await. - Database call must be within a try/except block for `SQLAlchemyError`. - Log an error message with `user_id` if exception occurs.

看到区别了吗？传统提示词充满了需要AI“意会”的空间（“处理异常”具体怎么处理？返回404是返回什么对象？）。而OpenSpec规格几乎就是伪代码，它明确规定了编程语言、框架、输入输出的具体类型、核心逻辑步骤、以及必须遵守的约束条件（异步、错误处理、日志）。AI拿到这份规格，其任务从“创意性实现”降级为“精确翻译”，出错的概率自然大大降低。

3. 核心工具链与实战上手

OpenSpec目前主要提供CLI工具，可以集成到你的终端或IDE中。它的工作流非常清晰。

3.1 安装与初始化

安装很简单，通常通过包管理器即可。以使用pip的Python环境为例：

pip install openspec-cli

安装后，在你的项目根目录下初始化：

openspec init

这个命令会做两件事：

在项目根目录创建一个.openspec的隐藏文件夹，用于存放全局配置和缓存。
生成一个示例的specs/目录和一份README.spec.md文件，里面是OpenSpec Markdown的语法手册和示例。

实操心得：建议把specs/目录纳入版本控制（如Git）。规格说明书和代码一样，是项目的重要资产，它的变更历史记录了需求与设计决策的演进。

3.2 编写你的第一份规格说明书

在specs/目录下，新建一个.md文件，例如user_service.get_user.md。OpenSpec的文件名通常建议反映模块和功能。

现在，我们来详细编写一个比刚才更实战化的规格。假设我们要为一个电商系统编写“创建订单”的API后端逻辑。

# 规格：创建订单接口 (Create Order API) **Scope**: Backend Service - Order Module **Last Updated**: 2023-10-27 ## 1. 接口概述 (API Overview) - **Endpoint**: `POST /api/v1/orders` - **Description**: 接收用户提交的商品列表和配送信息，验证后创建订单，扣减库存，并触发后续支付流程。 - **Framework**: Spring Boot 3.1+, Java 17 - **Database**: JPA (Hibernate) with MySQL ## 2. 输入规格 (Input Specification) ### 2.1 请求体 (Request Body) 必须使用以下DTO类接收请求，并启用Bean Validation： ```java // CreateOrderRequest.java public class CreateOrderRequest { @NotNull private Long userId; @NotEmpty private List<OrderItemRequest> items; @Valid private ShippingAddressRequest shippingAddress; // ... getters and setters } // OrderItemRequest.java public class OrderItemRequest { @NotNull private Long skuId; @Min(1) private Integer quantity; // ... getters and setters } ``` ### 2.2 请求头 (Request Headers) - `X-Request-ID: String` (用于全链路追踪，必须从网关传入并记录在日志中) - `Authorization: Bearer <JWT>` (JWT令牌，用于解析用户身份，需在服务内验证有效性) ## 3. 处理逻辑与约束 (Processing Logic & Constraints) ### 3.1 核心逻辑步骤 1. **参数校验**：使用Spring的`@Valid`自动校验请求体，校验失败返回HTTP 400。 2. **身份与权限验证**：解析JWT，确认`userId`与令牌中subject一致，且用户状态正常。 3. **业务校验**（需在数据库事务中）： a. 遍历`items`，查询商品SKU信息，校验是否存在、是否上架、库存是否充足。 b. 校验配送地址是否在服务范围内。 4. **数据操作**（在同一事务中）： a. 生成唯一的订单号（规则：`ORD` + yyyyMMdd + 6位随机数）。 b. 创建`Order`主实体及`OrderItem`子实体，初始状态为`PENDING_PAYMENT`。 c. 批量扣减对应SKU的库存（使用乐观锁版本号控制，防止超卖）。 5. **后续操作**（事务提交后）： a. 发送订单创建成功事件到消息队列（如RabbitMQ的`order.created`队列），用于触发支付超时定时任务、发送通知等。 b. 记录审计日志。 ### 3.2 关键约束 - **事务边界**：步骤3和4必须在同一个`@Transactional`注解的方法内完成。 - **异常处理**： - 业务校验失败（如库存不足），抛出自定义业务异常`BizException`，全局处理器捕获后返回HTTP 200，但body中包含特定的错误码和消息。 - 数据库操作失败、消息发送失败等系统异常，记录ERROR级别日志后，抛出`RuntimeException`，由Spring Boot返回HTTP 500。 - **性能要求**：核心事务内操作（校验+创建+扣库存）的数据库RT（响应时间）需低于50ms。 - **日志规范**：必须在方法入口处记录INFO日志，包含`X-Request-ID`和`userId`；任何异常必须记录ERROR日志，包含请求上下文。 ## 4. 输出规格 (Output Specification) ### 4.1 成功响应 (Success Response) - **Status**: HTTP 201 Created - **Body**: ```json { "code": 0, "message": "success", "data": { "orderId": "ORD20231027123456", "totalAmount": 129.99, "status": "PENDING_PAYMENT", "estimatedDeliveryTime": "2023-11-01" } } ``` ### 4.2 错误响应 (Error Response) - **业务错误**：HTTP 200, Body: `{"code": 1001, "message": "库存不足"}` - **参数错误**：HTTP 400, Body: Spring默认错误格式 - **系统错误**：HTTP 500

这份规格说明书已经非常详细，它定义了一个合格的后端开发者需要知道的所有实现细节。接下来就是让AI来干活了。

3.3 生成与集成代码

在终端中，定位到规格文件所在目录，运行生成命令：

openspec generate specs/order_service.create_order.md --target ./src/main/java/com/example/order/service

OpenSpec CLI会做以下几件事：

解析规格：读取并解析Markdown文件，理解所有结构化的约束和要求。
构造提示：将规格内容、项目上下文（通过读取项目内其他文件感知框架、风格）以及你的个性化配置，组合成一个超级详细的、针对大模型的提示词。
调用AI：通过配置的AI服务API（如OpenAI GPT-4, Anthropic Claude等），发送提示词并获取生成的代码。
输出结果：将生成的代码保存到你指定的目标路径。它通常会生成完整的Java类文件，包括Controller、Service、DTO、甚至Repository接口的骨架。

注意事项：首次使用需要配置AI API密钥。执行openspec config set api_key YOUR_AI_API_KEY。建议使用性能最强的模型（如GPT-4），因为规格解析和代码生成需要很强的逻辑理解和遵从能力。对于团队使用，可以将密钥配置在环境变量或统一的配置中心。

生成后的代码，你需要将其集成到项目中。通常这意味着：

将生成的Java文件放入正确的包路径。
检查生成的代码是否与现有的项目结构、父类、接口匹配（OpenSpec会尽力推断，但可能需要微调）。
运行你已有的单元测试或集成测试（TDD环节），验证其行为是否符合预期。

4. 高级特性与团队协作实践

OpenSpec不仅仅是一个单兵作战的工具，它在团队协作和复杂系统维护方面，展现出更大的价值。

4.1 规格的模块化与复用

在大型项目中，你不会为每个函数都写一份独立的规格。OpenSpec支持规格的模块化和引用。

基础规格片段：你可以创建specs/_fragments/目录，存放可复用的规格块。例如，一个logging_constraints.md文件，定义了所有服务都必须遵守的日志格式和级别要求。一个pagination_spec.md定义了分页请求和响应的标准DTO。
引用机制：在新的规格文件中，你可以通过特定的语法引用这些片段。例如，在某个API规格中写入{{> _fragments/logging_constraints}}，该片段的内容就会被自动包含进来。这保证了跨服务、跨团队的一致性。
数据字典与类型定义：可以定义全局的DataDictionary.md，集中说明像UserId、OrderStatus这种通用类型的确切含义和取值范围，在所有相关规格中引用，确保领域语言统一。

4.2 与现有开发流程的集成

CI/CD流水线：可以将openspec generate --check命令集成到CI流程中。这个命令会检查项目内所有规格文件与已生成代码是否同步。如果规格更新了而代码未重新生成，CI会失败，防止规格与代码不一致的“腐化”。
代码审查：在Pull Request中，审查者可以同时查看规格说明书的变更和对应的代码变更。这使代码审查的重点从“这行语法对不对”上升到“这段实现是否完全、准确地满足了规格要求”，提升了审查的效率和深度。
文档即代码：规格说明书本身就是最好的、最及时的设计文档。它随着需求变更而更新，并且与最终代码强绑定。再也不用担心代码更新了而设计文档还停留在上个版本。

4.3 针对不同场景的规格编写策略

根据任务类型，规格的侧重点可以不同：

CRUD业务逻辑：如上面的订单示例，重点在输入校验、事务边界、业务规则、输出格式。要像写产品PRD一样细致。
算法或复杂计算：重点在定义清晰的输入输出数学关系、时间复杂度/空间复杂度约束、边界条件处理。可以包含伪代码或关键公式。
基础设施代码（如配置类、连接池工厂）：重点在配置项的结构、默认值、依赖关系、生命周期管理（如@Bean的作用域）。
API客户端或SDK：重点在方法签名、异常分类（网络异常、业务异常）、重试策略、序列化/反序列化方式。

5. 常见问题与避坑指南

在实际引入OpenSpec的过程中，我和团队踩过一些坑，也总结出一些让流程更顺滑的经验。

5.1 规格写得不好，比没有规格更糟

这是初期最容易犯的错误。模糊、矛盾或过度约束的规格，会导致AI生成低质量代码或直接失败。

问题1：约束矛盾。“必须使用异步非阻塞IO”和“方法必须是同步的”同时出现在规格里。
- 排查：在编写完规格后，用“人肉编译器”的视角通读一遍，检查逻辑是否自洽。OpenSpec未来可能会加入静态检查工具。
问题2：过度省略：只写了“调用支付服务”，但没有指定支付服务客户端的方法名、参数、异常处理。
- 解决：对于外部依赖，即使你不清楚具体实现，也要在规格中定义出你期望的接口。例如，“调用PaymentServiceClient.createTransaction(Order order)方法，该方法返回PaymentResponse，需处理其声明的PaymentFailedException。”
问题3：规格膨胀：试图在一个规格文件里定义一个完整的微服务。
- 解决：遵循单一职责原则。一个规格文件最好只对应一个类、一个函数或一个紧密相关的功能组。大规格可以拆分成多个小规格，通过引用来组织。

5.2 生成的代码需要“微调”，这是正常的

不要期望AI生成100%直接可用的代码，尤其是项目有特殊的历史包袱或独特的编码风格时。OpenSpec生成的是“符合规格的初版代码”。

典型微调场景：
- 导入包：可能需要调整import语句的顺序或修正个别缺失的import。
- 代码风格：生成的代码可能不完全符合你项目的Checkstyle或Spotless规则，需要格式化。
- 与现有代码集成：生成的Service可能需要实现某个已有的接口，或注入一个特定名称的Bean。
正确心态：将OpenSpec视为一个高级别的代码自动补全或初稿撰写助手。你的工作从“从零开始写”变成了“审查和优化一份高质量的初稿”，后者依然能节省70%以上的时间和脑力。

5.3 模型选择与提示词“黑盒”

OpenSpec内部如何构造最终发给大模型的提示词，对用户是个黑盒。不同模型的表现差异很大。

模型推荐：强烈建议使用GPT-4或同等级别的模型。我们在测试中发现，GPT-3.5-Turbo对于复杂规格的理解和遵从能力明显不足，容易忽略细节或产生幻觉。Claude Opus也是不错的选择。这笔投资对于生成代码的质量和可靠性是值得的。
成本控制：规格文件应尽量简洁、无冗余。避免在规格中粘贴大段的、与当前生成任务无关的示例代码或背景介绍，这会增加token消耗。利用好引用和片段复用。

5.4 团队采纳的文化阻力

引入任何新流程都会遇到阻力。“写规格的时间都够我写代码了”是常见的质疑。

应对策略：
1. 从小处试点：不要强迫所有项目立即改用SDD。选择一个新启动的、边界清晰的模块或一个重复性高的重构任务（如为所有实体增加审计字段）进行试点。
2. 展示价值：记录试点过程中，因为规格清晰而避免的沟通成本、返工次数和Bug数量。用数据说话。
3. 制作模板：为团队最常用的几种开发场景（如CRUD API、消息消费者、定时任务）制作规格模板，降低起步门槛。
4. 强调规格的长期价值：规格不仅是给AI看的，更是给未来接手代码的同事（包括半年后的你自己）看的最准确的设计文档。它降低了系统的心智负担和维护成本。

我个人最深的一个体会是，OpenSpec强迫我在动手写代码之前，更深入、更结构化地思考“我到底要什么”。这个过程本身就能提前发现很多设计上的模糊点和潜在矛盾。当AI严格按照这份深思熟虑后的“图纸”交出代码时，那种确定性和掌控感，是过去与AI“聊天式编程”完全无法比拟的。它没有取代程序员，而是把我们推向了更高维度的设计者和架构师角色。