AI编程跑偏解决方案：我的高效工作流推荐

2026-06-19阅读 0热度 0

公司在开发中全面引入 Claude Code 与 DeepSeek 辅助编码后，初期团队士气高涨——效率的跃升肉眼可见。

然而蜜月期很快结束，深层问题逐一暴露。

第一个痛点：每个人使用 AI 的方式各不相同。
有人直接丢需求让模型生成，有人先要求输出方案再动手，还有人边写边反复调整。最终代码风格割裂，Code Review 时头疼不已，修改耗时远超从头重写。

第二个痛点：AI 对项目上下文一无所知。
每次开启新对话，AI 就像重置了记忆。它不知道上周刚实现的功能，不理解某个字段的设计由来，时常在已有逻辑上叠加一堆冲突代码。

第三个痛点：需求未定义清晰就开工，返工成常态。
AI 的代码生成速度极快，快到来不及确认方向是否正确，它已经堆出了大量代码。后续修改的代价比从零开始还要高。

直到我们实践了 OpenSpec，这些核心痛点才被系统性解决。

OpenSpec 实战分享：从初始化到全流程落地

一、OpenSpec 到底是什么

OpenSpec 是一套基于规范驱动开发（Spec-Driven Development）的工作流工具，核心理念极简：先定义清楚，再开始编码。在写任何代码之前，先把需求明确、方案敲定、规范对齐。

它通过 4 个命令覆盖了从探索到归档的完整开发生命周期：

/openspec-explore → 思考与探索，不修改任何代码
/openspec-propose → 将思路固化为提案（含方案、设计、任务）
/openspec-apply → 按任务清单实际编码实现
/openspec-archive → 提案完成后的归档清理

二、安装与初始化实操

2.1 安装 OpenSpec

OpenSpec 通过 npm 分发，提供三种安装方式，可根据项目场景灵活选用：

方式一：全局安装（推荐，所有项目通用）

npm install -g @fission-ai/openspec@latest
openspec --version  # 验证安装成功并查看版本号

安装完成后，即可在任何项目目录下直接调用 OpenSpec 命令。

方式二：项目级安装（仅限于当前项目）

npm install --save-dev @fission-ai/openspec

适合需要在多个项目中使用不同版本 OpenSpec 的场景。

方式三：通过 npx 直接运行（免安装、临时使用）

npx @fission-ai/openspec init

适合偶尔使用，省去安装和卸载的麻烦。

2.2 项目初始化：openspec init

安装完成后，进入项目根目录执行初始化命令：

openspec init

执行后进入交互式引导流程，关键步骤是选择你使用的 AI 编程工具，主流的工具基本都支持：

Claude Code
CodeBuddy
Cursor
Gemini
……

选择完成后，按提示重启 IDE，初始化即告完成。之后即可在编程工具中使用 /openspec-* 系列命令。

2.3 目录结构

项目初始化后，根目录下会生成 openspec/ 文件夹：

openspec/
├── changes/          # 存放所有提案（change）
│   ├── archive/      # 已归档的提案（初始为空）
│   │   ├── 2026-05-24-gantt-show-all-users/
│   ├── async-export-task/  # 进行中的提案
│   │   ├── specs/         # 当前提案的规格说明
│   │   ├── .openspec.yaml # 提案的基本信息
│   │   ├── design.md      # 设计：如何实现？前后端分别做什么？存在哪些风险？
│   │   ├── proposal.md    # 方案：为什么做？具体需求是什么？可能影响的范围
│   │   └── task.md        # 任务：拆解为每个可执行的最小单元
│   └── specs/       # 全局规格文档
└── config.yaml      # 项目全局配置文件

2.4 对接开发规范：config.yaml

这一步是整个工作流的灵魂，也是解决「AI 不遵从团队规范」问题的关键。

在 config.yaml 的 context 字段中声明开发规范文档路径，AI 在执行 propose 或 apply 时会自动读取并严格遵循这些规范：

值得一提的是，开发规范也可以让 AI 通读现有代码结构，自动生成对应的代码规范文件，从而让团队风格完全一致。

# openspec/config.yaml
context:
  前端规范: "core-file/vue-arc.md"   # 前端 Vue 开发规范
  后端规范: "core-file/java-arc.md"  # 后端 Java 开发规范
  project: "./project.md"            # 项目提案记录

配置完成后，每次执行 /openspec-propose 或 /openspec-apply，AI 都会自动读取这两份规范文档，确保生成的方案和代码始终符合项目既定标准。

2.5 初始化提案记录：project.md

project.md 是一个轻量级的提案追踪文件，核心作用是解决「AI 失忆」问题。

它记录当前项目已完成哪些设计提案、每个提案的当前状态：

目录	日期	状态	简要说明
任务甘特图视图	2025-xx-xx	已完成	为任务模块增加甘特图展示
工时热力图	2025-xx-xx	进行中	……

变更记录表（可选）：

日期	提案名称	变更内容
2025-xx-xx	任务甘特图视图	新增移动端适配需求

在 config.yaml 中声明 project.md 路径后，AI 每次操作提案时都会自动同步这个文件。

三、四个命令的完整工作流

/openspec-explore → /openspec-propose → /openspec-apply → /openspec-archive

思考与探索 → 提案固化 → 编码实现 → 归档清理

Phase 1：/openspec-explore —— 想清楚再动手

这是整个工作流中最关键的环节，也是和「直接让 AI 写代码」的本质区别。

当你有一个模糊的需求但不确定具体方案时，先用 explore：

/openspec-explore 我想给任务模块加一个消息通知功能，但不确定推送方案怎么选

它会执行以下操作：

分析现有代码结构
绘制不同方案的对比图
帮你梳理各方案的优劣
不修改任何代码文件

等思路成熟后，告诉它「好了，帮我生成提案」，它才会调用 propose 创建正式文档。

Phase 2：/openspec-propose —— 方案固化

将 explore 阶段的思考转化为正式提案文档，包含：

Proposal：方案描述和技术决策
Design：说明如何实现方案
Tasks：拆解后的具体任务清单
Specs：涉及的接口、数据结构等技术规格

你需要做的，就是审核方案内容是否正确，确认无误后再进入执行阶段。

Phase 3：/openspec-apply —— 按计划编码

根据 proposal 中的任务列表逐项实现代码。此时 AI 会：

读取 config.yaml 中声明的开发规范
参考 project.md 了解已有提案，避免冲突
按任务顺序逐一编写代码

Phase 4：/openspec-archive —— 收尾归档

提案全部任务完成后执行归档：

标记提案状态为已完成
同步更新 project.md 记录
清理临时文件，保持工作区整洁

四、实战注意事项

4.1 规范先行，编码在后

不要跳过 config.yaml 的 context 配置。将开发规范接入看似多了一步，但它能避免后续大量返工。这是保证 AI 生成代码质量最简单有效的方式。

4.2 project.md 是团队的「共享记忆」

即便只有一个人开发，project.md 也极具价值：

快速回顾「这个功能之前是否做过？」
避免重复提案
方便新人了解项目演进历史

保持其简洁性——一张表格就够，不需要复杂格式。

4.3 充分利用 explore，别急着写代码

OpenSpec 最大的价值不在自动生成代码，而在 explore 阶段强制进行深度思考。多数 bug 和返工本质上源于「没想清楚就开始写」。给 explore 阶段留足时间，让它帮你画对比图、分析现有代码、理清思路，这笔时间投入会在后续开发中连本带利地省回来。

4.4 变更要留痕

当提案在执行过程中发生范围变更或任务调整时，及时在 project.md 的变更记录表中追加一行。复盘时能清楚理解「为什么最终做出来的和最初设想的不一样」。

总结

采用 OpenSpec 之后，团队在 AI 辅助开发中最显著的变化是：

AI 不再失控：每次操作都有规范约束，代码风格高度统一
不再重复踩坑：project.md 让 AI 具备了「项目记忆」
返工大幅减少：explore 阶段把方向想清楚再动手，比「写了再改」节省大量时间

如果你的团队也在使用 AI 辅助开发，并且遇到了类似问题，不妨尝试这套工作流。