Claude Code + React 19 全栈入门：从组件到部署全实战

node --version   # 应输出 v18.x 或更高
npm --version    # 应输出 9.x 或更高

# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

wsl --install
# 重启后打开 Ubuntu 终端继续

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

brew install claude-code

claude --version
# 应输出类似 claude-code/1.x.x

claude

export ANTHROPIC_API_KEY="sk-ant-api03-..."

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc

mkdir ~/taskflow && cd ~/taskflow
claude

> 帮我用 Vite 创建一个 React 19 项目，使用 TypeScript 模板，项目名叫 taskflow

npm create vite@latest . -- --template react-ts
npm install

✔ 帮我用 Vite 创建一个 React 19 项目...
> Running: npm create vite@latest . -- --template react-ts
> Running: npm install
✅ 项目已创建，React 19 + TypeScript + Vite 就绪

graph TD
    A[Claude Code REPL] --> B[普通输入模式]
    A --> C[Shift+Enter: 多行输入]
    A --> D[斜杠命令: /xxx]
    B --> B1[直接提问或下指令]
    C --> C1[粘贴代码块/多步指令]
    D --> D1[执行内置命令]
    D --> D2[/clear /compact /init]
    D --> D3[/model /review /vim]

> 检查 package.json，确认 React 版本是 19.x，如果不是就升级

> 运行 /init 生成项目配置文件

# TaskFlow - 任务管理应用

## 技术栈
- React 19 + TypeScript
- Vite 构建工具
- CSS Modules 样式方案
- Vitest 单元测试

## 项目结构
- `src/components/` - React 组件，每个组件一个目录
- `src/hooks/` - 自定义 Hooks
- `src/types/` - TypeScript 类型定义
- `src/utils/` - 工具函数

## 编码规范
- 使用函数式组件 + Hooks
- 组件文件名使用 PascalCase
- 工具函数文件名使用 camelCase
- CSS 类名使用 BEM 命名
- 所有组件必须有 TypeScript 类型

## 命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm run test` - 运行测试
- `npm run lint` - 代码检查

graph BT
    A["CLAUDE.md<br/>(项目根目录)"] -->|最高优先级| B[".claude/rules/*.md<br/>(模块化规则)"]
    B --> C["~/.claude/CLAUDE.md<br/>(全局用户配置)"]
    C --> D[".claude/settings.json<br/>(项目设置)"]
    D -->|最低优先级| E["~/.claude/settings.json<br/>(全局设置)"]

    style A fill:#4CAF50,color:#fff
    style B fill:#66BB6A,color:#fff
    style C fill:#81C784,color:#fff
    style D fill:#A5D6A7,color:#333
    style E fill:#C8E6C9,color:#333

> 设计一个任务管理应用的数据模型。任务(Task)有以下属性：
> - id: 唯一标识
> - title: 任务标题
> - description: 任务描述（可选）
> - status: 待办/进行中/已完成
> - priority: 高/中/低
> - createdAt: 创建时间
> - updatedAt: 更新时间
> 
> 请创建 TypeScript 类型定义文件 src/types/task.ts

// src/types/task.ts

export type TaskStatus = 'todo' | 'in-progress' | 'done';
export type TaskPriority = 'high' | 'medium' | 'low';

export interface Task {
  id: string;
  title: string;
  description?: string;
  status: TaskStatus;
  priority: TaskPriority;
  createdAt: string;
  updatedAt: string;
}

export type CreateTaskInput = Omit<Task, 'id' | 'createdAt' | 'updatedAt'>;
export type UpdateTaskInput = Partial<CreateTaskInput> & Pick<Task, 'id'>;

> 创建一个 useTasks 自定义 Hook，管理任务的 CRUD 操作。
> 使用 useState 管理状态，支持添加、删除、更新、筛选任务。
> 初始数据包含 3 个示例任务。文件放在 src/hooks/useTasks.ts

> 创建以下组件，全部使用 CSS Modules：
> 1. TaskBoard - 看板布局，三列展示不同状态的任务
> 2. TaskCard - 单个任务卡片，显示标题、优先级标签、操作按钮
> 3. TaskForm - 添加/编辑任务的表单，包含标题、描述、优先级选择
> 4. FilterBar - 筛选栏，按优先级和状态筛选任务
>
> 每个组件一个目录，包含 index.tsx 和 styles.module.css
> 主入口 App.tsx 组装所有组件

> 允许在 src/components/ 目录下创建文件，不需要每次确认

{
  "permissions": {
    "allow": [
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm run *)"
    ]
  }
}

> 为 TaskCard 添加以下交互：
> 1. 点击卡片展开详情（使用 React 19 的 <details> 原生支持）
> 2. 拖拽排序功能（用 HTML5 Drag and Drop API）
> 3. 删除前弹出确认对话框
> 4. 状态切换时有过渡动画

> 启动开发服务器，打开浏览器看看效果

npm run dev

  VITE v6.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

flowchart TD
    A[开始新任务] --> B{任务相关吗？}
    B -->|是，继续当前会话| C[直接提问]
    B -->|否，全新任务| D["/clear 清除上下文"]
    D --> E[开始新话题]
    C --> F{上下文太长？}
    F -->|是| G["/compact 压缩"]
    F -->|否| H[继续工作]
    G --> H

    style D fill:#FF9800,color:#fff
    style G fill:#FF9800,color:#fff
    style A fill:#4CAF50,color:#fff

graph LR
    A[任务复杂度] --> B[简单：格式化/小修改]
    A --> C[中等：新功能/调试]
    A --> D[复杂：架构设计/重构]

    B --> E["Haiku<br/>快速且便宜"]
    C --> F["Sonnet<br/>平衡之选"]
    D --> G["Opus<br/>最强推理"]

    style E fill:#81C784
    style F fill:#FFB74D
    style G fill:#E57373

> 做一个好看的页面

> 创建一个任务看板页面，要求：
> - 三列布局：待办、进行中、已完成
> - 每个任务卡片显示标题、优先级色标（高红/中黄/低绿）
> - 支持拖拽移动任务到不同列
> - 响应式设计，移动端纵向排列
> - 参考 Trello 的视觉风格，圆角卡片 + 柔和阴影

动作 + 具体需求列表 + 技术约束 + 视觉/风格参考

> 配置 Vitest 测试环境，安装 @testing-library/react 和 jsdom。
> 创建一个测试示例文件验证配置是否正确

> 为 useTasks Hook 编写完整的单元测试：
> - 测试初始状态包含 3 个示例任务
> - 测试添加任务
> - 测试删除任务
> - 测试更新任务状态
> - 测试按优先级筛选
> - 测试按状态筛选
> 使用 vitest 和 @testing-library/react-hooks

> /review 检查整个项目的代码质量，重点关注：
> 1. TypeScript 类型安全性
> 2. React 19 最佳实践
> 3. 性能问题（不必要的重渲染）
> 4. 可访问性（a11y）

graph TD
    A[权限模式] --> B["🟢 Allow<br/>自动批准，无需确认"]
    A --> C["🟡 Ask<br/>每次执行前询问"]
    A --> D["🔴 Deny<br/>完全禁止"]

    B --> B1["例：读取项目内文件"]
    C --> C1["例：执行 npm 命令"]
    D --> D1["例：删除文件、访问敏感路径"]

    style B fill:#4CAF50,color:#fff
    style C fill:#FF9800,color:#fff
    style D fill:#F44336,color:#fff

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Read(.env*)",
      "Write(.env*)"
    ]
  }
}

# 启用沙箱运行（推荐用于不信任的项目）
claude --sandbox

taskflow/
├── CLAUDE.md                    # Claude Code 项目配置
├── .claude/
│   └── settings.json            # 权限和工具配置
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── src/
│   ├── main.tsx                 # 应用入口
│   ├── App.tsx                  # 根组件
│   ├── App.module.css
│   ├── types/
│   │   └── task.ts              # 类型定义
│   ├── hooks/
│   │   └── useTasks.ts          # 任务管理 Hook
│   ├── components/
│   │   ├── TaskBoard/
│   │   │   ├── index.tsx
│   │   │   └── styles.module.css
│   │   ├── TaskCard/
│   │   │   ├── index.tsx
│   │   │   └── styles.module.css
│   │   ├── TaskForm/
│   │   │   ├── index.tsx
│   │   │   └── styles.module.css
│   │   └── FilterBar/
│   │       ├── index.tsx
│   │       └── styles.module.css
│   └── utils/
│       └── id.ts                # ID 生成工具
├── __tests__/
│   ├── useTasks.test.ts
│   └── TaskCard.test.tsx
└── public/
    └── favicon.svg

flowchart LR
    A["1. 创建项目<br/>npm create vite"] --> B["2. 配置 Claude<br/>CLAUDE.md"]
    B --> C["3. 定义类型<br/>src/types/"]
    C --> D["4. 构建 Hook<br/>src/hooks/"]
    D --> E["5. 开发组件<br/>src/components/"]
    E --> F["6. 测试验证<br/>npm run test"]
    F --> G["7. 代码审查<br/>/review"]
    G --> H["8. 构建部署<br/>npm run build"]

    style A fill:#E3F2FD
    style B fill:#E8F5E9
    style C fill:#FFF3E0
    style D fill:#F3E5F5
    style E fill:#FFEBEE
    style F fill:#E0F7FA
    style G fill:#FFF9C4
    style H fill:#C8E6C9

import { TaskBoard } from './components/TaskBoard';
import { useTasks } from './hooks/useTasks';
import styles from './App.module.css';

function App() {
  const {
    tasks,
    addTask,
    deleteTask,
    updateTask,
    filterByStatus,
    filterByPriority,
  } = useTasks();

  return (
    <div className={styles.app}>
      <header className={styles.header}>
        <h1>TaskFlow</h1>
        <p className={styles.subtitle}>
          用 Claude Code 构建的任务管理器
        </p>
      </header>
      <TaskBoard
        tasks={tasks}
        onAddTask={addTask}
        onDeleteTask={deleteTask}
        onUpdateTask={updateTask}
        onFilterByStatus={filterByStatus}
        onFilterByPriority={filterByPriority}
      />
    </div>
  );
}

export default App;

> 帮我将项目部署到 Vercel。先构建确认没有错误，然后用 Vercel CLI 部署

npm run build
npx vercel --prod

✓ Build successful.
🔍 Deploying...
✅ Production: https://taskflow-xxx.vercel.app

sequenceDiagram
    participant D as 开发者
    participant CC as Claude Code
    participant FS as 文件系统
    participant BR as 浏览器

    D->>CC: 描述需求
    CC->>CC: 分析上下文 & 规划
    CC->>D: 展示计划（待审批）
    D->>CC: 确认执行
    CC->>FS: 创建/修改文件
    CC->>D: 展示变更结果
    D->>CC: 提出调整或新需求
    CC->>FS: 执行修改
    CC->>BR: 启动 dev server 预览
    D->>CC: /review 审查代码
    CC->>D: 审查报告
    D->>CC: 确认构建
    CC->>FS: npm run build