从Vibe Coding到Spec Coding：AI驱动全栈开发的工程实践

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Claude 随心用，限时 5 折。 👉 点击领海量免费额度

最近在独立开发一个前后端分离的 Todo 应用时，我深刻体会到了“一人分饰多角”的困境：既要写产品文档、设计数据库，又要实现前端界面和后端接口，还得考虑部署和测试。每个环节都需要切换思维模式，效率低下不说，文档和代码还经常脱节。直到我尝试了Codex+Spec Coding这套组合拳，才发现 AI 辅助开发已经进化到了可以系统性管理整个软件生命周期的阶段。它不仅仅是生成代码片段，而是将产品意图（Spec）转化为可执行的开发计划，并引导开发者一步步完成实现。本文将带你从零开始，通过一个完整的企业级 Todo 应用实战，体验如何用 Codex+Spec 单人搞定产品、设计、前后端开发、测试乃至部署的全流程，真正实现“AI 重构前端全栈新标准”。

本文适合有一定前端或全栈开发基础，希望提升个人开发效率、探索 AI 工程化实践的开发者。无论你是独立开发者、小团队的技术负责人，还是对 AI 编程充满好奇的探索者，都能从中获得一套可复用的方法论和实战经验。

1. 背景与核心概念：从 Vibe Coding 到 Spec Coding

在深入实战之前，我们有必要厘清几个关键概念，理解为什么 Codex+Spec Coding 代表了下一代开发范式。

1.1 传统开发流程的瓶颈传统的软件开发，尤其是全栈项目，通常遵循“需求分析 -> 设计 -> 编码 -> 测试 -> 部署”的线性流程。对于独立开发者或小团队而言，这个流程存在几个痛点：

• 上下文切换成本高：开发者需要在产品经理、架构师、前端、后端、运维等多个角色间频繁切换，思维容易断裂。
• 文档与代码脱节：设计文档（PRD、原型图）一旦写完，很少同步更新，最终代码实现与最初设想往往南辕北辙。
• AI 辅助的局限性：直接使用 GitHub Copilot 或 ChatGPT 进行“Vibe Coding”（即兴编码），虽然能快速生成代码片段，但缺乏整体规划和上下文一致性，生成的代码可能风格不一、难以集成，且无法保证符合业务逻辑。

1.2 什么是 Spec Coding？Spec Coding，即规格驱动开发，其核心思想是将清晰、结构化的规格说明（Specification）作为开发的唯一可信源。AI 不再是随意发挥的“代码补全工具”，而是严格遵循 Spec 的“执行引擎”。一个完整的 Spec 通常包含：

• 产品需求：功能描述、用户故事、验收标准。
• 技术设计：系统架构、技术栈选型、API 设计、数据库 Schema。
• 实施计划：拆解后的具体任务、依赖关系、优先级。

1.3 Codex 与 codex-spec 工具

• OpenAI Codex：一个强大的 AI 模型，擅长理解和生成代码。它是 GitHub Copilot 背后的核心技术之一。
• codex-spec：一个基于 Node.js 的命令行工具（即搜索材料中提到的项目），它构建在 Codex 等 AI 模型之上，实现了 Spec Coding 的工作流自动化。它的价值在于：
  • 流程化：将“意图 -> 规格 -> 计划 -> 代码”的流程固化。
  • 上下文感知：为 AI 提供持续更新的项目上下文（产品背景、技术栈、代码结构），确保生成的代码符合项目现状。
  • 任务追踪：将大功能拆解为小任务，并跟踪执行状态。

1.4 新工作流对比传统流程：需求 -> (人工设计) -> (人工编码) -> 代码Vibe Coding：模糊描述 -> AI生成代码 -> 人工修改集成Spec Coding：产品意图 -> AI生成Spec -> AI生成计划 -> AI引导编码 -> 一致性代码

接下来，我们将通过构建一个具备用户认证、任务管理的全栈 Todo 应用，来完整演练这套新流程。

2. 环境准备与版本说明

工欲善其事，必先利其器。以下是本次实战所需的环境和工具，请确保你的开发机已满足以下条件。

2.1 基础运行环境

• 操作系统：macOS / Linux (WSL2) / Windows。建议使用 macOS 或 Linux 以获得最佳命令行体验。
• Node.js：版本 >= 16。这是运行codex-spec工具的基础。推荐使用nvm管理 Node 版本。
• 包管理器：npm或yarn。本文示例使用npm。
• 代码编辑器：VS Code。确保已安装项目相关的插件（如 ESLint、Prettier、Vue/React 扩展等）。
• Git：用于版本控制和codex-spec的自动上下文更新。

2.2 AI 相关服务与工具

• OpenAI API Key：这是驱动codex-spec的核心。你需要注册 OpenAI 平台并获取 API Key。请注意保管，不要泄露。
• codex-spec CLI 工具：我们将全局安装这个核心工具。
• 可选：Codex CLI：如果你本地安装了 OpenAI 的 Codex CLI，codex-spec可以与之集成。但非必需，工具会默认使用 OpenAI API。

2.3 项目技术栈说明本次实战将构建一个现代化的全栈应用，技术栈选型兼顾流行度和codex-spec的演示效果：

• 前端：Vue 3 + TypeScript + Vite + Element Plus
• 后端：Node.js + Express + TypeScript + Prisma (ORM)
• 数据库：SQLite (开发环境) / PostgreSQL (生产环境建议)
• 认证：JWT (JSON Web Token)

2.4 环境变量配置将你的 OpenAI API Key 设置为环境变量，这是后续所有操作的前提。

# Linux/macOS export OPENAI_API_KEY='你的-api-key-here' # 可以将其添加到 ~/.bashrc 或 ~/.zshrc 中永久生效 # Windows (PowerShell) $env:OPENAI_API_KEY='你的-api-key-here' # 或在系统环境变量中设置

设置完成后，可以通过echo $OPENAI_API_KEY(Linux/macOS) 或echo $env:OPENAI_API_KEY(PowerShell) 来验证。

3. 核心工具安装与初始化

现在，我们来安装并初始化本次实战的核心引擎——codex-spec。

3.1 安装 codex-spec打开终端，执行以下命令进行全局安装：

npm install -g codex-spec

安装完成后，验证安装是否成功：

codex-spec --version # 或查看帮助 codex-spec --help

如果看到命令列表和版本信息，说明安装成功。

3.2 创建并初始化项目为我们的全栈 Todo 应用创建一个全新的项目目录，并初始化为 Git 仓库（这对codex-spec的上下文更新功能很重要）。

# 创建项目目录 mkdir ai-todo-fullstack && cd ai-todo-fullstack # 初始化 Git 仓库 git init # 初始化 codex-spec 项目上下文 codex-spec context-setup --force

context-setup --force命令会在当前目录下创建.codex-specs/文件夹，并生成三个核心的上下文文件：

• .codex-specs/context/product.md: 用于描述产品愿景、目标用户、核心价值。
• .codex-specs/context/tech.md: 用于定义技术栈、架构决策、开发规范。
• .codex-specs/context/structure.md: 用于描述项目的目录结构、模块划分。

3.3 编写初始项目上下文工具生成的上下文文件是空的，我们需要手动填充初始信息，这是 AI 理解我们项目的基础。这是 Spec Coding 中“对齐意图”的关键一步。

编辑.codex-specs/context/product.md：

# 产品上下文：智能全栈 Todo 应用 ## 产品愿景 打造一款极简、高效、跨平台的任务管理工具，帮助个人和轻量级团队清晰规划每日工作，并通过智能建议提升完成效率。 ## 目标用户 1. 独立开发者、自由职业者。 2. 小型创业团队或项目组。 3. 有日常任务管理需求的普通用户。 ## 核心价值主张 * **极简上手**：界面清爽，3分钟内即可开始记录任务。 * **数据私有**：支持本地部署，核心数据掌握在用户自己手中。 * **智能辅助**：基于历史任务数据，提供任务模板、时间预估等轻度智能建议。 * **全平台同步**：Web 端为主，未来可扩展移动端。 ## 核心功能范围 (MVP 1.0) 1. 用户系统：注册、登录、JWT 鉴权。 2. Todo 管理：任务的增、删、改、查、标记完成。 3. 任务列表：支持按项目、标签、状态进行筛选和查看。 4. 响应式界面：适配桌面和移动端浏览器。

编辑.codex-specs/context/tech.md：

# 技术上下文 ## 技术栈 * **前端**： * 框架：Vue 3 (Composition API) * 语言：TypeScript * 构建工具：Vite * UI 组件库：Element Plus * 状态管理：Pinia * 路由：Vue Router * HTTP 客户端：Axios * **后端**： * 运行时：Node.js (>=16) * 框架：Express.js * 语言：TypeScript * ORM：Prisma * 数据库：SQLite (开发)，PostgreSQL (生产) * 认证：JWT (jsonwebtoken) * 密码加密：bcryptjs * **开发与质量**： * 代码格式化：Prettier * 代码检查：ESLint * 版本控制：Git ## 架构风格 * 前后端分离架构 (SPA + RESTful API)。 * 前端通过 Axios 调用后端 API。 * 后端提供标准的 JSON API。 ## 代码规范 * 使用 TypeScript 严格模式。 * 遵循 Element Plus 的组件使用规范。 * API 响应格式统一为 `{ code: number, data: any, message: string }`。 * 错误处理使用 HTTP 状态码和统一的错误响应体。

编辑.codex-specs/context/structure.md：

# 项目结构上下文 ## 整体目录结构 ai-todo-fullstack/ ├── client/ # 前端 Vue 项目 │ ├── public/ │ ├── src/ │ │ ├── assets/ │ │ ├── components/ # 公共组件 │ │ ├── views/ # 页面组件 │ │ ├── stores/ # Pinia 状态管理 │ │ ├── router/ # 路由配置 │ │ ├── utils/ # 工具函数 │ │ ├── api/ # API 接口封装 │ │ └── App.vue, main.ts │ ├── index.html │ ├── package.json │ ├── vite.config.ts │ └── tsconfig.json ├── server/ # 后端 Express 项目 │ ├── src/ │ │ ├── controllers/ # 控制器 │ │ ├── middleware/ # 中间件 (如认证) │ │ ├── models/ # Prisma 模型定义 (schema.prisma) │ │ ├── routes/ # 路由定义 │ │ ├── utils/ # 工具函数 (如 JWT) │ │ └── app.ts, server.ts │ ├── package.json │ ├── tsconfig.json │ └── prisma/ │ └── schema.prisma # 数据库模型 ├── .codex-specs/ # codex-spec 工作区 (已存在) └── README.md ## 关键文件说明 * `client/vite.config.ts`: 前端构建配置。 * `server/prisma/schema.prisma`: 定义所有数据模型，是数据库的单一事实来源。 * `server/src/middleware/auth.ts`: JWT 认证中间件。

完成以上步骤后，你的项目就拥有了一个清晰的“大脑”（上下文）。接下来，AI 将基于这个大脑来理解和生成一切。

4. 实战：使用 Spec Coding 驱动全栈开发

我们将按照codex-spec的标准工作流：创建规格 -> 生成需求 -> 制定计划 -> 执行任务，来一步步构建我们的应用。

4.1 创建第一个功能规格：用户认证系统我们从一个独立且核心的功能模块开始。运行以下命令：

codex-spec create "用户认证系统" "实现用户注册、登录、JWT令牌颁发与验证、保护API接口的核心认证流程"

这个命令会与 AI 交互，基于我们之前定义的上下文，在.codex-specs/目录下生成一个以日期和功能名命名的子目录（例如2025-XX-XX_user_authentication_system），并在其中创建specification.md文件。让我们查看并理解 AI 生成的规格文档。

生成的specification.md核心内容示例：

# 规格：用户认证系统 ## 概述 本规格定义了智能全栈 Todo 应用的用户认证系统，确保用户数据隔离和安全访问。 ## 功能详情 1. **用户注册** * 端点：`POST /api/auth/register` * 输入：`username`, `email`, `password` * 处理：验证输入，密码加密存储，创建用户记录。 * 输出：成功消息或验证错误。 2. **用户登录** * 端点：`POST /api/auth/login` * 输入：`username`/`email`, `password` * 处理：验证凭证，密码比对。 * 输出：包含用户基本信息和 `accessToken` 的 JWT。 3. **令牌验证中间件** * 创建一个 Express 中间件 `authenticateToken`。 * 从 `Authorization: Bearer <token>` 头中提取 JWT。 * 验证令牌有效性，并将解码后的用户信息附加到 `req.user`。 4. **受保护的路由** * 将 `authenticateToken` 中间件应用于需要认证的 API 路由（如 Todo 相关操作）。 ## 非功能需求 * 安全性：密码必须使用 `bcryptjs` 加盐哈希存储。 * 性能：JWT 验证应高效，避免不必要的数据库查询。 * 可维护性：认证逻辑应集中，便于未来扩展（如 OAuth）。

这份规格文档已经非常结构化，它直接成为了我们开发的“蓝图”。

4.2 从规格生成详细需求与计划接下来，我们让 AI 将这份蓝图拆解成更具体的需求清单和实施计划。

# 基于规格生成详细需求文档 codex-spec requirements # 基于需求和上下文，生成可执行的开发计划 codex-spec plan

执行plan命令后，AI 会做几件事：

1. 分析specification.md和requirements.md。
2. 结合tech.md和structure.md，制定一个分阶段的实施计划。
3. 将计划拆解为具体的、有依赖关系的任务，并保存到tasks.json。
4. 输出计划概览 (plan-summary)。

查看生成的任务列表：

codex-spec tasks

你会看到一个类似下面的任务列表，每个任务都有唯一的 ID、标题、所属阶段和状态（默认为pending）。

任务列表： - task-1: [Phase 1: 后端基础] 初始化后端 Express + TypeScript 项目 (pending) - task-2: [Phase 1: 后端基础] 配置 Prisma 和 SQLite 数据库 (pending) - task-3: [Phase 2: 认证核心] 定义 User 数据模型 (Prisma Schema) (pending) - task-4: [Phase 2: 认证核心] 实现用户注册 API (pending) - task-5: [Phase 2: 认证核心] 实现用户登录与 JWT 生成 API (pending) - task-6: [Phase 2: 认证核心] 创建 JWT 认证中间件 (pending) - task-7: [Phase 3: 前端集成] 初始化前端 Vue 3 + Vite + TypeScript 项目 (pending) - task-8: [Phase 3: 前端集成] 创建注册页面组件 (pending) - task-9: [Phase 3: 前端集成] 创建登录页面组件 (pending) - task-10: [Phase 3: 前端集成] 封装认证相关的 API 调用 (pending) - task-11: [Phase 4: 联调测试] 前后端联调认证流程 (pending)

4.3 执行任务：让 AI 引导编码这是最激动人心的部分。我们不需要自己从头编写代码，而是让codex-spec引导我们完成每个任务。它会根据任务描述、项目上下文和已有代码，生成具体的代码变更。

执行第一个任务（初始化后端）：

codex-spec execute task-1

工具会开始思考，并输出它将要做的事情。由于是第一个任务，它会创建server/目录，并生成package.json,tsconfig.json,app.ts,server.ts等文件。关键点来了：它不会直接覆盖你的文件，而是会以“建议”或“交互”的方式呈现。对于新文件，它会直接创建；对于可能修改的已有文件，它会提示差异。你需要根据提示进行确认。

任务执行过程示例（简化）：

执行任务: task-1 [初始化后端 Express + TypeScript 项目] 分析上下文：技术栈为 Node.js + Express + TypeScript。 计划行动： 1. 创建 `server/` 目录。 2. 初始化 `package.json`，添加 express, typescript, ts-node, @types/express 等依赖。 3. 创建基础的 `tsconfig.json`。 4. 创建 `src/app.ts` 和 `src/server.ts` 启动文件。 开始执行... 创建文件: server/package.json 创建文件: server/tsconfig.json 创建文件: server/src/app.ts 创建文件: server/src/server.ts 任务 task-1 完成。状态: completed

现在，去查看server/目录，你会发现一个结构清晰、配置完整的 Express 后端项目骨架已经生成。app.ts中可能已经配置了基础的 JSON 解析中间件。

继续执行后续任务： 你可以按顺序执行，也可以根据依赖关系跳着执行。codex-spec能理解任务间的依赖。例如，执行task-4（实现注册 API）时，它会知道需要先有task-3定义的User模型。

# 执行定义数据模型的任务 codex-spec execute task-3

这个任务会创建或更新server/prisma/schema.prisma文件。

// server/prisma/schema.prisma generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") // 将使用 file:./dev.db } model User { id Int @id @default(autoincrement()) username String @unique email String @unique password String // 存储 bcrypt 哈希值 createdAt DateTime @default(now()) updatedAt DateTime @updatedAt todos Todo[] // 与 Todo 的一对多关系 } model Todo { id Int @id @default(autoincrement()) title String description String? completed Boolean @default(false) userId Int user User @relation(fields: [userId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

AI 不仅生成了User模型，还前瞻性地添加了Todo模型以及它们之间的关系，这得益于我们全局的“产品上下文”。

执行认证相关任务：

codex-spec execute task-4 codex-spec execute task-5 codex-spec execute task-6

这些任务会分别生成：

• server/src/routes/auth.ts：包含/register和/login路由。
• server/src/controllers/authController.ts：处理注册和登录逻辑，包含密码哈希和 JWT 生成。
• server/src/middleware/auth.ts：JWT 验证中间件。
• 更新server/src/app.ts以使用路由和中间件。

查看进度： 随时可以使用以下命令查看整体进度和计划概览：

codex-spec status # 或 codex-spec plan-summary

4.4 切换到前端任务后端认证核心完成后，我们开始前端部分。执行前端初始化任务：

codex-spec execute task-7

这个任务会在项目根目录创建client/文件夹，并用 Vite 初始化一个 Vue 3 + TypeScript 项目，自动安装vue-router,pinia,axios,element-plus等依赖。

接着，执行前端页面和 API 封装任务：

codex-spec execute task-8 codex-spec execute task-9 codex-spec execute task-10

AI 会生成：

• client/src/views/RegisterView.vue和client/src/views/LoginView.vue页面组件。
• client/src/stores/auth.ts：Pinia Store 用于管理用户认证状态。
• client/src/api/client.ts：Axios 实例配置和拦截器。
• client/src/api/auth.ts：封装register和loginAPI 调用。
• 更新client/src/router/index.ts配置路由。
• 更新client/src/App.vue添加路由视图和导航。

4.5 联调与测试最后，执行联调任务：

codex-spec execute task-11

这个任务可能会：

1. 提示你安装并初始化 Prisma 客户端、生成数据库迁移。

   cd server npx prisma generate npx prisma migrate dev --name init

2. 提示你启动后端服务器 (npm run dev) 和前端开发服务器 (npm run dev)。
3. 可能会生成一个简单的测试脚本或 Postman 集合，指导你验证注册、登录、访问受保护 API 的完整流程。

至此，一个具备完整用户认证功能的全栈 Todo 应用骨架已经搭建完毕。整个过程，你更像一个“技术负责人”和“审核者”，而 AI 扮演了“架构师”和“高级开发”的角色，负责将你的意图转化为具体的、符合项目规范的代码。

5. 扩展功能：使用相同流程开发 Todo 管理

认证系统完成后，我们可以用完全相同的流程来开发核心的 Todo 管理功能。

5.1 创建新规格

codex-spec create "Todo任务管理" "实现Todo任务的创建、读取、更新、删除、标记完成功能，并关联到已登录用户"

5.2 生成计划与执行

codex-spec requirements codex-spec plan codex-spec tasks

你会看到新的任务被创建，例如task-12到task-20，涵盖了后端 CRUD API、前端页面和组件。

5.3 执行新任务你可以选择一次执行一个任务，或者按阶段批量执行：

# 执行“后端 API”阶段的所有任务 codex-spec execute-phase "后端 API"

在这个过程中，AI 会复用已有的User模型、认证中间件，并创建Todo相关的控制器、路由，以及前端的TodoListView.vue,TodoForm.vue等组件。由于上下文是持续更新的，AI 能确保新代码的风格、技术栈与已有部分保持一致。

6. 常见问题与排查思路

在实际使用codex-spec或类似 AI 开发工作流时，你可能会遇到一些典型问题。

7. 最佳实践与工程建议

将 Spec Coding 融入日常开发，需要一些最佳实践来保证效率和代码质量。

7.1 如何编写高质量的上下文 (Context)上下文是 AI 的“知识库”，质量直接决定输出结果。

• 产品上下文 (product.md)：不仅要写功能，还要写用户画像、使用场景、业务规则和非功能需求（如性能、安全性）。这能帮助 AI 做出更合理的架构决策。
• 技术上下文 (tech.md)：尽可能详细。包括：
  • 精确的库及其版本（如”vue”: “^3.3.4″）。
  • 代码规范（命名约定、目录规范、API 响应格式）。
  • 架构图或关键设计决策（如为什么选 REST 而非 GraphQL）。
• 结构上下文 (structure.md)：保持与真实代码同步。每次大的目录结构调整后，手动更新此文件，或使用codex-spec context-update --auto（它依赖 Git diff）。

7.2 任务拆解与执行策略

• 原子化任务：鼓励 AI 创建更小、更原子的任务。一个任务最好只完成一个明确的、可验证的目标（如“创建用户模型文件”比“实现用户系统”要好）。
• 阶段性执行与验证：不要一次性执行完所有任务。每完成一个阶段（如“后端 API”），就手动运行和测试一下，确保基础稳固。
• 善用execute-phase：合理规划任务阶段，利用execute-phase批量执行同一阶段的任务，提高效率。

7.3 代码审查与质量控制AI 是强大的助手，但不是完美的工程师。生成的每一行代码都必须经过你的审查。

• 安全检查：检查 API 密钥、密码、令牌的处理是否安全（是否硬编码？）。
• 错误处理：AI 生成的代码可能缺乏完善的错误处理（如数据库连接失败、网络异常）。你需要补充。
• 性能与优化：检查数据库查询（N+1 问题）、循环复杂度等。
• 符合规范：检查代码风格是否与团队规范一致。

7.4 将 Spec Coding 融入团队流程对于小团队，这套流程可以极大提升协同效率。

1. 需求评审会：产出初步的specification.md。
2. 技术规划：共同维护tech.md和structure.md。
3. AI 生成计划：使用codex-spec plan生成任务列表，作为 sprint 待办事项的参考。
4. 开发与审查：开发者执行任务，同时进行代码审查。AI 生成的代码可作为高质量的“初稿”。
5. 上下文同步：任何架构或规范的变更，都应及时更新到共享的上下文文件中。

7.5 生产环境注意事项

• 环境隔离：确保tech.md中区分开发、测试、生产环境的配置。
• 敏感信息：永远不要将 API Keys、数据库密码等写入上下文文件或让 AI 处理。使用环境变量和.env文件。
• 测试覆盖：Spec Coding 擅长生成业务代码，但单元测试、集成测试仍需开发者重点编写和维护。可以在规格中明确要求 AI 生成测试用例，但需仔细审查。
• CI/CD 集成：可以将codex-spec的某些检查步骤（如上下文一致性检查）集成到 CI 流水线中。

通过本次从零到一的实战，我们体验了如何利用 Codex+Spec Coding 将产品意图自动化地转化为可运行的全栈代码。这套方法论的核心价值不在于替代开发者，而是重构开发流程，将开发者从重复性、模式化的编码中解放出来，更专注于架构设计、复杂逻辑和创造性的问题解决。它要求开发者具备更强的抽象能力（编写清晰的规格）和审查能力，从而在“一人全栈”或小团队协作中实现效率的质的飞跃。下一步，你可以尝试用这套流程去构建更复杂的模块，如任务提醒、数据统计、多租户等，并探索如何将自动化测试、部署脚本也纳入到 Spec 驱动的流程中，打造真正端到端的 AI 辅助工程体系。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Claude 随心用，限时 5 折。 👉 点击领海量免费额度