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

30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度最近在独立开发一个前后端分离的 Todo 应用时我深刻体会到了“一人分饰多角”的困境既要写产品文档、设计数据库又要实现前端界面和后端接口还得考虑部署和测试。每个环节都需要切换思维模式效率低下不说文档和代码还经常脱节。直到我尝试了CodexSpec Coding这套组合拳才发现 AI 辅助开发已经进化到了可以系统性管理整个软件生命周期的阶段。它不仅仅是生成代码片段而是将产品意图Spec转化为可执行的开发计划并引导开发者一步步完成实现。本文将带你从零开始通过一个完整的企业级 Todo 应用实战体验如何用 CodexSpec 单人搞定产品、设计、前后端开发、测试乃至部署的全流程真正实现“AI 重构前端全栈新标准”。本文适合有一定前端或全栈开发基础希望提升个人开发效率、探索 AI 工程化实践的开发者。无论你是独立开发者、小团队的技术负责人还是对 AI 编程充满好奇的探索者都能从中获得一套可复用的方法论和实战经验。1. 背景与核心概念从 Vibe Coding 到 Spec Coding在深入实战之前我们有必要厘清几个关键概念理解为什么 CodexSpec Coding 代表了下一代开发范式。1.1 传统开发流程的瓶颈传统的软件开发尤其是全栈项目通常遵循“需求分析 - 设计 - 编码 - 测试 - 部署”的线性流程。对于独立开发者或小团队而言这个流程存在几个痛点上下文切换成本高开发者需要在产品经理、架构师、前端、后端、运维等多个角色间频繁切换思维容易断裂。文档与代码脱节设计文档PRD、原型图一旦写完很少同步更新最终代码实现与最初设想往往南辕北辙。AI 辅助的局限性直接使用 GitHub Copilot 或 ChatGPT 进行“Vibe Coding”即兴编码虽然能快速生成代码片段但缺乏整体规划和上下文一致性生成的代码可能风格不一、难以集成且无法保证符合业务逻辑。1.2 什么是 Spec CodingSpec 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 CLIcodex-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 --forcecontext-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 * ORMPrisma * 数据库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 会做几件事分析specification.md和requirements.md。结合tech.md和structure.md制定一个分阶段的实施计划。将计划拆解为具体的、有依赖关系的任务并保存到tasks.json。输出计划概览 (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.tsJWT 验证中间件。更新server/src/app.ts以使用路由和中间件。查看进度 随时可以使用以下命令查看整体进度和计划概览codex-spec status # 或 codex-spec plan-summary4.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-10AI 会生成client/src/views/RegisterView.vue和client/src/views/LoginView.vue页面组件。client/src/stores/auth.tsPinia Store 用于管理用户认证状态。client/src/api/client.tsAxios 实例配置和拦截器。client/src/api/auth.ts封装register和loginAPI 调用。更新client/src/router/index.ts配置路由。更新client/src/App.vue添加路由视图和导航。4.5 联调与测试最后执行联调任务codex-spec execute task-11这个任务可能会提示你安装并初始化 Prisma 客户端、生成数据库迁移。cd server npx prisma generate npx prisma migrate dev --name init提示你启动后端服务器 (npm run dev) 和前端开发服务器 (npm run dev)。可能会生成一个简单的测试脚本或 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 开发工作流时你可能会遇到一些典型问题。问题现象可能原因排查思路与解决方案codex-spec命令无响应或报 API 错误1. OpenAI API Key 未设置或无效。2. 网络连接问题。3. API 额度用尽。1. 检查环境变量echo $OPENAI_API_KEY。2. 尝试curl测试 OpenAI API 连通性。3. 登录 OpenAI 平台检查额度与账单。AI 生成的代码无法运行语法错误1. 项目上下文 (tech.md,structure.md) 描述不清或过时。2. AI 模型理解偏差。1.更新上下文运行codex-spec context-update --auto或手动更新.codex-specs/context/下的文件确保技术栈和目录结构准确。2.人工修正将 AI 视为高级助手生成的代码需要经过审查和微调。修正后上下文也可能随之更新。生成的任务计划不合理或缺失步骤初始规格 (specification.md) 不够详细或存在歧义。1.细化规格重新编辑specification.md将功能描述得更具体明确输入、输出、边界条件。2.分而治之将一个大的功能规格拆分成多个更小、更具体的规格分别创建和执行。执行任务时AI 对已有文件做出了意外的更改AI 在理解代码上下文时可能出错。1.使用--read-only模式先预览 AI 将要做的更改而不实际写入。codex-spec execute task-xx --read-only。2.版本控制是生命线务必在 Git 仓库中操作。执行任何任务前确保当前更改已提交或暂存以便随时回退。前端/后端服务启动失败1. 依赖未安装。2. 端口冲突。3. 环境配置错误如数据库连接。1. 分别进入client/和server/目录运行npm install。2. 检查server/.env文件中的DATABASE_URL和端口配置。3. 查看终端报错信息通常是依赖缺失或语法错误。数据库操作失败Prisma1. 数据库未初始化。2. Prisma Client 未生成。3. 模型定义与数据库不同步。1. 在server/目录下运行npx prisma generate生成客户端。2. 运行npx prisma migrate dev --name init创建数据库和表。3. 使用npx prisma studio可视化查看数据。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 生成的代码可能缺乏完善的错误处理如数据库连接失败、网络异常。你需要补充。性能与优化检查数据库查询N1 问题、循环复杂度等。符合规范检查代码风格是否与团队规范一致。7.4 将 Spec Coding 融入团队流程对于小团队这套流程可以极大提升协同效率。需求评审会产出初步的specification.md。技术规划共同维护tech.md和structure.md。AI 生成计划使用codex-spec plan生成任务列表作为 sprint 待办事项的参考。开发与审查开发者执行任务同时进行代码审查。AI 生成的代码可作为高质量的“初稿”。上下文同步任何架构或规范的变更都应及时更新到共享的上下文文件中。7.5 生产环境注意事项环境隔离确保tech.md中区分开发、测试、生产环境的配置。敏感信息永远不要将 API Keys、数据库密码等写入上下文文件或让 AI 处理。使用环境变量和.env文件。测试覆盖Spec Coding 擅长生成业务代码但单元测试、集成测试仍需开发者重点编写和维护。可以在规格中明确要求 AI 生成测试用例但需仔细审查。CI/CD 集成可以将codex-spec的某些检查步骤如上下文一致性检查集成到 CI 流水线中。通过本次从零到一的实战我们体验了如何利用 CodexSpec Coding 将产品意图自动化地转化为可运行的全栈代码。这套方法论的核心价值不在于替代开发者而是重构开发流程将开发者从重复性、模式化的编码中解放出来更专注于架构设计、复杂逻辑和创造性的问题解决。它要求开发者具备更强的抽象能力编写清晰的规格和审查能力从而在“一人全栈”或小团队协作中实现效率的质的飞跃。下一步你可以尝试用这套流程去构建更复杂的模块如任务提醒、数据统计、多租户等并探索如何将自动化测试、部署脚本也纳入到 Spec 驱动的流程中打造真正端到端的 AI 辅助工程体系。 30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度