Claude 编程实战：从零到一构建“AI 驱动的待办清单”Web App

Claude 编程实战：从零到一构建“AI 驱动的待办清单”Web App

实战目标：使用 Claude 3.5 Sonnet（Claude Code） + Spec-Kit 构建支持 自然语言任务解析 + 智能分类 + 拖拽排序 + PWA 部署 的 Todo App
技术栈：Vite + React + TypeScript + Tailwind CSS + localStorage + Workbox
AI 工具：Claude Code（VS Code 插件）
时间预估：25 分钟
成果：可一键部署、可离线运行、可扩展 的生产级项目

---

项目结构

ai-todo-app/
├── .specify/                     # Spec-Kit 核心配置目录
│   ├── memory/constitution.md    # 项目宪法（质量/性能约束）
│   └── specs/ai-todo/            # 功能规格相关文件
│       ├── spec.md               # 自然语言解析的功能需求
│       ├── plan.md               # 技术栈与架构规划
│       └── tasks.md              # 分阶段任务清单
├── src/                          # 源代码目录
│   ├── components/               # UI 组件
│   │   ├── TaskInput.tsx         # 任务输入（含自然语言解析）
│   │   ├── TaskList.tsx          # 任务列表（含拖拽排序）
│   │   └── TaskItem.tsx          # 单个任务项（优先级/标签展示）
│   ├── hooks/useTasks.ts         # 任务状态管理钩子
│   ├── utils/parseTask.ts        # 自然语言任务解析工具
│   ├── service-worker.ts         # PWA 离线服务工作器
│   ├── types/index.ts            # TypeScript 类型定义
│   └── App.tsx                   # 根组件
├── public/                       # 静态资源
│   ├── icon-192.png              # PWA 图标
│   ├── icon-512.png              # PWA 图标
│   └── manifest.json             # PWA 配置文件
├── vite.config.ts                # Vite 构建配置
├── tailwind.config.ts            # Tailwind CSS 配置
├── package.json                  # 项目依赖与脚本
└── vitest.config.ts              # 单元测试配置

📌 说明：新增 types 目录规范类型定义，补充 vitest.config.ts 支持自动化测试，完善 PWA 相关资源文件。

---

第一步：一键初始化

安装步骤

# 一行命令完成项目初始化（自动集成所有技术栈）
npx create-spec-kit@latest ai-todo-app --template react-ts --ai claude# 进入项目目录
cd ai-todo-app# 验证环境（可选）
npm run dev

自动完成的工作内容

执行命令后，无需手动配置，系统自动完成以下操作：

1. 初始化 Vite + React + TypeScript 基础项目
2. 集成 Tailwind CSS 并配置基础样式
3. 安装 Spec-Kit 及 Claude Code 适配插件
4. 生成 package.json 常用脚本（dev/build/test/preview）
5. 创建 PWA 基础配置文件框架

⚠️ 注意：若提示“端口 5173 被占用”，可修改 vite.config.ts 中的 server.port 配置，指定其他空闲端口（如 5174）。

---

第二步：自然语言定义规格（智能解析需求）

操作前提

确保已安装 VS Code 及 Claude Code 插件，打开项目后启动 Claude Code 聊天面板。

执行规格定义命令

在 Claude Code 聊天框中输入以下命令，触发功能规格生成：

/speckit.specify AI Todo

输入自然语言需求

粘贴以下需求描述（可根据实际需求修改）：

1. 支持自然语言输入任务，自动解析截止日期（如‘明天’‘下周一’‘3月15日’）、优先级（高/中/低）、标签（如‘工作’‘学习’）；
2. 任务列表支持拖拽排序，排序结果持久化到本地存储；
3. 支持 PWA 安装，离线状态下可正常操作任务；
4. 新增语音输入功能，通过麦克风录入任务内容并解析；
5. 任务卡片显示优先级颜色标识（高：红色，中：黄色，低：绿色）和标签徽章。”

自动生成的核心内容

Claude 会自动创建 spec.md 文件，AI 任务解析与存储流程场景描述及流程图：

图1：AI 任务解析与存储流程

---

第三步：技术规划与任务分解

生成技术规划

执行以下命令，AI 自动生成 plan.md 文件，明确技术栈细节与架构设计：

/speckit.plan ai-todo

核心技术规划内容

## 技术栈明细
- 前端框架：React 18.2.0 + TypeScript 5.2.2
- 构建工具：Vite 5.0.0
- 样式解决方案：Tailwind CSS 3.3.5
- 本地存储：localStorage（基础数据）+ IndexedDB（PWA 离线缓存）
- 拖拽功能：SortableJS 1.15.0
- 日期处理：date-fns 2.30.0
- PWA 实现：Workbox 7.0.0
- 语音输入：Web Speech API
- 测试工具：Vitest 1.0.0## 核心架构设计
1. 状态管理：使用自定义 Hook（useTasks）封装任务 CRUD 逻辑
2. 解析层：parseTask 函数处理自然语言到 Task 对象的转换
3. 离线层：service-worker 拦截请求，缓存静态资源与任务数据
4. 交互层：组件拆分遵循单一职责，TaskInput 负责输入，TaskList 负责展示与排序

生成任务清单

执行命令自动拆分任务，标记并行任务以提升开发效率：

/speckit.tasks ai-todo

任务清单（带优先级与并行标记）

## 任务清单（按执行顺序排序）
[ ] 1. 完善 TypeScript 类型定义（Task 接口）
[P] 2. 实现 parseTask 函数及单元测试（覆盖多场景日期/优先级解析）
[P] 3. 开发 useTasks Hook（封装 localStorage 操作与任务逻辑）
[ ] 4. 开发 TaskInput 组件（支持文本输入 + 语音输入）
[ ] 5. 开发 TaskItem 组件（优先级颜色 + 标签展示）
[ ] 6. 开发 TaskList 组件（集成 SortableJS 实现拖拽排序）
[ ] 7. 配置 PWA 相关文件（manifest.json + service-worker.ts）
[ ] 8. 编写 E2E 测试用例，覆盖核心功能场景
[ ] 9. 优化 Bundle 体积，移除冗余依赖

标记 [P] 的任务可并行开发（如解析函数与状态 Hook 可同时实现）。

---

第四步：Claude 一键生成完整代码（核心模块详解）

执行代码生成命令

/speckit.implement ai-todo

Claude 会根据规格与规划生成完整代码，以下为关键模块的实现：

1. 类型定义（src/types/index.ts）

/** 任务优先级类型 */
export type TaskPriority = 'high' | 'medium' | 'low';/** 任务核心接口 */
export interface Task {id: string; // 唯一标识（UUID）title: string; // 任务标题priority: TaskPriority; // 优先级tags: string[]; // 标签数组dueDate: Date | null; // 截止日期completed: boolean; // 完成状态order: number; // 排序索引（用于拖拽排序）
}

2. 自然语言解析工具（src/utils/parseTask.ts）

import { parse, nextMonday, format, addDays } from 'date-fns';
import { Task, TaskPriority } from '../types';// 优先级映射表
const PRIORITY_MAP: Record<string, TaskPriority> = {'高': 'high','中': 'medium','低': 'low'
};// 星期映射表（用于解析“下周一”等场景）
const WEEKDAY_MAP: Record<string, number> = {'一': 1,'二': 2,'三': 3,'四': 4,'五': 5,'六': 6,'日': 0
};/*** 自然语言任务解析函数* @param input 自然语言输入字符串* @returns 解析后的 Task 对象，失败返回 null*/
export function parseTask(input: string): Task | null {try {// 输入校验：空字符串直接返回 nullif (!input