# ai-coder-demonstration

**Repository Path**: rymaker/ai-coder-demonstration

## Basic Information

- **Project Name**: ai-coder-demonstration
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 全流程开发实战指南

从想法到产品，用 Claude Code + Spec Workflow + Figma + Debug 打通完整开发链路。

## 📋 目录

- [核心思想](#核心思想)
- [为什么需要全流程工作流](#为什么需要全流程工作流)
- [第一步：从想法到文档](#第一步从想法到文档)
- [第二步：用 Spec Workflow 把需求变成可执行规格](#第二步用-spec-workflow-把需求变成可执行规格)
- [第三步：Figma 设计与 HTML 原型验证](#第三步figma-设计与-html-原型验证)
- [第四步：进入 Claude Code 编写代码](#第四步进入-claude-code-编写代码)
- [第五步：Debug 验证整条链路](#第五步debug-验证整条链路)
- [实战案例：CMS 工期管理系统](#实战案例cms-工期管理系统)
- [工具选择与最佳实践](#工具选择与最佳实践)

---

## 核心思想

**开发效率低，很多时候不是因为代码写得慢，而是因为上下游信息传递失真。**

传统流程里常见的问题：
- 文档写完了，设计没跟上
- 设计有了，代码理解偏了
- 代码写出来了，和需求不一致
- 开始 debug 时才发现前面每一步都埋了坑

这套方法的核心理念：
> **让每一步都成为下一步的高质量输入，而不是让 AI "自由发挥"。**

---

## 为什么需要全流程工作流

### 传统流程的四类问题

#### 1. 需求不清晰
需求文档写得像愿景，不像可执行说明。开发拿到之后，还是得靠猜。

#### 2. 设计与实现脱节
Figma 里看起来很完整，但没有明确状态、交互逻辑、异常情况。最后前端只能"脑补"。

#### 3. AI 生成代码缺乏约束
如果直接让 AI "帮我做一个页面"，结果往往是：
- 风格不统一
- 结构不可维护
- 和真实需求偏差很大
- 后续改动成本高

#### 4. Debug 被动发生
很多人把 debug 当成最后一步，但实际上，debug 应该是贯穿全流程的验证机制。

### 解决方案

**一套可追踪、可拆解、可验证、可迭代的开发方法：**

```
文档 → Spec → HTML → Figma → Code → Debug
```

---

## 第一步：从想法到文档

在写代码之前，先写清楚：

- 这个产品是给谁用的
- 用户要完成什么任务
- 页面有哪些关键模块
- 每个模块的输入输出是什么
- 成功路径是什么
- 异常路径是什么

这一步的意义：
> **文档不是为了存档，而是为了减少误解。**

---

## 第二步：用 Spec Workflow 把需求变成可执行规格

`@pimzino/claude-code-spec-workflow` 的核心价值：
> **把需求从"描述"升级成"规格"。**

### 描述 vs 规格

- **描述**：告诉别人你想要什么
- **规格**：明确告诉系统应该怎么做

### 规格带来的好处

1. **降低歧义**：功能边界更明确，页面结构更稳定
2. **方便分阶段推进**：可以按模块拆分任务，而不是一口气生成整站
3. **让代码更可控**：AI 输出会更接近真实项目需要的结构

### Spec Workflow 使用方法

```bash
# 安装
npm install -g @pimzino/claude-code-spec-workflow

# 初始化项目
cd your-project
claude-code-spec-workflow

# 启动 Claude Code
claude
```

在 Claude Code 中：

```
# 建立项目上下文
/spec-steering-setup

# 创建功能 spec
/spec-create cms-schedule-management "构建一个 CMS 工期管理系统..."

# 执行任务
/spec-execute 1 cms-schedule-management

# 查看进度
/spec-status cms-schedule-management
```

### Spec 输出结构

- `requirements.md`：用户故事 + 验收标准
- `design.md`：技术架构、接口设计、关键流程图
- `tasks.md`：原子化、易于 AI 执行的开发任务

---

## 第三步：Figma 设计与 HTML 原型验证

### 传统设计的问题

设计师从空白画布开始设计，经常遇到：
- 信息结构不确定，反复调整版式
- 内容不明确，用占位符导致尺寸预估不准
- 没有代码约束，设计出"好看但难实现"的效果

### 优化流程：先 HTML 后 Figma

#### 1. Claude Code 生成纯 HTML

基于 spec 生成静态 HTML 页面（如 `index.html`、`about.html` 等）：
- 完整的 HTML 标签结构
- 基础的 class 命名约定
- 内容的占位数据
- 基本的响应式布局

**重要说明**：这个阶段生成的是**纯静态 HTML 文件**，不是 Nuxt 项目。

#### 2. 启动微型服务器

```bash
# 使用 npx 上的微型服务器
npx serve@latest .

# 或使用 http-server
npx http-server -p 3000 .

# 或使用 live-server（带热刷新）
npx live-server --port=3000
```

#### 3. 使用 `/implement-design` 同步到 Figma

```text
/implement-design http://localhost:3000/index.html
/implement-design http://localhost:3000/about.html
```

逐个页面执行 `/implement-design` 命令，配合 Figma 的 `html.to.design` 插件，将 HTML 同步到 Figma。

### 配置 Figma MCP 连接

首次使用时：

```bash
# 查看已配置的 MCP 服务
claude mcp list

# 添加 Figma MCP 服务
claude mcp add --transport  http figma-server http://127.0.0.1:3845/mcp

# 首次使用时登录 Figma
claude mcp list
# 会提示打开 Figma 授权页面，完成登录
```

### 这个环节的价值

- **HTML 验证了信息架构**，设计师只需要处理视觉
- **HTML 提供了真实内容尺寸**，设计师能准确预估版式空间
- **HTML 明确了技术边界**，设计师知道哪些布局是可实现、哪些需要妥协

> **这不是让 AI 做设计工作，而是让 AI 为设计工作打底子。**

---

## 第四步：进入 Claude Code 编写代码

当文档、spec、Figma（以及从 HTML 同步来的结构）都准备好之后，才是 Claude Code 发挥最大价值的时候。

### 两种不同的思路

- ❌ **让 AI 直接替你"完成项目"** → 得到的是 demo
- ✅ **让 AI 按照规格"实现项目"** → 更接近真正可以迭代的产品

### 代码实现方式

在 spec workflow 生成的设计文档里，遵循结构：
- 明确的页面目标
- 已经拆好的模块
- 清晰的视觉参考
- 已定义的交互逻辑
- 约束好的实现范围

逐步完成页面开发。

### 数据库设计规范

对于数据库操作，建议采用：

**ORM 让我们写得更抽象，SQL 让我们看得更清楚。**

在 spec workflow 生成的设计文档里：
- **表结构 SQL**：`CREATE TABLE` 完整语句，包含字段类型、默认值、注释、索引、外键约束
- **TypeORM 实体定义**：用装饰器定义实体
- **SQL 操作示例**：增删改查的实际 SQL
- **API 与 SQL 对应关系**：每个 API 对应的 SQL 语句一览表
- **复杂查询 SQL**：统计类查询、前台列表查询等

---

## 第五步：Debug 验证整条链路

> **debug 的本质，不只是修技术错误，而是发现链路中哪一步出现了偏差。**

### Debug 分成四层

#### 第一层：运行级问题
- 页面打不开
- 依赖报错
- 构建失败
- 接口异常

#### 第二层：功能级问题
- 按钮能点但逻辑不对
- 页面切换和预期不一致
- 某个状态没处理

#### 第三层：体验级问题
- 信息层级混乱
- 用户不知道下一步做什么
- 动效和反馈缺失
- 阅读节奏断裂

#### 第四层：需求级问题
- 做出来的东西和最初目标不一致
- 某一屏看着对，但没有真正传达核心信息
- 功能存在，但价值表达不清楚

### Debug 在 AI 协作中的价值

AI 可以帮助做交叉核对：
- 对照 spec 检查实现是否完整
- 对照设计稿检查 UI 是否偏移
- 对照需求判断功能是否跑偏
- 对照实际行为分析 bug 发生的原因

---

## 实战案例：CMS 工期管理系统

### 项目概述

一个贯穿演示案例，用于展示完整开发流程：
- 技术栈：Nuxt + Pinia + TypeORM + MySQL
- 前后台都要有，形成完整闭环
- 前台使用 Vue 3 开发，不使用 UI 组件库
- 页面基于远程 HTML 参考进行结构开发，再用 SCSS 完成视觉实现
- 后台负责项目、阶段、任务、工期、风险等内容维护
- 前台负责项目概览、进度展示、节点状态和工期信息呈现

### 数据库设计

#### 创建数据库

```sql
CREATE DATABASE IF NOT EXISTS cms_schedule_management
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_unicode_ci;

USE cms_schedule_management;
```

#### 项目表

```sql
CREATE TABLE `projects` (
  `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY COMMENT '主键 ID',
  `name` VARCHAR(255) NOT NULL COMMENT '项目名称',
  `description` TEXT COMMENT '项目描述',
  `start_date` DATE NOT NULL COMMENT '开始日期',
  `end_date` DATE NOT NULL COMMENT '结束日期',
  `actual_end_date` DATE NULL COMMENT '实际结束日期',
  `status` ENUM('planning', 'active', 'completed', 'cancelled', 'delayed')
    NOT NULL DEFAULT 'planning' COMMENT '项目状态',
  `progress` TINYINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '进度百分比 (0-100)',
  `is_public` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否公开显示 (1:是，0:否)',
  `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX `idx_status` (`status`),
  INDEX `idx_is_public` (`is_public`),
  INDEX `idx_dates` (`start_date`, `end_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='项目表';
```

（其他表：phases、tasks、risks 结构类似，详见完整文档）

### 项目结构

```
cms-test-project/
├── components/         # Vue 组件
├── pages/            # 页面
├── server/
│   ├── api/          # API 路由
│   ├── models/       # TypeORM 实体
│   └── utils/        # 工具函数
├── stores/           # Pinia 状态管理
├── assets/           # 静态资源
├── types/            # TypeScript 类型
├── nuxt.config.ts    # Nuxt 配置
├── Dockerfile        # Docker 配置
└── docker-compose.yml # Docker Compose 配置
```

### Docker 一键启动

```bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

访问：http://localhost:40008

---

## 工具选择与最佳实践

### Claude Code 的局限性

#### 1. API 成本高昂
- 定价对个人开发者和小团队不低
- 切换到国产模型降低成本，但生成质量和理解能力会打折扣

**建议**：不要只在模型选择上纠结，而要在工具链上做优化。

#### 2. 依赖 MCP 插件生态
- 需要配置和维护多个 MCP 服务
- 某个插件故障会影响整个流程
- 学习成本高，每个插件的用法都要了解

**建议**：评估团队的资源，如果不想折腾 MCP 生态，可以看看集成了这些能力的第三方工具。

#### 3. 第三方 API 限制带来的中断风险
- 请求频率限制
- 网络不稳定
- 并发限制

**建议**：在核心环节使用更稳定的工具链，减少对不稳定 API 的依赖。

### 实践建议

#### 建议 1：Figma 环节使用 FigJam
- 使用 FigJam 快速生成设计图
- 拉到本地进行细节修改
- 减少对 Figma MCP 的依赖

**优点**：
- 降低 MCP 配置成本
- 减少网络依赖
- 设计师更习惯 FigJam 的工作流

#### 建议 2：编码环节使用第三方 AI 开发工具
经过测试，推荐两个：

**1. 腾讯的 CodeBuddy（推荐）**
- 中文文档和社区支持，上手更快
- 内置完整的 debug、file、code 能力
- 集成了腾讯云系的模型和服务
- 适合国内团队和小型项目

**2. 亚马逊的 Kiro**
- 开发时自动切换模型，避免单一 API 频率限制
- 内置 debug、file、code 解决方案
- 相当于 Claude + 一系列 MCP 的集合
- 适合需要高度定制化的大型项目

**为什么推荐这些工具？**
- 开发时自动切换模型，保证生成连续性
- 统一的工具链，debug、file、code 都在一套工具里
- 降低维护成本，不需要自己维护 MCP 服务
- 更稳定的体验，厂商会对工具做整体优化

#### 建议 3：测试阶段采用 AI 自动化 + 人工测试

**AI 自动化测试**：
- 使用 AI 生成测试用例
- 自动执行基础功能测试
- 覆盖常见的边界情况

**人工测试非常重要**：
- 真实用户场景测试
- 用户体验评估
- 业务逻辑验证

> **机器人永远不知道人类可以拿杯子装水，也可以装胡辣汤。**

---

## 总结

### 这套流程的真正价值

> **Claude Code 不是替代开发流程，AI 的真正价值是增强开发流程。**

越想把 AI 用好，越需要清晰的流程和明确的约束。

```
文档 → Spec Workflow → Figma → Claude Code → Debug
```

带来的真正价值：
- 不是让你少做事，而是让你少做无效的事
- 不是让你不思考，而是让你的思考可以被持续继承
- 不是只提升写代码速度，而是提升从想法到产品的整体成功率

### 最终建议

**先对齐需求，再让 AI 参与实现。**
**先设计结构，再追求生成速度。**
**先保证质量，再追求功能数量。**

当流程是正确的，AI 才会真正放大团队能力。

---

## 7 天试点行动清单

如果你们想把这套流程真正跑起来，建议用 7 天做一个小试点：

### Day 1：确定试点业务
- 选择一个中小模块（如：活动报名页、后台列表页）
- 明确成功标准（交付时间、缺陷率、改动成本）

### Day 2：完成需求文档
- 目标用户是谁
- 关键业务流程是什么
- 验收标准怎么定义

### Day 3：用 Spec Workflow 产出方案
- `requirements.md`
- `design.md`
- `tasks.md`

### Day 4：设计与原型
- FigJam 快速生成界面草稿
- 本地完善交互细节

### Day 5-6：Claude Code 开发 + Debug
- 按任务拆分逐步实现
- 每完成一个模块即验证
- 关键路径优先回归

### Day 7：复盘
- 与"传统开发方式"对比：效率、质量、返工次数
- 形成团队自己的最佳实践清单

---

## 相关资源

- `@pimzino/claude-code-spec-workflow`：https://github.com/pimzino/claude-code-spec-workflow
- Claude Code 官方文档
- Figma + html.to.design 插件
- CodeBuddy：腾讯云 AI 开发工具

---

**开始之前记住：** 真正能让项目成功的，不是单点工具有多强，而是清晰的流程、合适的工具、以及人的参与。