AI 开发时代的简要重构范式，一个指令完成重构，始终保证项目可验证性和稳定性
在 AI 辅助编程（Vide Coding）快速普及的今天，很多开发者产生了一个错觉：既然 AI 能帮我写代码，那我的代码结构是否乱一点也无所谓？反正 AI 能读懂。
事实恰恰相反。
在 AI 协作时代，项目代码的模块化和可验证性，不仅没有过时，反而成为了决定开发效率和系统稳定性的核心准则。
本文将结合我们在 PushPen 项目中的重构实践，深入探讨这一话题。
1. 重构：从“能跑就行”到“可持续演进”
重构不是为了追求某种代码美学，而是为了扩展的稳定。
随着功能不断叠加，系统会不可避免地产生“技术熵增”。如果不对代码进行周期性的重构，系统最终会进入“技术破产”状态：开发者不敢动代码，AI 也会因为上下文过于混乱而给出错误的建议和操作。
通过重构，我们将混乱的单体逻辑拆解为清晰的模块架构，保证可验证性、可测试性，这本质上是在为 AI 建立**“操作索引”**。
2. 单一职责原则（SRP）：AI 开发的最小信任单元
在我们的重构指南中，SRP 被提升到了前所未有的高度：
- 函数级 SRP：一个函数只干一件事。
- 文件级 SRP：一个文件只干一类事。
- 编排与执行分离：入口文件（如
main）只负责挂载和编排，不实现具体业务。
为什么要这样做？
因为 AI 的上下文窗口是有限的。当你要求 AI 修改一个拥有 1000 行逻辑、职责混杂的文件时，它很容易迷失在细节中。但如果你给它一个职责单一、逻辑闭环的小模块，它的生成准确率接近 100%。
单一职责，就是你与 AI 之间建立的“最小信任单元”。
众多个最小信任单元，就能组成一个复杂的大软件。软件的复杂性不大于大，不在于代码多，而在于项目管理混乱。
3. 结构化与编排：指挥官与士兵
一个维护良好的项目，其结构应该是“指挥官（Orchestrator）”与“士兵（Services/Utils）”的关系。
- Services：实现核心业务逻辑（如 Git 同步、文件解析）。
- Utils：提供无状态的通用工具（如路径处理、格式转换）。
- Main/App：作为指挥官，像路由文件，只负责调用这些模块实现业务流程的编排。
这种分离让逻辑变得**“可组合”**。当 AI 知道士兵们都在哪里、各司其职时，它就能更有效地帮你调度这些士兵去打新的胜仗。
4. 可验证性与可测试性：AI 时代的“防撞墙”
在 AI 时代，代码生成的量级呈指数级增长。如果没有自动化测试，人工审计这些代码的时间成本将高得惊人。
我们强调：每一个新功能，必须配套单元测试。
- 结构化：决定了代码好不好测。
- 可验证性：决定了你敢不敢合并 AI 生成的代码。
- mise 指挥官：通过
mise保证语言环境一致性，确保“在我的机器上能跑，换一台电脑也能跑”。
没有测试的代码是不可信的。在 AI 时代，**“自动化测试”就是保护系统不被错误代码冲垮的最后一道“防撞墙”。**而 因为 AI 的参与，编写测试代码和运行测试，成本变得极其低廉，甚至低到可以忽略不计。在 AI 开发时代，编写测试代码甚至都应该与撰写业务代码强绑定，变成一项硬性要求都不过分。
小结
AI 不是为了让我们变懒，而是为了让我们能站在更高的维度思考系统的设计，让我们更快地完成项目开发。当人类有汽车后，骑马就变成了娱乐，但汽车和马作为运输工具并没有区别的区别，这是我们开车时应有的常识认知。
当我们坚持单一职责、重视代码结构、强化自动化验证时，我们其实是在为 AI 提供一套清晰的“安全操作手册”。只有当代码变得更有序，AI 才能真正释放出它那排山倒海般的生产力。
在这个 AI 大航海时代，代码是写给人看的，也是写给 AI 读的。让它变简单，就是对自己最大的负责。
最后，附上我在 Antigravity 中使用的 refactor workflow，将它保存在项目的.agent/workflows 目录，向 AI Agent 发出 /refactor 指令就可以使用它了。当然，如果你觉得它有什么不完善的地方，还可以修改。
---
description: 系统级代码模块化重构指南，确保符合单一职责原则 (SRP)
---
# 🚀 系统级重构工作流 (Refactoring Workflow)
本工作流旨在指导 Antigravity 对项目代码进行模块化重构，确保在维持功能 100% 一致（黑盒等效）的前提下，实现高标准的模块化、可维护性、可验证性。
## ⚠️ 核心准则：绝对的单一职责原则 (SRP)
1. **函数级 SRP**：一个函数只做一件事。
2. **文件级 SRP**：一个文件只处理一类强相关的事物。
3. **编排与执行分离**：编排文件（如 main）只负责组织模块，不包含具体逻辑。
## 🚫 绝对禁令
- **禁止删除功能**：严禁丢失、阉割或改变原有业务逻辑。
- **禁止擅自删除代码**：对于疑似“僵尸代码”，须使用 `// TODO: [Antigravity 疑义]` 标记并请示人类朋友。
## 📋 执行步骤
### 1. 代码全盘分析 (Analyze & Map)
- 扫描源文件，识别 Utils、Services、Handlers/Controllers。
- 梳理数据流向与依赖关系树。
### 2. 制定重构蓝图 (Architectural Planning)
- 输出重构后的目录树结构图，并简要标出文件用途。
- 明确每个模块的“单一职责”，并在文件头部添加说明。
### 3. 模块化拆解 (Extraction & Isolation)
- 提取配置与常量：将硬编码的配置提取到独立配置文件（如 `.pushpen/config.toml`），并使用 `mise` 指定工具链版本。
- **Vue 组件重构**：
- 编排组件：大页面组件应作为容器，仅负责逻辑组织。
- 功能组件：将 template、script、style 封装在单一 `.vue` 文件中，但职责必须单一。
- 组合式函数：复杂逻辑应提取到 `useXxx` 组合式函数中。
- **抽离 Utils/Helpers**：提取无状态通用工具函数。
- **抽离 Services**：将核心业务逻辑拆解为独立模块。
- **抽离 Data Access**：隔离 API 请求、数据库查询、文件读写等。
#### 4. 验证与演练 (Verify)
- **单元测试强制化**：
- 每一个新 Service 或重构后的逻辑必须配套测试用例。
- 使用 mise 保证不同系统之间的编程语言环境一致，实现目录自足。在 `.mise.toml` 中定义 `test` 命令，确保可以一键运行所有检查。
- 开发者在分阶段提交前，必须运行并通过自动化测试。
### 4. 路由与主干重组 (Orchestration in Main)
- 改造入口文件为纯粹的“指挥官”，仅负责流程编排。
### 5. 注释、审计与锁定 (Annotation & Audit)
- 为每个新文件添加模块级注释。
- 为核心函数添加 JSDoc/Docstring 注释。
- **文件锁定机制**：在文件头添加 `lock` 属性：
- `lock: true` 表示测试通过，不可修改。
- `lock: false` 或向开发者请示后方可修改。
- 审计僵尸代码并打上 `TODO: [Antigravity 疑义]` 标签。
