微型商城（Mini Mall）—— 完整演示 Claude Code 13 项核心功能（一）

这是一个完整的全栈电商项目，也是本教程的核心案例。你将在这个项目中从零构建一个可部署的 Web 应用，并依次体验 /plan、CLAUDE.md、Hook、Memory、Skill、/review、/security-review、多模型切换等 Claude Code 全部核心功能。

5.0.1 本章概述

本项目将全程演示 Claude Code 的 13 项核心功能。你不只是学会做一个商城，你还将学会如何把 Claude Code 用到极致。

5.0.2 你将学到的 Claude Code 核心功能

#	功能	是什么	什么时候用
1	/plan	让 AI 先出方案，人审核后再动手	任何复杂任务开始前
2	/init + CLAUDE.md	自动生成项目规范文档	项目搭好后，让 AI 理解你的规范
3	Task 任务列表	把大任务拆成小步骤，逐个跟踪	多步骤任务时告诉 AI “创建任务列表”
4	自定义 Skill	把重复性工作封装成可复用的"操作手册"	相同的模式要重复做多次时
5	官方 Skill	使用社区维护的高质量技能	需要前端设计、文档生成等专业能力时
6	Hook 配置	让 AI 在特定操作前后自动执行命令	每次改完代码想自动格式化时
7	Memory 系统	让 AI 记住你的偏好，越用越懂你	你的技术偏好、项目约定
8	/review	让 AI 审查代码质量	每完成一个功能模块后
9	/security-review	安全检查：密码、认证、漏洞	认证模块完成 + 上线前
10	多模型切换	简单任务用便宜模型，复杂任务用强模型	省钱 + 提效
11	权限模式	控制 AI 的操作权限	保护你的代码不被意外修改
12	Git 工作流	版本控制，随时能"后悔"	每个功能完成后提交一次
13	环境变量管理	API 密钥、数据库连接等敏感信息	任何需要连接外部服务的项目

5.0.3 我们要做什么

一个微型电商网站，包含：

买家视角：浏览商品 → 搜索筛选 → 查看详情 → 注册登录 → 加入购物车 → 下单 → 模拟支付 → 查看订单
管理员视角：商品管理（增删改查）→ 订单管理（状态流转）→ 分类管理

5.0.4 技术栈说明

层面	选型	为什么选它
框架	Next.js 16	前后端一体化，一个项目搞定全部
语言	TypeScript	类型安全，AI 写代码时能自动发现低级错误
数据库	SQLite + Prisma 5	SQLite 零配置，Prisma 让数据库操作像写作文一样直观
样式	TailwindCSS 4	无需写 CSS 文件，直接在标签上加样式类名
认证	自制 Cookie Session	比第三方库更透明，能看到认证的每一步

提示： 为什么不用 MySQL/PostgreSQL？ SQLite 是一个单文件数据库，不需要安装数据库服务器，开箱即用。对于学习阶段和原型项目，它是完美的选择。如果将来需要迁移到 PostgreSQL，只需要改一行配置。

---

5.1 项目启动：用 /plan 做架构设计

本节目标：学会用 /plan 模式让 AI 在动手前先出方案

演示的 Claude Code 功能：/plan 模式、AskUserQuestion

5.1.1 什么是 /plan 模式，为什么重要

新手最容易犯的错误是：上来就让 AI 写代码。结果往往是 AI 写了一堆，方向偏了，又要重来。

/plan 模式的思路是先想清楚再动手：

你说"我要做什么"
  → AI 探索代码库、理解现状
  → AI 出一个详细方案
  → 你审核，确认方向正确
  → AI 按方案分步实施

这就像装修之前先出设计图——你不会让装修队直接开砸吧？

5.1.2 实际操作

在终端中进入项目目录后，启动 Claude Code：

$ claude

然后告诉它你的需求：

我要做一个微型电商项目，叫 Mini Mall。
技术栈用 Next.js 16 + TypeScript + Prisma 5 + SQLite + TailwindCSS 4。
功能包括：
- 商品浏览（列表、详情、搜索、分类筛选）
- 用户注册登录
- 购物车
- 下单和订单管理（模拟支付）
- 后台管理（商品CRUD、订单管理、分类管理）

请用 /plan 模式帮我做架构设计。

Claude Code 会进入 plan 模式，提出几个问题来确认你的需求（这就是 AskUserQuestion 功能），比如：

• 用什么语言？（TypeScript）
• 用什么样式方案？（TailwindCSS）
• 你是新手还是老手？（新手友好）

确认后，AI 会生成一份完整的架构方案，包括：

数据库设计：6 个表的 ER 关系图
页面路由：10 个页面的路径和权限
API 设计：18 个接口的请求/响应格式
项目目录结构：每个文件放哪里
实施步骤：按什么顺序开发

5.1.3 阅读和审核方案

AI 出的方案不是圣旨——你才是决策者。仔细看一下：

• 数据库设计合理吗？（用户-商品-购物车-订单的关系是否清晰）
• 页面路由符合预期吗？（有没有漏掉什么页面）
• 技术选型合适吗？（有没有过度设计）

确认无误后，告诉 AI “可以开始”。

验证：AI 输出了包含数据库设计、页面路由、API 列表的完整方案，你审核后表示同意。

5.1.4 你学到了什么

概念	说明
/plan 模式	先规划后编码，避免方向性返工
AskUserQuestion	AI 会主动问你不确定的问题，而不是瞎猜
架构方案	包含 ER 图、路由表、API 清单的完整设计文档

---

5.2 环境搭建：项目骨架 + CLAUDE.md

本节目标：创建 Next.js 项目，生成 CLAUDE.md 让 AI 始终理解你的项目

演示的 Claude Code 功能：/init、CLAUDE.md

5.2.1 创建项目

在终端执行以下命令：

# 1. 进入工作目录
cd ~/projects

# 2. 用 create-next-app 创建项目（会自动安装依赖）
npx create-next-app@latest mini-mall --typescript --tailwind --app --src-dir

# 3. 进入项目目录
cd mini-mall

# 4. 安装额外依赖
npm install prisma @prisma/client bcryptjs
npm install -D tsx @types/bcryptjs

注意： 避坑：项目路径不要用中文，否则某些工具会出奇怪的问题。

5.2.2 初始化 Prisma（数据库 ORM）

# 初始化 Prisma，选择 SQLite 作为数据库
npx prisma init --datasource-provider sqlite

这个命令会创建 prisma/schema.prisma 文件和 .env 环境变量文件。

5.2.3 CLAUDE.md — AI 的项目"说明书"

CLAUDE.md 是 Claude Code 最核心的概念之一。它是一个放在项目根目录的 Markdown 文件，每次你和 AI 对话时，AI 都会自动读取它。

你可以把 CLAUDE.md 理解为给 AI 的"项目说明书"——里面写了：

• 用了什么技术栈
• 文件怎么组织的
• 命名规范是什么
• 有什么特殊的约定

5.2.3.1 两种方式创建 CLAUDE.md

方式一：让 AI 自动生成

在 Claude Code 对话中输入：

/init

AI 会扫描你的项目结构，自动生成一份 CLAUDE.md。

方式二：自己写（更精确）

你可以在 CLAUDE.md 中写任何你想让 AI 记住的信息。以下是我们项目的 CLAUDE.md 内容：

# Mini Mall 项目规范

## 技术栈
- 框架：Next.js 16 (App Router) + TypeScript
- 样式：TailwindCSS 4
- 数据库：SQLite + Prisma 5
- 认证：自制 Cookie Session + bcryptjs

## 目录结构
- src/app/ — 页面和 API
- src/components/ — 可复用组件
- src/lib/ — 工具函数
- prisma/ — 数据库模型

## 命名规范
- 文件名：kebab-case（如 product-card.tsx）
- 组件：PascalCase（如 ProductCard）
- 函数：camelCase（如 getProducts）

## 约定
- 所有 UI 文案和注释用中文
- 优先使用 Server Components
- API 返回 JSON，错误返回 { error: string }

提示：有了 CLAUDE.md，你不需要每次对话都重新解释项目背景。AI 会自动读取它，就像新同事入职时先看员工手册一样。

5.2.4 定义数据库模型

在 prisma/schema.prisma 中定义 6 个数据模型。以下是完整的模型定义：

// 用户
model User {
  id      Int      @id @default(autoincrement())
  name     String
  email    String    @unique
  password  String
  role     String    @default("USER")  // USER 或 ADMIN
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt
  cartItems CartItem[]
  orders   Order[]
}

// 商品分类
model Category {
  id      Int      @id @default(autoincrement())
  name    String   @unique
  slug    String   @unique      // URL 友好的英文标识
  products Product[]
}

// 商品
model Product {
  id        Int       @id @default(autoincrement())
  name      String
  description String     @default("")
  price      Float
  image      String     @default("")
  stock      Int       @default(0)
  categoryId  Int
  category   Category   @relation(fields: [categoryId], references: [id])
  createdAt   DateTime   @default(now())
  updatedAt   DateTime   @updatedAt
  cartItems   CartItem[]
  orderItems  OrderItem[]
}

// 购物车项
model CartItem {
  id      Int     @id @default(autoincrement())
  userId   Int
  productId Int
  quantity  Int     @default(1)
  user     User    @relation(fields: [userId], references: [id], onDelete: Cascade)
  product   Product  @relation(fields: [productId], references: [id], onDelete: Cascade)
  @@unique([userId, productId])  // 同一用户同一商品只允许一条记录
}

// 订单
model Order {
  id      Int       @id @default(autoincrement())
  userId   Int
  status   String     @default("PENDING")
  total    Float
  createdAt DateTime   @default(now())
  user     User      @relation(fields: [userId], references: [id])
  items    OrderItem[]
}

// 订单明细
model OrderItem {
  id        Int    @id @default(autoincrement())
  orderId    Int
  productId   Int
  productName String  // 下单时锁定商品名，防止后续改名影响历史订单
  price      Float   // 下单时锁定价格
  quantity   Int
  order      Order   @relation(fields: [orderId], references: [id], onDelete: Cascade)
  product    Product @relation(fields: [productId], references: [id])
}

然后执行迁移：

# 生成 Prisma 客户端 + 创建数据库表
npx prisma migrate dev --name init

提示：Prisma 的 migrate dev 做了三件事：1）对比 schema 和数据库；2）生成迁移 SQL 文件；3）应用到数据库。这些迁移文件可以提交到 Git，团队成员都能复现相同的数据库结构。

5.2.5 填充种子数据

空数据库没法开发。写一个种子脚本，插入 12 个商品和 2 个测试用户。

创建 prisma/seed.ts：

import { PrismaClient } from "@prisma/client";
import bcrypt from "bcryptjs";

const prisma = new PrismaClient();

async function main() {
  // 创建 5 个分类
  const categories = await Promise.all([
   prisma.category.create({ data: { name: "数码电子", slug: "digital" } }),
   prisma.category.create({ data: { name: "服装鞋帽", slug: "clothing" } }),
   prisma.category.create({ data: { name: "家居生活", slug: "home" } }),
   prisma.category.create({ data: { name: "食品饮料", slug: "food" } }),
   prisma.category.create({ data: { name: "图书教育", slug: "books" } }),
  ]);

  // 创建 12 个商品（代码略，见完整源码）
  // ...

  // 创建管理员和测试用户
  const adminPassword = await bcrypt.hash("admin123", 10);
  const userPassword = await bcrypt.hash("user123", 10);
  await prisma.user.create({
   data: { name: "管理员", email: "admin@example.com", password: adminPassword, role: "ADMIN" },
  });
  await prisma.user.create({
   data: { name: "测试用户", email: "user@example.com", password: userPassword, role: "USER" },
  });

  console.log("种子数据创建完成！");
}

main().finally(() => prisma.$disconnect());

在 package.json 中添加 seed 配置：

"prisma": {
  "seed": "tsx prisma/seed.ts"
}

执行：

npx prisma db seed

验证：终端输出 “种子数据创建完成”。数据库中已有 5 个分类、12 个商品、2 个用户。

5.2.6 你学到了什么

概念	说明
create-next-app	Next.js 官方脚手架，一键生成项目
Prisma	ORM 工具，用代码定义数据库结构
Prisma Migrate	数据库版本管理，像 Git 管理代码一样管理数据库
Seed 脚本	开发阶段用来填充测试数据
CLAUDE.md	AI 的项目说明书，每次对话自动加载

---

5.3 配置 Claude Code：Hook + 权限模式 + Memory

本节目标：配置 Claude Code 的进阶设置，让开发更安全、更高效

演示的 Claude Code 功能：Hook 配置、权限模式、Memory 系统

5.3.1 Hook 配置：让 AI 自动执行命令

Hook（钩子）是 Claude Code 的一个强大功能——你可以在特定事件发生时（比如 AI 修改了文件），自动触发一条命令。

在我们的项目中，创建一个 .claude/settings.json 文件：

{
  "permissions": {
   "allow": [
     "Bash(npm run dev)",
     "Bash(npm run build)",
     "Bash(npx prisma *)",
     "Bash(npm install *)"
   ]
  },
  "hooks": {
   "PostToolUse": [
     {
      "matcher": "Write|Edit",
      "hooks": [
        {
         "type": "command",
         "command": "echo \"文件已修改，建议检查一下改了什么\""
        }
      ]
     }
   ]
  }
}

解释一下这段配置：

• permissions.allow：这些命令 AI 可以直接执行，不需要每次弹出确认框
• hooks.PostToolUse：当 AI 使用 Write 或 Edit 工具修改文件后，自动执行提醒命令

提示：Hook 可以做很多事——自动运行 Prettier 格式化代码、自动运行 ESLint 检查、甚至自动提交 Git。但初期不建议配置太多，够用就好。

5.3.2 权限模式：控制 AI 的"自由度"

Claude Code 有三种权限模式，针对不同的场景：

模式	行为	适用场景
Safe（安全）	所有危险操作都需要确认	新手阶段，不想让 AI 乱动文件
Approve（审批）	大部分操作要确认	日常开发，看到关键操作再放行
Edit（编辑）	AI 自主操作	信任 AI，不想频繁点确认

注意：建议初期使用 Approve 模式。当 AI 要执行 rm -rf、git push --force 等危险操作时，它会强制要求确认——这是保护你的最后一道防线。

5.3.3 Memory 系统：让 AI 记住你的偏好

Memory 是 Claude Code 的持久化记忆系统。你可以让 AI 记住：

• 你的技术偏好：“我喜欢用 TypeScript 严格模式”
• 项目约定：“这个项目用 TailwindCSS，不要写 CSS 文件”
• 你踩过的坑：“上次用 Prisma 7 有兼容问题，这次用 Prisma 5”

在任何对话中，直接告诉 AI：

请记住：我所有的项目都用 TypeScript 严格模式，UI 文案用中文，代码注释用中文。

AI 会把这条信息存到持久化记忆中，以后的对话都会自动读取。

验证：后续对话中问 AI “我们之前约定过编码规范吗？”——AI 会从 Memory 中检索并回答你。

5.3.4 你学到了什么

概念	说明
settings.json	Claude Code 的配置文件，控制权限、Hook 等
Hook	事件触发的自动命令
权限模式	Safe / Approve / Edit 三种级别
Memory	跨对话持久化的记忆系统

---

5.4 创建自定义 Skill：api-crud-generator 重点

本节目标：手把手创建你的第一个自定义 Skill，理解 Skill 的完整结构

演示的 Claude Code 功能：自定义 Skill、Skill 的四层目录结构

5.4.1 为什么要创建 Skill

在电商项目中，你会反复做同样的事情：

商品需要 CRUD → 写 Prisma 查询 + API Route + 管理页面
分类需要 CRUD → 写 Prisma 查询 + API Route + 管理页面
订单需要 CRUD → 写 Prisma 查询 + API Route + 管理页面

每次都是相似的代码结构，只是换了个模型名。如果每次都让 AI 从零写，不仅慢，而且每次的代码风格可能不一致。

Skill 就是解决这个问题的——把重复的模式封装成可复用的"标准操作流程"。

5.4.2 Skill 的目录结构

一个完整的 Skill 是一个目录，推荐放在 .claude/skills/ 下：

.claude/skills/api-crud-generator/
├── SKILL.md           ← 核心：技能描述文件（必选）
├── scripts/           ← 辅助脚本（可选）
├── resources/         ← 模板和配置（可选）
└── references/         ← 参考文档（可选）

对于我们这个项目，只需要 SKILL.md 就够了。

5.4.3 编写 SKILL.md

创建 .claude/skills/api-crud-generator/SKILL.md：

---
name: api-crud-generator
version: 1.0
description: 根据 Prisma 模型生成标准的 Next.js API Route + 前端管理页面
trigger: ["生成CRUD", "生成接口", "生成管理页面"]
---

# API CRUD 生成器

## 功能说明
根据指定的 Prisma 模型，自动生成标准的管理后台 CRUD 代码：
1. API Routes（5 个）：GET 列表、GET 详情、POST 创建、PUT 更新、DELETE 删除
2. 前端页面：数据列表页、创建/编辑表单

## 执行步骤

### 第 1 步：确认模型信息
询问用户：
- 要生成的模型名称（如 Product、Category）
- API 路径（如 /api/admin/products）
- 页面路由（如 /admin/products）

### 第 2 步：生成 API Route Handlers
按照标准模板生成以下文件：
1. `route.ts` — GET 列表 + POST 创建
2. `[id]/route.ts` — GET 详情 + PUT 更新 + DELETE 删除

### 第 3 步：生成前端管理页面
生成一个包含以下功能的管理页面：
- 数据表格（列出所有字段）
- "新增"按钮 + 表单
- 每行的"编辑"和"删除"按钮
- TailwindCSS 样式

### 第 4 步：确认并验证
- 列出所有生成的文件
- 提醒用户执行 npx prisma generate（如果模型有变更）
- 给出测试方法

## 注意事项
- 所有 UI 文案使用中文
- 使用 Next.js App Router 的 params 语法
- 创建和更新前做输入验证
- 密码字段永远不通过 API 返回

5.4.4 SKILL.md 的结构解析

每个 Skill 文件包含两部分：

1. Frontmatter（文件头部的 YAML 元数据）

---
name: 技能唯一名称
description: 一句话描述
trigger: 触发关键词列表
---

• name：技能的唯一标识
• description：帮助 AI 判断什么时候该用这个技能
• trigger：当用户消息包含这些关键词时，AI 知道要加载这个 Skill

2. 正文（Markdown 格式的指令）

这是 AI 执行任务时会阅读的"操作手册"。写得好坏直接决定 AI 的输出质量。

提示：写 Skill 时想象你在给一个聪明的实习生写工作说明书——告诉他做什么、用什么工具、注意什么坑。

5.4.5 在开发中使用 Skill

创建好 Skill 后，在 Claude Code 对话中，你只需要这样说：

请用 api-crud-generator Skill 为 Category 模型生成管理后台代码。
API 路径放在 /api/admin/categories，页面放在 /admin/categories。

AI 会：

1. 自动加载 SKILL.md 中的指令
2. 按照步骤 1-4 的标准流程执行
3. 生成符合项目规范的代码

这就是 Skill 的威力——一次编写，反复使用，标准统一。

5.4.6 你学到了什么

概念	说明
Skill 的定义	封装了特定能力的可复用指令集
Frontmatter	Skill 的元数据，AI 用来判断何时加载
SKILL.md	Skill 的核心载体
触发关键词	用户说什么话会激活这个 Skill
@ 引用	安装官方 Skill 的方式，如 anthropics/skills@frontend-design

---