![openmole-logo-small.jpg](https://developer.qcloudimg.com/http-save/yehe-1327231/3cd6fb4c254b2032e72a9d5a6b6dae83.jpg)
## 起由

软件工程的现实是：上线运行的代码才是真正说了算的“事实源”。需求文档和设计图写得再漂亮，也敌不过代码仓库里日积月累的坏味道。在 AI 辅助编程越来越普及的今天，我们面临一个两难困境：AI 很乐意帮你大改特改，但它未必守得住“外部行为不变”这条重构底线。

规约驱动开发（Specification-Driven Development，SDD）给出了一条路：将业务需求、架构决策和技术约束作为规约，使其成为整个 AI 研发过程的唯一事实源。这套理念在新功能开发上很自然，但重构呢？重构的“意图”不是用户故事里的新按钮，而是“这坨代码闻起来不对、将来会咬人”。

既然 SDD 可以把业务规约当作事实源，那为什么不能把代码坏味道当作事实源？基于这个想法，我提出了**坏味道驱动重构（Bad smells-Driven Refactoring，BDR）**。BDR 的硬规矩可以压缩成一句话：没有写进坏味道规约的重构，原则上不准做；识别出坏味道之后，也不允许跳过规约直接开改。

BDR 与 SDD 五步同构，只是工件内容不同。它把“规约的内容”从用户需求替换为由 AI 识别出来的代码坏味道：首先建立重构宪法（Constitution），定义重构第一性原则、标准步骤和流程门禁；然后由 AI 扫描代码库，将发现的坏味道写成可验收的规约条目（badsmells.md）；再根据规约分解任务（tasks.md），通过分析环节（analysis.md）做差分检查；最后按标准步骤执行重构。最关键的认知转变是：坏味道不是聊天框里一闪而过的牢骚，而是和 PRD 同级的事实源。

## 推进

BDR 最初只是一套方法论文档——在 Cursor 中定义好重构宪法和元规约，然后用提示词指引 AI 按流程执行。但这个方法有一个明显的问题：每次新开项目都要手动复制文档、重新描述流程、反复纠正 AI 的行为偏差。它的重复性太高了，而这恰恰是适合提炼为 skill 的信号。

于是我将 BDR 开发为一套面向编码 Agent 的软件重构方法论与 Plugin 框架，命名为 **OpenMole**，并开源在 GitHub 上（[github.com/agiledon/openmole](https://github.com/agiledon/openmole)）。OpenMole 将 BDR 的完整流程封装为五个 phase skill，每个 skill 内嵌了重构宪法、元规约和标准步骤，AI 无需额外提示词就能按 BDR 纪律执行重构。

OpenMole 同时是一个跨平台的 Agent Plugin 框架。它通过 npm 包 `openmole` 分发，支持七种主流 AI 开发工具：

| IDE         | 表现形式                                                   |
| ----------- | ------------------------------------------------------ |
| Cursor      | 项目 `.cursor/skills/` + `.cursor/commands/`；用户级 symlink |
| OpenCode    | 项目 `opencode.json` 注册 `.opencode/plugins/openmole.js`  |
| Claude Code | 用户级 `~/.claude/plugins/local/openmole` symlink         |
| Codex       | 项目 `plugins/openmole` symlink + marketplace 注册         |
| Gemini CLI  | 项目 `.gemini/skills/`、`.gemini/commands/`               |
| Kiro        | 项目 `.kiro/skills/`、`.kiro/commands/`                   |
| Qoder       | 项目 `.qoder/skills/`、`.qoder/commands/`                 |

安装方式极为简单：`npm install -g openmole`，然后在目标项目中执行 `openmole init` 即可完成 IDE 配置。技术栈采用 Markdown + YAML frontmatter 编写 skill 和 command，CLI 使用 Node.js ESM，plugin 运行时零第三方依赖。

## 过程

OpenMole 将完整的坏味道驱动重构过程分为五个阶段，每个阶段有独立的工作区和输出物：

```
openmole/
├── config.yaml              # current_change · installed_ides
└── changes/
    ├── <change-name>/
    │   ├── badsmells.md
    │   ├── tasks.md
    │   └── analysis.md
    └── archive/
```

借鉴 OpenSpec 的做法，每次发起 BDR 重构都会创建一个独立的 change，change 的名称可由用户指定或由 AI 根据重构内容自动提炼。五个阶段通过以下命令驱动：

**Explore（`mole:explore`）**。对遗留系统的代码库展开探索，依据重构宪法定义的第一性原则（清晰、一致、可读、复用、扩展、健壮、安全、简单），结合面向对象设计原则（SOLID、迪米特法则等）和目标语言的最佳实践，系统性地识别代码坏味道。每条坏味道按元规约格式写入 `badsmells.md`，包含稳定 ID、位置、现象描述、对齐原则、消除标准和风险约束。每个 change 的坏味道规约即为该轮重构的唯一事实源。

**Plan（`mole:plan`）**。针对坏味道规约中标记为“未清除”的条目，将其分解为可执行的重构任务，输出 `tasks.md`。每条任务须能追溯到 `badsmells.md` 中的条目 ID，写清依赖关系、完成定义（DoD）、涉及路径和具体步骤。任务按风险等级和依赖关系分阶段组织：从快速清理、异常修复、配置规范化，到重复代码消除、大型重构，再到安全加固和代码规范。

**Verify（`mole:verify`）**。对坏味道规约和重构任务进行交叉验证。每当 `badsmells.md` 的版本或内容发生变化，verify 环节自动执行差分分析：比对坏味道条目集合与任务列表，检查是否存在遗漏任务、孤儿任务或过时的完成定义。发现不一致时，严格遵循“先改文档、后改代码”的黄金准则。

**Apply（`mole:apply`）**。执行重构任务。每个任务严格执行标准步骤：先确定测试覆盖（无测试则补写），运行测试确保全绿，在测试保护下实施最小必要重构以消除指定坏味道，再次运行测试验证未破坏既有功能，最后经用户确认才能继续下一任务。这套“识别—补测—测绿—重构—再测绿”的闭环形成了重构的绝对底线。

**Archive（`mole:archive`）**。对已完成的 change 进行归档。archive 会检查当前 change 中所有坏味道是否已消除，所有任务是否已完成。若有未完成的项，会提示用户确认是否仍要归档。归档后的 change 移入 `changes/archive/` 目录，作为项目重构历史的永久记录。

五个阶段形成闭环工作流：`mole:explore` 生成坏味道规约，经人工审阅后进入 `mole:plan` 分解任务，再经人工审阅进入 `mole:verify` 交叉验证，验证通过后通过 `mole:apply` 执行重构，每个任务经用户确认后继续，全部完成后执行 `mole:archive` 归档。

## 效果

为了验证 OpenMole 的实际效果，我在 GitHub 上选择了一个开源项目 [roncoo-pay](https://github.com/roncoo/roncoo-pay)——一款使用 Java 开发的在线支付系统。该项目包含多个模块（common-core、service、web-boss、web-merchant、web-gateway、app-notify、app-reconciliation 等），代码规模适中，且有明显的历史积累痕迹，是验证 BDR 方法的理想素材。

执行 `mole:explore` 后，AI 对全项目代码库进行了系统扫描，生成了坏味道规约文档，共识别出 32 条坏味道，按类别分为：

**重复代码（Duplicated Code，8 条）**。包括四个 web 模块各自维护一份 90% 相同代码的 BaseController；六个完全相同模式的 ConfigUtil 静态配置类（每个都是 private static Properties + static 初始化吞异常 + public static readConfig）；五个枚举类各自 copy-paste 了 toMap()、toList()、getEnum() 等方法的相同实现；六个文件中存在相同的 MD5 工具逻辑；三套相互独立的 HTTP 客户端工具包；两个 ServiceImpl 中相同的 getMerchantNotifyUrl 方法；ReconciliationCheckBiz 中金额对比逻辑 copy-paste 了三次；两个模块中相同包名、相同类名的 ActiveMQ 监听器配置。

**大型类和方法（Bloaters，4 条）**。DateUtils 巨型类 1486 行约 60 个方法；RpTradePaymentManagerServiceImpl 是 1532 行的 God Class，承担 8 种以上职责；ReconciliationCheckBiz.baseOnBank() 方法 116 行嵌套 5 层循环；4 个方法参数超过 16 个，其中 sealRpTradePaymentRecord 达 19 个参数。

**耦合问题（Couplers，4 条）**。BaseDaoImpl.getStatement() 将类名与 MyBatis XML namespace 强耦合；DAO 层越权设置 entity.editTime；Spring Bean 通过 public static 字段暴露访问绕过依赖注入；createMistake() 方法通过“至少有一个为 null”的隐式约定区分三种调用路径。

**异常处理（Exception Handling，4 条）**。DateUtils 中 8 处异常吞没返回 null，一处甚至使用空 catch 块；MD5Util 计算失败时返回明文密码；6 个 ConfigUtil 的 static 初始化吞没异常导致 fail-silent；全项目 15 处以上的 e.printStackTrace() 和 30 多个控制器使用 generic catch。

**不良实践（Bad Practice，7 条）**。public static 可变配置字段暴露全局状态；7 个 public static SimpleDateFormat 线程不安全；使用 Java 9 已移除的 sun.misc.BASE64Decoder；所有枚举提供 setDesc() 允许运行时修改；main() 方法留在生产类中；中英文注释混用和 snake_case 参数命名；大量魔法数字和魔法字符串。

**面向对象问题（3 条）**。贫血领域模型（实体类全是 getter/setter 无业务行为）；控制层 @Autowired 字段注入和 BaseDao 泄露 SqlSessionTemplate；纯内存 ID 生成方法标记 @Transactional。

**安全问题（2 条）**。MD5 用于密码哈希；e.printStackTrace() 可能泄露支付密钥等敏感信息。

`mole:plan` 阶段将 32 条坏味道分解为 31 个重构任务，按风险等级和依赖关系分为九个阶段：阶段一快速清理（移除 main()、@Transactional、sun.misc API、枚举 setter、枚举重复方法），阶段二异常处理修复，阶段三配置与状态管理规范化（ConfigUtil 迁移 Spring @ConfigurationProperties、消除 public static 可变字段、修复线程安全问题），阶段四重复代码消除（统一 MD5、HTTP 客户端、提取 NotifyUrlBuilder、AbstractActiveMqListenerConfig、金额对比方法、统一 BaseController），阶段五大型重构（拆分 DateUtils、ReconciliationCheckBiz 超长方法、消除长参数列表、拆分 God Class），阶段六耦合修复，阶段七领域模型提升，阶段八安全加固（MD5 升级 BCrypt），阶段九代码规范（命名规范化、消除魔法数字）。

在 `mole:apply` 阶段，AI 按照任务顺序逐项执行。以阶段一的快速清理为例：B-T01 移除了三个生产类中的 main() 方法；B-T02 移除了纯内存 ID 生成方法上浪费事务资源的 @Transactional 注解，补写了 ID 生成测试并验证全绿；B-T03 将 sun.misc.BASE64Decoder/Encoder 替换为 java.util.Base64 标准 API，确保项目在 Java 9+ 上可编译。每个任务完成后，AI 自动更新 tasks.md 中的完成状态并填写修订历史。

从 roncoo-pay 的实际效果来看，OpenMole 展现了三项核心价值：

第一，**让 AI 重构变得可审计**。每一次重构都有规约可查、有任务可追、有测试可验。重构不再是“AI 改完就忘”的黑箱操作，而是可追溯、可回滚的工程活动。

第二，**显著降低重构的认知负荷**。面对一个完全陌生的遗留代码库，开发者无需逐个文件阅读才能判断哪里需要改、怎么改。OpenMole 自动完成代码扫描、坏味道识别、任务分解和交叉验证，开发者只需要做决策和确认。

第三，**形成可持续的代码质量治理机制**。项目在持续开发过程中，新的坏味道不可避免。OpenMole 的 change 机制和跨 change 去重能力，使得团队可以定期发起新的重构周期，每次聚焦一批坏味道，小步迭代地持续提升代码质量，而不是等到代码债台高筑后再发动一场伤筋动骨的“大重构”。

从方法论到框架再到实际验证，BDR 走的是一条从个人实践出发、提炼为可复用工具、再回到真实项目中检验的路。坏味道从来不是目的，可维护、可验证、可持续演进的代码才是。BDR 的底层逻辑很简单：在 AI 时代，若没有一个和代码同权的规约层，“重构”最容易退化成不可审计的聊天。把坏味道上升为重构的“纲”，让规约走在前面——SDD 已经证明了这条路在产品上走得通，BDR 说的是：重构也值得同等待遇。

欢迎大家访问遵循BDR方法的开源框架[openmole](https://github.com/agiledon/openmole)。


软件工程的现实是：上线运行的代码才是真正说了算的“事实源”。需求文档和设计图写得再漂亮，也敌不过代码仓库里日积月累的坏味道。在 AI 辅助编程越来越普及的今天，我们面临一个两难困境：AI 很乐意帮你大改特改，但它未必守得住“外部行为不变”这条重构底线。

OpenMole：坏味道驱动重构的工程化实践

创始人/CEO

编程语言

架构设计

开发工具

坏味道驱动重构(BDR)提出将代码坏味道作为重构的事实源，通过OpenMole框架实现AI辅助重构。该框架将重构过程分为探索、规划、验证、应用和归档五个阶段，确保重构可审计、可追溯。实际案例显示，BDR能有效识别重复代码、大型类等32种坏味道，分解为31个重构任务，显著降低认知负荷并形成可持续的代码质量治理机制。

软件工程

GitHub

Agent

Java

2026年中大促 | AI 领航 智绘未来

tcap

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenMole：坏味道驱动重构的工程化实践-腾讯云开发者社区-腾讯云

OpenMole：坏味道驱动重构的工程化实践

OpenMole：坏味道驱动重构的工程化实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐