我开源了个不一样的AI编码插件CodeSpec，让 vibe coding 不再痛苦

前言

用 AI 写代码这事儿，真的是 vibe coding 一时爽，一直 vibe 一直爽。

但用多了就会发现问题：

• 需求讲完了，但是 AI 理解偏了，得人工去审核AI写的代码
• AI 一口气生成了成百上千行代码，可是根本跑不起来，开始人工检查错误

这时候可能就有聪明的同学马上会跳出来反驳

"理解偏了，你再纠正一下，让 AI 重新写啊"

"跑不起来你就把报错贴给 AI，让 AI 自己排查啊"

的确，这个应对方式几乎是下意识的，我一开始也是这么想、这么做的

But， 这么处理之后，并没有解决问题，AI 重写之后往往会暴露出更多细节问题，不是交互方式不对、就是 UI 不对；AI 自己排查之后，确实能跑了，可当你点击某个按钮或输入框时，新的报错立刻就出现；

结果就是 token 一直烧，需求一直 delay

那咋办？就没办法了？

NO NO NO，办法有的，有的，兄弟

既然 AI 不能很好的理解需求，我们就让它先去做需求分析；

既然 AI 写的代码容易出 bug，我们就让它写完再仔仔细细 review 一番

于是乎，我做了 CodeSpec：

一个规格驱动开发（SDD）、技术栈无关、支持断点续做、可扩展、半自动，覆盖需求规格到代码交付的 AI 全流程编排插件

核心思路很简单：让 AI 按规范、按流程执行，别一上来就想开始写代码。

项目地址: LucivHuang/CodeSpec

注意，这是个 Claude Code 插件

这里说个题外话，如果你用不了 Claude 大模型，也是可以使用 Claude Code 的，这俩不是一个东西；Claude Code + DeepSeekV4 性价比直接拉满

CodeSpec 是如何工作的

CodeSpec 把 AI 开发流程拆成 6 个不同阶段，每个阶段只干一件事：

黄色标记的阶段是强制暂停点，需要你做决策才能继续。

这个插件跟我以往的开源项目一样，同样是可扩展的

你可以在 6 个阶段的任意位置插入你想要的阶段，比如：在规格生成前，可以 DIY 一个读取你们内部需求文档的指令

1. 规格生成

这个阶段作为初始阶段，是用来做需求分析的

你需要给一个需求描述，AI 会自动分析并生成一份结构化的功能规格说明 spec.md。

比如你说"新增一个用户个人资料页面"，它会输出：

## 功能概述

用户可以查看和编辑个人资料，包括头像、昵称、邮箱

## 功能边界

- 支持：头像上传（≤2MB）、昵称修改、邮箱修改
- 不支持：密码修改（已有独立页面）

## 用户场景

1. 用户点击导航栏头像 → 进入个人资料页
2. 点击头像区域 → 上传新头像 → 实时预览
   ...

这一步的作用是为了 把模糊需求沉淀为明确的文档

注意，这一步生成的文档只是初步文档，还不是定稿

2. 需求澄清

AI 读完上一步的 spec 文档后，会主动找出需求模糊的地方，并询问你

还是继续个人资料页的例子，在这个阶段AI可能会问你：

Q1: 头像上传失败时如何处理？
  A. 显示错误提示，保留原头像
  B. 回退到默认头像
  C. 其他

Q2: 昵称是否有长度限制？

你回答完后，它会在 spec 文档里加上具体的需求锚点（RQ-001、RQ-002...）

经过这一步修改后的 spec.md 就是定稿了，后续的所有阶段都会基于这个文档进行，生成的每个任务、代码都能对应上文档内的需求锚点。

3. 方案设计

到了这一步，AI 已经完全搞懂需求了，准备开始设计方案

AI 会先扫描你的代码，了解你现有的架构，然后结合需求给出 2-3 个实现方案供你选择：

## 方案 A：复用现有 ProfileForm 组件

优点：开发快，风格统一
缺点：组件较重，可能需要拆分

## 方案 B：新建轻量级 ProfileEditor

优点：独立可控，性能更好
缺点：需要重新实现表单验证逻辑

## 方案 C：...

这一步需要你做出决策，从 AI 提供的方案中选出一个

当然，你也可以不选，直接给出另一套方案或者是去微调 AI 给出的方案

在你确定了方案后，AI 会自动生成 plan.md 文档，详细描述实现方案的细节

产生的文档同样是给后续阶段使用的，这一步能有效避免 AI 自作主张选了个你不想要的技术方案的问题。

4. 任务拆解

方案有了，接下来就是要实现它

AI 会根据你选定的方案，把工作拆成一个个具体的任务：

- [ ] 创建 ProfileEditor 组件 (RQ-001, RQ-002)
- [ ] 实现头像上传逻辑 (RQ-003)
- [ ] 添加表单验证 (RQ-004)

每个任务都会关联到 spec 文档中的需求锚点

拆分好任务以后，AI 还会询问你的意见，让你确认任务划分是否合理、是否有遗漏之类的

如果都没问题就会生成 tasks.md，并进入下一阶段，AI 就开始写代码了

5. 代码实现

这一步就没啥说的了，AI 会严格按照任务清单（tasks.md）逐个实现，每完成一个就打上标记。

6. 代码审查

代码写完了，最后一步就是检查代码质量

AI 会从以下 7 个维度审查代码：

• 功能完整性（是否满足所有需求）
• 代码质量（命名、结构、复杂度）
• 错误处理
• 性能
• 安全性
• 测试覆盖
• 文档

问题按 P0/P1/P2 分级，P0 为必须修复，P1 是建议修复，P2 可选。

最后生成一份审查报告review-report.md

这一步虽然能发现问题，但也只是代码层面的问题，如果想检查运行时是否有 bug，还是建议在阶段 6 之后自己 DIY 一个自动化测试的扩展

（因为自动化测试牵扯到特定的技术栈了，我这里就没纳入核心阶段）

关键设计

聊完插件如何工作，聊一下插件的几个关键设计

人在回路

这是插件的核心设计

介绍 6 个核心阶段的时候，聪明的同学应该留意到了

这个工作流存在三个明显的强制暂停点：

1. 需求澄清
2. 方案选择
3. 任务确认

当然，故意设置这些点不是为了给你添堵

而是为了 让你在关键的决策点适时地介入

在主观层面上与AI对齐需求，避免 AI 误入歧途，在错误的道路上越走越远

技术栈无关

这也是插件的核心设计

6个阶段不硬编码任何框架或是语言

项目信息都从以下两个地方获取：

1. 自动扫描：读取目标项目的 package.json、pom.xml 等配置文件
2. 记忆文件：.codespec/memory/ 下存放的项目规范、技术栈、历史偏好等前置内容（插件自动获取）

所以不管你是前端、后端、移动端、还是嵌入式开发，通通都能使用这个工作流插件。

可扩展

这也也是插件的核心设计

虽然 6 个核心阶段是固定的，但你还是可以通过 Hook Points 在任意位置强行插入你的扩展

如下图所示

你可以选择在规格生成前，让 AI 自动从 jira 获取需求传递给阶段 1，也可以在代码审查结束后，让 AI 做自动化测试

配置如下：

{
  "extensions": {
    "stages": [
      {
        "id": "fetch-jira",
        "name": "从 Jira 获取需求",
        "command": [你的自定义命令],
        "runBefore": 1,
        "onFailure": "block"
      },
      {
        "id": "e2e-test",
        "name": "运行 E2E 测试",
        "command": [你的自定义命令],
        "runAfter": 6
      }
    ]
  }
}

有了扩展能力，你就能轻松将 Jira、Linear、Figma、CI/CD 等外部系统，以及自动跑测试、部署等，通通加到工作流里来。

断点续做

这也也也是插件的核心设计

因为在每个阶段完成后，会有相应的文档产生，并且状态会持久化到 .workflow-state.json

所以，如果工作流在执行时被意外中断了（比如：落班了）

下次你再打开时，直接运行 /codespec:workflow ，AI 会自动检测是否存在未完成的工作流

然后问你是否继续，如果选 "是" 就会从上次中断的地方继续运行，不需要重新再跑一遍完整工作流

实际使用

快速开始

1. 安装 Claude Code

如果你还没有 Claude Code，就需要先装一下下

npm install -g @anthropic-ai/claude-code

具体配置我就不写了，随机抓一个 AI 问一下

2. 安装 CodeSpec

# 添加插件市场
/plugin marketplace add https://github.com/LucivHuang/CodeSpec.git

# 安装插件：
/plugin install codespec@codespec-marketplace

2. 使用

/codespec:workflow 新增用户个人资料页面功能

第一次运行

直接跑 /codespec:workflow，它会引导你初始化项目：

1. 问你有没有特殊规范（编码规范、分支规范、Commit 规范等）
2. 扫描项目结构，识别技术栈
3. 自动生成 .codespec/memory/constitution.md 和 project-context.json

这里生成的两个文件都是可以自己手动修改的，之后每次跑工作流，AI 都会遵循这些规范

你可能会觉得，你这不就是 CLAUDE.md 吗？

我知道你很急，但你先别急，继续往下看嘛

分步执行

所有阶段都是可以独立运行的，防止你对哪个阶段生成的结果不满意

/codespec:specify 新增用户个人资料页面功能
/codespec:clarify
/codespec:plan
/codespec:tasks
/codespec:implement
/codespec:review

完成后微调

工作流完成之后，如果还需要修改

不需要重新跑，只要执行一下 refine 命令

/codespec:refine 把登录超时从30s改为60s

它会基于现有的 spec 和 plan 做局部调整，不会再重新跑一遍完整流程。

和其他工具的区别

我们这里需要做一下区分，主流的工作流工具粗暴的划分一般分为两类

一类是与 CodeSpec 有本质区别的非 SDD 的工作流，典型的就是 Anthropic 官方推出的 feature-dev

另一类，就是同为 SDD 的工作流，例如 SpecKit、OpenSpec

vs 非 SDD 的工作流

我们就以 feature-dev 为例进行对比吧

维度	feature-dev	CodeSpec
开发范式	探索式，边理解边实现	SDD，规格文档驱动全流程
适合场景	单次会话能完成的中小功能	跨会话的大型功能开发
上手成本	零配置，一条命令启动	首次使用，插件自动初始化项目规范
需求管理	口头确认后直接探索	结构化 spec.md + 交互式澄清
任务追踪	无，直接实现	tasks.md 逐项执行、标记进度
中断恢复	不支持，中断需从头开始	自动持久化状态，断点续做
项目记忆	无	自动积累团队或个人的编码规范、代码模式、偏好

vs SDD 的工作流

这里我直接从 SpecKit 与 OpenSpec 的社区中收集到的几类痛点问题当做维度做横向对比

1. Spec 漂移

问题：围绕"spec vs code 谁是 source of truth"争论 8 个月无共识。spec 写完就过时，多轮迭代后 spec 链变成没人读的历史档案

• SpecKit: 未解决
• OpenSpec: archive 命令部分缓解
• CodeSpec: Spec 的定位不是系统的永久描述，而是 AI 到人的理解校验协议，允许用后即弃

2. 实现后修改流程缺失

问题：没有官方的 post-implementation 修改流程，用户不知道实现完发现问题该怎么办

• SpecKit: 无
• OpenSpec: 无
• CodeSpec: 小修小补可以使用 refine 命令，需要重新设计可以单独执行 plan 等命令

3. Brownfield 项目适配

问题：SDD 工具普遍假设 Greenfield，也就是只适合新开项目，对存量代码库适配差

• SpecKit: 确实没有适配 Brownfield 场景
• OpenSpec: 同上
• CodeSpec: Plan 阶段内置 code-exploration，AI 先分析现有代码结构再出方案，无论 Greenfield 还是 Brownfield 都适用

4. 单向管道无法回退

问题：如题，原文是："Do we back out and update the specs/plan and redo everything?"

• SpecKit: 无状态机，基本无法回退
• OpenSpec: 同上
• CodeSpec: 支持从任意阶段重新开始，即单独执行命令，无需从头开始执行完整流程

一些思考

与其说是思考，不如说是问答 （提前堵住你们的嘴）

小需求的成本浪费

就一句话，小需求直接 vibe coding 或者手动改吧，真没必要上什么工作流插件了

CodeSpec 本质是模拟现实开发团队的工作模式，更适合复杂需求的开发工作

信任边界问题

具体表现就是不清楚该在工作流哪些环节信任 AI、哪些环节需要人工介入

这个问题应该所有 AI 工具都存在

我这里把边界设在了 “理解” 与 “执行” 之间

• 不信任 AI 的需求理解：通过需求分析（规格生成）与需求澄清让 AI 展示它对需求的理解，人再介入审查
• 不信任 AI 的设计决策：具体方案设计时，由 AI 起头，给出多项方案，最后由人介入选择或调整
• 信任 AI 执行：当需求理解透彻了，方案清晰了，就可以让 AI 自行完成了

这也是为什么在本可以完全自动化运行的工作流中加入了暂停点

在主观判断环节人工把关，在客观执行环节放手

为什么是 Claude Code

为什么 CodeSpec 要选择做 Claude Code 的插件？因为它很火啊

下表是 AI 总结的

工具	定位	核心能力	适用场景	局限性
GitHub Copilot	代码补全助手	行级/函数级补全、Chat 对话	日常编码、快速补全	无工具调用、无 Agent 系统、无法编排复杂工作流
Cursor	AI-first IDE	多文件编辑、Composer 模式	快速原型开发、重构	闭源、无插件系统、工作流固定、成本较高
Windsurf (Codeium)	AI IDE	Cascade 多步骤编辑	类似 Cursor 的场景	工作流不可定制、无 Agent 编排能力
通义灵码	国产代码助手	代码补全、Chat、单元测试	国内用户、中文友好	工具调用能力弱、无复杂工作流支持
CodeGeeX	开源代码助手	多语言补全、免费	预算有限的个人开发者	模型能力较弱、无高级编排功能
Baidu Comate	企业级助手	代码补全、知识库集成	企业内部开发	生态封闭、定制能力有限
Claude Code	可编程 AI 工具	原生工具调用、Agent 系统、插件机制	复杂工作流、自动化、深度定制	需要一定学习成本

Claude Code 无疑是编码领域 Harness 做的最出色的了

这里再强调一下，Claude 模型（opus 4.7、sonnet等） 与 Claude Code 不是一个东西；然后，DeepSeek API 是兼容 Anthropic 的接口的，也就是说你完全可以在 Claude Code 中使用 DeepSeekV4，我也很推荐这么玩，因为便宜

最后

好的工具不是让 AI 做所有事，而是让 AI 做它擅长的事（生成代码、分析代码、提供方案），让人做人擅长的事（决策、判断、权衡）。而好的工具链，是让你可以用最合适的工具和最合适的模型，完成最合适的任务。Claude Code 提供了稳定的基础设施，CodeSpec 提供了结构化的流程。二者结合，让 AI 辅助编程真正变得实用。

上面这段话是AI写的，写的真好啊（doge）

但你要说它会不会取代人类？

要我说，那不一定，起码在学会玩抽象之前，它还取代不了我