OpenSpec+Superpowers 实战：SeaTunnel Zeta 管理面板开发全流程

前言

AI辅助编程时代，最大的痛点不是"AI写不出代码"，而是需求理解偏差、架构漂移、代码质量不可控。很多人用AI开发时，陷入了"反复提需求→AI写代码→发现不对→返工"的恶性循环。

今天我们用OpenSpec规范驱动+Superpowers工程化执行的黄金组合，以开发一个功能完整的SeaTunnel Zeta管理面板为例，展示AI开发的正确姿势。全程在本地OpenCode CLI环境下进行。

一、黄金搭档：OpenSpec+Superpowers的能力边界

在开始实战前，我们先明确两个工具的核心定位，这是高效配合的基础：

工具	核心角色	解决的问题	核心能力
OpenSpec	产品经理+架构师	需求混乱、上下文丢失、架构漂移	将模糊需求转化为结构化、机器可读的规格文档
Superpowers	资深开发工程师+测试工程师	AI代码质量差、跳过测试、调试混乱	通过可组合技能强制AI遵循软件工程最佳实践

核心配合逻辑：

OpenSpec负责"做什么"和"怎么做"的规范定义
Superpowers负责"如何高效可靠地实现"
两者通过本地文件系统无缝集成，完全不需要人工传递上下文

简单来说： OpenSpec 画好图纸，Superpowers 按图施工。没有图纸的施工是瞎盖，没有施工的图纸是废纸。

二、实战：SeaTunnel管理面板开发全流程

我们将开发一个轻量级SeaTunnel Zeta管理面板，支持集群概览、作业全生命周期管理、日志查看和系统监控。所有数据通过SeaTunnel官方REST API V2获取。

前置准备

安装OpenCode CLI，详见https://opencode.ai/docs/zh-cn/
opencode中安装superpowers，详见https://github.com/jnMetaCode/superpowers-zh/blob/main/docs/README.opencode.md
openspec安装以及集成，详见https://github.com/Fission-AI/OpenSpec/blob/main/README.md

阶段1：需求探索与澄清（OpenSpec单独执行）

目标：将模糊的一句话需求转化为清晰的问题清单，与利益相关者对齐。

执行命令（在OpenCode CLI中输入）：

/opsx:explore "我需要开发一个SeaTunnel Zeta引擎的管理面板，后端用Spring Boot 3，前端用Spring Boot自带的Thymeleaf，不要前后端分离。功能包括集群概览、作业管理、日志查看、系统监控。所有数据通过SeaTunnel REST API V2获取，相关API详细参考 https://seatunnel.apache.org/zh-CN/docs/2.3.13/engines/zeta/rest-api-v2 。不需要自己的数据库。"

OpenSpec自动输出问题清单：

# 需求探索问题清单

## 关键设计问题
1. SSR vs SSR+AJAX？
2. 作业提交要支持到什么程度？
3. 日志查看需要搜索过滤吗？
4. UI 框架偏好？
5. ...

人工回答确认（直接在CLI中输入）：

1. SSR+AJAX
2. 完整版：支持文件上传 + 三种格式切换 + 加密配置预览
3. 需要搜索过滤
4. Bootstrap 5
5. ...

阶段2：规格提案生成（OpenSpec单独执行）

目标：基于澄清后的需求，生成完整的结构化规格文档，作为后续开发的唯一依据。

执行命令：

/opsx:propose seatunnel-admin-panel

OpenSpec自动在本地生成以下文件结构：

your-project/
└── changes/
    └── seatunnel-admin-panel/  # 变更名称 = 目录名称
        ├── proposal.md         # 为什么做、业务价值、范围边界
        ├── specs/
        │   ├── cluster-overview/spec.md  # 详细功能需求
        │   └── seatunnel-api-client/spec.md  # API 客户端封装 + 错误处理
        ├── design.md          # 技术设计方案
        └── tasks.md           # 初步任务清单

人工操作：用VS Code或者其他编辑器打开这4个文件，审查并修改不符合预期的内容。这是整个开发过程中唯一需要人工大量编辑的步骤。

关键提示：在每个文件开头添加版本号和变更日志：

version: 1.0.0
changeTime: 2026-05-25
changeLog: 定义日志查看页面，含双栏布局、截断策略、按作业过滤、关键词搜索高亮及自动刷新

阶段3：技术方案评估（OpenSpec主导，Superpowers辅助）

目标：让AI评估技术设计的合理性，发现潜在风险，提出改进建议。

执行命令：

/brainstorming @openspec\changes\seatunnel-admin-panel/ 整体方案评估，提出改进建议和潜在风险

Superpowers自动读取本地changes/seatunnel-admin-panel/目录下的所有文件，输出评估报告：

────┬───────────────────────────────┬──────────────────────────────────┐
│ #  │ 改动点                         │ 具体变更                         │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 1  │ 作业提交路径                    │ 移除 upload 端点，统一走         │
│    │                               │ POST /submit-job (文本端点)      │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 2  │ 日志截断策略                    │ 后端截断最后 1000 行返回，       │
│    │                               │ 提供手动全量查看选项             │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 3  │ API 响应模型                    │ 全量 DTO + @JsonIgnoreProperties│
│    │                               │ + Lombok @Data + @JsonProperty  │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 4  │ 静态资源引入方式                │ Bootstrap 5 + Mermaid.js        │
│    │                               │ 全部本地引入，不依赖 CDN         │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 5  │ DAG 可视化                     │ 用 Mermaid.js 渲染流程图        │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 6  │ 补充缺失设计细节                │ 包结构/超时配置/模板组织         │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 7  │ 系统监控摘要计算                │ 摘要卡片需从多节点数据聚合       │
├────┼───────────────────────────────┼──────────────────────────────────┤
│ 8  │ Spec 细化                      │ 日志搜索/指标分组等实现细节      │
└────┴───────────────────────────────┴────────────────

人工操作：根据评估建议修改design.md和tasks.md，将版本号升级为1.1.0。
注：也可以通过人工确认后，后面opencode会依次执行：用户批准设计->编写设计文档到 docs/superpowers/specs/->规格自检（内联修复）->用户审查规格->同步更新 OpenSpec 制品

阶段4：任务计划细化（双向配合）

目标：将高层级任务分解为可执行的原子任务，明确每个任务的输入输出和验收标准。
注： opencode在你确认后，会自动执行writing-plans。你可以手动执行如下命令，进行更细致的描述，以及让AI再次进行自检确认

执行命令：

/writing-plans @openspec\changes\seatunnel-admin-panel/  生成详细的原子任务执行计划，每个任务预计耗时不超过10分钟

Superpowers自动读取最新的规格文档，生成24个原子任务：

# 详细执行计划

## 任务 1：项目基础配置
- 文件：pom.xml
- 步骤：创建Spring Boot项目，添加必要依赖

## 任务 3：配置类
- 文件：src/main/java/com/example/seatunnel/config/SeaTunnelApiProperties.java
- 步骤：创建 SeaTunnelApiProperties


...（其余22个任务省略）

人工操作：审查任务计划，调整不合理的地方，更新tasks.md，版本号升级为1.1.0。

阶段5：代码实现与测试（Superpowers单独执行）

目标：让AI按照任务计划和规格文档，自动完成所有代码编写和单元测试。
注：在你superpowers-plan生成完后，AI会自动提示选择是要使用子代理即（subagent-driven-development）或者内联执行（executing-plans），你可以根据实际需要进行选择。
也可以手动执行形如下命令，进行进一步要求

执行命令：

请使用subagent-driven-development和test-driven-development技能，严格按照规格文档@openspec\changes\seatunnel-admin-panel/和任务计划 @docs\superpowers\plans\2026-05-22-seatunnel-admin-panel.md实现代码。所有代码必须100%符合规格文档要求，任何与规格不符的地方都必须先暂停开发并反馈给我，由我更新规格文档后再继续

Superpowers执行过程：

自动创建Git分支和工作树
为每个任务分配独立的子代理
严格执行TDD：先写测试，再写实现
每个任务完成后自动运行验证
遇到问题自动使用systematic-debugging技能

关键代码示例（自动生成）：

@Service
public class SeaTunnelApiClient {
    private final RestClient restClient;
    private final SeaTunnelApiProperties properties;

    public SeaTunnelApiClient(Builder restClientBuilder, SeaTunnelApiProperties properties) {
        this.restClient = restClientBuilder.build();
        this.properties = properties;
    }

    private String buildUrl(String path, Map<String, String> queryParams) {
        String url = properties.getBaseUrl() + path;
        if (queryParams != null && !queryParams.isEmpty()) {
            StringBuilder sb = new StringBuilder(url);
            sb.append("?");
            queryParams.forEach((k, v) -> sb.append(k).append("=").append(v).append("&"));
            sb.deleteCharAt(sb.length() - 1);
            url = sb.toString();
        }
        return url;
    }


    // 其他API方法自动生成...
}

整个代码实现过程约1小时，期间不需要任何人工干预。

阶段6：代码审查与验证（Superpowers 主导，OpenSpec 辅助）

目标：确保代码符合规格要求，质量达标。
注：自动触发

执行命令：

/requesting-code-review @openspec\changes\seatunnel-admin-panel/

Superpowers自动生成代码审查报告：


**人工操作**：根据审查建议修改代码，然后执行最终验证：
```bash
/verification-before-completion @openspec\changes\seatunnel-admin-panel/

验证报告：

# 完成前验证报告

# 项目验证结果

## 新鲜验证结果
- `mvn compile` → BUILD SUCCESS ✅
- `mvn test` → 13 tests, 0 failures, 0 errors ✅
- `application.yml` 存在、`application.properties` 已删除 ✅

## 文件清单验证

| 类别       | 计划要求 | 实际存在 | 状态 |
|------------|----------|----------|------|
| Java 源码  | 43 个    | 43 个    | ✅   |
| 测试文件   | 5+1 个   | 6 个     | ✅   |
| 模板文件   | 9 个     | 9 个     | ✅   |
| JS 文件    | 7 个     | 7 个     | ✅   |
| CSS 文件   | 1 个     | 1 个     | ✅   |
| 静态资源   | 3 个     | 3 个     | ✅   |
| 配置文件   | 1 个     | 1 个     | ✅   |

阶段7：文档归档与维护（OpenSpec单独执行）

目标：将已完成的变更归档，更新系统整体文档。

执行命令：

/opsx:archive seatunnel-admin-panel

OpenSpec自动完成：

将变更合并到主规格文档
更新系统整体架构图
归档所有开发过程文档
生成最终的用户手册和部署文档

三、常见问题解答

Q1：如果开发过程中需求变更怎么办？

A：使用/opsx:update命令更新规格文档，记录变更原因和影响范围，升级版本号（如 1.3.0），Superpowers 根据更新后的规格调整任务计划,重新执行受影响的测试

示例：

执行/opsx:update seatunnel-admin-panel
修改本地规格文档，升级版本号（如 1.3.0）
执行/writing-plans @openspec\changes\seatunnel-admin-panel/更新任务计划
执行/subagent-driven-development @openspec\changes\seatunnel-admin-panel/和任务计划 @docs\superpowers\plans\2026-05-22-seatunnel-admin-panel.md继续开发

Superpowers会自动识别变更，只修改受影响的代码。

Q2：Superpowers生成的代码不符合预期怎么办？

A：首先，在传递文档的时候，一定要加上这句话：

所有代码必须100%符合规格文档要求，任何与规格不符的地方都必须先暂停开发并反馈给我，由我更新规格文档后再继续

如果 AI 还是写得不对，不要直接让它改代码，而是先检查规格文档是不是写得不够清楚。永远是先改规格，再改代码。

Q3：我只想实现某个特定功能怎么办？

A：指定具体的文件或章节。

/subagent-driven-development 实现系统监控页面功能，基于@openspec\changes\seatunnel-admin-panel\specs\system-monitoring\spec.md以及@docs\superpowers\plans\2026-05-22-seatunnel-admin-panel.md##任务 23：系统监控页面模板

Q4：我只改了一行需求，也要重新传递所有文档吗？？

A：如果是基于superpowers的子代理实现，必须传递所有文档。Superpowers 的子代理是独立的，它们看不到之前的对话内容。只传部分内容会导致 AI 基于不完整的信息工作，最后写出来的代码肯定有问题

Q5：如何回滚到之前的规格版本？

A：前置条件使用git来做版本管理。使用 Git 回滚规格文件，然后执行/opsx:update seatunnel-admin-panel即可。

四、几条最佳实践

永远不要用 OpenSpec 的 /opsx:apply 命令。用 Superpowers 来执行代码实现，它在代码质量和工程化方面做得比 OpenSpec 好得多
用 verification-before-completion 作为质量闸门。在每个主要阶段结束时，强制 AI 验证是否符合规格和质量要求，不达标就不能进入下一阶段
保持规格的轻量级。不要过度设计规格文档，只包含必要的信息，让 AI 能够快速理解和执行
所有变更都必须先更新规格。开发过程中如果发现规格有问题或者需要变更，永远先更新规格文档，再修改代码

五、总结

OpenSpec+Superpowers的配合，本质上是将软件工程的最佳实践固化为AI可以执行的流程。它解决了AI开发中最致命的两个问题：

需求不确定性：通过结构化规格文档消除歧义
代码不可靠性：通过工程化技能保证代码质量

在AI时代，程序员的核心竞争力不再是写代码的速度，而是定义问题和制定规范的能力。掌握了OpenSpec+Superpowers的配合方法，你就掌握了AI开发的正确姿势。

posted @ 2026-08-25 09:40 Linyb极客之路阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

Linyb极客之路

OpenSpec+Superpowers 实战：SeaTunnel Zeta 管理面板开发全流程

前言

一、黄金搭档：OpenSpec+Superpowers的能力边界

二、实战：SeaTunnel管理面板开发全流程

前置准备

阶段1：需求探索与澄清（OpenSpec单独执行）

阶段2：规格提案生成（OpenSpec单独执行）

阶段3：技术方案评估（OpenSpec主导，Superpowers辅助）

阶段4：任务计划细化（双向配合）

阶段5：代码实现与测试（Superpowers单独执行）

阶段6：代码审查与验证（Superpowers 主导，OpenSpec 辅助）

阶段7：文档归档与维护（OpenSpec单独执行）

三、常见问题解答

Q1：如果开发过程中需求变更怎么办？

Q2：Superpowers生成的代码不符合预期怎么办？

Q3：我只想实现某个特定功能怎么办？

Q4：我只改了一行需求，也要重新传递所有文档吗？？

Q5：如何回滚到之前的规格版本？

四、几条最佳实践

五、总结

公告